eva4j 1.0.13 → 1.0.15

package/templates/aggregate/DomainEventSnapshot.java.ejs

@@ -0,0 +1,46 @@
+package <%= packageName %>.<%= moduleName %>.domain.models.events;
+<%
+  const needsBigDecimal = fields && fields.some(f => f.javaType === 'BigDecimal');
+  const needsLocalDate  = fields && fields.some(f => ['LocalDate','LocalDateTime','LocalTime'].includes(f.javaType));
+  const needsInstant    = fields && fields.some(f => f.javaType === 'Instant');
+  const needsUUID       = fields && fields.some(f => f.javaType === 'UUID');
+  const needsList       = fields && fields.some(f => f.javaType && f.javaType.startsWith('List'));
+%>
+<% if (needsBigDecimal) { %>
+import java.math.BigDecimal;
+<% } %>
+<% if (needsLocalDate) { %>
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+<% } %>
+<% if (needsInstant) { %>
+import java.time.Instant;
+<% } %>
+<% if (needsUUID) { %>
+import java.util.UUID;
+<% } %>
+<% if (needsList) { %>
+import java.util.List;
+<% } %>
+
+/**
+ * <%= name %> — snapshot value type carried in domain events.
+ *
+ * This is a pure domain record with no infrastructure dependencies.
+ * TODO: Define the fields this snapshot should carry.
+ * Example for an order item:
+ *   String productId,
+ *   String productName,
+ *   Integer quantity,
+ *   BigDecimal unitPrice
+ */
+public record <%= name %>(
+<% if (fields && fields.length > 0) { %>
+<% fields.forEach((field, idx) => { %>
+    <%- field.javaType %> <%= field.name %><%= idx < fields.length - 1 ? ',' : '' %>
+<% }); %>
+<% } else { %>
+    // TODO: Add the fields this snapshot should carry
+<% } %>
+) {
+}

package/templates/aggregate/JpaAggregateRoot.java.ejs

@@ -22,11 +22,17 @@ import <%= packageName %>.shared.domain.AuditableEntity;
 <% } else if (auditable) { %>
 import <%= packageName %>.shared.domain.AuditableEntity;
 <% } %>
+<% if (hasSoftDelete) { %>
+import org.hibernate.annotations.SQLRestriction;
+<% } %>
 
 /**
  * <%= name %>Jpa - JPA Entity
  * Persistence entity with JPA annotations
  */
+<% if (hasSoftDelete) { %>
+@SQLRestriction("deleted_at IS NULL")
+<% } %>
 @Entity
 @Table(name = "<%= tableName %>")
 @Getter

package/templates/aggregate/JpaRepository.java.ejs

@@ -8,4 +8,9 @@ import <%= packageName %>.<%= moduleName %>.infrastructure.database.entities.<%=
  * Spring Data JPA repository
  */
 public interface <%= rootEntity.name %>JpaRepository extends JpaRepository<<%= rootEntity.name %>Jpa, <%= rootEntity.fields[0].javaType %>> {
+<% if (findByOps && findByOps.length > 0) { %>
+<% findByOps.forEach(function(op) { %>
+    org.springframework.data.domain.Page<<%= rootEntity.name %>Jpa> <%= op.jpaMethodName %>(<%= op.fieldJavaType %> <%= op.fieldName %>, org.springframework.data.domain.Pageable pageable);
+<% }); %>
+<% } %>
 }

package/templates/base/gradle/build.gradle.ejs

