eva4j 1.0.16 → 1.0.18

package/docs/prototype/system/RISKS.md

@@ -0,0 +1,277 @@
+# Temporal-Only Architecture: Análisis de Riesgos y Trade-offs
+
+## 📐 Visión General
+
+Este documento analiza los riesgos de usar **Temporal como único mecanismo de 
+comunicación** entre módulos, reemplazando Kafka (async) y Feign (sync).
+
+Los archivos de diseño en esta carpeta (`docs/prototype/system/`) reflejan cómo 
+se vería la arquitectura `test-eva` bajo este enfoque.
+
+**Actualización (v2):** Se eliminaron Read Models. Los datos cross-module se 
+obtienen on-demand via Remote Activities de lectura (`GetCustomerById`, 
+`GetProductsByIds`). Se eliminaron 4 workflows que solo sincronizaban datos 
+(`ProductUpdated/Deactivated`, `CustomerCreated/Updated`). Esto reduce 
+significativamente el acoplamiento productor→consumidor (R1).
+
+---
+
+## 🔴 Riesgos Altos
+
+### R1. Acoplamiento del productor a sus consumidores
+
+**Kafka (actual):**
+```
+products publica ProductCreatedEvent → no sabe quién consume
+   ├── inventory (se suscribe solo)
+   └── orders (se suscribe solo)
+   └── [futuro módulo X] (se suscribe sin tocar products)
+```
+
+**Temporal (prototipo v2):**
+```
+products.ProductCreatedWorkflow lista explícitamente:
+   └── step: InitializeStock → target: inventory
+   (solo 1 consumer — efecto de negocio real, no sync de datos)
+
+Pero: cualquier workflow puede invocar GetProductById/GetProductsByIds
+sin que products lo sepa → desacoplamiento por lectura on-demand.
+```
+
+**Impacto (v2 — REDUCIDO):**
+Con la eliminación de read models, products ya no necesita saber que orders 
+consume sus datos. Solo mantiene `notifies: ProductCreatedWorkflow` porque 
+InitializeStock es un **efecto de negocio real** (crear stock), no sincronización.
+
+`customers` queda **completamente desacoplado** — sus Domain Events son internos 
+y no notifican a nadie. Los workflows de orders obtienen datos del cliente via 
+`GetCustomerById` (Remote Activity) on-demand.
+
+**Severidad:** 🟡 Media (reducida de 🔴 Alta) — el acoplamiento solo existe 
+para efectos de negocio reales (InitializeStock), no para sincronización de datos.
+
+---
+
+### R2. Pérdida de comunicación asíncrona real (fire-and-forget)
+
+**Kafka:** El productor publica y continúa. Los consumidores procesan a su ritmo.
+Si notifications tarda 30s en enviar un email, orders no se entera ni se bloquea.
+
+**Temporal:** Aunque una activity se marque como `type: async` en el workflow, el
+**workflow como instancia sigue vivo** hasta que todos los pasos terminen. Temporal
+trackea el estado de cada step. Si NotifyOrderPlaced falla 3 veces, el workflow
+completo queda en estado "running" indefinidamente.
+
+**Mitigación:** Usar `Async.function()` para activities non-critical 
+(notificaciones) y NOT registrar compensación en la saga. Si falla, el workflow 
+no se bloquea — solo se pierde la notificación.
+
+**Severidad:** 🔴 Alta — afecta resiliencia y operaciones.
+
+---
+
+### R3. Single Point of Failure: Temporal Server
+
+**Kafka:** El broker tiene replicación nativa (particiones, ISR). Si un broker 
+cae, otro toma el liderazgo de la partición. Los productores y consumidores 
+tienen decenas de librerías y patrones maduros para manejar desconexiones.
+
+**Temporal:** El Temporal Server (frontend + history + matching + worker services)
+es el punto central. Si cae:
+- Ningún workflow puede avanzar
+- Ninguna activity puede ejecutarse
+- La comunicación entre TODOS los módulos se detiene simultáneamente
+
+Temporal sí soporta clusters multi-nodo, pero la complejidad operativa es mayor
+que Kafka para este tipo de uso (Temporal no fue diseñado como message bus).
+
+**Severidad:** 🔴 Alta — riesgo operativo en producción.
+
+---
+
+## 🟡 Riesgos Medios
+
+### R4. Complejidad operativa: N workers por módulo
+
+Con Kafka, cada módulo tiene un consumer group. Escalar = agregar instancias.
+
+Con Temporal y module-prefixed queues, cada módulo tiene su propio set de queues:
+```
+{MODULE}_WORKFLOW_QUEUE, {MODULE}_LIGHT_TASK_QUEUE, {MODULE}_HEAVY_TASK_QUEUE
+```
+
+Esto permite **escalado selectivo** (ej: más workers para 
+`PAYMENT_HEAVY_TASK_QUEUE`), pero multiplica la cantidad de workers en deployment.
+
+**Severidad:** 🟡 Media — manejable con module-scoped queues.
+
+---
+
+### R5. Latencia on-demand vs Read Models locales
+
+Sin read models, cada workflow que necesita datos cross-module hace una llamada
+on-demand via Remote Activity:
+- `PlaceOrderWorkflow` → `GetCustomerById` (~5ms) + `GetProductsByIds` (~10ms)
+- `CancelOrderWorkflow` → `GetCustomerById` (~5ms)
+
+Con read models, esta data ya estaba en la BD local del módulo (~1ms).
+
+**Impacto:** ~10-15ms extra por workflow. Aceptable para volúmenes bajos/medios.
+Para alto volumen, se pueden agregar **caches con TTL** en las Activities sin 
+necesidad de read models persistentes.
+
+**Severidad:** 🟡 Media — trade-off aceptable para la simplificación obtenida.
+
+---
+
+### R6. Servicios externos siguen necesitando HTTP
+
+El módulo `payments` llama a un gateway externo de pagos 
+(`https://api.payments.example.com`). Ese servicio:
+- No corre workers Temporal
+- No entiende Activities
+- Solo expone HTTP
+
+Resultado: `ports[]` (Feign) **no puede eliminarse** para integraciones externas.
+Temporal solo reemplaza comunicación **interna** entre módulos propios.
+
+En la práctica, esto crea un modelo híbrido: Temporal entre módulos internos + 
+HTTP para servicios externos. La promesa de "un solo mecanismo" no se cumple.
+
+**Severidad:** 🟡 Media — la arquitectura no es tan uniforme como parece.
+
+---
+
+### R7. Modelo de Datos del Diseño: Secciones Nuevas sin soporte
+
+El prototipo introduce conceptos que eva4j no tiene:
+
+| Concepto nuevo | Dónde aparece | Genera código? |
+|---|---|---|
+| `orchestration:` en system.yaml | Reemplaza `messaging:` | ❌ No |
+| `workflows:` en system.yaml | Reemplaza `integrations:` | ❌ No |
+| `activities:` en domain.yaml | Concepto nuevo | ❌ No |
+| `notifies:` en events | Reemplaza `topic:` | ❌ No |
+| `parallel:` en workflow steps | Indica `Async.function()` | ❌ No |
+
+Implementar esto requiere nuevos generadores, templates, y validadores.
+
+**Nota:** `saga:` y `readModels.syncedBy.activity` fueron eliminados en v2.
+
+**Severidad:** 🟡 Media — alto esfuerzo de desarrollo en eva4j.
+
+---
+
+## 🟢 Riesgos Bajos (Ventajas del enfoque)
+
+### V1. Saga nativa con compensación
+
+El flujo `CreateOrder → GetCustomer → GetProducts ∥ ReserveStock → 
+ProcessPayment → ConfirmOrder → NotifyOrderPlaced` es **sustancialmente mejor** 
+con Temporal. La saga tiene compensación automática, timeouts durables, y 
+visibilidad del estado en el Temporal UI.
+
+Con Kafka, este mismo flujo requiere implementar manualmente:
+- Correlation IDs
+- Estado de la saga en base de datos
+- Compensación manual con eventos de rollback
+- Timeout checks con scheduled jobs
+
+**Veredicto:** Para este patrón específico, Temporal es claramente superior.
+
+---
+
+### V2. Observabilidad centralizada
+
+Cada workflow es visible en el Temporal UI con su historial completo: qué 
+activities se ejecutaron, cuáles fallaron, tiempos de ejecución, payloads.
+
+Con Kafka, rastrear un flujo cross-module requiere correlación de logs,
+distributed tracing (Zipkin/Jaeger), y mucha disciplina en los correlation IDs.
+
+---
+
+### V3. Retry con backoff nativo
+
+Temporal reintenta activities automáticamente con backoff exponencial configurable.
+Con Kafka, los retrys se implementan con DLQ (Dead Letter Queue), retry topics,
+o lógica manual en el consumer.
+
+---
+
+### V4. Simplicidad sin Read Models
+
+Eliminar read models simplifica significativamente la arquitectura:
+- No hay tablas `rm_*` que mantener sincronizadas
+- No hay workflows/listeners de sincronización
+- No hay riesgo de datos stale en proyecciones
+- Menos acoplamiento productor→consumidor (customers y products no notifican 
+  a nadie para sync)
+- Cada módulo es responsable solo de sus datos; otros acceden on-demand
+
+**Trade-off:** Latencia on-demand (~10ms vs ~1ms local). Mitigable con caches.
+
+---
+
+## 📊 Matriz Comparativa
+
+| Criterio | Kafka + Read Models | Temporal-only (v2, sin RM) |
+|---|---|---|
+| Acoplamiento productor→consumidor | ✅ Nulo | 🟡 Solo para efectos de negocio |
+| Agregar nuevo consumidor | ✅ Solo en consumidor | 🟡 Agregar Activity de lectura |
+| Fan-out 1→N | ✅ Nativo (topics) | ⚠️ Manual (N steps en workflow) |
+| Saga con compensación | ❌ Manual | ✅ Nativo |
+| Replay de eventos | ✅ Desde offset 0 | ❌ No disponible |
+| Observabilidad de flujos | ⚠️ Tracing externo | ✅ Temporal UI |
+| SPOF | ⚠️ Broker (mitigable) | 🔴 Temporal Server |
+| Servicios externos (HTTP) | ✅ Feign/ports[] | ⚠️ Híbrido obligatorio |
+| Complejidad operativa | ⚠️ Kafka + Zookeeper/KRaft | ⚠️ Temporal Server + Workers |
+| Soporte en eva4j | ✅ Completo | ❌ No existe |
+| Escalabilidad selectiva | ✅ Consumer groups | ✅ Module-prefixed queues |
+| Simplicidad del esquema | ⚠️ Tablas rm_* + sync | ✅ Sin proyecciones |
+| Latencia cross-module | ✅ Local (~1ms) | 🟡 On-demand (~10ms) |
+| Event sourcing futuro | ✅ Natural | ❌ No aplica |
+
+---
+
+## 🎯 Recomendación
+
+### Para este e-commerce: **Temporal-only es viable**
+
+Con la eliminación de read models, la arquitectura Temporal-only se simplifica 
+considerablemente. Los riesgos principales se reducen:
+
+```
+R1 (acoplamiento):  🔴 → 🟡  (solo efectos de negocio, no sync de datos)
+R5 (read models):   🟡 → ✅  (eliminado — reemplazado por latencia on-demand)
+```
+
+La arquitectura queda:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Comunicación                               │
+├──────────────────────────────┬───────────────────────────────┤
+│       Temporal               │   Feign (HTTP)                │
+│                              │                               │
+│ • Saga de orden              │ • Servicios externos          │
+│   (PlaceOrder, CancelOrder)  │   (payment gateway)           │
+│ • Efectos de negocio         │                               │
+│   (ProductCreated→InitStock) │                               │
+│ • Lectura on-demand          │                               │
+│   (GetCustomer, GetProducts) │                               │
+│ • Notificaciones             │                               │
+│   (Async.function, no-block) │                               │
+│ • Retry + compensación       │                               │
+└──────────────────────────────┴───────────────────────────────┘
+```
+
+### Cuándo escalar a Kafka + Temporal complementarios
+
+Si el sistema evoluciona a:
+- **15+ módulos** con fan-out 1→N frecuente → Kafka para eventos de dominio
+- **Alto volumen** donde ~10ms on-demand es inaceptable → Read Models + Kafka
+- **Event sourcing** necesario → Kafka como log de eventos
+
+Para un e-commerce de complejidad media-baja, Temporal-only cubre todos los 
+casos con menos infraestructura y menos complejidad operativa.

package/docs/prototype/system/customers.yaml

@@ -0,0 +1,133 @@
+# =============================================================================
+# PROTOTYPE: customers.yaml — versión Temporal (sin Kafka)
+# =============================================================================
+
+aggregates:
+  - name: Customer
+    entities:
+      - name: customer
+        isRoot: true
+        tableName: customers
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: firstName
+            type: String
+            validations:
+              - type: NotBlank
+                message: "First name is required"
+          - name: lastName
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Last name is required"
+          - name: email
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Email is required"
+              - type: Email
+                message: "Invalid email format"
+          - name: phone
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Phone number is required"
+          - name: address
+            type: Address
+
+    valueObjects:
+      - name: Address
+        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;"
+
+    events:
+      - name: CustomerCreatedEvent
+        lifecycle: create
+        fields:
+          - name: customerId
+            type: String
+          - name: firstName
+            type: String
+          - name: lastName
+            type: String
+          - name: email
+            type: String
+          - name: phone
+            type: String
+        # SIN notifies → Domain Event interno.
+        # Sin read models, no hay workflows de sincronización.
+        # Los workflows que necesitan datos de cliente los obtienen
+        # on-demand via GetCustomerById (Remote Activity).
+
+      - name: CustomerUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: customerId
+            type: String
+          - name: firstName
+            type: String
+          - name: lastName
+            type: String
+          - name: email
+            type: String
+          - name: phone
+            type: String
+        # SIN notifies → Domain Event interno.
+
+# ─── Activities que este módulo EXPONE ───────────────────────────────────────
+# Activity de lectura: permite a PlaceOrderWorkflow y CancelOrderWorkflow
+# obtener datos del cliente on-demand (nombre, email para notificaciones).
+activities:
+  - name: GetCustomerById
+    type: light
+    description: "Obtiene un cliente por su ID"
+    input:
+      - name: customerId
+        type: String
+    output:
+      - name: customerId
+        type: String
+      - name: firstName
+        type: String
+      - name: lastName
+        type: String
+      - name: email
+        type: String
+      - name: phone
+        type: String
+    timeout: 5s
+
+endpoints:
+  basePath: /customers
+  versions:
+    - version: v1
+      operations:
+        - useCase: GetCustomer
+          method: GET
+          path: /{id}
+        - useCase: FindAllCustomers
+          method: GET
+          path: /
+        - useCase: CreateCustomer
+          method: POST
+          path: /
+        - useCase: UpdateCustomer
+          method: PUT
+          path: /{id}

package/docs/prototype/system/inventory.yaml

@@ -0,0 +1,109 @@
+# =============================================================================
+# PROTOTYPE: inventory.yaml — versión Temporal (sin Kafka)
+# =============================================================================
+# Cambios vs original:
+#   - ELIMINA listeners[] — ya no consume ProductCreatedEvent por Kafka
+#   - AGREGA activities[] — expone Activities para que workflows las invoquen
+#   - endpoints, aggregates → SIN CAMBIOS
+# =============================================================================
+
+aggregates:
+  - name: Stock
+    entities:
+      - name: stock
+        isRoot: true
+        tableName: stock_items
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: productId
+            type: String
+            reference:
+              aggregate: Product
+              module: products
+            validations:
+              - type: NotBlank
+                message: "Product ID is required"
+          - name: quantity
+            type: Integer
+            validations:
+              - type: PositiveOrZero
+                message: "Quantity cannot be negative"
+
+# ─── Activities que este módulo EXPONE ───────────────────────────────────────
+activities:
+  - name: InitializeStock
+    type: light
+    description: "Crea un registro de stock inicial para un producto nuevo"
+    input:
+      - name: productId
+        type: String
+      - name: name
+        type: String
+    timeout: 10s
+
+  - name: ReserveStock
+    type: light
+    description: "Reserva stock para una orden"
+    input:
+      - name: orderId
+        type: String
+      - name: items
+        type: List<OrderItemDetail>
+    output:
+      - name: success
+        type: Boolean
+      - name: availableQuantity
+        type: Integer
+    externalTypes:
+      - name: OrderItemDetail
+        module: orders
+    timeout: 10s
+    compensation: ReleaseStock  # Compensación explícita
+
+  - name: ReleaseStock
+    type: light
+    description: "Libera stock reservado (compensación)"
+    input:
+      - name: orderId
+        type: String
+      - name: items
+        type: List<OrderItemDetail>
+    externalTypes:
+      - name: OrderItemDetail
+        module: orders
+    timeout: 10s
+
+  - name: DeleteStock
+    type: light
+    description: "Elimina stock de un producto (compensación de InitializeStock)"
+    input:
+      - name: productId
+        type: String
+    timeout: 5s
+
+# ─── ELIMINADOS: listeners[] ─────────────────────────────────────────────────
+# ProductCreatedEvent → ya no se consume. InitializeStock es una Activity.
+
+endpoints:
+  basePath: /inventory
+  versions:
+    - version: v1
+      operations:
+        - useCase: GetStock
+          method: GET
+          path: /{productId}
+        - useCase: FindAllStocks
+          method: GET
+          path: /
+        - useCase: AdjustStock
+          method: PUT
+          path: /{productId}/adjust
+        - useCase: ReserveStock
+          method: POST
+          path: /{productId}/reserve
+        - useCase: ReleaseStock
+          method: POST
+          path: /{productId}/release

package/docs/prototype/system/notifications.yaml

@@ -0,0 +1,131 @@
+# =============================================================================
+# PROTOTYPE: notifications.yaml — versión Temporal (sin Kafka, sin Read Models)
+# =============================================================================
+# Cambios vs original:
+#   - ELIMINA listeners[] (4 listeners de eventos Kafka)
+#   - ELIMINA readModels[] (CustomerReadModel) — datos de cliente llegan como
+#     input de las Activities, inyectados por el workflow caller
+#   - AGREGA activities[] — cada notificación es una Activity
+#   - Activities reciben datos del cliente directamente (no lookup local)
+# =============================================================================
+
+aggregates:
+  - name: Notification
+    entities:
+      - name: notification
+        isRoot: true
+        tableName: notifications
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: recipientEmail
+            type: String
+          - name: recipientPhone
+            type: String
+          - name: type
+            type: NotificationType
+          - name: channel
+            type: NotificationChannel
+          - name: status
+            type: NotificationStatus
+            readOnly: true
+          - name: subject
+            type: String
+          - name: body
+            type: String
+          - name: referenceId
+            type: String
+          - name: sentAt
+            type: LocalDateTime
+            readOnly: true
+
+    enums:
+      - name: NotificationType
+        values:
+          - ORDER_PLACED
+          - ORDER_CANCELLED
+          - PAYMENT_APPROVED
+          - PAYMENT_FAILED
+
+      - name: NotificationChannel
+        values:
+          - EMAIL
+          - SMS
+
+      - name: NotificationStatus
+        initialValue: PENDING
+        transitions:
+          - from: PENDING
+            to: SENT
+            method: markAsSent
+          - from: PENDING
+            to: FAILED
+            method: markAsFailed
+        values: [PENDING, SENT, FAILED]
+
+# ─── Activities que este módulo EXPONE ───────────────────────────────────────
+# Cada activity recibe TODA la data necesaria como input — zero lookups locales.
+# El workflow caller (PlaceOrderWorkflow, CancelOrderWorkflow) obtiene datos
+# del cliente via GetCustomerById y los pasa aquí directamente.
+activities:
+  - name: NotifyOrderPlaced
+    type: light
+    description: "Envía notificación de orden colocada al cliente"
+    input:
+      - name: orderId
+        type: String
+      - name: email
+        type: String
+      - name: firstName
+        type: String
+      - name: totalAmount
+        type: BigDecimal
+    timeout: 15s
+
+  - name: NotifyOrderCancelled
+    type: light
+    description: "Envía notificación de orden cancelada al cliente"
+    input:
+      - name: orderId
+        type: String
+      - name: email
+        type: String
+      - name: firstName
+        type: String
+    timeout: 15s
+
+  - name: NotifyPaymentApproved
+    type: light
+    description: "Envía notificación de pago aprobado al cliente"
+    input:
+      - name: orderId
+        type: String
+      - name: customerEmail
+        type: String
+      - name: customerName
+        type: String
+      - name: amount
+        type: BigDecimal
+    timeout: 15s
+
+  - name: NotifyPaymentFailed
+    type: light
+    description: "Envía notificación de pago fallido al cliente"
+    input:
+      - name: orderId
+        type: String
+      - name: customerEmail
+        type: String
+      - name: customerName
+        type: String
+      - name: reason
+        type: String
+    timeout: 15s
+
+# ─── ELIMINADOS: listeners[], readModels[], SyncCustomerReadModel ────────────
+# CustomerReadModel ELIMINADO — datos del cliente llegan como input directo.
+# SyncCustomerReadModel ELIMINADO — ya no hay proyección local que mantener.
+# Consecuencia: notifications es un módulo stateless para datos cross-module.
+# Solo persiste las notificaciones enviadas (entidad Notification).