eva4j 1.0.16 → 1.0.18

package/src/skills/build-system-yaml/references/domain-yaml-spec.md

@@ -25,13 +25,21 @@ Propón campos necesarios no mencionados, Value Objects expresivos, invariantes
 4. ❌ **No `transitions` sin `initialValue`** en el enum
 5. ❌ **No inventar módulos en `reference.module`** — solo los de `system/system.yaml`
 6. ❌ **No duplicar en `endpoints:`** lo de `system.yaml → exposes:`
-7. ❌ **`endpoints:` NUNCA es lista plana** — siempre `{ basePath, versions: [{ version, operations }] }`
+7. ❌ **`endpoints:` NUNCA es lista plana** — siempre `{ basePath, versions: [{ version, operations }] }`. Si el módulo tiene **2+ agregados**, usar `basePath: ""` y paths absolutos por operación
 8. ❌ **No inventar eventos** — deben coincidir con `integrations.async[]` donde `producer` es este módulo
 9. ❌ **No inventar listeners** — deben coincidir con `integrations.async[].consumers[]` donde `module` es este módulo
 10. ❌ **No inventar ports** — deben coincidir con `integrations.sync[]` donde `caller` es este módulo
 11. ❌ **Todo en inglés**
 12. ❌ **No transiciones sin evidencia de activación** — toda transición activada por `ports:` o scheduler necesita un domain event con `triggers`
 13. ❌ **No reutilizar `service:` en `ports[]` entre módulos** — nombres propios del bounded context
+14. ❌ **No `readModels[].source.module` igual al módulo actual** — readModels son cross-module exclusivamente
+15. ❌ **No auditoría, endpoints REST ni lógica de negocio en `readModels:`** — son proyecciones inmutables
+16. ❌ **No `readModels[].name` sin sufijo `ReadModel`** — siempre `PascalCase + ReadModel`
+17. ❌ **No `readModels[].tableName` sin prefijo `rm_`** — identificación visual obligatoria
+18. ❌ **No `lifecycle:` y `triggers:` en el mismo evento** — son mutuamente excluyentes
+19. ❌ **No `lifecycle: softDelete` sin `hasSoftDelete: true`** en la entidad raíz
+20. ❌ **No `lifecycle: delete` con `hasSoftDelete: true`** — delete es hard delete
+21. ❌ **No declarar campos en lifecycle events que no existan en la entidad raíz** — solo `{entityName}Id`, campos de la entidad y campos temporales auto-resolubles (`*At` + `LocalDateTime`). Genera error `C2-010`
 
 ---
 
@@ -41,7 +49,8 @@ Propón campos necesarios no mencionados, Value Objects expresivos, invariantes
 |---|---|
 | `modules[x].exposes[]` | `endpoints:` con `basePath` + `versions[].operations[]` |
 | `integrations.async[]` donde `producer = módulo` | `events:` |
-| `integrations.async[].consumers[]` donde `module = módulo` | `listeners:` (con `useCase`) |
+| `integrations.async[].consumers[]` donde `module = módulo` y tiene `useCase` | `listeners:` (con `useCase`) |
+| `integrations.async[].consumers[]` donde `module = módulo` y tiene `readModel` | `readModels:` (con `syncedBy`) |
 | `integrations.sync[]` donde `caller = módulo` | `ports:` (con `service`, `http`) |
 
 ### Formato correcto de endpoints
