eva4j 1.0.17 → 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-read-models.yaml

@@ -74,7 +74,7 @@ readModels:
     source:
       module: products
       aggregate: Product
-    tableName: rm_products
+    tableName: rm_orders_products
     fields:
       - name: id
         type: String
@@ -96,7 +96,7 @@ readModels:
     source:
       module: customers
       aggregate: Customer
-    tableName: rm_customers
+    tableName: rm_orders_customers
     fields:
       - name: id
         type: String

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}

package/examples/system/orders.yaml

@@ -0,0 +1,119 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# orders — Domain Model
+# ─────────────────────────────────────────────────────────────────────────────
+# Gestión de órdenes de compra. Usa readModels para mantener proyecciones
+# locales de Product y Customer, eliminando dependencias HTTP síncronas.
+# ─────────────────────────────────────────────────────────────────────────────
+
+aggregates:
+  - name: Order
+    entities:
+      - name: Order
+        isRoot: true
+        tableName: orders
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          - name: orderNumber
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Order number is required"
+          - name: customerId
+            type: String
+            reference:
+              aggregate: Customer
+              module: customer
+            validations:
+              - type: NotBlank
+                message: "Customer ID is required"
+          - name: productId
+            type: String
+            reference:
+              aggregate: Product
+              module: product
+            validations:
+              - type: NotBlank
+                message: "Product ID is required"
+          - name: quantity
+            type: Integer
+            validations:
+              - type: Positive
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true
+            defaultValue: "0.00"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Declarative REST endpoints
+# ─────────────────────────────────────────────────────────────────────────────
+endpoints:
+  basePath: /orders
+  versions:
+    - version: v1
+      operations:
+        - useCase: CreateOrder
+          method: POST
+          path: /
+        - useCase: GetOrder
+          method: GET
+          path: /{id}
+        - useCase: FindAllOrders
+          method: GET
+          path: /
+        - useCase: UpdateOrder
+          method: PUT
+          path: /{id}
+        - useCase: DeleteOrder
+          method: DELETE
+          path: /{id}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Read Models — proyecciones locales de datos de otros módulos
+# ─────────────────────────────────────────────────────────────────────────────
+# Cada readModel mantiene una tabla local (rm_*) sincronizada por eventos de
+# ciclo de vida del módulo productor. Elimina la necesidad de ports: (HTTP).
+# ─────────────────────────────────────────────────────────────────────────────
+readModels:
+  - name: ProductReadModel
+    source:
+      module: product
+      aggregate: Product
+    tableName: rm_orders_products
+    fields:
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+      - name: categoryId
+        type: String
+    syncedBy:
+      - event: ProductCreatedEvent
+        action: UPSERT
+      - event: ProductUpdatedEvent
+        action: UPSERT
+
+  - name: CustomerReadModel
+    source:
+      module: customer
+      aggregate: Customer
+    tableName: rm_orders_customers
+    fields:
+      - name: id
+        type: String
+      - name: fullName
+        type: String
+      - name: email
+        type: String
+    syncedBy:
+      - event: CustomerCreatedEvent
+        action: UPSERT
+      - event: CustomerUpdatedEvent
+        action: UPSERT
+      - event: CustomerDeletedEvent
+        action: DELETE

package/examples/system/product.yaml

@@ -80,6 +80,33 @@ aggregates:
           - DISCONTINUED
 
     events:
+      # ProductCreatedEvent — lifecycle: create → raise() in creation constructor
+      # Feeds readModels in consumer modules (e.g. orders/ProductReadModel)
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: categoryId
+            type: String
+
+      # ProductUpdatedEvent — lifecycle: update → raise() in update() method
+      - name: ProductUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: categoryId
+            type: String
+
       # ProductPublishedEvent — triggered by publish transition.
       # price: BigDecimal tests VO-unwrap: entity.price is Price, event expects BigDecimal
       # → generator should emit: this.getPrice().getAmount()