eva4j 1.0.13 → 1.0.15

package/examples/domain-events.yaml

@@ -45,30 +45,49 @@
 #
 # ─────────────────────────────────────────────────────────────────────────────
 #
-# 3. orders/domain/models/entities/Order.java  (modificaciones al agregado)
+# 3. orders/domain/models/entities/Order.java  (con triggers: declarados en events[])
 #
-#    public class Order {
-#        // ... campos normales ...
+#    // El desarrollador NO escribe raise() manualmente — el generador lo emite
+#    // automáticamente basándose en triggers: declarados en domain.yaml.
 #
-#        // ─── Domain Events ───────────────────────────────────────
-#        private final List<DomainEvent> _domainEvents = new ArrayList<>();
+#    // Construcción de args (en orden):
+#    //   1º  aggregateId  → this.getId()  (primer arg del constructor DomainEvent, siempre)
+#    //   2º+ campos del evento → resolución automática:
+#    //       · {entityName}Id (ej: orderId en Order) → this.getId()
+#    //       · coincide con campo de la entidad       → this.get{Field}()
+#    //       · nombre termina en At + tipo LocalDateTime → LocalDateTime.now()
+#    //       · no resuelto                            → null /* TODO: provide X */
 #
-#        protected void raise(DomainEvent event) {
-#            _domainEvents.add(event);
-#        }
+#    public void place() {
+#        this.status = this.status.transitionTo(OrderStatus.PLACED);
+#        raise(new OrderPlaced(this.getId(), this.getCustomerId(), this.getOrderNumber(), this.getTotalAmount()));
+#        //                    ^—aggregateId  ^—customerId           ^—orderNumber          ^—totalAmount
+#        //  orderId no se pasa — disponible como event.getAggregateId() en el consumidor
+#    }
+#
+#    public void cancel() {
+#        this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+#        raise(new OrderCancelled(this.getId(), null /* TODO: provide reason */));
+#        //                       ^—aggregateId  ^—reason no resuelto automáticamente
+#    }
+#
+#    public void ship() {
+#        this.status = this.status.transitionTo(OrderStatus.SHIPPED);
+#        raise(new OrderShipped(this.getId(), null /* TODO: provide shippingAddress */, null /* TODO: provide estimatedDeliveryDate */));
+#    }
 #
-#        public List<DomainEvent> pullDomainEvents() {
 #            List<DomainEvent> events =
 #                Collections.unmodifiableList(new ArrayList<>(_domainEvents));
 #            _domainEvents.clear();
 #            return events;   // retorna y limpia (operación atómica)
 #        }
 #
-#        // El desarrollador llama a raise() dentro de sus métodos de negocio:
-#        public void place(String customerId, BigDecimal total) {
-#            this.status = this.status.transitionTo(OrderStatus.PLACED);  // lanza InvalidStateTransitionException si no es válida
-#            raise(new OrderPlacedEvent(this.id, customerId, this.orderNumber, total));
-#        }
+#        // Con triggers: auto-generados NO hace falta escribir raise() a mano. Ver arriba.
+#        // Si un evento NO declara triggers, el dev puede llamar a raise() explicitamente:
+#        //     public void placeManual(String customerId, BigDecimal total) {
+#        //         this.status = OrderStatus.PLACED;
+#        //         raise(new OrderPlaced(this.id, customerId, orderNumber, total));
+#        //     }
 #    }
 #
 # ─────────────────────────────────────────────────────────────────────────────
