eva4j 1.0.16 → 1.0.18

package/AGENTS.md

@@ -616,12 +616,16 @@ public void cancel() {
 }
 ```
 
-Si un evento **no declara `triggers`**, el desarrollador debe llamar a `raise()` manualmente dentro del método de negocio.
+Si un evento **no declara `triggers`** ni `lifecycle`, el desarrollador debe llamar a `raise()` manualmente dentro del método de negocio.
 
 **Validaciones generadas:**
-- **C2-004** (error): trigger referencia un método que no existe en ninguna transición del módulo
+- **C2-004** (error): trigger referencia un método que no existe en ninguna transición del módulo (se omite para eventos con `lifecycle`)
 - **C2-005** (info): transición sin ningún evento asociado — considera declarar `triggers`
 - **C2-001** se silencia automáticamente para transiciones que ya tienen `triggers`
+- **C2-008** (error): valor de `lifecycle` inválido (no es `create`, `update`, `delete` ni `softDelete`)
+- **C2-009** (warning): `lifecycle: softDelete` sin `hasSoftDelete: true` en la entidad raíz, o `lifecycle: delete` con `hasSoftDelete: true`
+- **C2-010** (error): campo de lifecycle event no existe en la entidad raíz del agregado (excluyendo `{entityName}Id` y campos `*At` + `LocalDateTime`)
+- **C2-012** (error): nombre del agregado no coincide con la entidad raíz — el generador usa `aggregate.name` para imports/mappers pero la clase de dominio se genera desde `entity.name`, causando `cannot find symbol`
 
 **Auto-wiring de broker:** Si el proyecto tiene un broker de mensajería instalado (`eva add kafka-client`), `eva g entities` genera automáticamente la capa de Integration Events para **todos** los eventos declarados — sin necesidad de ejecutar `eva g kafka-event` por separado:
 
@@ -658,6 +662,114 @@ public void confirm() {
 
 **Nota:** el flag `kafka: true` por evento ya no es necesario — todos los eventos se cablearán automáticamente cuando haya un broker instalado.
 
+#### Propiedad `lifecycle`
+
+Conecta un evento a una operación CRUD del ciclo de vida del agregado. A diferencia de `triggers` (que se conecta a métodos de transición de estado), `lifecycle` emite `raise()` automáticamente en el punto CRUD correspondiente.
+
+**Valores válidos:**
+
+| Valor | Punto de emisión | Descripción |
+|---|---|---|
+| `create` | Constructor de creación de la entidad | UUID auto-generado como id antes de raise() |
+| `update` | Método `update()` de la entidad raíz | Handler llama `existing.update(...)`; `raise()` interno |
+| `delete` | DeleteCommandHandler, antes de `repository.delete()` | Requiere `hasSoftDelete: false`; genera `repository.delete(entity)` |
+| `softDelete` | Método `softDelete()` de la entidad | Requiere `hasSoftDelete: true`; raise() después de `this.deletedAt = ...` |
+
+**Ejemplo en domain.yaml:**
+
+```yaml
+events:
+  - name: ProductCreatedEvent
+    lifecycle: create
+    fields:
+      - name: productId
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+
+  - name: ProductUpdatedEvent
+    lifecycle: update
+    fields:
+      - name: productId
+        type: String
+      - name: name
+        type: String
+
+  - name: ProductDeletedEvent
+    lifecycle: delete
+    fields:
+      - name: productId
+        type: String
+      - name: deletedAt
+        type: LocalDateTime
+```
+
+**Resultado generado para `lifecycle: create`:**
+
+```java
+// En Product.java — constructor de creación
+public Product(String name, String description, BigDecimal price) {
+    this.id = java.util.UUID.randomUUID().toString();
+    this.name = name;
+    this.description = description;
+    this.price = price;
+    raise(new ProductCreatedEvent(this.getId(), this.getName(), this.getPrice()));
+}
+```
+
+**Resultado generado para `lifecycle: update`:**
+
+```java
+// En Product.java — método update()
+public void update(String name, String description, BigDecimal price) {
+    this.name = name;
+    this.description = description;
+    this.price = price;
+    raise(new ProductUpdatedEvent(this.getId(), this.getName(), this.getPrice()));
+}
+```
+
+```java
+// En UpdateProductCommandHandler.java
+Product existing = repository.findById(command.id())...;
+existing.update(
+    command.name() != null ? command.name() : existing.getName(),
+    command.description() != null ? command.description() : existing.getDescription(),
+    command.price() != null ? command.price() : existing.getPrice()
+);
+repository.save(existing);
+```
+
+**Resultado generado para `lifecycle: delete`:**
+
+```java
+// En DeleteProductCommandHandler.java
+Product entity = repository.findById(command.id())...;
+entity.raise(new ProductDeletedEvent(entity.getId(), LocalDateTime.now()));
+repository.delete(entity);
+```
+
+**Resultado generado para `lifecycle: softDelete`:**
+
+```java
+// En Product.java — método softDelete()
+public void softDelete() {
+    if (this.deletedAt != null) { throw new IllegalStateException("..."); }
+    this.deletedAt = java.time.LocalDateTime.now();
+    raise(new ProductDeactivatedEvent(this.getId(), LocalDateTime.now()));
+}
+```
+
+**Resolución de argumentos:** usa las mismas reglas que `triggers` (match por nombre de campo, VO unwrapping, `LocalDateTime.now()` para campos *At, `null /* TODO */` para no resueltos).
+
+**Visibilidad de `raise()`:** cuando un evento usa `lifecycle: delete`, el método `raise()` en la entidad se genera como `public` (en vez de `protected`) para permitir que los handlers de aplicación lo invoquen. Con `lifecycle: update`, `raise()` permanece `protected` porque se invoca internamente desde el método `update()` de la entidad.
+
+**Infraestructura de repositorio:** cuando un evento usa `lifecycle: delete`, el generador agrega automáticamente `void delete(Entity entity)` al repositorio (interface + implementación). La implementación publica los eventos pendientes antes de la eliminación física.
+
+**Restricción:** un evento puede declarar `triggers` O `lifecycle`, no ambos. `lifecycle` aplica solo a eventos de la entidad raíz del agregado.
+
 ### Consumo de Eventos Externos (`listeners[]`)
 
 ```yaml
