eva4j 1.0.16 → 1.0.18

package/docs/prototype/system/system.yaml

@@ -0,0 +1,269 @@
+# =============================================================================
+# PROTOTYPE: system.yaml con Temporal como único mecanismo de comunicación
+# =============================================================================
+# Este es el formato target para generación de código con Temporal.
+# eva4j leerá este archivo para generar workflows cross-module
+# y contratos compartidos entre módulos.
+# =============================================================================
+
+system:
+  name: test-eva
+  groupId: com.example
+  javaVersion: 21
+  springBootVersion: 3.5.5
+  database: postgresql
+
+# ─── Temporal reemplaza tanto messaging (Kafka) como sync (Feign) ────────────
+orchestration:
+  enabled: true
+  engine: temporal
+  temporal:
+    target: localhost:7233
+    namespace: test-eva
+    # Task queues con prefijo de módulo (module-scoped)
+    # Cada módulo tiene su propio set de queues:
+    #   {MODULE}_WORKFLOW_QUEUE    — Workflows del módulo
+    #   {MODULE}_LIGHT_TASK_QUEUE  — Activities rápidas (< 30s)
+    #   {MODULE}_HEAVY_TASK_QUEUE  — Activities pesadas (hasta 2min)
+
+modules:
+  - name: products
+    description: "Product catalog management for household goods"
+    exposes:
+      - method: GET
+        path: /products/{id}
+        useCase: GetProduct
+      - method: GET
+        path: /products
+        useCase: FindAllProducts
+      - method: POST
+        path: /products
+        useCase: CreateProduct
+      - method: PUT
+        path: /products/{id}
+        useCase: UpdateProduct
+      - method: DELETE
+        path: /products/{id}
+        useCase: DeleteProduct
+
+  - name: customers
+    description: "Customer registration and profile management"
+    exposes:
+      - method: GET
+        path: /customers/{id}
+        useCase: GetCustomer
+      - method: GET
+        path: /customers
+        useCase: FindAllCustomers
+      - method: POST
+        path: /customers
+        useCase: CreateCustomer
+      - method: PUT
+        path: /customers/{id}
+        useCase: UpdateCustomer
+
+  - name: orders
+    description: "Order lifecycle management from placement to completion"
+    exposes:
+      - method: POST
+        path: /orders
+        useCase: CreateOrder
+      - method: GET
+        path: /orders/{id}
+        useCase: GetOrder
+      - method: GET
+        path: /orders
+        useCase: FindAllOrders
+      - method: PUT
+        path: /orders/{id}/cancel
+        useCase: CancelOrder
+
+  - name: payments
+    description: "Payment processing and external payment gateway integration"
+    exposes:
+      - method: POST
+        path: /payments
+        useCase: CreatePayment
+      - method: GET
+        path: /payments/{id}
+        useCase: GetPayment
+      - method: GET
+        path: /payments
+        useCase: FindAllPayments
+      - method: POST
+        path: /payments/{id}/refund
+        useCase: RefundPayment
+
+  - name: inventory
+    description: "Stock level management, reservation, and replenishment"
+    exposes:
+      - method: GET
+        path: /inventory/{productId}
+        useCase: GetStock
+      - method: GET
+        path: /inventory
+        useCase: FindAllStocks
+      - method: PUT
+        path: /inventory/{productId}/adjust
+        useCase: AdjustStock
+      - method: POST
+        path: /inventory/{productId}/reserve
+        useCase: ReserveStock
+      - method: POST
+        path: /inventory/{productId}/release
+        useCase: ReleaseStock
+
+  - name: notifications
+    description: "Notification delivery service for email and SMS alerts"
+
+# =============================================================================
+# WORKFLOWS: Flujos de negocio cross-module orquestados por Temporal
+# =============================================================================
+# Solo flujos de negocio REALES — no hay workflows de sincronización de datos.
+# Datos cross-module se obtienen on-demand con Remote Activities de lectura.
+# Patrones usados (ver TEMPORAL_COMMUNICATION_PATTERNS.md):
+#   - Remote Activity: operación atómica cross-service
+#   - Remote Activity + Async.function(): operaciones independientes en paralelo
+# =============================================================================
+
+workflows:
+
+  # ─── Producto creado: inicializar stock en inventory ───────────────────────
+  # Único consumer real de ProductCreatedEvent.
+  # Sin read models, ya no hay steps de sincronización.
+  - name: ProductCreatedWorkflow
+    trigger:
+      module: products
+      on: create
+    taskQueue: PRODUCT_WORKFLOW_QUEUE
+    steps:
+      - activity: InitializeStock              # Remote Activity → inventory
+        target: inventory
+        type: sync
+        input:
+          - productId
+          - name
+        compensation: DeleteStock
+        timeout: 10s
+
+  # ─── Orden creada: SAGA completa ───────────────────────────────────────────
+  # El caso estrella de Temporal — saga con compensación durable.
+  # Sin read models: customer y product data se obtienen on-demand
+  # mediante Remote Activities de lectura.
+  - name: PlaceOrderWorkflow
+    trigger:
+      module: orders
+      on: create
+    taskQueue: ORDER_WORKFLOW_QUEUE
+    saga: true
+    steps:
+      # Paso 1: Obtener detalles de la orden (Local Activity → orders)
+      # Lee el agregado completo: items, customerId, totalAmount.
+      # Permite que el workflow input sea solo orderId.
+      - activity: GetOrderDetails
+        target: orders
+        type: sync
+        input: [orderId]
+        output: [customerId, items, totalAmount]
+        timeout: 5s
+
+      # Paso 2: Obtener datos del cliente (Remote Activity → customers)
+      # Valida existencia y obtiene email/nombre para notificaciones.
+      - activity: GetCustomerById
+        target: customers
+        type: sync
+        input: [customerId]
+        output: [customerId, firstName, lastName, email, phone]
+        timeout: 5s
+
+      # Paso 3: Reservar stock (Remote Activity → inventory)
+      - activity: ReserveStock
+        target: inventory
+        type: sync
+        input: [orderId, items]
+        compensation: ReleaseStock
+        timeout: 10s
+
+      # Paso 4: Procesar pago (Remote Activity → payments)
+      - activity: ProcessOrderPayment
+        target: payments
+        type: sync
+        input: [orderId, customerId, totalAmount]
+        output: [paymentId]
+        compensation: RefundPayment
+        timeout: 30s
+
+      # Paso 5: Confirmar orden (Local Activity → orders)
+      - activity: ConfirmOrder
+        target: orders
+        type: sync
+        input: [orderId]
+
+      # Paso 6: Notificar (Remote Activity → notifications)
+      # ⚡ Async.function() — fire-and-forget, NO bloquea la saga.
+      - activity: NotifyOrderPlaced
+        target: notifications
+        type: async
+        input: [orderId, email, firstName, totalAmount]
+
+  # ─── Orden cancelada ──────────────────────────────────────────────────────
+  - name: CancelOrderWorkflow
+    trigger:
+      module: orders
+      on: cancel
+    taskQueue: ORDER_WORKFLOW_QUEUE
+    steps:
+      # Paso 1: Obtener detalles de la orden (Local Activity → orders)
+      - activity: GetOrderDetails
+        target: orders
+        type: sync
+        input: [orderId]
+        output: [customerId, items, paymentId]
+        timeout: 5s
+
+      # Paso 2: Obtener datos del cliente (para email de notificación)
+      - activity: GetCustomerById
+        target: customers
+        type: sync
+        input: [customerId]
+        output: [customerId, firstName, lastName, email, phone]
+        timeout: 5s
+
+      # Paso 3: Liberar stock reservado
+      - activity: ReleaseStock
+        target: inventory
+        type: sync
+        input: [orderId, items]
+        timeout: 10s
+
+      # Paso 4: Reembolsar pago (si hubo pago previo)
+      - activity: RefundPayment
+        target: payments
+        type: sync
+        input: [paymentId]
+        timeout: 30s
+        optional: true                         # No falla si no hubo pago
+
+      # Paso 5: Notificar cancelación (async, non-blocking)
+      - activity: NotifyOrderCancelled
+        target: notifications
+        type: async
+        input: [orderId, email, firstName]
+
+  # ─── ELIMINADOS: Workflows de sincronización de datos ──────────────────────
+  # Antes había 4 workflows que SOLO sincronizaban read models:
+  #   - ProductUpdatedWorkflow     → SyncProductReadModel en orders
+  #   - ProductDeactivatedWorkflow → SoftDeleteProductReadModel en orders
+  #   - CustomerCreatedWorkflow    → SyncCustomerReadModel en orders + notifications
+  #   - CustomerUpdatedWorkflow    → SyncCustomerReadModel en orders + notifications
+  #
+  # ELIMINADOS porque:
+  #   1. Read models eliminados — datos se obtienen on-demand via Remote Activity
+  #   2. GetCustomerById reemplaza las proyecciones locales
+  #   3. Menos acoplamiento productor→consumidor (customers/products ya no saben
+  #      quién los consume)
+
+  # ─── ABSORBIDOS por PlaceOrderWorkflow (saga) ─────────────────────────────
+  # PaymentApprovedWorkflow / PaymentFailedWorkflow → la saga integra el
+  # resultado de ProcessOrderPayment directamente. Si falla → compensa.
+  # Si aprueba → ConfirmOrder.