@@ -67,6 +76,50 @@ endpoints:
           path: /{id}
 ```
 
+### Módulos con múltiples agregados
+
+Cuando un módulo contiene **2 o más agregados** (ej: Product + Category), NO es posible usar un solo `basePath` porque cada agregado tiene su propio recurso REST. En este caso:
+
+- Usar `basePath: ""` (string vacío — **NO** `basePath: /` que genera slash trailing)
+- Declarar paths **absolutos** en cada operación (ej: `/products`, `/categories/{id}`)
+- El controlador generado tendrá `@RequestMapping("/api/v1")` (limpio, sin slash extra)
+
+```yaml
+# ✅ Módulo con múltiples agregados — basePath vacío + paths absolutos
+endpoints:
+  basePath: ""
+  versions:
+    - version: v1
+      operations:
+        # ── Product operations ──
+        - useCase: CreateProduct
+          method: POST
+          path: /products
+        - useCase: GetProduct
+          method: GET
+          path: /products/{id}
+        - useCase: FindAllProducts
+          method: GET
+          path: /products
+        # ── Category operations ──
+        - useCase: CreateCategory
+          method: POST
+          path: /categories
+        - useCase: GetCategory
+          method: GET
+          path: /categories/{id}
+        - useCase: FindProductsByCategory
+          method: GET
+          path: /categories/{id}/products
+```
+
+**Regla de decisión:**
+
+| Agregados en el módulo | basePath | Paths en operations |
+|---|---|---|
+| 1 agregado | `/recurso` (ej: `/orders`) | Relativos: `/`, `/{id}`, `/{id}/confirm` |
+| 2+ agregados | `""` (vacío) | Absolutos: `/products`, `/categories/{id}` |
+
 ---
 
 ## Estructura completa del module.yaml
@@ -176,6 +229,35 @@ aggregates:
           - name: reason
             type: String
 
+      # ── Lifecycle events (CRUD-based, no transitions) ──
+      # Use lifecycle: instead of triggers: when the event is emitted
+      # at a CRUD operation (create/update/delete/softDelete).
+      # Typical use: source modules whose events feed readModels.
+      #
+      # - name: ProductCreatedEvent
+      #   lifecycle: create          # raise() in creation constructor
+      #   fields:
+      #     - name: productId
+      #       type: String
+      #     - name: name
+      #       type: String
+      #
+      # - name: ProductUpdatedEvent
+      #   lifecycle: update          # raise() in UpdateCommandHandler
+      #   fields: [...]
+      #
+      # - name: ProductDeletedEvent
+      #   lifecycle: delete          # raise() in DeleteCommandHandler
+      #   fields:
+      #     - name: productId
+      #       type: String
+      #
+      # - name: ProductDeactivatedEvent
+      #   lifecycle: softDelete      # raise() in softDelete() method
+      #   fields:
+      #     - name: productId
+      #       type: String
+
 endpoints:
   basePath: /orders
   versions:
@@ -289,34 +371,164 @@ Anotaciones: `NotNull`, `NotBlank`, `NotEmpty`, `Email`, `Size`, `Min`, `Max`, `
 
 ---
 
