eva4j 1.0.16 → 1.0.18

package/docs/prototype/system/orders.yaml

@@ -0,0 +1,241 @@
+# =============================================================================
+# PROTOTYPE: orders.yaml — versión Temporal (sin Kafka, sin Read Models)
+# =============================================================================
+# Cambios vs original:
+#   - ELIMINA listeners[] — el workflow ya integra la respuesta del pago
+#   - ELIMINA ports[] — la reserva de stock es una Activity del workflow
+#   - ELIMINA readModels[] — datos cross-module se obtienen on-demand via
+#     Remote Activities de lectura (GetCustomerById)
+#   - ELIMINA saga: — la saga se define en system.yaml workflows
+#   - events[].notifies referencia workflows definidos en system.yaml
+# =============================================================================
+
+aggregates:
+  - name: Order
+    entities:
+      - name: order
+        isRoot: true
+        tableName: orders
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          - name: customerId
+            type: String
+            reference:
+              aggregate: Customer
+              module: customers
+            validations:
+              - type: NotBlank
+                message: "Customer ID is required"
+          - name: status
+            type: OrderStatus
+            readOnly: true
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true
+            defaultValue: "0.00"
+          - name: itemCount
+            type: Integer
+            readOnly: true
+            defaultValue: 0
+          - name: shippingAddress
+            type: ShippingAddress
+          - name: notes
+            type: String
+        relationships:
+          - type: OneToMany
+            target: OrderItem
+            mappedBy: order
+            cascade: [PERSIST, MERGE, REMOVE]
+            fetch: LAZY
+
+      - name: orderItem
+        tableName: order_items
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: productId
+            type: String
+            reference:
+              aggregate: Product
+              module: products
+          - name: productName
+            type: String
+          - name: quantity
+            type: Integer
+            validations:
+              - type: Min
+                value: 1
+                message: "Quantity must be at least 1"
+          - name: unitPrice
+            type: BigDecimal
+            validations:
+              - type: Positive
+                message: "Unit price must be positive"
+          - name: subtotal
+            type: BigDecimal
+            readOnly: true
+
+    valueObjects:
+      - name: ShippingAddress
+        fields:
+          - name: street
+            type: String
+          - name: city
+            type: String
+          - name: department
+            type: String
+          - name: zipCode
+            type: String
+          - name: neighborhood
+            type: String
+        methods:
+          - name: format
+            returnType: String
+            parameters: []
+            body: "return street + \", \" + neighborhood + \", \" + city + \" (\" + department + \") \" + zipCode;"
+
+    enums:
+      - name: OrderStatus
+        initialValue: PENDING
+        transitions:
+          - from: PENDING
+            to: CONFIRMED
+            method: confirm
+          - from: PENDING
+            to: CANCELLED
+            method: cancel
+          - from: PENDING
+            to: PAYMENT_FAILED
+            method: failPayment
+        values: [PENDING, CONFIRMED, CANCELLED, PAYMENT_FAILED]
+
+    events:
+      - name: OrderPlacedEvent
+        lifecycle: create
+        fields:
+          - name: orderId
+            type: String
+          - name: placedAt
+            type: LocalDateTime
+        notifies:
+          - workflow: PlaceOrderWorkflow      # ← La saga completa
+
+      - name: OrderCancelledEvent
+        triggers:
+          - cancel
+        fields:
+          - name: orderId
+            type: String
+        notifies:
+          - workflow: CancelOrderWorkflow
+
+# ─── ELIMINADO: listeners[] ──────────────────────────────────────────────────
+# PaymentApprovedEvent y PaymentFailedEvent ya no llegan como eventos Kafka.
+# El PlaceOrderWorkflow espera el resultado de ProcessOrderPayment directamente
+# (paso sync en la saga). Si falla → compensa. Si aprueba → confirma.
+
+# ─── ELIMINADO: ports[] ─────────────────────────────────────────────────────
+# ReserveStock y ReleaseStock ya no son Feign calls.
+# Son Activities ejecutadas por el worker de inventory via Temporal.
+
+# ─── ELIMINADO: readModels[] ────────────────────────────────────────────────
+# CustomerReadModel y ProductReadModel ELIMINADOS.
+# Datos cross-module se obtienen ON-DEMAND en los workflows:
+#   - PlaceOrderWorkflow: GetCustomerById → customers (Remote Activity)
+#     Valida existencia, obtiene email/nombre para notificaciones.
+#   - CancelOrderWorkflow: GetCustomerById → customers
+#     Obtiene email para notificación de cancelación.
+#
+# Productos se validan al crear la orden; no se re-validan en la saga.
+
+# ─── ELIMINADO: saga: ───────────────────────────────────────────────────────
+# La saga (PlaceOrderWorkflow) se define en system.yaml, no en el módulo.
+# El CreateOrderCommandHandler persiste la orden y lanza el workflow.
+
+# ─── Activities del módulo ───────────────────────────────────────────────────
+# Activities LOCALES — invocadas por workflows cross-module (system.yaml)
+# y workflows single-module (definidos abajo).
+activities:
+  - name: GetOrderDetails
+    type: light
+    description: "Obtiene los detalles completos de una orden (items, totales, IDs relacionados)"
+    input:
+      - name: orderId
+        type: String
+    output:
+      - name: customerId
+        type: String
+      - name: items
+        type: List<OrderItemDetail>
+      - name: totalAmount
+        type: BigDecimal
+      - name: paymentId
+        type: String
+    nestedTypes:
+      - name: OrderItemDetail
+        fields:
+          - name: productId
+            type: String
+          - name: productName
+            type: String
+          - name: quantity
+            type: Integer
+          - name: unitPrice
+            type: BigDecimal
+          - name: subtotal
+            type: BigDecimal
+    timeout: 5s
+
+  - name: ConfirmOrder
+    type: light
+    description: "Confirma la orden tras pago exitoso (invocada por PlaceOrderWorkflow)"
+    input:
+      - name: orderId
+        type: String
+    timeout: 5s
+
+  - name: CancelExpiredOrder
+    type: light
+    description: "Cancela orden pendiente que no recibió pago a tiempo"
+    input:
+      - name: orderId
+        type: String
+    timeout: 5s
+
+# ─── Workflows single-module ────────────────────────────────────────────────
+# Flujos que NO cruzan fronteras de módulo → se definen aquí, no en system.yaml.
+workflows:
+  - name: ExpireOrderWorkflow
+    description: "Cancela la orden si no se recibe pago dentro del timeout"
+    trigger:
+      on: orderCreated
+    taskQueue: ORDER_WORKFLOW_QUEUE
+    steps:
+      - wait: paymentCompleted
+        timeout: 30m
+      - activity: CancelExpiredOrder
+        timeout: 5s
+
+endpoints:
+  basePath: /orders
+  versions:
+    - version: v1
+      operations:
+        - useCase: CreateOrder
+          method: POST
+          path: /
+        - useCase: GetOrder
+          method: GET
+          path: /{id}
+        - useCase: FindAllOrders
+          method: GET
+          path: /
+        - useCase: CancelOrder
+          method: PUT
+          path: /{id}/cancel