@@ -123,6 +142,65 @@
 # Para conectar un broker externo después de generar:
 #   eva4j g kafka-event orders OrderPlaced
 #   (el selector muestra los eventos declarados en este domain.yaml como opciones)
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# SECCIÓN listeners: — eventos externos que CONSUME este módulo
+#
+# Complemento de events: (producción). A diferencia de events:, que vive
+# DENTRO del agregado porque pertenece al modelo de dominio, listeners: vive
+# en el NIVEL RAÍZ del domain.yaml porque es una preocupación de integración.
+#
+# Estructura generada por cada listener:
+#
+#   ┌─ application/events/
+#   │    PaymentApprovedIntegrationEvent.java   ← record tipado con los fields
+#   │
+#   └─ infrastructure/kafkaListener/
+#        PaymentApprovedKafkaListener.java      ← @KafkaListener que despacha
+#                                                  al useCase via UseCaseMediator
+#
+# Código generado de ejemplo:
+#
+#   // application/events/PaymentApprovedIntegrationEvent.java
+#   public record PaymentApprovedIntegrationEvent(
+#       String orderId,
+#       String paymentId,
+#       LocalDateTime approvedAt
+#   ) {}
+#
+#   // infrastructure/kafkaListener/PaymentApprovedKafkaListener.java
+#   @Component
+#   public class PaymentApprovedKafkaListener {
+#
+#       private final UseCaseMediator useCaseMediator;
+#
+#       @Value("${kafka.topics.PAYMENT_APPROVED}")
+#       private String paymentApprovedTopic;
+#
+#       @KafkaListener(topics = "${kafka.topics.PAYMENT_APPROVED}")
+#       public void handle(EventEnvelope<PaymentApprovedIntegrationEvent> envelope,
+#                          Acknowledgment ack) {
+#           PaymentApprovedIntegrationEvent event = envelope.data();
+#           useCaseMediator.dispatch(new ConfirmOrderCommand(event.orderId()));
+#           ack.acknowledge();
+#       }
+#   }
+#
+# Propiedades:
+#   event       (requerido) — Nombre del evento consumido (PascalCase + sufijo Event)
+#   producer    (requerido) — Módulo que produce el evento (referencia documental)
+#   topic       (requerido) — Topic Kafka. Si el proyecto tiene system.yaml el generador
+#                             puede inferirlo; en módulos standalone es obligatorio
+#                             declararlo explícitamente (no hay otra fuente de verdad).
+#   useCase     (requerido) — Caso de uso que maneja el evento (PascalCase)
+#   fields      (requerido) — Payload recibido; genera el record IntegrationEvent
+#                             y tipifica el Command despachado desde el listener.
+#   nestedTypes (opcional)  — Tipos auxiliares para campos objeto en fields.
+#                             Genera {Name}.java en application/events/ por cada entrada.
+#                             Usar cuando un field no es un tipo Java primitivo sino
+#                             un objeto estructurado del dominio del productor.
+#                             El name se declara camelCase y se genera en PascalCase.
 
 aggregates:
   - name: Order
@@ -160,42 +238,110 @@ aggregates:
         transitions:
           - from: DRAFT
             to: PLACED
+            method: place
           - from: DRAFT
             to: CANCELLED
+            method: cancel
           - from: PLACED
             to: CONFIRMED
+            method: confirm
           - from: PLACED
             to: CANCELLED
+            method: cancel
           - from: CONFIRMED
             to: SHIPPED
+            method: ship
           - from: CONFIRMED
             to: CANCELLED
+            method: cancel
           - from: SHIPPED
             to: DELIVERED
+            method: deliver
 
     # ─── Domain Events ────────────────────────────────────────────────────────
     # Siblings de entities:, enums: y valueObjects:
     # La declaración es agnóstica al broker — ningún campo de infraestructura aquí.
     # Cada entrada genera: domain/models/events/{Name}Event.java
+    #
+    # triggers: (lista de nombres de métodos de transición)
+    #   Conecta automáticamente una transición de estado con la publicación de este evento.
+    #   El generador emite raise(new XEvent(...)) dentro del método de transición.
+    #   Si no se declara triggers, el dev debe llamar a raise() manualmente.
+    #
+    # Reglas de resolución de argumentos (automática):
+    #   1. aggregateId → siempre this.getId() (primer arg del constructor de DomainEvent)
+    #   2. {entityName}Id (ej: orderId en Order) → IGNORADO — el id ya está en aggregateId
+    #      El consumidor usa event.getAggregateId(); no declarar este campo en events[].fields
+    #   3. coincide con campo de la entidad → this.get{Field}()
+    #   4. nombre termina en At + tipo LocalDateTime → LocalDateTime.now()
+    #   5. no resuelto → null /* TODO: provide {fieldName} */
 
     events:
       - name: OrderPlaced
+        triggers:
+          - place           # auto-genera raise() en el método place() de Order
         fields:
-          - name: customerId
+          # orderId NO se declara aquí — ya disponible como event.getAggregateId()
+          - name: customerId  # → this.getCustomerId()  (campo de la entidad)
             type: String
-          - name: orderNumber
+          - name: orderNumber  # → this.getOrderNumber()
             type: String
-          - name: totalAmount
+          - name: totalAmount  # → this.getTotalAmount()
             type: BigDecimal
 
       - name: OrderCancelled
+        triggers:
+          - cancel          # auto-genera raise() en cancel() de Order
         fields:
-          - name: reason
+          - name: reason    # no resuelto → null /* TODO: provide reason */
             type: String
 
       - name: OrderShipped
+        triggers:
+          - ship
         fields:
-          - name: shippingAddress
+          - name: shippingAddress       # no resuelto → null /* TODO */
             type: String
-          - name: estimatedDeliveryDate
+          - name: estimatedDeliveryDate # no resuelto → null /* TODO */
             type: LocalDate
+
+# ─── Eventos externos que este módulo CONSUME ────────────────────────────────
+# Nivel raíz, sibling de aggregates:
+# Requiere broker instalado (eva add kafka-client) para generación.
+# topic: es obligatorio en módulos standalone (sin system.yaml).
+
+listeners:
+  - event: PaymentApprovedEvent
+    producer: payments             # módulo origen (solo documental)
+    topic: PAYMENT_APPROVED        # obligatorio si no hay system.yaml
+    useCase: ConfirmOrder          # Command handler que se ejecuta
+    fields:                        # payload del Integration Event recibido
+      - name: orderId
+        type: String
+      - name: approvedAt
+        type: LocalDateTime
+      - name: details
+        type: PaymentDetails       # objeto estructurado → declarado en nestedTypes
+    nestedTypes:                   # genera PaymentDetails.java en application/events/
+      - name: paymentDetails
+        fields:
+          - name: paymentId
+            type: String
+          - name: method
+            type: String
+          - name: currency
+            type: String
+          - name: amount
+            type: BigDecimal
+
+  - event: PaymentRejectedEvent
+    producer: payments
+    topic: PAYMENT_REJECTED
+    useCase: CancelOrder
+    fields:
+      - name: orderId
+        type: String
+      - name: rejectedAt
+        type: LocalDateTime
+      - name: reason
+        type: String

package/examples/domain-listeners.yaml