-## Proyecciones locales (read models)
+## Proyecciones locales (`readModels:`)
+
+Cuando un módulo necesita datos de otro bounded context para validar precondiciones o enriquecer entidades, usar `readModels:` en vez de `ports:` (sync HTTP). Esto elimina dependencias síncronas y mejora autonomía, resiliencia y rendimiento.
+
+### Cuándo usar readModels vs ports
+
+| Criterio | `readModels:` (async) | `ports:` (sync) |
+|---|---|---|
+| Consistencia eventual aceptable | ✅ | — |
+| Se necesita consistencia fuerte | — | ✅ |
+| Datos se consultan frecuentemente | ✅ | — |
+| Llamada infrecuente y simple | — | ✅ |
+| Preparación para microservicios | ✅ | — |
+
+### Estructura
+
+```yaml
+# Nivel raíz, sibling de aggregates:, listeners:, ports:
+readModels:
+  - name: ProductReadModel               # PascalCase + sufijo "ReadModel" (OBLIGATORIO)
+    source:                              # Trazabilidad al módulo fuente (OBLIGATORIO)
+      module: products                   # Módulo fuente (kebab-case)
+      aggregate: Product                 # Agregado fuente (PascalCase)
+    tableName: rm_orders_products         # Tabla en BD (OBLIGATORIO, prefijo rm_{consumer}_{source})
+    fields:                              # Campos proyectados — subconjunto del fuente
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+      - name: status
+        type: String
+    syncedBy:                            # Eventos que mantienen esta tabla (min 1)
+      - event: ProductCreatedEvent       # Nombre del evento (PascalCase + sufijo Event)
+        action: UPSERT                   # Acción: UPSERT | DELETE | SOFT_DELETE
+      - event: ProductUpdatedEvent
+        action: UPSERT
+      - event: ProductDeactivatedEvent
+        action: SOFT_DELETE
+```
+
+### Reglas
+
+- **`name:`** — PascalCase, **DEBE** terminar con `ReadModel`
+- **`tableName:`** — **DEBE** seguir el patrón `rm_{consumerModule}_{sourceModule}` (ej: `rm_orders_products`) para evitar colisiones en monolitos
+- **`fields:`** — **DEBE** incluir un campo `id`
+- **`syncedBy:`** — **DEBE** tener al menos una entrada
+- **`source.module:`** — **NO PUEDE** ser el mismo módulo actual (cross-module exclusivamente)
+- **Sin auditoría** — Los readModels **nunca** tienen campos de auditoría
+- **Sin endpoints REST** — Los readModels **nunca** exponen endpoints
+- **Sin lógica de negocio** — La clase de dominio es inmutable (solo getters)
+
+### Acciones de sincronización
+
+| Acción | Significado | Uso |
+|---|---|---|
+| `UPSERT` | Insertar si es nuevo, actualizar si existe | Creaciones, actualizaciones, cambios de estado |
+| `DELETE` | Eliminar el registro permanentemente | Hard deletes en el módulo fuente |
+| `SOFT_DELETE` | Marcar como inactivo con timestamp | Cuando el fuente usa soft delete |
+
+### Inferencia desde system.yaml
+
+| Fuente en system.yaml | Destino en domain.yaml |
+|---|---|
+| `consumers[].readModel: ProductReadModel` | `readModels:` entry con ese nombre |
+| `integrations.async[].producer` | `readModels[].source.module` |
+| `integrations.async[].topic` | Topic derivado automáticamente del nombre del evento |
+
+### Impacto en el módulo fuente
+
+El módulo fuente **debe** emitir los eventos referenciados en `syncedBy`. Asegurar que los `events:` del fuente incluyan todos los campos declarados en `readModels[].fields` (el payload es la fuente de verdad para la proyección).
+
+**Restricción de cobertura:** Los campos del readModel (excepto `id`) deben estar cubiertos por al menos un evento UPSERT en `syncedBy[]`. Si un campo no aparece en ningún evento UPSERT, siempre será null — genera warning `C1-007`. Además, los campos del readModel deben ser subconjunto de los campos de la entidad raíz del módulo fuente (por C2-010, los lifecycle events no pueden emitir campos ajenos a la entidad).
 
-Agregados sincronizados por listeners Kafka. Señales:
-- Campos coinciden con `listeners[].fields`
-- useCase: `Register*InLocalCatalog`, `Sync*`, `Update*FromEvent`
-- Sin endpoints de escritura
-- Existe para evitar llamadas síncronas en tiempo real
+### Propiedad `lifecycle:` en eventos del módulo fuente
+
+Cuando un evento existe para alimentar un readModel (operación CRUD pura, sin transición de estado), usar `lifecycle:` en vez de `triggers:`.
+
+| Valor | Punto de emisión | Descripción |
+|---|---|---|
+| `create` | Constructor de creación de la entidad | UUID auto-generado como id antes de raise() |
+| `update` | UpdateCommandHandler, antes de `repository.save()` | raise() sobre la entidad reconstruida |
+| `delete` | DeleteCommandHandler, antes de `repository.delete()` | Hard delete — requiere `hasSoftDelete` ausente o false |
+| `softDelete` | Método `softDelete()` de la entidad | Requiere `hasSoftDelete: true` en la entidad raíz |
 