@@ -50,14 +50,15 @@ dependencies {
 <% } %><% if (dependencies.includes('security')) { %>    implementation 'org.springframework.boot:spring-boot-starter-security'
 <% } %><% if (dependencies.includes('validation')) { %>    implementation 'org.springframework.boot:spring-boot-starter-validation'
 <% } %><% if (dependencies.includes('actuator')) { %>    implementation 'org.springframework.boot:spring-boot-starter-aop'
-<% } %><% if (features.includeDevtools) { %>    developmentOnly 'org.springframework.boot:spring-boot-devtools'
+<% } %>    implementation 'org.springframework.boot:spring-boot-starter-actuator'
+<% if (features.includeDevtools) { %>    developmentOnly 'org.springframework.boot:spring-boot-devtools'
 <% } %><% if (features.includeLombok) { %>    
     compileOnly 'org.projectlombok:lombok'
     annotationProcessor 'org.projectlombok:lombok'
 <% } %><% if (dependencies.includes('data-jpa')) { %>    
     runtimeOnly '<%= databaseDriver %>'
 <% } %><% if (features.includeSwagger) { %>    
-    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:<%= springdocVersion %>'
 <% } %>    
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
 <% if (dependencies.includes('security')) { %>    testImplementation 'org.springframework.security:spring-security-test'

package/templates/base/root/AGENTS.md.ejs

@@ -328,13 +328,21 @@ aggregates:
           - CANCELLED
     
     events:                          # Domain Events emitted by this aggregate
-      - name: OrderConfirmedEvent
-        fields:
-          - name: orderId
+      - name: OrderConfirmedEvent    # Nota: kafka: true ya NO es necesario.
+        fields:                      # Si hay kafka-client instalado, eva g entities
+          - name: orderId            # cableará automáticamente todos los eventos.
             type: String
           - name: confirmedAt
             type: LocalDateTime
-        # kafka: true                # Optional — publishes to Kafka via MessageBroker
+
+# listeners:                        # Sibling de aggregates: — eventos externos que CONSUME
+#   - event: PaymentApprovedEvent
+#     producer: payments
+#     topic: PAYMENT_APPROVED        # obligatorio en módulos standalone
+#     useCase: ConfirmOrder
+#     fields:
+#       - name: orderId
+#         type: String
 ```
 
 ### Supported Field Types
@@ -1525,6 +1533,8 @@ public boolean canConfirm()  { return this.status.canTransitionTo(OrderStatus.CO
 
 ### Domain Events (`events[]`)
 
+Los eventos se declaran bajo el agregado (al mismo nivel que `entities:`, `enums:`, `valueObjects:`). Opcionalmente, se conectan con transiciones de estado mediante la propiedad `triggers`.
+
 ```yaml
 aggregates:
   - name: Order
@@ -1532,64 +1542,301 @@ aggregates:
       - name: order
         isRoot: true
         # ...
+    enums:
+      - name: OrderStatus
+        initialValue: DRAFT
+        transitions:
+          - from: DRAFT
+            to: PLACED
+            method: place
+          - from: PLACED
+            to: CANCELLED
+            method: cancel
+        values: [DRAFT, PLACED, CANCELLED]
     events:
-      - name: OrderConfirmedEvent
+      - name: OrderPlaced
+        topic: ORDER_PLACED       # opcional: sobreescribe el topic auto-derivado
+        triggers:
+          - place             # ← nombre del método de transición
         fields:
-          - name: orderId
+          - name: orderId             # declarar para consumidores cross-módulo via Kafka
             type: String
-          - name: confirmedAt
+          - name: customerId
+            type: String
+          - name: totalAmount
+            type: BigDecimal
+          - name: placedAt
             type: LocalDateTime
-        # kafka: true            # Optional — generates messageBroker.sendOrderConfirmedEvent()
-      
-      - name: OrderShippedEvent
-        kafka: true              # Publishes to Kafka after commit
+      - name: OrderCancelled
+        triggers:
+          - cancel
         fields:
-          - name: orderId
-            type: String
-          - name: trackingNumber
+          - name: reason      # no resuelto → null /* TODO: provide reason */
             type: String
 ```
 
-**Archivos generados:**
+#### Propiedad `topic` (opcional)
 
-`OrderConfirmedEvent.java` — en `domain/models/events/`:
-```java
-public final class OrderConfirmedEvent extends DomainEvent {
-    private final String orderId;
-    private final LocalDateTime confirmedAt;
-
-    public OrderConfirmedEvent(String aggregateId, String orderId, LocalDateTime confirmedAt) {
-        super(aggregateId);
-        this.orderId = orderId;
-        this.confirmedAt = confirmedAt;
-    }
-    // getters
-}
+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: [...]
 ```
 
-`OrderDomainEventHandler.java` — en `application/usecases/`:
-```java
-@Component
-public class OrderDomainEventHandler {
+> **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`.
 
-    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
-    public void handle(OrderConfirmedEvent event) { /* lógica post-commit */ }
+#### Propiedad `triggers`
 
-    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
-    public void handle(OrderShippedEvent event) {
-        messageBroker.sendOrderShippedEvent(event);  // kafka: true
-    }
+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.
+
+**Código generado:**
+
+```java
+public void place() {
+    this.status = this.status.transitionTo(OrderStatus.PLACED);
+    raise(new OrderPlaced(this.getId(), this.getCustomerId(), this.getTotalAmount(), LocalDateTime.now()));
+    //                    ^—aggregateId  ^—customerId         ^—totalAmount         ^—placedAt
+}
+
+public void cancel() {
+    this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+    raise(new OrderCancelled(this.getId(), null /* TODO: provide reason */));
 }
 ```
 
-**Publicar desde la entidad raíz** usando `raise()` heredado:
+Si un evento **no declara `triggers`**, el desarrollador debe llamar a `raise()` manualmente dentro del método de negocio.
+
+Genera `OrderPlaced.java` (en `domain/models/events/`) que extiende `DomainEvent`, y `OrderDomainEventHandler.java` (en `application/usecases/`) con `@TransactionalEventListener(AFTER_COMMIT)`.
+
+**Validaciones del generador:**
+
+| Código | Severidad | Condición |
+|---|---|---|
+| C2-001 | warning | Transición sin use-case — silenciado si tiene `triggers` |
+| C2-004 | error | `triggers` referencia un método que no existe en ninguna transición |
+| C2-005 | info | Transición sin ningún evento asociado — considera declarar `triggers` |
+
+**Auto-wiring de broker:** Si el proyecto tiene `eva add kafka-client` instalado, `eva g entities` genera automáticamente la capa de Integration Events para **todos** los eventos declarados:
+
+| Archivo generado | Descripción |
+|---|---|
+| `application/events/OrderPlacedIntegrationEvent.java` | Record broker-facing (Integration Event) |
+| `application/ports/MessageBroker.java` | Puerto broker-agnóstico (creado/actualizado) |
+| `infrastructure/adapters/kafkaMessageBroker/…` | Adaptador Kafka (creado/actualizado) |
+| `shared/…/kafkaConfig/KafkaConfig.java` | Bean `NewTopic` (actualizado) |
+| `parameters/*/kafka.yaml` | Configuración de topic (actualizada) |
+
+**Domain Event vs Integration Event:**
+- **Domain Event** (`domain/models/events/OrderPlaced.java`) — señal interna del bounded context. Nunca depende de infraestructura.
+- **Integration Event** (`application/events/OrderPlacedIntegrationEvent.java`) — proyección para el broker. Cambiar de Kafka a RabbitMQ solo requiere cambiar el adaptador `MessageBroker`.
+
+El `DomainEventHandler` mapea un Domain Event a un Integration Event:
 ```java
-public void confirm() {
-    this.status = this.status.transitionTo(OrderStatus.CONFIRMED);
-    raise(new OrderConfirmedEvent(this.id, this.id, LocalDateTime.now()));
+@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+public void onOrderPlaced(OrderPlaced event) {
+    messageBroker.publishOrderPlacedIntegrationEvent(
+        new OrderPlacedIntegrationEvent(event.getCustomerId(), event.getTotalAmount(), event.getPlacedAt())
+    );
 }
 ```
 
+**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**):
+
+| Artefacto | 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í |
+
+**Deserialization:** 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
+- 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` usarán directamente.
+
+**Contraste producidos vs. consumidos:**
+```
+aggregates:
+  └── events:     → Domain Events que PRODUCE (domain/models/events/)
+
+listeners:          → Integration Events que CONSUME (infrastructure/kafkaListener/)
+```
+
+---
+
+### 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
+    fields:                            # campos de respuesta → domain model + infra DTO
+      - 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<Seat> en la interfaz del puerto
+    domainType: Seat                   # sobrescribe el tipo auto-derivado
+    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 → domain model Payment + infra DTO
+      - 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
+- **`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)
+```
+
+---
+
 ### Estrategias de Cascade
 
 ```yaml
@@ -1725,6 +1972,8 @@ public class Product {
 
 ### Reglas para Agentes con Soft Delete
 
+- **SOLO** aplicar `hasSoftDelete: true` en la **entidad raíz** del agregado (`isRoot: true`)
+- **NUNCA** poner `hasSoftDelete: true` en entidades secundarias — el ciclo de vida lo controla la raíz mediante `cascade`; el generador emite un warning y descarta el flag
 - **NUNCA** usar `repository.deleteById()` — usar `entity.softDelete()` + `repository.save(entity)`
 - **NUNCA** exponer `deletedAt` en ResponseDtos (campo interno)
 - **SIEMPRE** usar `@SQLRestriction("deleted_at IS NULL")` para filtrado automático en JPA
@@ -1995,8 +2244,10 @@ public record UserResponseDto(
 2. **SI** el módulo requiere ciclo de vida → usar `transitions` + `initialValue` en el enum
 3. **SI** un Value Object tiene comportamiento → declarar `methods` en `domain.yaml`
 4. **SI** ocurren hechos relevantes de negocio → declarar `events[]` en el agregado
-5. **SI** el evento debe propagarse a otros servicios → agregar `kafka: true` al evento
-6. **DESPUÉS** de generar el `domain.yaml` → ejecutar `eva g entities <module>`
+5. **SI** el evento debe propagarse vía broker → **no** usar `kafka: true`; si `eva add kafka-client` está instalado, `eva g entities` auto-cablea todos los eventos
+6. **SI** el módulo consume eventos de otros servicios → declarar `listeners:` (sibling de `aggregates:`) con `topic:` obligatorio en módulos standalone
+7. **SI** el módulo llama servicios HTTP externos de forma síncrona → declarar `ports:` (sibling de `aggregates:`) con `baseUrl:` en la primera entrada de cada `service:`
+8. **DESPUÉS** de generar el `domain.yaml` → ejecutar `eva g entities <module>`
 
 ### Al Generar Código de Dominio
 
@@ -2089,7 +2340,17 @@ Al generar o modificar código, verificar:
 - [ ] Enum con ciclo de vida → `transitions` + `initialValue`, no setters
 - [ ] Value Object con comportamiento → `methods` en domain.yaml
 - [ ] Evento de dominio → `events[]`, publicar con `raise()` en método de negocio
-- [ ] Evento con Kafka → `kafka: true` en el evento
+- [ ] Evento con broker → **no** usar `kafka: true`; si `eva add kafka-client` está instalado, `eva g entities` auto-cablea todos los eventos
+- [ ] Distinguir Domain Event (`domain/models/events/`) e Integration Event (`application/events/`) — 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
+- [ ] Campos de tipo objeto en listeners → declarar `nestedTypes:` para generar records auxiliares en `application/events/`
+- [ ] Clientes HTTP síncronos → declarar en `ports[]` (nivel raíz); `baseUrl:` en la primera entrada de cada `service:`
+- [ ] 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 hay colisión
+- [ ] Cada `service:` en `ports[]` genera: interfaz (devuelve modelos de dominio en `domain/models/{service}/`), FeignClient, FeignAdapter (ACL), FeignConfig + `urls.yaml`
 
 ---