package/examples/domain-endpoints-multi-aggregate.yaml

@@ -0,0 +1,140 @@
+# EJEMPLO: ENDPOINTS — MÓDULO CON MÚLTIPLES AGREGADOS
+# Módulo de productos con dos agregados: Product y Category.
+#
+# REGLA CLAVE:
+#   Cuando un módulo tiene 2+ agregados, NO se puede usar un solo
+#   basePath (ej: /products) porque cada agregado tiene su propio
+#   recurso REST. En este caso:
+#
+#   - Usar basePath: "" (string vacío — NUNCA basePath: / con slash)
+#   - Declarar paths ABSOLUTOS en cada operación
+#   - El controlador generado tendrá @RequestMapping("/api/v1") (limpio)
+#
+# CONTRASTE CON MÓDULO DE UN SOLO AGREGADO:
+#   basePath: /orders        → paths relativos: /, /{id}, /{id}/confirm
+#   basePath: ""             → paths absolutos: /products, /categories/{id}
+
+aggregates:
+  # ── Primer agregado: Product ──────────────────────────────────────────────
+  - name: Product
+    entities:
+      - name: product
+        isRoot: true
+        tableName: products
+        hasSoftDelete: true
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Product name is required"
+          - name: description
+            type: String
+          - name: price
+            type: BigDecimal
+            validations:
+              - type: Positive
+          - name: categoryId
+            type: String
+            reference:
+              aggregate: Category
+          - name: status
+            type: ProductStatus
+            readOnly: true
+
+    enums:
+      - name: ProductStatus
+        initialValue: DRAFT
+        transitions:
+          - from: DRAFT
+            to: PUBLISHED
+            method: publish
+          - from: PUBLISHED
+            to: ARCHIVED
+            method: archive
+        values: [DRAFT, PUBLISHED, ARCHIVED]
+
+    events:
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+      - name: ProductPublishedEvent
+        triggers:
+          - publish
+        fields:
+          - name: productId
+            type: String
+          - name: publishedAt
+            type: LocalDateTime
+
+  # ── Segundo agregado: Category ────────────────────────────────────────────
+  - name: Category
+    entities:
+      - name: category
+        isRoot: true
+        tableName: categories
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Category name is required"
+          - name: description
+            type: String
+
+# ── Endpoints: basePath vacío + paths absolutos ─────────────────────────────
+# NOTA: basePath: "" (vacío) porque hay 2 agregados.
+#       Cada path es absoluto: /products, /categories, etc.
+endpoints:
+  basePath: ""
+  versions:
+    - version: v1
+      operations:
+        # ── Product operations ──
+        - useCase: CreateProduct
+          method: POST
+          path: /products
+        - useCase: UpdateProduct
+          method: PUT
+          path: /products/{id}
+        - useCase: GetProduct
+          method: GET
+          path: /products/{id}
+        - useCase: FindAllProducts
+          method: GET
+          path: /products
+        - useCase: PublishProduct
+          method: PUT
+          path: /products/{id}/publish
+        # ── Category operations ──
+        - useCase: CreateCategory
+          method: POST
+          path: /categories
+        - useCase: UpdateCategory
+          method: PUT
+          path: /categories/{id}
+        - useCase: GetCategory
+          method: GET
+          path: /categories/{id}
+        - useCase: FindAllCategories
+          method: GET
+          path: /categories
+        # ── Cross-aggregate query ──
+        - useCase: FindProductsByCategory
+          method: GET
+          path: /categories/{id}/products