package/docs/prototype/system/payments.yaml

@@ -0,0 +1,256 @@
+# =============================================================================
+# PROTOTYPE: payments.yaml — versión Temporal (sin Kafka)
+# =============================================================================
+# Cambios vs original:
+#   - ELIMINA listeners[] — ya no consume OrderPlacedEvent por Kafka
+#   - ELIMINA events[] con topic: — ya no publica por Kafka
+#   - Los eventos internos siguen existiendo para lógica de dominio
+#   - ports[] SE MANTIENE — PaymentGateway es un servicio EXTERNO (no Temporal)
+#   - ProcessOrderPayment es ahora una Activity invocada por PlaceOrderWorkflow
+# =============================================================================
+
+aggregates:
+  - name: Payment
+    entities:
+      - name: payment
+        isRoot: true
+        tableName: payments
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: orderId
+            type: String
+            reference:
+              aggregate: Order
+              module: orders
+            validations:
+              - type: NotBlank
+                message: "Order ID is required"
+          - name: customerId
+            type: String
+            reference:
+              aggregate: Customer
+              module: customers
+          - name: amount
+            type: BigDecimal
+            validations:
+              - type: Positive
+                message: "Amount must be positive"
+              - type: NotNull
+                message: "Amount is required"
+          - name: currency
+            type: String
+            readOnly: true
+            defaultValue: "COP"
+          - name: status
+            type: PaymentStatus
+            readOnly: true
+          - name: paymentMethod
+            type: PaymentMethod
+          - name: transactionId
+            type: String
+            readOnly: true
+            hidden: true
+          - name: gatewayResponse
+            type: String
+            readOnly: true
+            hidden: true
+
+    enums:
+      - name: PaymentStatus
+        initialValue: PENDING
+        transitions:
+          - from: PENDING
+            to: APPROVED
+            method: approve
+          - from: PENDING
+            to: FAILED
+            method: fail
+          - from: APPROVED
+            to: REFUNDED
+            method: refund
+        values: [PENDING, APPROVED, FAILED, REFUNDED]
+
+      - name: PaymentMethod
+        values:
+          - CREDIT_CARD
+          - DEBIT_CARD
+          - PSE
+          - NEQUI
+          - CASH_ON_DELIVERY
+
+    events:
+      # Domain Events internos — siguen existiendo para la entidad.
+      # PERO ya no generan IntegrationEvent ni MessageBroker.
+      # El resultado del pago lo retorna la Activity directamente al workflow.
+      - name: PaymentApprovedEvent
+        triggers:
+          - approve
+        fields:
+          - name: paymentId
+            type: String
+          - name: orderId
+            type: String
+          - name: customerId
+            type: String
+          - name: amount
+            type: BigDecimal
+          - name: approvedAt
+            type: LocalDateTime
+        # ⚠️ SIN notifies: — el resultado viaja como retorno de Activity,
+        #    no como evento. El workflow ya sabe qué hacer.
+
+      - name: PaymentFailedEvent
+        triggers:
+          - fail
+        fields:
+          - name: paymentId
+            type: String
+          - name: orderId
+            type: String
+          - name: customerId
+            type: String
+          - name: reason
+            type: String
+
+# ─── Activities que este módulo EXPONE a workflows de otros módulos ──────────
+# Concepto nuevo: en Kafka, payments "escuchaba" OrderPlacedEvent.
+# Con Temporal, payments "ofrece" una Activity que el workflow de orders invoca.
+activities:
+  - name: ProcessOrderPayment
+    type: heavy                        # Puede tardar (gateway externo)
+    description: "Crea un pago y cobra al gateway externo"
+    input:
+      - name: orderId
+        type: String
+      - name: customerId
+        type: String
+      - name: totalAmount
+        type: BigDecimal
+    output:
+      - name: paymentId
+        type: String
+      - name: status
+        type: String                   # APPROVED | FAILED
+      - name: reason
+        type: String                   # null si APPROVED
+    timeout: 30s
+    retryPolicy:
+      maxAttempts: 3
+      initialInterval: 1s
+      backoffCoefficient: 2.0
+
+  - name: RefundPayment
+    type: heavy
+    description: "Reembolsa un pago aprobado (compensación de saga)"
+    input:
+      - name: paymentId
+        type: String
+    output:
+      - name: refundId
+        type: String
+      - name: status
+        type: String
+
+  # Activities INTERNAS — solo usadas por workflows single-module de payments
+  - name: RetryCharge
+    type: heavy
+    description: "Reintenta cobro al gateway externo"
+    input:
+      - name: paymentId
+        type: String
+    output:
+      - name: status
+        type: String
+      - name: reason
+        type: String
+    timeout: 30s
+
+  - name: MarkPaymentFailed
+    type: light
+    description: "Marca el pago como fallido definitivamente tras agotar reintentos"
+    input:
+      - name: paymentId
+        type: String
+    timeout: 5s
+
+# ─── Workflows single-module ────────────────────────────────────────────────
+# Flujos internos que NO cruzan fronteras de módulo.
+workflows:
+  - name: RetryChargeWorkflow
+    description: "Reintenta cobro fallido con backoff exponencial"
+    trigger:
+      on: chargeFailed
+    taskQueue: PAYMENT_WORKFLOW_QUEUE
+    steps:
+      - activity: RetryCharge
+        retryPolicy:
+          maxAttempts: 3
+          initialInterval: 2s
+          backoffCoefficient: 2.0
+      - activity: MarkPaymentFailed
+        timeout: 5s
+
+# ─── ELIMINADOS: listeners[] ─────────────────────────────────────────────────
+# OrderPlacedEvent ya no se consume. ProcessOrderPayment es una Activity.
+
+# ─── ports[] SE MANTIENE para servicios EXTERNOS (no-Temporal) ───────────────
+# PaymentGateway es un proveedor externo — no corre workers Temporal.
+# Para servicios externos, HTTP sigue siendo necesario.
+ports:
+  - name: processCharge
+    service: PaymentGatewayService
+    target: payment-gateway
+    baseUrl: https://api.payments.example.com
+    http: POST /charges
+    body:
+      - name: amount
+        type: BigDecimal
+      - name: currency
+        type: String
+      - name: paymentMethod
+        type: String
+      - name: description
+        type: String
+    fields:
+      - name: transactionId
+        type: String
+      - name: status
+        type: String
+      - name: message
+        type: String
+
+  - name: processRefund
+    service: PaymentGatewayService
+    target: payment-gateway
+    http: POST /refunds
+    body:
+      - name: transactionId
+        type: String
+      - name: amount
+        type: BigDecimal
+    fields:
+      - name: refundId
+        type: String
+      - name: status
+        type: String
+
+endpoints:
+  basePath: /payments
+  versions:
+    - version: v1
+      operations:
+        - useCase: CreatePayment
+          method: POST
+          path: /
+        - useCase: GetPayment
+          method: GET
+          path: /{id}
+        - useCase: FindAllPayments
+          method: GET
+          path: /
+        - useCase: RefundPayment
+          method: POST
+          path: /{id}/refund

