eva4j 1.0.14 → 1.0.15

package/AGENTS.md

@@ -464,6 +464,10 @@ aggregates:
 
 El `domain.yaml` también soporta una sección `endpoints:` opcional (sibling de `aggregates:`) para declarar los endpoints REST. Ver sección [⚡ Características Avanzadas](#-características-avanzadas-del-domainyaml) para detalles.
 
+El `domain.yaml` también soporta una sección `listeners:` opcional (sibling de `aggregates:`) para declarar los eventos externos que **consume** este módulo. Ver sección [⚡ Características Avanzadas](#-características-avanzadas-del-domainyaml) para detalles.
+
+El `domain.yaml` también soporta una sección `ports:` opcional (sibling de `aggregates:`) para declarar los servicios HTTP síncronos que **llama** este módulo. Ver sección [⚡ Características Avanzadas](#-características-avanzadas-del-domainyaml) para detalles.
+
 ---
 
 ## ⚡ Características Avanzadas del domain.yaml
@@ -526,16 +530,98 @@ Genera automáticamente **en el enum**: `VALID_TRANSITIONS`, `canTransitionTo()`
 aggregates:
   - name: Order
     entities: [...]
+    enums:
+      - name: OrderStatus
+        transitions:
+          - from: DRAFT
+            to: PLACED
+            method: place
+          - from: PLACED
+            to: CANCELLED
+            method: cancel
     events:
-      - name: OrderConfirmed
+      - name: OrderPlaced
+        topic: ORDER_PLACED       # opcional: sobreescribe el topic auto-derivado
+        triggers:
+          - place         # ← conecta la transición con este evento
         fields:
           - name: orderId
             type: String
           - name: confirmedAt
             type: LocalDateTime
+
+      - name: OrderCancelled
+        triggers:
+          - cancel
+        fields:
+          - name: reason   # campo no resuelto → null /* TODO: provide reason */
+            type: String
+```
+
+#### Propiedad `topic` (opcional)
+
+Sobreescribe el nombre del topic Kafka auto-derivado para este evento.
+
+**Regla de derivación por defecto:** el generador quita el sufijo `Event` del nombre de la clase antes de convertir a SCREAMING_SNAKE_CASE:
+- `ProductPublishedEvent` → `PRODUCT_PUBLISHED` ✓ (no `PRODUCT_PUBLISHED_EVENT`)
+- `OrderCancelled` → `ORDER_CANCELLED` (sin sufijo, sin cambios)
+
+**Cuándo usar `topic:` explícito:**
+- El producer y el consumer de otro módulo deben usar exactamente el mismo nombre.
+- Si el consumer en `listeners[]` declara `topic: MY_CUSTOM_TOPIC`, declara el mismo valor aquí para que el match sea garantizado.
+
+```yaml
+events:
+  - name: ProductPublishedEvent
+    # topic auto-derivado: PRODUCT_PUBLISHED (sufijo 'Event' eliminado)
+    triggers: [publish]
+    fields: [...]
+
+  - name: OrderReadyEvent
+    topic: ORDER_READY_FOR_PICKUP   # override explícito
+    triggers: [markReady]
+    fields: [...]
 ```
 
-Genera `OrderConfirmed.java` (en `domain/models/events/`) que extiende `DomainEvent`, y `OrderDomainEventHandler.java` (en `application/usecases/`) con `@TransactionalEventListener(AFTER_COMMIT)`.
+> **Nota:** el flag `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`.
+
+#### Propiedad `triggers`
+
+Lista de nombres de métodos de transición que publican este evento. El generador emite automáticamente `raise(new XEvent(...))` dentro de cada método listado.
+
+**Reglas de resolución de argumentos (en orden):**
+
+| Condición del campo del evento | Argumento generado |
+|---|---|
+| Siempre (primer arg, aggregateId del DomainEvent base) | `this.getId()` |
+| Nombre = `{entityName}Id` (ej: `orderId` en `Order`) | **Ignorado** en el Domain Event class — mapeado a `event.getAggregateId()` en el Integration Event |
+| Nombre coincide con un campo de la entidad | `this.get{Field}()` |
+| Nombre termina en `At` + tipo `LocalDateTime` | `LocalDateTime.now()` |
+| No resuelto | `null /* TODO: provide {fieldName} */` |
+
+> **Convención:** Sí declarar `{entityName}Id` en `events[].fields` cuando el evento **cruza módulos via Kafka** — es necesario para que el id viaje en el payload del Integration Event. El generador lo mapea automáticamente a `event.getAggregateId()` en el handler, evitando la duplicación en el Domain Event class interno.
+
+**Resultado generado:**
+
+```java
+public void place() {
+    this.status = this.status.transitionTo(OrderStatus.PLACED);
+    raise(new OrderPlaced(this.getId(), this.getId(), LocalDateTime.now()));
+    //                    ^—aggregateId  ^—orderId     ^—confirmedAt
+}
+
+public void cancel() {
+    this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+    raise(new OrderCancelled(this.getId(), null /* TODO: provide reason */));
+}
+```
+
+Si un evento **no declara `triggers`**, 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-005** (info): transición sin ningún evento asociado — considera declarar `triggers`
+- **C2-001** se silencia automáticamente para transiciones que ya tienen `triggers`
 
 **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:
 
@@ -572,9 +658,170 @@ 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.
 
+### Consumo de Eventos Externos (`listeners[]`)
+
+```yaml
+# Nivel raíz, sibling de aggregates:
+listeners:
+  - event: PaymentApprovedEvent    # PascalCase + sufijo Event
+    producer: payments             # Módulo que lo produce (referencia documental)
+    topic: PAYMENT_APPROVED        # Topic Kafka — obligatorio en módulos standalone
+    useCase: ConfirmOrder          # Caso de uso que maneja el evento (PascalCase)
+    fields:                        # Campos del payload recibido
+      - name: orderId
+        type: String
+      - name: approvedAt
+        type: LocalDateTime
+      - name: details              # Tipo complejo → declarar en nestedTypes
+        type: PaymentDetails
+    nestedTypes:                   # Records auxiliares para campos de tipo objeto
+      - name: paymentDetails       # camelCase → normalizado a PaymentDetails
+        fields:
+          - name: paymentId
+            type: String
+          - name: method
+            type: String
+          - name: amount
+            type: BigDecimal
+```
+
+Genera por cada entrada (hasta **6 artefactos**):
+
+| Archivo generado | Descripción |
+|---|---|
+| `application/events/PaymentDetails.java` | Record auxiliar (uno por `nestedTypes` entry) |
+| `application/events/PaymentApprovedIntegrationEvent.java` | Record tipado con los `fields` declarados |
+| `infrastructure/kafkaListener/PaymentApprovedKafkaListener.java` | `@KafkaListener` → deserializa y despacha al `useCase` |
+| `parameters/*/kafka.yaml` | Registro del topic en `topics:` |
+| `application/commands/ConfirmOrderCommand.java` | Command tipado para el `useCase` |
+| `application/usecases/ConfirmOrderCommandHandler.java` | Handler stub — implementar la lógica de negocio aquí |
+
+**Deserialización:** el listener usa `EventEnvelope<Map<String,Object>>` + `objectMapper.convertValue()` para deserializar cada campo del payload de forma robusta y tipada.
+
+**Regla de `topic:`:**
+- Módulo standalone (sin `system.yaml`) → `topic:` **obligatorio**
+- Proyecto con `system.yaml` → puede omitirse; el generador lo infiere de `integrations.async[].topic`
+- Declarado explícitamente → tiene **precedencia** sobre la inferencia
+
+**`nestedTypes:` — cuándo usarlo:**  
+Declara un `nestedType` cuando un campo del payload es un **objeto anidado** (no un escalar). El generador produce un record en el mismo paquete `application/events/`, que tanto la `IntegrationEvent` como el `Command` y el `KafkaListener` usan directamente.
+
+**Colisión de nombres entre módulos:** cuando varios módulos consumen el mismo evento Kafka, el generador produce clases listener con el mismo nombre (ej: `PaymentApprovedKafkaListener` en `orders` y en `notifications`). Esto es seguro porque el generador usa `@Component("<moduleName>.<listenerClassName>")` para calificar el bean y evitar `ConflictingBeanDefinitionException`. **No se requiere acción del agente** — a diferencia de `ports[]`, donde el nombre de `service:` debe ser único por módulo.
+
+**Contraste eventos producidos vs. consumidos:**
+```
+aggregates:
+  └── events:     → Domain Events que PRODUCE (domain/models/events/)
+
+listeners:          → Integration Events que CONSUME (infrastructure/kafkaListener/)
+```
+
 ---
 
-## �️ Soft Delete
+### Clientes HTTP Síncronos (`ports[]`)
+
+```yaml
+# Nivel raíz, sibling de aggregates: y listeners:
+# Un método = una entrada; entries del mismo service: forman un solo FeignClient.
+
+ports:
+  - name: findScreeningById            # nombre del método (camelCase)
+    service: ScreeningService          # agrupa en una interfaz/FeignClient (PascalCase)
+    target: screenings                 # módulo destino (referencia documental)
+    baseUrl: http://localhost:8081     # → parameters/*/urls.yaml (primera entrada del service)
+    http: GET /screenings/{id}         # verbo + path (igual que en system.yaml exposes:)
+    fields:                            # campos de respuesta → {MethodPascal}ResponseDto.java
+      - name: id
+        type: String
+      - name: startTime
+        type: LocalDateTime
+
+  - name: findAvailableSeats
+    service: ScreeningService          # mismo service → mismo FeignClient
+    target: screenings
+    http: GET /screenings/{id}/seats
+    returnList: true                   # → List<FindAvailableSeatResponseDto>
+    fields:
+      - name: seatId
+        type: String
+      - name: seatType
+        type: String
+
+  - name: processPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    baseUrl: https://api.payments.example.com
+    http: POST /payments
+    body:                              # @RequestBody → ProcessPaymentRequestDto.java
+      - name: amount
+        type: BigDecimal
+      - name: paymentMethod
+        type: PaymentMethodInput       # tipo objeto → declarar en nestedTypes:
+    nestedTypes:
+      - name: paymentMethodInput
+        fields:
+          - name: type
+            type: String
+          - name: cardToken
+            type: String
+    fields:                            # respuesta → ProcessPaymentResponseDto.java
+      - name: paymentId
+        type: String
+      - name: status
+        type: String
+
+  - name: cancelPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    http: DELETE /payments/{id}
+    # fields: omitido → retorno void
+```
+
+### Artefactos generados por `ports[]`
+
+Por cada `service:` único:
+
+| Archivo generado | Descripción |
+|---|---|
+| `domain/repositories/{ServiceName}.java` | Interfaz del puerto secundario (devuelve modelos de dominio) |
+| `infrastructure/adapters/{service}/{ServiceName}FeignClient.java` | Cliente Feign tipado (devuelve DTOs infra) |
+| `infrastructure/adapters/{service}/{ServiceName}FeignAdapter.java` | `@Component implements {ServiceName}` — actúa como ACL |
+| `infrastructure/adapters/{service}/{ServiceName}FeignConfig.java` | Timeouts Feign |
+| `parameters/*/urls.yaml` | Base URL parametrizada |
+
+Por cada modelo de dominio único derivado de los métodos con `fields:`:
+
+| Archivo generado | Descripción |
+|---|---|
+| `domain/models/{service}/{DomainType}.java` | Modelo de dominio (ACL) — abstracción interna |
+
+Por cada método:
+
+| Archivo generado | Condición |
+|---|---|
+| `infrastructure/adapters/{service}/{MethodPascal}Dto.java` | Cuando `fields:` presente — DTO infra (forma externa) |
+| `application/dtos/{MethodPascal}RequestDto.java` | Cuando `body:` presente (POST/PUT/PATCH) |
+| `application/dtos/{NestedTypePascal}.java` | Cuando `nestedTypes:` declarado |
+
+**Patrón ACL:** Los DTOs de infraestructura (forma de la API externa) viven en `infrastructure/adapters/{service}/`. Los modelos de dominio (abstracción interna) viven en `domain/models/{service}/`. El `FeignAdapter` mapea `InfraDto → DomainModel` inline con métodos privados `to{DomainType}()`. Si la API externa cambia, solo hay que actualizar el adaptador.
+
+### Reglas de `ports[]`
+
+- **`service:`** — PascalCase, agrupa métodos en un mismo FeignClient. **Si varios módulos llaman al mismo servicio externo, cada módulo debe usar un nombre de `service:` propio que refleje su bounded context** (ej: `OrderCustomerService` en `orders`, `DeliveryCustomerService` en `deliveries`). Reutilizar el mismo nombre (`CustomerService`) en módulos distintos causa colisión de beans Spring (`ConflictingBeanDefinitionException`) porque el generador produce un `FeignAdapter` con el mismo nombre de clase en cada módulo
+- **`baseUrl:`** — declarar solo en la primera entrada de cada `service:`; si se omite en todas → warning + `http://localhost:8080`
+- **`body:`** — solo en POST/PUT/PATCH; en GET/DELETE emite warning y se ignora
+- **`domainType:`** — sobrescribe el tipo de dominio auto-derivado del nombre del método (ej: `domainType: Seat` en `findAvailableSeats`)
+- **`returnList: true`** — el tipo de retorno es `List<{DomainType}>` en la interfaz y `List<{InfraDto}>` en el FeignClient (default: `false`)
+- **`nestedTypes:`** — records auxiliares en `application/dtos/`; mismo patrón que `listeners:`
+- **`fields:` omitido** → retorno `void` en interfaz y FeignClient
+
+**Contraste async vs sync:**
+```
+aggregates:
+  └── events:     → Domain Events que PRODUCE  (async, broker)
+listeners:          → Integration Events que CONSUME (async, broker)
+ports:              → Servicios HTTP que LLAMA    (sync, Feign)
+```
 
 Cuando una entidad tiene `hasSoftDelete: true`, eva4j genera eliminación lógica en lugar de física.
 
@@ -627,6 +874,8 @@ public class Product {
 
 ### Reglas para Agentes
 
+- **SOLO** aplicar `hasSoftDelete: true` en la **entidad raíz** del agregado (`isRoot: true`)
+- **NUNCA** poner `hasSoftDelete: true` en entidades secundarias — el ciclo de vida de estas lo controla la raíz mediante `cascade`; si se ignora, el generador emite un warning y descarta el flag
 - **NUNCA** usar `repository.deleteById()` cuando hay soft delete
 - **SIEMPRE** usar `entity.softDelete()` + `repository.save(entity)`
 - **NUNCA** exponer `deletedAt` en ResponseDtos
@@ -993,7 +1242,7 @@ private String customerId;
 1. **SIEMPRE** declarar `endpoints:` cuando el API REST tiene comportamientos custom (confirmar, cancelar, activar, etc.)
 2. **NUNCA** usar `endpoints:` si solo necesitas CRUD estándar — el flujo interactivo es más simple
 3. **SIEMPRE** usar PascalCase para los nombres de `useCase` (ej: `ConfirmOrder`, no `confirmOrder`)
-4. **CONOCER** cuáles son los 5 use cases estándar por aggregate: `Create{E}`, `Update{E}`, `Delete{E}`, `Get{E}`, `FindAll{E}s` — estos generan implementación completa
+4. **CONOCER** cuáles son los 5 use cases estándar por aggregate: `Create{E}`, `Update{E}`, `Delete{E}`, `Get{E}`, `FindAll{Plural(E)}` — estos generan implementación completa (e.g. `FindAllOrders`, `FindAllDeliveries`, `FindAllCategories`)
 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`)
@@ -1228,12 +1477,25 @@ Al generar o modificar código, verificar:
 - [ ] Enum con ciclo de vida → usar `transitions` + `initialValue`, no setters manuales
 - [ ] 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 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
+- [ ] Cada `listener` genera hasta 6 artefactos: NestedType(s) → IntegrationEvent → KafkaListener → kafka.yaml → Command → CommandHandler
+- [ ] Varios módulos pueden consumir el mismo evento Kafka sin colisión — el generador califica el bean automáticamente con `@Component("moduleName.listenerClassName")`
+- [ ] Campos de tipo objeto en listeners → declarar `nestedTypes:` para generar records auxiliares en `application/events/`
 - [ ] Endpoints REST específicos → declarar `endpoints:` con versiones y operaciones; usar nombres estándar para implementación completa
+- [ ] Clientes HTTP síncronos → declarar en `ports[]` (nivel raíz); `baseUrl:` en la primera entrada de cada `service:`
+- [ ] Si varios módulos llaman al mismo servicio → cada uno usa un `service:` con nombre propio del bounded context (ej: `OrderCustomerService`, `DeliveryCustomerService`) — nunca el mismo nombre genérico en módulos distintos
+- [ ] Métodos con respuesta → incluir `fields:` en la entrada del puerto; sin `fields:` = retorno `void`
+- [ ] Respuestas en lista → agregar `returnList: true` en el método correspondiente
+- [ ] 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`
 
 ---
 
-**Última actualización:** 2026-03-11  
-**Versión de eva4j:** 1.0.13  
+**Última actualización:** 2026-03-12  
+**Versión de eva4j:** 1.0.14  
 **Estado:** Documento de referencia para agentes IA

package/COMMAND_EVALUATION.md

@@ -412,20 +412,20 @@ aggregates:
 
 ---
 
-### 4. Soft Delete (0% implementado)
+### 4. Soft Delete ✅ Implementado
 
 **Impacto**: Medio - Común en apps business
 
-#### Casos de Uso No Cubiertos
+#### Sintaxis
 ```yaml
-# ❌ No soportado actualmente
-rootEntity:
-  name: order
-  softDelete: true  # Debería agregar deletedAt y lógica
+# ✅ Soportado — solo en la entidad raíz (isRoot: true)
+entities:
+  - name: order
+    isRoot: true
+    hasSoftDelete: true  # Genera deletedAt, softDelete(), @SQLRestriction
 ```
 
-**Esfuerzo para implementar**: Medio (4-5 horas)  
-**Prioridad**: 🟡 Media
+**Estado**: Implementado en `yaml-to-entity.js` + templates `AggregateRoot`, `JpaAggregateRoot`, repositorios y `DeleteCommandHandler`.
 
 ---
 
@@ -558,7 +558,7 @@ aggregates:
 
 1. ❌ **Validaciones JSR-303** (0%)
 2. ❌ **Auditoría (createdAt, updatedAt)** (0%)
-3. ❌ **Soft delete** (0%)
+3. ✅ **Soft delete** (implementado con `hasSoftDelete: true`)
 4. ❌ **Índices y constraints** (0%)
 5. ❌ **Herencia de entidades** (0%)
 6. ❌ **DTOs de aplicación** (0%)
@@ -598,7 +598,7 @@ aggregates:
 
 | # | Mejora | Impacto | Esfuerzo | Prioridad |
 |---|--------|---------|----------|-----------|
-| 5 | Soft delete | 🟡 Medio | 5h | 🟡 Media |
+| 5 | ~~Soft delete~~ | ✅ Implementado | — | — |
 | 6 | ManyToMany completo | 🟡 Medio | 6h | 🟡 Media |
 | 7 | OneToOne avanzado | 🟡 Bajo | 4h | 🔵 Baja |
 
@@ -640,9 +640,7 @@ aggregates:
 
 ### Mediano Plazo
 
-4. **Soft Delete**
-   - Útil para muchas apps
-   - Buena relación esfuerzo/beneficio
+4. ~~**Soft Delete**~~ ✅ Implementado con `hasSoftDelete: true`
 
 5. **ManyToMany completo**
    - Completa el soporte de relaciones JPA
@@ -794,15 +792,16 @@ entities:
 
 ---
 
-### 4. Soft Delete
+### 4. Soft Delete ✅ Implementado
 
 ```yaml
 entities:
   - name: Order
-    softDelete: true  # Agrega deletedAt y lógica
+    isRoot: true
+    hasSoftDelete: true  # Genera deletedAt, softDelete(), isDeleted(), @SQLRestriction
 ```
 
-**Implementación**: Campo `deletedAt` + custom queries en repositorio.
+**Implementado**: `deletedAt` inyectado automáticamente, `@SQLRestriction("deleted_at IS NULL")` en JPA, `softDelete()` + `isDeleted()` en dominio, `DeleteCommandHandler` usa borrado lógico.
 
 ---