-**Auditoría:** `audit.enabled: true`, `trackUser: false` (cambios vienen de eventos, no de usuarios).
+**Derivación desde el nombre del evento:**
+
+| Patrón del nombre del evento | `lifecycle:` |
+|---|---|
+| `*CreatedEvent`, `*RegisteredEvent` | `create` |
+| `*UpdatedEvent` | `update` |
+| `*DeletedEvent` | `delete` |
+| `*DeactivatedEvent` | `softDelete` |
+
+**Ejemplo — módulo fuente `products`:**
 
 ```yaml
-- name: BikeCatalog
-  entities:
-    - name: bikeCatalogEntry
-      isRoot: true
-      tableName: bike_catalog_entries
-      audit:
-        enabled: true
-        trackUser: false
-      fields:
-        - name: id
-          type: String
-        - name: isAvailable
-          type: Boolean
-          readOnly: true
-          defaultValue: true
+aggregates:
+  - name: Product
+    entities:
+      - name: product
+        isRoot: true
+        tableName: products
+        hasSoftDelete: true              # requerido por lifecycle: softDelete
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+            readOnly: true
+            defaultValue: "ACTIVE"
+    events:
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductDeactivatedEvent
+        lifecycle: softDelete
+        fields:
+          - name: productId
+            type: String
+          - name: deactivatedAt
+            type: LocalDateTime
 ```
 
+**Reglas:**
+- `lifecycle:` y `triggers:` son mutuamente excluyentes — un evento usa uno u otro, nunca ambos
+- `lifecycle: softDelete` requiere `hasSoftDelete: true` en la entidad raíz
+- `lifecycle: delete` requiere que `hasSoftDelete` sea `false` o esté ausente
+- `fields:` del evento debe incluir **todos** los campos del readModel que lo consume (el payload es la fuente de verdad para la proyección)
+- Siempre incluir `{entityName}Id` como campo (se mapea a `aggregateId` del DomainEvent base)
+- `fields:` del lifecycle event solo puede contener: (a) `{entityName}Id`, (b) campos que existen en la entidad raíz del agregado, (c) campos temporales auto-resolubles (nombre termina en `At` + tipo `LocalDateTime`). Cualquier otro campo genera error `C2-010`
+
 ---
 
 ## Clasificación de campos readOnly
@@ -397,7 +609,9 @@ Si un valor no es trazable → falta un endpoint o listener en el diseño.
 - [ ] `events[].triggers[]` referencia métodos existentes en `transitions[].method`
 - [ ] `{entityName}Id` en `events[].fields` cuando cruza módulos via Kafka
 - [ ] `endpoints:` con estructura `{ basePath, versions }` — no lista plana
-- [ ] `endpoints[].path` relativos al basePath
+- [ ] Módulo con 1 agregado → `basePath: /recurso` y paths relativos
+- [ ] Módulo con 2+ agregados → `basePath: ""` y paths absolutos por operación
+- [ ] `endpoints[].path` coherentes con el basePath elegido
 - [ ] `listeners[]` para todos los eventos donde este módulo es consumidor
 - [ ] `listeners[].useCase` coincide con `consumers[].useCase`
 - [ ] `listeners[].topic` bare SCREAMING_SNAKE_CASE (sin topicPrefix)
@@ -406,5 +620,18 @@ Si un valor no es trazable → falta un endpoint o listener en el diseño.
 - [ ] `nestedTypes[]` para campos de tipo objeto en listeners/ports
 - [ ] Transiciones por `ports:` tienen domain event con `triggers`
 - [ ] Cada enum `*Type` valor trazable a listener/endpoint/event
-- [ ] Proyecciones: `audit.enabled: true`, `trackUser: false`
+- [ ] Proyecciones cross-module: usar `readModels:` con `source`, `tableName` (prefijo `rm_`), `fields` (incluye `id`), `syncedBy`
+- [ ] `readModels[].name` termina con `ReadModel` (PascalCase)
+- [ ] `readModels[].source.module` ≠ módulo actual
+- [ ] `readModels[].syncedBy` → al menos una entrada con `action` válida (UPSERT, DELETE, SOFT_DELETE)
+- [ ] Eventos en `syncedBy` deben existir como `events:` en el módulo fuente
+- [ ] Eventos del módulo fuente consumidos por readModels → deben tener `lifecycle:` (no `triggers:`)
+- [ ] `lifecycle:` derivado del nombre del evento: `*CreatedEvent`→`create`, `*UpdatedEvent`→`update`, `*DeletedEvent`→`delete`, `*DeactivatedEvent`→`softDelete`
+- [ ] `lifecycle: softDelete` → entidad raíz tiene `hasSoftDelete: true`
+- [ ] `lifecycle: delete` → entidad raíz NO tiene `hasSoftDelete: true`
+- [ ] `lifecycle:` y `triggers:` nunca en el mismo evento
+- [ ] Lifecycle event fields son campos de la entidad raíz (excluyendo `{entityName}Id` y `*At` temporal) — `C2-010`
+- [ ] ReadModel fields cubiertos por eventos UPSERT del productor — `C1-007`
+- [ ] ReadModel fields son subconjunto de los campos de la entidad raíz fuente
+- [ ] Si `readModels:` reemplaza un `ports:`, eliminar la entrada sync correspondiente
 - [ ] Todo en inglés