@@ -821,8 +933,94 @@ aggregates:
   └── events:     → Domain Events que PRODUCE  (async, broker)
 listeners:          → Integration Events que CONSUME (async, broker)
 ports:              → Servicios HTTP que LLAMA    (sync, Feign)
+readModels:         → Proyecciones locales mantenidas por eventos (async, broker)
 ```
 
+### Proyecciones Locales (`readModels[]`)
+
+Un Read Model es una **proyección local de datos de otro bounded context**, mantenida mediante eventos de dominio. Elimina dependencias síncronas (HTTP) entre módulos, mejorando autonomía, resiliencia y rendimiento.
+
+```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_products               # Tabla en BD (OBLIGATORIO, prefijo rm_)
+    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
+```
+
+### Artefactos generados por `readModels[]`
+
+Por cada read model:
+
+| Archivo generado | Descripción |
+|---|---|
+| `domain/models/readmodels/{Name}.java` | Clase de dominio (inmutable, sin setters, sin auditoría) |
+| `infrastructure/database/entities/{Name}Jpa.java` | Entidad JPA (Lombok, `@Id` NO auto-generado) |
+| `infrastructure/database/repositories/{Name}JpaRepository.java` | Spring Data JPA interface |
+| `domain/repositories/{Name}Repository.java` | Interfaz de repositorio (puerto) |
+| `infrastructure/database/repositories/{Name}RepositoryImpl.java` | Implementación del repositorio |
+| `application/usecases/Sync{Source}ReadModelHandler.java` | Handler de sincronización (un método por evento) |
+
+Por cada entrada en `syncedBy`:
+
+| Archivo generado | Descripción |
+|---|---|
+| `application/events/{EventBase}IntegrationEvent.java` | Integration Event (reutilizado si ya existe) |
+| `infrastructure/kafkaListener/{EventBase}ReadModelListener.java` | Kafka listener que delega al sync handler |
+| `parameters/*/kafka.yaml` | Registro del topic (actualizado) |
+
+### 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 |
+
+> **Nota:** Para acciones `DELETE` y `SOFT_DELETE`, el listener **no usa IntegrationEvent** — extrae directamente el `id` del payload y lo pasa como `String` al `SyncHandler`. El `SyncHandler` llama a `repository.deleteById(id)` o `repository.softDeleteById(id)` respectivamente. El generador tampoco produce el archivo IntegrationEvent para estas acciones.
+
+### Reglas de `readModels[]`
+
+- **`name:`** — PascalCase, **DEBE** terminar con `ReadModel`
+- **`tableName:`** — **DEBE** empezar con `rm_` (identificación visual en BD)
+- **`fields:`** — **DEBE** incluir un campo `id`
+- **`syncedBy:`** — **DEBE** tener al menos una entrada
+- **`source.module:`** — **NO PUEDE** ser el mismo módulo actual (readModels son para proyecciones cross-module)
+- **Topic derivado automáticamente** — Se deriva del nombre del evento: strip sufijo `Event` → SCREAMING_SNAKE_CASE. Override opcional con `topic:` explícito
+- **Sin auditoría** — Los readModels **nunca** tienen campos de auditoría
+- **Sin endpoints REST** — Los readModels **nunca** exponen endpoints REST
+- **Sin lógica de negocio** — La clase de dominio es inmutable (solo getters)
+
+### Validaciones
+
+| Código | Severidad | Regla |
+|---|---|---|
+| RM-001 | ERROR | `name` debe terminar con `ReadModel` |
+| RM-002 | ERROR | `tableName` debe empezar con `rm_` |
+| RM-004 | ERROR | `fields` debe incluir un campo `id` |
+| RM-005 | ERROR | `syncedBy` debe tener al menos una entrada |
+| RM-006 | ERROR | `syncedBy[].action` debe ser `UPSERT`, `DELETE` o `SOFT_DELETE` |
+| RM-009 | WARNING | `ports:` todavía tiene llamadas sync al mismo `source.module` — considerar removerlas |
+| RM-010 | ERROR | `source.module` es el mismo módulo actual |
+
 Cuando una entidad tiene `hasSoftDelete: true`, eva4j genera eliminación lógica en lugar de física.
 
 ### Configuración en domain.yaml
@@ -1246,6 +1444,7 @@ private String customerId;
 5. **SABER** que cualquier otro nombre genera un **scaffold** con `UnsupportedOperationException` — el desarrollador debe implementar el handler
 6. **APLICAR** la regla anti-duplicado: si el mismo useCase aparece en v1 y v2, se genera solo una vez
 7. **NOMBRAR** los controladores según la convención: `{Aggregate}{VersionCapitalized}Controller` (ej: `OrderV1Controller`)
+8. **SI** el módulo tiene **2+ agregados** → usar `basePath: ""` (string vacío, **NO** `basePath: /`) y paths absolutos por operación (ej: `/products`, `/categories/{id}`). Si tiene un solo agregado → `basePath: /recurso` con paths relativos
 
 ### Al Generar Código de Dominio
 
@@ -1478,7 +1677,13 @@ Al generar o modificar código, verificar:
 - [ ] Value Object con comportamiento → declarar `methods` en lugar de lógica en entidad
 - [ ] Evento de dominio → declarar en `events[]`, publicar con `raise()` en método de negocio
 - [ ] Evento con `triggers: [methodName]` → el generador emite `raise()` automáticamente; args no resolubles quedan como `null /* TODO */`
-- [ ] Sin `triggers` en el evento → el dev llama a `raise()` manualmente
+- [ ] Evento con `lifecycle: create` → el generador emite UUID auto-generado + `raise()` en el constructor de creación
+- [ ] Evento con `lifecycle: update` → el generador emite método `update()` en la entidad raíz con `raise()` interno; handler llama `existing.update(...)`; `raise()` permanece `protected`
+- [ ] Evento con `lifecycle: delete` → el generador emite `raise()` en DeleteCommandHandler + genera `repository.delete(entity)` con publicación de eventos; `raise()` se genera como `public`
+- [ ] Evento con `lifecycle: softDelete` → el generador emite `raise()` dentro del método `softDelete()` de la entidad; requiere `hasSoftDelete: true`
+- [ ] Un evento puede declarar `triggers` O `lifecycle`, no ambos
+- [ ] Campos de lifecycle events son campos de la entidad raíz (excluyendo `{entityName}Id` y `*At` temporal) — `C2-010`
+- [ ] Sin `triggers` ni `lifecycle` en el evento → el dev llama a `raise()` manualmente
 - [ ] Evento con broker → **no** usar `kafka: true`; si `eva add kafka-client` está instalado, `eva g entities` auto-cablea todos los eventos
 - [ ] Distinguir entre Domain Event (`domain/models/events/X.java`) e Integration Event (`application/events/XIntegrationEvent.java`) — cambios de broker solo afectan al adaptador `MessageBroker`
 - [ ] Consumo de eventos externos → declarar en `listeners[]` (nivel raíz); `topic:` obligatorio en módulos standalone
@@ -1493,9 +1698,19 @@ Al generar o modificar código, verificar:
 - [ ] Métodos con cuerpo (POST/PUT/PATCH) → incluir `body:`; campos de tipo objeto en `nestedTypes:`
 - [ ] Tipo de dominio auto-derivado del nombre del método — usar `domainType:` para sobrescribir si es necesario
 - [ ] Cada `service:` en `ports[]` genera: interfaz (devuelve modelos de dominio), FeignClient (devuelve DTOs infra), FeignAdapter (mapea ACL), FeignConfig + `urls.yaml`
+- [ ] Read models → declarar en `readModels[]` (nivel raíz); `name` debe terminar con `ReadModel`, `tableName` debe empezar con `rm_`
+- [ ] Read models nunca tienen auditoría, endpoints REST, ni lógica de negocio
+- [ ] Cada read model genera: clase de dominio inmutable, JPA entity (sin audit), repositorio (interface + impl), sync handler
+- [ ] Cada `syncedBy` entry genera: IntegrationEvent (reutilizado si ya existe), KafkaListener, registro de topic
+- [ ] Para `DELETE`/`SOFT_DELETE`, el listener bypasses IntegrationEvent — extrae `id` directamente y pasa `String id` al SyncHandler
+- [ ] `SOFT_DELETE` → `repository.softDeleteById(id)`; `DELETE` → `repository.deleteById(id)`; `UPSERT` → reconstruye modelo completo con IntegrationEvent + `repository.upsert()`
+- [ ] `source.module` nunca puede ser el mismo módulo (RM-010) — readModels son exclusivamente cross-module
+- [ ] ReadModel fields cubiertos por eventos UPSERT del productor — `C1-007`
+- [ ] ReadModel fields son subconjunto de los campos de la entidad raíz fuente (por C2-010, los lifecycle events no pueden emitir campos ajenos)
+- [ ] Topics de readModels se derivan automáticamente del nombre del evento (strip `Event` → SCREAMING_SNAKE_CASE)
 
 ---
 
-**Última actualización:** 2026-03-12  
-**Versión de eva4j:** 1.0.14  
+**Última actualización:** 2026-03-24  
+**Versión de eva4j:** 1.0.15  
 **Estado:** Documento de referencia para agentes IA

package/DOMAIN_YAML_GUIDE.md

@@ -139,6 +139,9 @@ aggregates:
       # Eventos de dominio que emite este agregado (dentro del agregado)
       - name: NombreEventoOcurrido
         fields: []
+        # Opciones mutuamente excluyentes para emisión automática:
+        # triggers: [methodName]    # Emite raise() dentro de un método de transición
+        # lifecycle: create         # Emite raise() en operación CRUD (create|update|delete|softDelete)
 
 # listeners: — eventos externos que CONSUME este módulo (nivel raíz)
 listeners:
@@ -147,6 +150,18 @@ listeners:
     topic: TOPIC_NAME              # Topic Kafka (obligatorio en módulos standalone)
     useCase: HandleExternalEvent   # Caso de uso que maneja el evento
     fields: []                     # Payload del Integration Event recibido
+
+# readModels: — proyecciones locales de datos de otro módulo (nivel raíz)
+readModels:
+  - name: ProductReadModel         # PascalCase + sufijo ReadModel
+    source:
+      module: products             # Módulo fuente
+      aggregate: Product           # Agregado fuente
+    tableName: rm_products         # Tabla SQL (prefijo rm_)
+    fields: []                     # Campos proyectados
+    syncedBy:                      # Eventos que sincronizan la tabla
+      - event: ProductCreatedEvent
+        action: UPSERT             # UPSERT | DELETE | SOFT_DELETE
 ```
 
 ### Ubicación del archivo
