eva4j 1.0.16 → 1.0.18

package/src/commands/generate-usecase.js

@@ -5,7 +5,7 @@ const path = require('path');
 const fs = require('fs-extra');
 const ConfigManager = require('../utils/config-manager');
 const { isEva4jProject, moduleExists } = require('../utils/validator');
-const { toPackagePath, toPascalCase } = require('../utils/naming');
+const { toPackagePath, toPascalCase, toCamelCase } = require('../utils/naming');
 const { renderAndWrite } = require('../utils/template-engine');
 const ChecksumManager = require('../utils/checksum-manager');
 
@@ -32,6 +32,9 @@ async function generateUsecaseCommand(moduleName, usecaseName, options = {}) {
   const { packageName } = projectConfig;
   const packagePath = toPackagePath(packageName);
 
+  // Normalise module name to camelCase (system.yaml uses kebab-case, .eva4j.json stores camelCase)
+  moduleName = toCamelCase(moduleName);
+
   // Validate module exists
   if (!(await configManager.moduleExists(moduleName))) {
     console.error(chalk.red(`❌ Module '${moduleName}' not found in project configuration`));

package/src/skills/build-system-yaml/SKILL.md

@@ -47,6 +47,9 @@ Antes de generar nada, lee estos archivos del proyecto para obtener contexto:
 | 6.5 | `system/c4-context.mmd` + `system/c4-container.mmd` | Este archivo (sección C4) |
 | 7 | `system/{module}.yaml` (uno por módulo) | `references/domain-yaml-spec.md` |
 | 8 | `system/{module}.md` (uno por módulo) | `references/module-spec.md` |
+| 9a | `AGENTS.md` (project root — rewrite) | Este archivo (Paso 9) |
+| 9b | `system/VALIDATION_FLOWS.md` | Este archivo (Paso 9) |
+| 9c | `system/USER_FLOWS.md` | Este archivo (Paso 9) |
 
 Ejecuta **todos** los pasos en orden antes de devolver el control al usuario.
 
@@ -54,7 +57,14 @@ Ejecuta **todos** los pasos en orden antes de devolver el control al usuario.
 
 ## Paso 1 — Recopilar información
 
-Si el usuario no proveyó todos los datos, **pregunta** antes de generar:
+**Antes de preguntar nada**, verifica si ya existen artefactos del skill `requirements-elicitation`:
+- `system/FUNCTIONAL_REQUIREMENTS.md` — casos de uso, actores, ciclos de vida, integraciones externas
+- `system/PRODUCT_FLOWS.md` — flujos de negocio por actor (happy paths + alternativos)
+- `system/BUSINESS_RULES.md` — reglas de negocio, invariantes, restricciones
+
+Si existen, **léelos primero** y extrae de ellos el contexto de negocio. Reduce o elimina las preguntas que ya están respondidas por estos archivos. Estos documentos son la fuente de verdad funcional — los módulos, casos de uso, estados y reglas que diseñes deben ser consistentes con lo que describen.
+
+Si el usuario no proveyó todos los datos y los archivos anteriores no existen, **pregunta** antes de generar:
 
 0. **Contexto del negocio** — ¿Cuál es el dominio? Actores, procesos clave, reglas importantes.
 1. **¿Usa mensajería asíncrona?** `kafka` | `rabbitmq` | `sns-sqs`
@@ -62,11 +72,32 @@ Si el usuario no proveyó todos los datos, **pregunta** antes de generar:
 3. **Endpoints REST** por módulo (método + path + caso de uso)
 4. **Flujos async**: evento → productor → consumidores + `useCase` de cada consumidor
 5. **Llamadas sync**: caller → destino → endpoints usados
+6. **Dependencias de datos cross-module**: ¿algún módulo necesita datos de otro para validar o enriquecer? → candidato a **Read Model** (proyección local mantenida por eventos) en vez de llamada sync
 
 > Si `system/system.yaml` ya existe, léelo y pregunta solo por cambios.
 
 Aplica el rol funcional: sugiere módulos necesarios no mencionados, propone flujos async coherentes, anticipa invariantes. Confirma antes de agregar elementos no solicitados.
 
+### Read Models — decisión de diseño
+
+Cuando un módulo necesita datos de otro módulo, evalúa antes de decidir entre `ports:` (sync HTTP) y `readModels:` (async, proyección local):
+
+| Pregunta | Si la respuesta es SÍ → |
+|---|---|
+| ¿El dato se consulta en cada request o en operaciones frecuentes? | `readModels:` |
+| ¿Se tolera consistencia eventual (ms de delay)? | `readModels:` |
+| ¿Se prepara el sistema para microservicios (`eva detach`)? | `readModels:` |
+| ¿Se necesita consistencia fuerte (ej: saldo financiero)? | `ports:` |
+| ¿Es una llamada infrecuente y simple (ej: lookup puntual)? | `ports:` |
+
+**Patrón típico:** Si un módulo ya consume eventos de otro módulo (`listeners:`) y además llama sync para obtener datos del mismo módulo (`ports:`), es candidato fuerte a reemplazar el port por un readModel.
+
+Si decides usar readModel:
+1. En `system.yaml`: declarar eventos con `consumers[].readModel:` en vez de `useCase:`
+2. En `{module}.yaml`: declarar `readModels:` con `source`, `tableName`, `fields`, `syncedBy`
+3. Eliminar la entrada `integrations.sync[]` que reemplaza
+4. Asegurar que el módulo fuente emita los eventos necesarios en sus `events:` — usar `lifecycle:` para eventos CRUD (`create`/`update`/`delete`/`softDelete`) en vez de `triggers:`
+
 ---
 
 ## Paso 2 — Estructura del system.yaml
@@ -108,6 +139,13 @@ integrations:
       consumers:
         - module: payments
           useCase: HandleOrderPlaced
+    # Read Model sync — usa readModel: en vez de useCase:
+    - event: ProductCreatedEvent
+      producer: products
+      topic: PRODUCT_CREATED
+      consumers:
+        - module: orders
+          readModel: ProductReadModel    # proyección local de datos cross-module
   sync:
     - caller: orders
       calls: customers
@@ -134,6 +172,8 @@ integrations:
 - Sin port names genéricos compartidos entre módulos
 - `consumers[].useCase` siempre presente y en PascalCase
 - `calls.using:` solo referencia endpoints de `exposes:` del destino
+- Cada consumer declara exactamente `useCase:` (lógica de negocio) o `readModel:` (proyección local), nunca ambos
+- `readModel:` PascalCase + sufijo `ReadModel` — su módulo consumidor declara `readModels:` en domain.yaml
 
 ---
 
@@ -146,6 +186,8 @@ Antes de proponer el `system.yaml`, verifica:
 - [ ] Sin dependencias circulares síncronas
 - [ ] Todos los `consumers[].module` existen en `modules:`
 - [ ] Todos los `consumers[].useCase` presentes y en PascalCase
+- [ ] `consumers[]` con `readModel:` en PascalCase + sufijo `ReadModel`
+- [ ] Cada consumer tiene exactamente `useCase:` o `readModel:`, nunca ambos
 - [ ] Todos los `calls.using:` existen en `exposes:` del destino
 - [ ] Módulos pasivos no son `caller`
 - [ ] Todo en inglés
@@ -257,6 +299,7 @@ C4Container
 - `ContainerQueue()` para el broker — solo si `messaging.enabled: true`; usar el tipo de `messaging.broker`
 - `System_Ext()` fuera del boundary para servicios externos
 - **Flechas async siempre pasan por el broker**: `producer → broker` y `broker → consumer`, nunca directo
+- **Read Model sync también pasa por el broker**: `Rel(source, broker, "ProductCreatedEvent", "Kafka")` + `Rel(broker, consumer, "Sync ProductReadModel", "Kafka")` — no usar flecha directa
 - **Flechas sync** directas entre containers: de caller a callee con label del port name
 - Los `Rel()` de eventos incluyen el nombre del evento en el campo `technology`/label
 - Derivar actores `Person()` de quienes consumen los `exposes[]`
@@ -302,7 +345,118 @@ Antes de guardar, verifica:
 
 Lee `references/domain-yaml-spec.md` para la especificación completa de estructura, reglas, restricciones y checklist del `system/{module}.yaml`.
 
-Para cada módulo en `modules:`, genera `system/{nombre-del-modulo}.yaml` con: aggregates, entities, valueObjects, enums (con transitions si aplica), events, endpoints, listeners y ports — todo inferido del `system.yaml`.
+Para cada módulo en `modules:`, genera `system/{nombre-del-modulo}.yaml` con: aggregates, entities, valueObjects, enums (con transitions si aplica), events, endpoints, listeners, ports y **readModels** — todo inferido del `system.yaml`.
+
+### Endpoints en módulos con múltiples agregados
+
+Si el módulo tiene **2 o más agregados** (ej: `Product` + `Category`), la sección `endpoints:` debe usar `basePath: ""` (string vacío) y paths **absolutos** en cada operación:
+
+```yaml
+# Módulo con 2+ agregados → basePath vacío
+endpoints:
+  basePath: ""
+  versions:
+    - version: v1
+      operations:
+        - useCase: CreateProduct
+          method: POST
+          path: /products
+        - useCase: CreateCategory
+          method: POST
+          path: /categories
+```
+
+Si el módulo tiene **un solo agregado**, usar `basePath: /recurso` con paths relativos (ej: `/`, `/{id}`).
+
+**NUNCA usar `basePath: /`** (con slash) — genera trailing slash en `@RequestMapping`. Usar `basePath: ""` (vacío).
+
+### Inferencia de readModels desde system.yaml
+
+Cuando `integrations.async[].consumers[]` tiene `readModel:` y el `module` es el módulo actual:
+1. Agrupar todos los eventos del mismo `readModel:` → una entrada `readModels:` con múltiples `syncedBy`
+2. `source.module` = el `producer` de esas integraciones async
+3. `source.aggregate` = derivar del nombre del readModel (ej: `ProductReadModel` → `Product`)
+4. `tableName` = `rm_` + consumer module + `_` + source module en snake_case (ej: `rm_orders_products`)
+5. `fields` = inferir del payload del evento fuente (incluir siempre `id`)
+6. `syncedBy[].action` = `UPSERT` para Created/Updated, `SOFT_DELETE` para Deactivated, `DELETE` para Deleted
+7. Si había una entrada `integrations.sync[]` al mismo módulo fuente → **no generar `ports:`** para esa llamada (el readModel la reemplaza)
+
+### Lifecycle events en módulos fuente
+
+Cuando el módulo actual es `producer` en `integrations.async[]` y algún consumer tiene `readModel:`, los eventos de este módulo deben usar `lifecycle:` (operación CRUD) en vez de `triggers:` (transición de estado).
+
+Para cada evento de este módulo consumido por un readModel:
+
+1. Agregar `lifecycle:` al evento — derivar el valor del nombre del evento:
+   | Patrón del nombre | `lifecycle:` |
+   |---|---|
+   | `*CreatedEvent`, `*RegisteredEvent` | `create` |
+   | `*UpdatedEvent` | `update` |
+   | `*DeletedEvent` | `delete` |
+   | `*DeactivatedEvent` | `softDelete` |
+
+2. **NO** agregar `triggers:` — estos eventos son CRUD, no transiciones de estado
+3. Si `lifecycle: softDelete` → la entidad raíz **debe** tener `hasSoftDelete: true`
+4. Si `lifecycle: delete` → la entidad raíz **NO debe** tener `hasSoftDelete: true`
+5. `fields:` del evento debe incluir **todos** los campos declarados en el `readModels[].fields` del módulo consumidor (el payload es la fuente de verdad de la proyección)
+6. Siempre incluir `{entityName}Id` como campo (se mapea a `aggregateId` del DomainEvent base)
+7. `fields:` del lifecycle event solo puede contener: (a) `{entityName}Id` (aggregateId), (b) campos que existen en la entidad raíz, (c) campos temporales `*At` + `LocalDateTime`. No incluir campos que no existan en la entidad — genera error `C2-010`
+8. Los campos de los readModels consumidores deben ser subconjunto de los campos de la entidad raíz del productor. Si el readModel necesita un campo, ese campo debe existir en la entidad fuente — de lo contrario los lifecycle events no podrán emitirlo (C2-010) y el campo siempre será null (C1-007)
+
+**Ejemplo — módulo `products` como fuente de `ProductReadModel`:**
+
+```yaml
+aggregates:
+  - name: Product
+    entities:
+      - name: product
+        isRoot: true
+        tableName: products
+        hasSoftDelete: true
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+            readOnly: true
+            defaultValue: "ACTIVE"
+    events:
+      - name: ProductCreatedEvent
+        lifecycle: create
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductUpdatedEvent
+        lifecycle: update
+        fields:
+          - name: productId
+            type: String
+          - name: name
+            type: String
+          - name: price
+            type: BigDecimal
+          - name: status
+            type: String
+      - name: ProductDeactivatedEvent
+        lifecycle: softDelete
+        fields:
+          - name: productId
+            type: String
+          - name: deactivatedAt
+            type: LocalDateTime
+```
 
 ---
 
@@ -314,10 +468,197 @@ Para cada módulo, genera `system/{nombre-del-modulo}.md` con: rol del módulo,
 
 ---
 
+## Paso 9 — Artefactos post-diseño
+
+Inmediatamente después de completar el Paso 8, genera tres artefactos finales que contextualizan el sistema recién diseñado.
+
+### Paso 9a — Reescribir AGENTS.md (project-specific)
+
+Reescribe el archivo `AGENTS.md` en la **raíz del proyecto** con contenido específico para el sistema diseñado.
+
+**Proceso:**
+
+1. Lee el `AGENTS.md` actual como template base
+2. Analiza `system/system.yaml` y todos los `system/{module}.yaml` para detectar qué features se usan:
+   - Tipo de broker (Kafka / RabbitMQ / ninguno)
+   - `readModels:` en algún módulo
+   - `ports:` (llamadas HTTP síncronas)
+   - `listeners:` (consumidores de eventos)
+   - `events:` con `triggers:` vs `lifecycle:`
+   - `hasSoftDelete` en alguna entidad
+   - `audit.trackUser` en alguna entidad
+   - Value Objects con `methods:`
+   - Enums con `transitions:` e `initialValue`
+   - Flags de campo: `readOnly`, `hidden`, `defaultValue`, `validations`, `reference`
+3. **Poda** secciones de features no usados según estas reglas:
+
+| Condición | Sección a eliminar |
+|---|---|
+| Sin Temporal | "Temporal Workflows" completa |
+| Sin `readModels:` | Subsecciones readModels de "Características Avanzadas" y checklist |
+| Sin `ports:` | Subsecciones ports |
+| Sin `listeners:` | Subsecciones listeners |
+| Sin `hasSoftDelete` | Sección soft delete y checklist items |
+| Sin `audit.trackUser` | Infraestructura UserContextFilter/UserContextHolder/AuditorAwareImpl (mantener audit básico si `audit.enabled`) |
+| Sin VO `methods:` | "Value Objects con Métodos" |
+| Sin enum `transitions:` | "Enums con Ciclo de Vida" |
+
+4. **Especializa** el contenido restante:
+   - Reemplaza ejemplos genéricos (`User`, `Order`) con entidades/módulos reales del proyecto
+   - Actualiza la sección de comandos `eva` con los nombres de módulos reales
+   - Actualiza el ejemplo de `domain.yaml` con la estructura real del proyecto
+   - Reduce el checklist a solo items relevantes para este proyecto
+5. Agrega un **header de contexto** al inicio:
+
+```markdown
+# AI Agent Guide — {System Name}
+
+## Project Overview
+- **System:** {name} — {brief description from system.yaml}
+- **Modules:** {list of modules with 1-line descriptions}
+- **Messaging:** {broker type or "none"}
+- **Database:** {database type}
+- **Java:** {javaVersion} / **Spring Boot:** {springBootVersion}
+```
+
+6. **Siempre conserva** (son universales): principios DDD, arquitectura hexagonal, reglas de mappers, reglas de DTOs, diagramas de flujo de datos (Command write / Query read), patrones de testing
+7. Escribe **todo en inglés**
+8. **Límite: ≤ 1000 líneas** — poda agresivamente, comprime ejemplos, evita redundancia
+
+---
+
+### Paso 9b — Crear system/VALIDATION_FLOWS.md
+
+Genera `system/VALIDATION_FLOWS.md` con los flujos de validación técnica del sistema. Toda la información se deriva de `system.yaml` y los `{module}.yaml`.
+
+**Estructura obligatoria:**
+
+```markdown
+# Validation Flows — {System Name}
+
+## Prerequisites
+- Services: {infrastructure requerida — DB, broker, etc.}
+- Startup order: {si relevante}
+- Base URLs: {por módulo si difieren}
+
+## 1. Module Validation
+
+### 1.1 {Module Name}
+
+#### CRUD Operations
+| # | Operation | Endpoint | Payload/Params | Expected Result | Validates |
+|---|-----------|----------|----------------|-----------------|------ ----|
+| 1 | Create | POST /x | {key fields} | 201 + entity | {invariant} |
+| 2 | Get by ID | GET /x/{id} | — | 200 + entity | — |
+| 3 | List | GET /x | — | 200 + page | — |
+| 4 | Update | PUT /x/{id} | {fields} | 200 + updated | — |
+| 5 | Delete | DELETE /x/{id} | — | 204 | — |
+
+#### State Transitions (if module has enum transitions)
+| # | Transition | Endpoint | Precondition | Expected | Event Emitted |
+|---|-----------|----------|--------------|----------|---------------|
+| 1 | DRAFT→PUBLISHED | PUT /x/{id}/publish | exists in DRAFT | 200, status=PUBLISHED | XPublishedEvent |
+
+#### Business Rules
+| # | Rule | How to Trigger | Expected Error |
+|---|------|----------------|----------------|
+
+(repeat per module)
+
+## 2. Integration Flows
+
+### 2.1 {Flow Name}: {Event} → {Consumer Module}
+**Trigger:** {action that emits the event}
+**Steps:**
+1. {Create/modify entity in producer module}
+2. {Event emitted}: {EventName} on topic {TOPIC_NAME}
+3. {Consumer module} processes via {useCase}
+4. **Verify:** {expected state change in consumer}
+
+(repeat per async integration)
+
+## 3. Read Model Synchronization (if applicable)
+### 3.1 {ReadModelName}
+| Source Event | Action | Verification |
+|---|---|---|
+| XCreatedEvent | UPSERT | Query rm_table, record exists |
+| XUpdatedEvent | UPSERT | Fields updated |
+| XDeactivatedEvent | SOFT_DELETE | Record marked deleted |
+
+## 4. Sync Port Calls (if applicable)
+### 4.1 {PortName}: {caller} → {target}
+| Method | Expected | Fallback |
+|---|---|---|
+
+## 5. Error & Edge Cases
+| # | Scenario | Steps | Expected Error |
+|---|----------|-------|----------------|
+| 1 | Create with missing required field | POST /x without {field} | 400 + validation message |
+| 2 | Invalid state transition | PUT /x/{id}/action when invalid state | 400/409 + business error |
+| 3 | Get non-existent entity | GET /x/{invalid-id} | 404 |
+```
+
+**Reglas:**
+- Cada flujo debe ser concreto: paths reales, nombres de eventos reales, campos reales del proyecto
+- Incluir payloads JSON sugeridos donde sea útil
+- Omitir secciones enteras si no aplican (ej: sin readModels → omitir sección 3)
+- Todo en inglés
+
+---
+
+### Paso 9c — Crear system/USER_FLOWS.md
+
+Genera `system/USER_FLOWS.md` con los flujos end-to-end desde la perspectiva del usuario.
+
+**Estructura obligatoria:**
+
+```markdown
+# User Flows — {System Name}
+
+## Actors
+| Actor | Description | Modules Interacted |
+|-------|-------------|--------------------|
+| {Actor 1} | {role description} | {module list} |
+
+## Flow 1: {Business Process Name}
+**Actor:** {who}
+**Goal:** {what they want to achieve}
+**Preconditions:** {initial state}
+
+### Happy Path
+| Step | User Action | System Response | Behind the Scenes |
+|------|-------------|-----------------|-------------------|
+| 1 | {does X} | {sees Y} | {endpoint called, event emitted, etc.} |
+| 2 | {does Z} | {sees W} | {consumer processes, state changes} |
+
+### Alternative Paths
+| Condition | At Step | What Happens |
+|-----------|---------|---------- ---|
+| {condition} | {N} | {alternative outcome} |
+
+### Error Paths
+| Error | At Step | User Sees |
+|-------|---------|----------|
+| {error} | {N} | {error message/behavior} |
+
+(repeat per major business flow)
+```
+
+**Reglas:**
+- Derivar actores de quienes consumen los `exposes[]` (misma fuente que `Person()` del C4 Context)
+- Cada flujo es un **escenario de negocio completo** que cruza módulos cuando aplica
+- La columna "Behind the Scenes" conecta la experiencia de usuario con la realidad técnica (eventos, procesamiento async, state changes)
+- Incluir al menos un flujo por cada camino principal de caso de uso del sistema
+- Foco en comportamiento observable por el usuario, no implementación interna
+- Todo en inglés
+
+---
+
 ## Ciclo de refinamiento
 
 Después de entregar v1, si el usuario pide ajustes:
 - Aplica el **cambio mínimo** necesario
 - Revalida el checklist del Paso 4
 - Actualiza `system.md`, `c4-context.mmd`, `c4-container.mmd`, `{module}.yaml` y `{module}.md` afectados
+- Actualiza `AGENTS.md`, `VALIDATION_FLOWS.md` y `USER_FLOWS.md` si fueron afectados por el cambio
 - Entrega solo el diff explicado