package/examples/domain-events.yaml

@@ -305,6 +305,32 @@ aggregates:
           - name: estimatedDeliveryDate # no resuelto → null /* TODO */
             type: LocalDate
 
+      # ─── Eventos con lifecycle: (alterntiva a triggers:) ──────────────
+      # Cuando el evento se produce en una operación CRUD y no en una transición de estado,
+      # se usa lifecycle: en lugar de triggers:
+      # El generador emite raise() automáticamente en el punto CRUD correspondiente.
+
+      - name: OrderCreatedEvent
+        lifecycle: create           # raise() en el constructor de creación
+        fields:                     # UUID auto-generado como id antes de raise()
+          - name: orderId
+            type: String
+          - name: customerName      # → this.getCustomerName() si existe en la entidad
+            type: String
+          - name: createdAt
+            type: LocalDateTime     # → LocalDateTime.now()
+
+      - name: OrderUpdatedEvent
+        lifecycle: update           # raise() en el método update() de la entidad raíz
+        fields:
+          - name: orderId
+            type: String
+          - name: customerName
+            type: String
+
+      # lifecycle: delete requiere hasSoftDelete: false en la entidad raíz
+      # lifecycle: softDelete requiere hasSoftDelete: true en la entidad raíz
+
 # ─── Eventos externos que este módulo CONSUME ────────────────────────────────
 # Nivel raíz, sibling de aggregates:
 # Requiere broker instalado (eva add kafka-client) para generación.

package/examples/domain-read-models.yaml