@@ -1711,13 +1726,62 @@ aggregates:
 |-----------|------|-------------|-------------|
 | `name` | String | ✅ | Nombre de la clase del evento (PascalCase) |
 | `fields` | Array | ✅ | Campos que transporta el evento |
-| `triggers` | Array\<String\> | ➖ | Nombres de métodos de transición que publican este evento. El generador emite `raise(new XEvent(...))` automáticamente. |
+| `triggers` | Array\<String\> | ➖ | Nombres de métodos de transición que publican este evento. El generador emite `raise(new XEvent(...))` automáticamente. Mutuamente excluyente con `lifecycle`. |
+| `lifecycle` | String | ➖ | Operación CRUD que publica este evento: `create`, `update`, `delete`, `softDelete`. Mutuamente excluyente con `triggers`. |
 | `topic` | String | ➖ | **Override del topic Kafka.** Por defecto el generador quita el sufijo `Event` del nombre de la clase: `ProductPublishedEvent` → `PRODUCT_PUBLISHED`. Úsalo cuando el consumer en `listeners[]` de otro módulo declara un topic diferente al auto-derivado. |
 
 > **Regla de derivación de topic:** `ProductPublishedEvent` → quita `Event` → `ProductPublished` → SCREAMING_SNAKE → `PRODUCT_PUBLISHED`. Esto garantiza que el producer y el consumer coincidan cuando el consumer declara `topic: PRODUCT_PUBLISHED` en `listeners[]`.
 
 > **`kafka: true`** ya no es necesario — si el proyecto tiene `kafka-client` instalado, todos los eventos se cablearán automáticamente al ejecutar `eva g entities`.
 