package/src/skills/build-system-yaml/references/module-spec.md

@@ -34,16 +34,23 @@ Especificación técnica narrativa del sistema completo. Una sección `##` por c
 **Postconditions:** [system state after successful execution]
 **Validations and errors:** [exception conditions and error types]
 **Events emitted:** [DomainEvent name and trigger condition, or "none"]
+**Operations:**
+1. [Load entity / validate precondition — throw NotFoundException or 400 if invalid]
+2. [External port call: {PortName}.{method}() — if applicable]
+3. [Invoke domain method: entity.{method}()]
+4. [Persist via repository]
+5. [Emit event — if applicable]
 
 ### Exposed Endpoints
 [One `####` per endpoint in exposes:]
 
 #### {METHOD} {/path}
 **Purpose:** [endpoint description and usage context]
-**Path params / Query params:** [each parameter described]
-**Request body:** [expected fields, types, validation constraints]
-**Response:** [returned fields and their business meaning]
-**Errors:** [HTTP status codes and when they occur]
+**Path params:** [param — Type — Description; omit if none]
+**Query params:** [GET/DELETE only — param: Type, required/optional, default, description; omit if none]
+**Request body:** [POST/PUT/PATCH only — field: Type — constraint; omit for GET/DELETE]
+**Response:** [GET only — field: Type — business meaning; list endpoints include {content:[...], totalElements, page, size}]
+**Errors:** [HTTP status — condition]
 
 ### Emitted Events
 [Only if module is producer in integrations.async]
@@ -61,6 +68,17 @@ Especificación técnica narrativa del sistema completo. Una sección `##` por c
 **When called:** [in which use case and under what condition]
 **Endpoints used:** [METHOD /path list]
 **Data obtained and how it's used:** [detailed description]
+
+### Read Models (local projections)
+[Only if module has readModels: in its domain.yaml]
+
+#### {ReadModelName} ← {source-module}
+**Purpose:** [why this projection exists — what data it provides and why sync HTTP was replaced]
+**Source aggregate:** [{Aggregate} in {source-module}]
+**Table:** [{tableName}]
+**Projected fields:** [field list with types]
+**Synced by:** [event names and actions (UPSERT/DELETE/SOFT_DELETE)]
+**Consistency model:** Eventual — acceptable delay: [specify, e.g. "milliseconds"]
 ```
 
 ### Reglas del system.md
@@ -70,6 +88,8 @@ Especificación técnica narrativa del sistema completo. Una sección `##` por c
 - **Incluir useCases de consumers** como casos de uso del módulo consumidor.
 - **Referenciar módulos por nombre**.
 - **Máquinas de estado** cuando hay ciclos de vida.
+- **Endpoints detallados**: separar path params de query params. Para GETs indicar los campos clave de la respuesta con sus tipos. Para POST/PUT/PATCH listar los campos del body con tipo y constraint. Nunca "ver request" como descripción de response.
+- **Operations en casos de uso**: el campo `**Operations:**` es obligatorio en cada `#### {UseCaseName}`. Cada ítem describe un paso concreto del handler referenciando nombres reales de repositorios, ports, métodos de dominio y eventos. No usar items genéricos como "execute business logic".
 - Omitir secciones no aplicables.
 
 ---
@@ -204,6 +224,12 @@ sequenceDiagram
 **Invariants verified:** [ID list — e.g., INV-01, INV-03]
 **Validations and errors:** [exception conditions, error type, HTTP status]
 **Events emitted:** [DomainEvent name and condition, or "none"]