@@ -0,0 +1,113 @@
+# Example: Read Models (Local Projections)
+#
+# This example shows an "orders" module that uses readModels to maintain
+# local projections of data from "products" and "customers" modules,
+# eliminating synchronous HTTP dependencies.
+#
+# ─── SOURCE MODULE NOTE ──────────────────────────────────────────────────────
+# The source module (e.g. products/domain.yaml) must declare the events
+# that this readModel's syncedBy entries reference. Use lifecycle: to
+# automatically emit raise() at CRUD operations:
+#
+#   events:
+#     - name: ProductCreatedEvent
+#       lifecycle: create          # raise() in creation constructor
+#       fields:
+#         - name: productId
+#           type: String
+#         - name: name
+#           type: String
+#         - name: price
+#           type: BigDecimal
+#         - name: status
+#           type: String
+#
+#     - name: ProductUpdatedEvent
+#       lifecycle: update          # raise() in UpdateCommandHandler
+#       fields: [...]
+#
+#     - name: ProductDeactivatedEvent
+#       lifecycle: softDelete      # raise() in softDelete() method
+#       fields: [...]
+# ─────────────────────────────────────────────────────────────────────────────
+
+aggregates:
+  - name: Order
+    entities:
+      - name: Order
+        isRoot: true
+        tableName: orders
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          - name: orderNumber
+            type: String
+          - name: customerId
+            type: String
+            reference:
+              aggregate: Customer
+              module: customers
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true
+            defaultValue: "0.00"
+    enums:
+      - name: OrderStatus
+        initialValue: DRAFT
+        values: [DRAFT, PLACED, CONFIRMED, CANCELLED]
+        transitions:
+          - from: DRAFT
+            to: PLACED
+            method: place
+          - from: PLACED
+            to: CONFIRMED
+            method: confirm
+          - from: [DRAFT, PLACED]
+            to: CANCELLED
+            method: cancel
+
+readModels:
+  - name: ProductReadModel
+    source:
+      module: products
+      aggregate: Product
+    tableName: rm_orders_products
+    fields:
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+      - name: status
+        type: String
+    syncedBy:
+      - event: ProductCreatedEvent
+        action: UPSERT
+      - event: ProductUpdatedEvent
+        action: UPSERT
+      - event: ProductDeactivatedEvent
+        action: SOFT_DELETE
+
+  - name: CustomerReadModel
+    source:
+      module: customers
+      aggregate: Customer
+    tableName: rm_orders_customers
+    fields:
+      - name: id
+        type: String
+      - name: fullName
+        type: String
+      - name: email
+        type: String
+    syncedBy:
+      - event: CustomerRegisteredEvent
+        action: UPSERT
+      - event: CustomerUpdatedEvent
+        action: UPSERT
+      - event: CustomerDeletedEvent
+        action: DELETE

package/examples/system/customer.yaml

@@ -0,0 +1,89 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# customer — Domain Model
+# ─────────────────────────────────────────────────────────────────────────────
+# Gestión de clientes. Emite eventos de ciclo de vida (create, update, delete)
+# para que otros módulos mantengan proyecciones locales via readModels.
+# ─────────────────────────────────────────────────────────────────────────────
+
+aggregates:
+  - name: Customer
+    entities:
+      - name: Customer
+        isRoot: true
+        tableName: customers
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          - name: fullName
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Full name is required"
+          - name: email
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Email is required"
+              - type: Email
+                message: "Invalid email format"
+          - name: phone
+            type: String
+
+    events:
+      # CustomerCreatedEvent — lifecycle: create → raise() in creation constructor
+      - name: CustomerCreatedEvent
+        lifecycle: create
+        fields:
+          - name: customerId
+            type: String
+          - name: fullName
+            type: String
+          - name: email
+            type: String
+
+      # CustomerUpdatedEvent — lifecycle: update → raise() in update() method
+      - name: CustomerUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: customerId
+            type: String
+          - name: fullName
+            type: String
+          - name: email
+            type: String
+
+      # CustomerDeletedEvent — lifecycle: delete → raise() in DeleteCommandHandler
+      - name: CustomerDeletedEvent
+        lifecycle: delete
+        fields:
+          - name: customerId
+            type: String
+          - name: deletedAt
+            type: LocalDateTime
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Declarative REST endpoints
+# ─────────────────────────────────────────────────────────────────────────────
+endpoints:
+  basePath: /customers
+  versions:
+    - version: v1
+      operations:
+        - useCase: CreateCustomer
+          method: POST
+          path: /
+        - useCase: GetCustomer
+          method: GET
+          path: /{id}
+        - useCase: FindAllCustomers
+          method: GET
+          path: /
+        - useCase: UpdateCustomer
+          method: PUT
+          path: /{id}
+        - useCase: DeleteCustomer
+          method: DELETE
+          path: /{id}