package/docs/prototype/system/products.yaml

@@ -0,0 +1,168 @@
+# =============================================================================
+# PROTOTYPE: products.yaml — versión Temporal (sin Kafka)
+# =============================================================================
+# Cambios vs original:
+#   - events[] MANTIENE los Domain Events internos (raise() sigue funcionando)
+#   - ELIMINA topic: — ya no hay topics Kafka
+#   - AGREGA notifies: — lista de activities que el workflow debe invocar
+#   - endpoints, aggregates, enums → SIN CAMBIOS
+# =============================================================================
+
+aggregates:
+  - name: Product
+    entities:
+      - name: product
+        isRoot: true
+        tableName: products
+        hasSoftDelete: true
+        audit:
+          enabled: 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
+                message: "Price must be positive"
+              - type: NotNull
+                message: "Price is required"
+          - name: category
+            type: ProductCategory
+          - name: imageUrl
+            type: String
+          - name: sku
+            type: String
+            validations:
+              - type: NotBlank
+                message: "SKU is required"
+          - name: active
+            type: Boolean
+            readOnly: true
+            defaultValue: true
+
+    enums:
+      - name: ProductCategory
+        values:
+          - GRAINS
+          - DAIRY
+          - MEAT
+          - FRUITS
+          - VEGETABLES
+          - BEVERAGES
+          - CLEANING
+          - PERSONAL_CARE
+          - SNACKS
+          - OTHER
+
+    events:
+      # Domain Events internos se mantienen (raise() en la entidad).
+      # La diferencia: ya no generan IntegrationEvent ni MessageBroker.
+      # En su lugar, un WorkflowService los intercepta y lanza el workflow.
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: category
+            type: String
+        notifies:
+          - workflow: ProductCreatedWorkflow    # → InitializeStock en inventory
+
+      - name: ProductUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: category
+            type: String
+        # SIN notifies → Domain Event interno.
+        # Sin read models, no hay consumers cross-module para updates.
+        # Los workflows que necesitan datos de producto los obtienen
+        # on-demand via GetProductById / GetProductsByIds.
+
+      - name: ProductDeactivatedEvent
+        lifecycle: softDelete
+        fields:
+          - name: productId
+            type: String
+        # SIN notifies → Domain Event interno.
+        # Mismo razonamiento: sin read models, no hay consumers.
+
+# ─── Activities que este módulo EXPONE ───────────────────────────────────────
+# Activities de lectura: permiten a workflows de otros módulos obtener datos
+# de producto on-demand (Remote Activity), eliminando la necesidad de read models.
+activities:
+  - name: GetProductById
+    type: light
+    description: "Obtiene un producto por su ID"
+    input:
+      - name: productId
+        type: String
+    output:
+      - name: id
+        type: String
+      - name: name
+        type: String
+      - name: price
+        type: BigDecimal
+      - name: category
+        type: String
+      - name: sku
+        type: String
+    timeout: 5s
+
+  - name: GetProductsByIds
+    type: light
+    description: "Obtiene múltiples productos por sus IDs (batch)"
+    input:
+      - name: productIds
+        type: List<String>
+    output:
+      - name: products
+        type: List<String>             # List<{id, name, price, category, sku}>
+    timeout: 10s
+
+endpoints:
+  basePath: /products
+  versions:
+    - version: v1
+      operations:
+        - useCase: GetProduct
+          method: GET
+          path: /{id}
+        - useCase: FindAllProducts
+          method: GET
+          path: /
+        - useCase: CreateProduct
+          method: POST
+          path: /
+        - useCase: UpdateProduct
+          method: PUT
+          path: /{id}
+        - useCase: DeleteProduct
+          method: DELETE
+          path: /{id}
+
+# ─── ELIMINADO: No hay listeners (products no consume eventos) ───────────────
+# ─── ELIMINADO: No hay ports (products no llama a otros servicios) ────────────
+# ─── ELIMINADO: No hay readModels (products no proyecta datos ajenos) ─────────
+# ─── DESACOPLAMIENTO: products ya no necesita saber quién consume sus datos ──
+#     ProductUpdatedEvent y ProductDeactivatedEvent son Domain Events internos.
+#     Solo ProductCreatedEvent notifica ProductCreatedWorkflow (→ InitializeStock)
+#     porque es un efecto de negocio real, no sincronización de datos.