+**Operations:**
+1. [Load entity by id via {Repository}.findById() — throw NotFoundException if absent]
+2. [Call {PortName}.{method}() to obtain cross-module data — if applicable]
+3. [Invoke entity.{domainMethod}() — domain enforces invariants]
+4. [Persist via {Repository}.save(entity)]
+5. [DomainEventHandler publishes event after transaction commit — if applicable]
 
 **Flow diagram:**
 ```mermaid
@@ -224,10 +250,42 @@ flowchart TD
 ### {METHOD} {/path}
 **Use case:** `{UseCase}`
 **Purpose:** [description]
-**Path params / Query params:** [each parameter]
-**Request body:** [fields, types, validations]
-**Response:** [fields and business meaning]
-**Errors:** [HTTP status codes and conditions]
+**Path params:** _(omit table if none)_
+
+| Param | Type | Description |
+|-------|------|-------------|
+| {param} | `String` | [description] |
+
+**Query params:** _(GET / DELETE only — omit table if none)_
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| {param} | `String` | No | — | [description] |
+
+**Request body:** _(POST / PUT / PATCH only — omit for GET / DELETE)_
+```json
+{
+  "field": "String",       // required — [constraint]
+  "otherField": "Integer"  // optional — [constraint]
+}
+```
+
+**Response schema:** _(GET single only — omit for mutations)_
+```json
+{
+  "id": "String",
+  "field": "Type"          // [business meaning]
+}
+```
+_(For GET list: `{ "content": [...], "totalElements": "Long", "page": "Integer", "size": "Integer" }`)_
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | [entity] not found |
+| 400 | [validation failure] |
+| 409 | [invariant violated] |
 
 ## Emitted Events
 [Only if module is producer in integrations.async]
@@ -245,6 +303,27 @@ flowchart TD
 **When called:** [in which use case and condition]
 **Endpoints used:** [METHOD /path list]
 **Data obtained and how it's used:** [detailed description]
+
+## Read Models (local projections)
+[Only if module has readModels: in its domain.yaml]
+
+### {ReadModelName} ← {source-module}
+**Purpose:** [why this projection exists — what data it provides and why sync HTTP was not used]
+**Source aggregate:** [{Aggregate} in {source-module}]
+**Table:** [{tableName}]
+**Projected fields:** [field list with types and business meaning]
+**Synced by:** [event name → action, for each syncedBy entry]
+**Consistency model:** Eventual — acceptable delay: [specify]
+**Replaces:** [sync port name, if applicable — e.g., "Replaces OrderProductService sync call"]
+
+### Architectural Decision — {ReadModelName}
+
+**Context:** [{module} needs {data description} from {source-module} to {business reason}]
+**Decision:** Use event-driven Local Read Model instead of sync HTTP call.
+**Consequences:**
+- (+) Module is fully autonomous — no runtime dependency on {source-module}
+- (+) Lower latency — local DB query vs HTTP roundtrip
+- (-) Eventual consistency — milliseconds delay on updates
 ```
 
 ---
@@ -253,11 +332,13 @@ flowchart TD
 
 - **Todo en inglés**: títulos, secciones, descripciones, invariantes, use cases.
 - **INVARIANTES obligatorias**: al menos 2–3 por módulo. Analizar unicidad, estados válidos, rangos, precondiciones de transición.
-- **Diagrama de interacciones obligatorio**: todos los endpoints y eventos entrantes. Sin entradas → nodo `[[passive module]]`.
+- **Diagrama de interacciones obligatorio**: todos los endpoints, eventos entrantes y read models. Sin entradas → nodo `[[passive module]]`. Read models se muestran como subgraphs separados con label `Read Models` y nodos `📦 {ReadModelName}` conectados desde eventos de sincronización.
 - **Diagrama de secuencia obligatorio**: al menos un `sequenceDiagram` cubriendo el happy path. Diagramas adicionales para bifurcaciones (error, compensación). Modelar todos los actores reales.
 - **Diagrama de flujo por caso de uso**: `flowchart TD` dentro de cada `### {UseCase}` con trigger, invariantes, lógica y eventos.
 - **Máquina de estados condicional**: solo si hay entidades con ciclo de vida. Restricciones de transición son invariantes implícitas.
 - **Referenciar invariantes** en cada caso de uso (INV-01, INV-02...).