+### Ejemplo con `lifecycle:`
+
+```yaml
+events:
+  - name: ProductCreatedEvent
+    lifecycle: create              # raise() en el constructor de creación
+    fields:
+      - name: productId
+        type: String
+      - name: name
+        type: String
+
+  - name: ProductUpdatedEvent
+    lifecycle: update              # raise() en UpdateCommandHandler antes de save()
+    fields:
+      - name: productId
+        type: String
+      - name: name
+        type: String
+
+  - name: ProductDeletedEvent
+    lifecycle: delete              # raise() en DeleteCommandHandler; requiere !hasSoftDelete
+    fields:
+      - name: productId
+        type: String
+      - name: deletedAt
+        type: LocalDateTime
+
+  - name: ProductDeactivatedEvent
+    lifecycle: softDelete          # raise() en softDelete(); requiere hasSoftDelete: true
+    fields:
+      - name: productId
+        type: String
+      - name: deletedAt
+        type: LocalDateTime
+```
+
+**Puntos de emisión:**
+
+| `lifecycle` | Punto de emisión | UUID auto-gen | `raise()` visibility |
+|---|---|---|---|
+| `create` | Constructor de creación | ✅ `this.id = UUID.randomUUID().toString()` | `protected` |
+| `update` | `UpdateCommandHandler`, antes de `repository.save()` | — | `public` |
+| `delete` | `DeleteCommandHandler`, antes de `repository.delete()` | — | `public` |
+| `softDelete` | Método `softDelete()` de la entidad | — | `protected` |
+
+> **Validaciones:** `C2-008` (error) si el valor de lifecycle no es válido. `C2-009` (warning) si `lifecycle: softDelete` sin `hasSoftDelete: true`, o `lifecycle: delete` con `hasSoftDelete: true`. `C2-010` (error) si un campo del lifecycle event no existe en la entidad raíz del agregado.
+
 ### Archivos generados
 
 Para cada evento, eva4j genera dos archivos:
@@ -1946,7 +2010,9 @@ domain.yaml
 │
 ├── listeners:           → Integration Events que CONSUME (infrastructure/kafkaListener/)
 │
-└── ports:               → Servicios HTTP que LLAMA    (infrastructure/adapters/{service}/)
+├── ports:               → Servicios HTTP que LLAMA    (infrastructure/adapters/{service}/)
+│
+└── readModels:          → Proyecciones locales mantenidas por eventos (infrastructure/kafkaListener/)
 ```
 
 ---
@@ -2082,6 +2148,123 @@ Ver ejemplo completo en [`examples/domain-ports.yaml`](examples/domain-ports.yam
 
 ---
 
+## Sección readModels
+
+`readModels:` es una sección de nivel raíz (sibling de `aggregates:`, `listeners:` y `ports:`) que declara **proyecciones locales de datos de otro bounded context**, mantenidas mediante eventos de dominio. Elimina dependencias síncronas (HTTP) entre módulos.
+
+### Estructura completa
+
+```yaml
+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_products               # Tabla en BD (OBLIGATORIO, prefijo rm_)
+    fields:                              # Campos proyectados (OBLIGATORIO, debe incluir id)
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+      - name: status
+        type: String
+    syncedBy:                            # Eventos que mantienen la tabla (OBLIGATORIO, min 1)
+      - event: ProductCreatedEvent       # Nombre del evento (PascalCase)
+        action: UPSERT                   # UPSERT | DELETE | SOFT_DELETE
+      - event: ProductUpdatedEvent
+        action: UPSERT
+      - event: ProductDeactivatedEvent
+        action: SOFT_DELETE
+```
+
+### Propiedades
+
+| Propiedad | Tipo | Obligatorio | Descripción |
+|---|---|---|---|
+| `name` | String | SÍ | Nombre del read model. **DEBE** terminar con `ReadModel`. PascalCase. |
+| `source` | Object | SÍ | Trazabilidad al módulo y agregado fuente. |
+| `source.module` | String | SÍ | Módulo que posee los datos. Kebab-case. |
+| `source.aggregate` | String | SÍ | Agregado fuente. PascalCase. |
+| `tableName` | String | SÍ | Nombre de tabla SQL. **DEBE** empezar con `rm_`. |
+| `fields` | Array | SÍ | Campos a proyectar. Debe incluir `id`. |
+| `syncedBy` | Array | SÍ | Eventos que sincronizan esta tabla. Mínimo 1. |
+| `syncedBy[].event` | String | SÍ | Nombre del evento. PascalCase. |
+| `syncedBy[].action` | String | SÍ | Uno de: `UPSERT`, `DELETE`, `SOFT_DELETE`. |
+| `syncedBy[].topic` | String | NO | Override del topic Kafka. Por defecto se auto-deriva del nombre del evento. |
+
+### Acciones de sincronización
+
+| Acción | Significado | Cuándo usarla |
+|---|---|---|
+| `UPSERT` | Insertar si no existe, actualizar si existe | Creaciones, actualizaciones, cambios de estado |
+| `DELETE` | Eliminar permanentemente | Hard deletes en el módulo fuente |
+| `SOFT_DELETE` | Marcar como inactivo con timestamp | Cuando el fuente usa soft delete |
+
+### Derivación automática de topics
+
+El topic se deriva del nombre del evento: se elimina el sufijo `Event` y se convierte a SCREAMING_SNAKE_CASE:
+
+- `ProductCreatedEvent` → `PRODUCT_CREATED`
+- `CustomerUpdatedEvent` → `CUSTOMER_UPDATED`
+- `OrderCancelled` → `ORDER_CANCELLED`
+
+Para sobrescribir, usar `topic:` explícito en la entrada de `syncedBy`.
+
+### Artefactos generados
+
+**Por cada read model (6 archivos):**
+
+| Archivo | Descripción |
+|---|---|
+| `domain/models/readmodels/{Name}.java` | Clase de dominio inmutable (sin setters, sin auditoría) |
+| `infrastructure/database/entities/{Name}Jpa.java` | Entidad JPA con Lombok. `@Id` no auto-generado |
+| `infrastructure/database/repositories/{Name}JpaRepository.java` | Spring Data JPA interface |
+| `domain/repositories/{Name}Repository.java` | Interfaz de repositorio (puerto) |
+| `infrastructure/database/repositories/{Name}RepositoryImpl.java` | Implementación del repositorio |
+| `application/usecases/Sync{Source}ReadModelHandler.java` | Handler con un método por evento |
+
+**Por cada entrada en `syncedBy` (hasta 3 archivos):**
+
+| Archivo | Descripción |
+|---|---|
+| `application/events/{EventBase}IntegrationEvent.java` | Integration Event (reutilizado si ya existe) |
+| `infrastructure/kafkaListener/{EventBase}ReadModelListener.java` | Kafka listener que delega al sync handler |
+| `parameters/*/kafka.yaml` | Registro del topic |
+
+### Validaciones
+
+| Código | Severidad | Regla |
+|---|---|---|
+| RM-001 | ERROR | `name` debe terminar con `ReadModel` |
+| RM-002 | ERROR | `tableName` debe empezar con `rm_` |
+| RM-004 | ERROR | `fields` debe incluir un campo `id` |
+| RM-005 | ERROR | `syncedBy` debe tener al menos una entrada |
+| RM-006 | ERROR | `syncedBy[].action` debe ser `UPSERT`, `DELETE` o `SOFT_DELETE` |
+| RM-008 / C1-007 | WARNING | Campo del readModel no cubierto por ningún evento UPSERT del productor — siempre será null |
+| RM-009 | WARNING | `ports:` tiene llamadas sync al mismo `source.module` — considerar eliminarlas |
+| RM-010 | ERROR | `source.module` es el mismo módulo actual |
+
+### Diferencias con agregados
+
+| Característica | Aggregate | Read Model |
+|---|---|---|
+| Sección YAML | `aggregates:` | `readModels:` |
+| Prefijo de tabla | Ninguno | `rm_` |
+| Lógica de negocio | Sí | No |
+| Emite eventos | Sí | Nunca |
+| Endpoints REST | Opcional | Nunca |
+| Clase de dominio | Entidad rica | Clase inmutable |
+| Campos de auditoría | Opcionales | Nunca |
+| `source:` requerido | No | Sí |
+
+### Referencia
+
+Ver ejemplo completo en [`examples/domain-read-models.yaml`](examples/domain-read-models.yaml).
+
+---
+
 ## Relaciones
 
 eva4j soporta relaciones JPA bidireccionales completas con generación automática del lado inverso.
@@ -2154,7 +2337,7 @@ public void removeOrderItem(OrderItem orderItem) {
 
 **Genera en JPA:**
 ```java
-@OneToMany(mappedBy = "order", cascade = {CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REMOVE}, fetch = FetchType.LAZY)
+@OneToMany(mappedBy = "order", cascade = {CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REMOVE}, orphanRemoval = true, fetch = FetchType.LAZY)
 @Builder.Default
 private List<OrderItemJpa> orderItems = new ArrayList<>();
 ```
@@ -2382,6 +2565,8 @@ relationships:
 | `DETACH` | Al separar el padre, separa los hijos | ⚠️ Rara vez necesario |
 | `ALL` | Todas las operaciones anteriores | ⚠️ Solo si estás seguro |
 
+> **Nota:** eva4j genera automáticamente `orphanRemoval = true` en todas las relaciones `@OneToMany` y `@OneToOne(mappedBy)`. Esto asegura que al remover un hijo de la colección del padre, JPA elimina la fila de la base de datos. Es el comportamiento correcto en DDD: las entidades secundarias del agregado no tienen existencia independiente — su ciclo de vida lo controla la raíz.
+
 #### **Configuraciones Recomendadas:**
 
 ```yaml

package/FUTURE_FEATURES.md

@@ -459,66 +459,47 @@ public ResponseEntity<ErrorDto> handleOptimisticLock(ObjectOptimisticLockingFail
 
 ---
 
-## 6. Read Models Separados (Proyecciones)
+## 6. Read Models Separados (Proyecciones) ✅
+
+> **Implementado en v1.0.15** — Sección `readModels:` en `domain.yaml` con generación automática de proyecciones locales mantenidas por eventos Kafka. Ver [`DOMAIN_YAML_GUIDE.md`](DOMAIN_YAML_GUIDE.md#sección-readmodels) y [`read-model-spec.md`](read-model-spec.md).
 
 ### Descripción
 
-En CQRS puro, el lado de lectura puede tener su propio modelo optimizado para consultas, independiente del modelo de escritura. Los `*ResponseDto` actuales son transformaciones directas del dominio, suficiente para casos simples pero insuficientes para reportes o vistas que joinean múltiples agregados.
+Proyecciones locales de datos de otro bounded context, mantenidas mediante eventos de dominio. Elimina dependencias síncronas (HTTP) entre módulos.
 
-### Sintaxis Propuesta
+### Sintaxis Implementada
 
 ```yaml
-aggregates:
-  - name: Order
-    readModels:
-      - name: OrderSummary
-        description: "Vista desnormalizada para listados"
-        fields:
-          - name: id
-            type: String
-          - name: orderNumber
-            type: String
-          - name: customerName
-            type: String
-          - name: totalAmount
-            type: BigDecimal
-          - name: itemCount
-            type: Integer
-          - name: status
-            type: OrderStatus
-        source: native_query
+readModels:
+  - name: ProductReadModel
+    source:
+      module: products
+      aggregate: Product
+    tableName: rm_products
+    fields:
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+    syncedBy:
+      - event: ProductCreatedEvent
+        action: UPSERT
+      - event: ProductUpdatedEvent
+        action: UPSERT
+      - event: ProductDeactivatedEvent
+        action: SOFT_DELETE
 ```
 
-### Código Generado
+### Artefactos Generados
 
-```java
-public interface OrderSummaryProjection {
-    String getId();
-    String getOrderNumber();
-    String getCustomerName();
-    BigDecimal getTotalAmount();
-    Integer getItemCount();
-    OrderStatus getStatus();
-}
-```
-
-```java
-@Query(value = """
-    SELECT
-        o.id,
-        o.order_number     AS orderNumber,
-        c.name             AS customerName,
-        o.total_amount     AS totalAmount,
-        COUNT(i.id)        AS itemCount,
-        o.status
-    FROM orders o
-    JOIN customers c ON c.id = o.customer_id
-    LEFT JOIN order_items i ON i.order_id = o.id
-    WHERE o.deleted = false
-    GROUP BY o.id, c.name
-    """, nativeQuery = true)
-Page<OrderSummaryProjection> findOrderSummaries(Pageable pageable);
-```
+- Clase de dominio inmutable (`domain/models/readmodels/`)
+- Entidad JPA sin auditoría (`infrastructure/database/entities/`)
+- Repositorio (interfaz + impl)
+- Sync handler con un método por evento
+- Kafka listeners (uno por entry en `syncedBy`)
+- Integration Events (reutilizados si ya existen)
 
 ---
 
@@ -1607,7 +1588,7 @@ Sin DataFaker, el seeder genera datos con patrones simples (`"User 0"`, `"user0@
 | 3 | Soft Delete Completo | Alta | Baja | ✅ Implementado |
 | 4 | Paginación en Queries | Impl. | -- | ✅ Implementado |
 | 5 | Optimistic Locking | Media | Baja | Pendiente |
-| 6 | Read Models / Proyecciones | Media | Alta | Pendiente |
+| 6 | Read Models / Proyecciones | Media | Alta | ✅ Implementado |
 | 7 | Enums con Transiciones | Impl. | -- | ✅ Implementado |
 | 8 | Specifications Pattern | Media | Media | Pendiente |
 | 9 | JSON Schema para domain.yaml | Tooling | Media | Pendiente |

package/QUICK_REFERENCE.md

@@ -120,13 +120,17 @@ eva detach order
 
 ## 🧩 Temporal Queue Model
 
+Queues are **module-scoped** — each module gets its own set of queues prefixed with the module name in SCREAMING_SNAKE_CASE:
+
 | Queue | Purpose | ActivityOptions var |
 |-------|---------|---------------------|
-| `FLOW_QUEUE` | Workflow orchestration | — |
-| `LIGHT_TASK_QUEUE` | Fast activities < 30 s | `lightActivityOptions` |
-| `HEAVY_TASK_QUEUE` | Long-running ≤ 2 min | `heavyActivityOptions` |
+| `{MODULE}_WORKFLOW_QUEUE` | Workflow orchestration | — |
+| `{MODULE}_LIGHT_TASK_QUEUE` | Fast activities < 30 s | `lightActivityOptions` |
+| `{MODULE}_HEAVY_TASK_QUEUE` | Long-running ≤ 2 min | `heavyActivityOptions` |
+
+Example for module `order`: `ORDER_WORKFLOW_QUEUE`, `ORDER_LIGHT_TASK_QUEUE`, `ORDER_HEAVY_TASK_QUEUE`.
 
-Activities are registered automatically via Spring DI (`LightActivity` / `HeavyActivity` marker interfaces). No manual `TemporalConfig.java` patching needed.
+Activities are registered automatically via Spring DI (`{Module}LightActivity` / `{Module}HeavyActivity` marker interfaces). Each module has its own `{Module}TemporalWorkerConfig.java` — no shared `TemporalConfig.java` patching needed.
 
 ---