@@ -0,0 +1,212 @@
+# EJEMPLO: LISTENERS — eventos externos que CONSUME un módulo
+# Complemento de domain-events.yaml (producción).
+#
+# La sección listeners: vive en el NIVEL RAÍZ del domain.yaml,
+# como sibling de aggregates:, porque es una responsabilidad de
+# integración/infraestructura, no de dominio.
+#
+# Generación:
+#   eva4j g entities reservations
+#
+# Requiere broker instalado:
+#   eva add kafka-client
+#
+# ─── ARCHIVOS GENERADOS ───────────────────────────────────────────────────────
+#
+# Por cada entrada en listeners: se generan CINCO archivos:
+#
+#   application/events/{Name}IntegrationEvent.java   ← record contrato (documentación)
+#   application/commands/{UseCase}Command.java        ← comando tipado despachado
+#   application/usecases/{UseCase}CommandHandler.java ← handler stub (implementar)
+#   infrastructure/kafkaListener/{Name}KafkaListener.java
+#   kafka.yaml (todas las envs)                       ← topic registrado
+#
+# Si se declaran nestedTypes:, se genera también:
+#   application/events/{NestedName}.java              ← record auxiliar por tipo objeto
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# EJEMPLO con nestedTypes: — campo 'details' de tipo PaymentDetails
+#
+# 0. reservations/application/events/PaymentDetails.java  (nested type)
+#
+#    public record PaymentDetails(
+#        String paymentId,
+#        String method,
+#        String currency,
+#        BigDecimal amount
+#    ) {}
+#
+# 1. reservations/application/events/PaymentApprovedIntegrationEvent.java
+#
+#    public record PaymentApprovedIntegrationEvent(
+#        String reservationId,
+#        LocalDateTime approvedAt,
+#        PaymentDetails details
+#    ) {}
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# 2. reservations/infrastructure/kafkaListener/PaymentApprovedKafkaListener.java
+#
+#    @Component
+#    public class PaymentApprovedKafkaListener {
+#
+#        private final UseCaseMediator useCaseMediator;
+#        private final ObjectMapper objectMapper;
+#
+#        @Value("${topics.payment-approved}")
+#        private String paymentApprovedTopic;
+#
+#        public PaymentApprovedKafkaListener(UseCaseMediator useCaseMediator,
+#                                            ObjectMapper objectMapper) {
+#            this.useCaseMediator = useCaseMediator;
+#            this.objectMapper = objectMapper;
+#        }
+#
+#        @KafkaListener(topics = "${topics.payment-approved}")
+#        public void handle(EventEnvelope<Map<String, Object>> event, Acknowledgment ack) {
+#            String reservationId = objectMapper.convertValue(
+#                    event.data().get("reservationId"), String.class);
+#            LocalDateTime approvedAt = objectMapper.convertValue(
+#                    event.data().get("approvedAt"), LocalDateTime.class);
+#            PaymentDetails details = objectMapper.convertValue(
+#                    event.data().get("details"), PaymentDetails.class);
+#            useCaseMediator.dispatch(new ConfirmReservationCommand(
+#                    reservationId, approvedAt, details));
+#            ack.acknowledge();
+#        }
+#    }
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# REGLA DE topic:
+#
+#   • Módulo standalone (sin system.yaml) → topic: OBLIGATORIO
+#     No hay ninguna otra fuente de verdad para el nombre del topic.
+#
+#   • Proyecto con system.yaml → topic: puede omitirse.
+#     El generador lo infiere de integrations.async[].topic donde coincidan
+#     event y producer.
+#
+#   • topic: declarado explícitamente + system.yaml → el valor declarado
+#     tiene PRECEDENCIA sobre la inferencia del system.yaml.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# CONTRASTE: producción vs. consumo
+#
+#   domain.yaml
+#   ├── aggregates:
+#   │   └── [Aggregate]
+#   │       └── events:      → Domain Events que PRODUCE  (domain/models/events/)
+#   │
+#   └── listeners:           → Integration Events que CONSUME (infrastructure/kafkaListener/)
+
+aggregates:
+  - name: Reservation
+    entities:
+      - name: reservation
+        isRoot: true
+        tableName: reservations
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: screeningId
+            type: String
+          - name: customerId
+            type: String
+          - name: status
+            type: ReservationStatus
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true
+
+    enums:
+      - name: ReservationStatus
+        initialValue: PENDING
+        values:
+          - PENDING
+          - CONFIRMED
+          - CANCELLED
+          - EXPIRED
+        transitions:
+          - from: PENDING
+            to: CONFIRMED
+            method: confirm
+          - from: PENDING
+            to: CANCELLED
+            method: cancel
+          - from: PENDING
+            to: EXPIRED
+            method: expire
+
+    events:
+      - name: ReservationConfirmed
+        triggers:
+          - confirm
+        fields:
+          # reservationId NO se declara — disponible como event.getAggregateId()
+          - name: customerId
+            type: String
+          - name: confirmedAt
+            type: LocalDateTime
+
+      - name: ReservationCancelled
+        fields:
+          - name: reservationId
+            type: String
+          - name: reason
+            type: String
+
+# ─── Eventos externos que este módulo CONSUME ────────────────────────────────
+# Nivel raíz, sibling de aggregates:
+# topic: es obligatorio en módulos standalone (sin system.yaml).
+
+listeners:
+  - event: PaymentApprovedEvent
+    producer: payments             # módulo origen (solo referencia documental)
+    topic: PAYMENT_APPROVED        # obligatorio: no hay system.yaml en este ejemplo
+    useCase: ConfirmReservation    # command handler invocado al recibir el evento
+    fields:                        # payload del Integration Event recibido
+      - name: reservationId
+        type: String
+      - name: approvedAt
+        type: LocalDateTime
+      - name: details
+        type: PaymentDetails       # objeto estructurado → declarado en nestedTypes
+    nestedTypes:                   # genera PaymentDetails.java en application/events/
+      - name: paymentDetails       # camelCase → PascalCase en el record generado
+        fields:
+          - name: paymentId
+            type: String
+          - name: method
+            type: String
+          - name: currency
+            type: String
+          - name: amount
+            type: BigDecimal
+
+  - event: PaymentRejectedEvent
+    producer: payments
+    topic: PAYMENT_REJECTED
+    useCase: ExpireReservation
+    fields:
+      - name: reservationId
+        type: String
+      - name: rejectedAt
+        type: LocalDateTime
+      - name: reason
+        type: String
+
+  - event: ScreeningCancelledEvent
+    producer: screenings
+    topic: SCREENING_CANCELLED
+    useCase: CancelReservationsByScreening
+    fields:
+      - name: screeningId
+        type: String
+      - name: cancelledAt
+        type: LocalDateTime

package/examples/domain-one-to-many.yaml

@@ -8,6 +8,7 @@ aggregates:
       - name: Order
         isRoot: true
         tableName: orders
+        hasSoftDelete: true
         audit:
           enabled: true      # Agrega createdAt, updatedAt
           trackUser: true    # Agrega createdBy, updatedBy

package/examples/domain-one-to-one.yaml

@@ -7,6 +7,7 @@ aggregates:
     entities:
       - name: User
         isRoot: true
+        hasSoftDelete: true
         tableName: users
         audit:
           enabled: true      # Agrega createdAt, updatedAt