+- **Endpoints con contratos ricos**: para cada endpoint separar path params, query params, body y response en bloques distintos con tipos y constraints reales del dominio. Para GETs incluir el JSON schema de respuesta; para POST/PUT/PATCH el JSON del body. Listas incluyen wrapper de paginación `{ content, totalElements, page, size }`. Nunca usar placeholders genéricos.
+- **Operations en casos de uso**: el campo `**Operations:**` es **obligatorio** en cada `### {UseCase}`. Lista los pasos del handler con nombres concretos: repositorio, port, método de dominio, evento. Sirve como contrato de implementación evaluable por revisores humanos antes de generar código.
 - **No duplicar** system.md — el `.md` del módulo es la especificación completa.
 - Archivos en `system/{module-name}.md`.
 

package/src/skills/build-system-yaml/references/system-yaml-spec.md

@@ -58,6 +58,14 @@ integrations:
         - module: notifications
           useCase: NotifyOrderPlaced   # acción que notifications ejecuta
 
+    # Read Model sync — consumer usa readModel: en vez de useCase:
+    - event: ProductCreatedEvent
+      producer: products
+      topic: PRODUCT_CREATED
+      consumers:
+        - module: orders
+          readModel: ProductReadModel  # ← indica sync de read model, no lógica de negocio
+
   sync:
     - caller: orders               # módulo que hace la llamada
       calls: customers             # módulo destino
@@ -78,6 +86,7 @@ integrations:
 | Port names | PascalCase + sufijo `Service` — **único por módulo** | `OrderCustomerService` | `CustomerService` (compartido) |
 | useCases | PascalCase, verbo + sustantivo | `CreateOrder`, `FindAllOrders` | `createOrder`, `orders` |
 | `consumers[].useCase` | PascalCase, verbo + sustantivo | `HandleOrderPlaced` | `orderPlaced` |
+| `consumers[].readModel` | PascalCase + `ReadModel` | `ProductReadModel` | `productReadModel` |
 
 ---
 
@@ -91,6 +100,31 @@ integrations:
 - ✅ `consumers[].module` debe existir en `modules:`
 - ✅ Módulos pasivos (notificaciones, auditoría) son **consumidores**, nunca `caller`
 - ℹ️ Varios módulos pueden consumir el mismo evento sin riesgo de colisión de beans
+- ℹ️ `consumers[]` puede usar `readModel:` en vez de `useCase:` para indicar sync de Read Model local (proyección de datos cross-module mantenida por eventos)
+
+---
+
+## Consumers: useCase vs readModel
+
+Cada entrada en `consumers[]` debe declarar **exactamente uno** de:
+
+| Campo | Cuándo usar | Qué genera en domain.yaml |
+|---|---|---|
+| `useCase:` | Lógica de negocio (handler + command) | `listeners:` entry |
+| `readModel:` | Proyección local de datos (sync handler) | `readModels:` entry con `syncedBy` |
+
+```yaml
+consumers:
+  - module: payments
+    useCase: HandleOrderPlaced       # → listeners: en payments.yaml
+  - module: orders
+    readModel: ProductReadModel      # → readModels: en orders.yaml
+```
+
+**Reglas de `readModel:`:**
+- PascalCase, sufijo `ReadModel`
+- El module consumidor declara `readModels:` en su `domain.yaml` con `source.module` apuntando al producer
+- Al reemplazar un port sync por un readModel, eliminar la entrada de `integrations.sync[]`
 
 ---
 
@@ -170,6 +204,8 @@ consumers:
 - [ ] Sin dependencias circulares síncronas
 - [ ] Todos los `consumers[].module` existen en `modules:`
 - [ ] Todos los `consumers[].useCase` presentes y en PascalCase
+- [ ] `consumers[]` con `readModel:` usan PascalCase + sufijo `ReadModel`
+- [ ] Cada consumer tiene exactamente uno de `useCase:` o `readModel:` (nunca ambos)
 - [ ] Todos los `calls.using:` existen en `exposes:` del destino
 - [ ] Módulos pasivos no son `caller`
 - [ ] `useCases` en PascalCase