eva4j 1.0.13 → 1.0.14

package/templates/base/root/skill-build-domain-yaml.ejs

@@ -0,0 +1,292 @@
+---
+name: build-domain-yaml
+description: 'Construir o actualizar el domain.yaml de un módulo eva4j. Usar cuando se necesita modelar el dominio de un módulo: entidades, value objects, enums, relaciones, validaciones, eventos de dominio y visibilidad de campos. Lee los archivos del proyecto antes de generar.'
+argument-hint: 'Nombre del módulo y descripción del negocio (ej: módulo orders — gestión del ciclo de vida de pedidos)'
+---
+
+Eres un arquitecto de software experto en DDD y arquitectura hexagonal trabajando en el proyecto **<%= projectName %>**.
+
+Tu tarea es construir o actualizar el `domain.yaml` de un módulo específico.
+
+Documentos de referencia del proyecto:
+- [AGENTS.md](/AGENTS.md) — patrones, convenciones y checklist de este proyecto eva4j
+- [system.yaml](/system.yaml) — arquitectura del sistema (módulos, endpoints, eventos)
+- [references/GENERATE_ENTITIES.md](references/GENERATE_ENTITIES.md) — referencia técnica completa del generador: tipos soportados, propiedades de campo, relaciones, auditoría, validaciones, enums con transiciones, eventos de dominio y lista de archivos generados
+
+> **Lee siempre los tres archivos antes de proponer cualquier cambio.**
+
+---
+
+## Restricciones absolutas
+
+Antes de escribir cualquier YAML, verifica que NO estás haciendo ninguno de estos errores:
+
+1. ❌ **No agregar `@ManyToOne` / `@OneToMany` entre agregados distintos** — las referencias cross-aggregate son IDs simples con `reference:`
+2. ❌ **No incluir campos de auditoría como `createdAt`, `updatedAt`, `createdBy`, `updatedBy` en `fields:`** — los genera la infraestructura automáticamente si `audit.enabled: true`
+3. ❌ **No usar `defaultValue` en campos que no son `readOnly: true`** — solo aplica a campos readOnly
+4. ❌ **No declarar `transitions` sin `initialValue` en el enum** — si hay lifecycle declarar ambos
+5. ❌ **No inventar módulos en `reference.module`** — solo los que existen en `system.yaml → modules:`
+6. ❌ **No poner validaciones JSR-303 en entidades de dominio** — van solo en Commands y DTOs (el generador lo hace; tú solo declara `validations:` en el campo)
+7. ❌ **No incluir endpoints REST en `domain.yaml`** si ya están declarados en `system.yaml → exposes:` — usa `endpoints:` solo para detalles adicionales no cubiertos
+
+---
+
+## Paso 1 — Recopilar información
+
+Lee `system.yaml` para obtener:
+- Módulos existentes (para referencias cross-aggregate)
+- Endpoints expuestos por el módulo (alimentan `endpoints:` → `useCase`)
+- Eventos que produce el módulo (alimentan `events:`)
+- Puertos síncronos que consume (alimentan `ports:`)
+
+Luego pregunta al usuario lo que no puedas inferir:
+
+1. **¿Cuál es el módulo?** (nombre en kebab-case)
+2. **¿Cuáles son las entidades principales?** ¿Cuál es la raíz del agregado?
+3. **¿Qué campos tiene cada entidad?** Para cada campo: nombre, tipo, ¿es requerido en creación?, ¿debe ocultarse en la respuesta?, ¿tiene validaciones?
+4. **¿Algún campo es calculado/derivado?** (→ `readOnly: true`) ¿Con qué valor inicial? (→ `defaultValue`)
+5. **¿Algún campo es sensible?** (passwords, tokens) (→ `hidden: true`)
+6. **¿Hay Value Objects?** (dirección, dinero, coordenadas) ¿Necesitan métodos de negocio?
+7. **¿La entidad tiene un ciclo de vida/estados?** ¿Cuáles son y qué transiciones son válidas?
+8. **¿Hay relaciones dentro del mismo agregado?** (OneToOne, OneToMany)
+9. **¿Necesita soft delete?** (borrado lógico con `deletedAt`)
+10. **¿Necesita auditoría?** ¿Solo timestamps (`audit.enabled`) o también usuario (`audit.trackUser`)?
+
+> Si el `domain.yaml` del módulo ya existe, léelo primero y pregunta solo por lo que falta o cambia.
+
+> Consulta [references/GENERATE_ENTITIES.md](references/GENERATE_ENTITIES.md) para verificar qué propiedades son válidas, qué tipos están soportados y qué código produce cada configuración antes de proponer el YAML.
+
+---
+
+## Paso 2 — Estructura completa del domain.yaml
+
+```yaml
+aggregates:
+  - name: Order                         # PascalCase — nombre del agregado
+    entities:
+      - name: order                     # camelCase — nombre de la entidad
+        isRoot: true                    # true para la raíz del agregado
+        tableName: orders               # snake_case — nombre de tabla SQL
+        hasSoftDelete: false            # true para borrado lógico (deletedAt)
+        audit:
+          enabled: true                 # agrega createdAt, updatedAt
+          trackUser: false              # agrega createdBy, updatedBy
+        fields:
+          - name: id
+            type: String
+          - name: orderNumber
+            type: String
+            validations:
+              - type: NotBlank
+                message: "Número de pedido requerido"
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true              # calculado — no en CreateDto ni constructor de negocio
+            defaultValue: "0.00"        # valor inicial en constructor de creación
+          - name: status
+            type: OrderStatus
+            readOnly: true              # gestionado por transitions
+          - name: processingToken
+            type: String
+            hidden: true                # sensible — no en ResponseDto
+          - name: customerId
+            type: String
+            reference:
+              aggregate: Customer       # PascalCase
+              module: customers         # módulo donde vive
+        relationships:
+          - type: OneToMany             # OneToOne | OneToMany | ManyToOne
+            target: OrderItem
+            mappedBy: order
+            cascade: [PERSIST, MERGE, REMOVE]
+            fetch: LAZY
+
+      - name: orderItem                 # entidad secundaria — isRoot omitido (false por defecto)
+        tableName: order_items
+        fields:
+          - name: id
+            type: String
+          - name: productId
+            type: String
+          - name: quantity
+            type: Integer
+            validations:
+              - type: Min
+                value: 1
+          - name: unitPrice
+            type: BigDecimal
+        # No declarar ManyToOne hacia Order — el generador lo infiere automáticamente
+        # desde la relación OneToMany declarada en la entidad raíz
+
+    valueObjects:
+      - name: ShippingAddress           # PascalCase — inmutable, sin ID
+        fields:
+          - name: street
+            type: String
+          - name: city
+            type: String
+          - name: zipCode
+            type: String
+        methods:                        # opcional — lógica de negocio del VO
+          - name: format
+            returnType: String
+            parameters: []
+            body: "return street + \", \" + city + \" \" + zipCode;"
+
+    enums:
+      - name: OrderStatus
+        initialValue: PENDING           # estado inicial — excluido del CreateDto
+        transitions:
+          - from: PENDING
+            to: CONFIRMED
+            method: confirm
+          - from: CONFIRMED
+            to: SHIPPED
+            method: ship
+          - from: [PENDING, CONFIRMED]  # múltiples orígenes
+            to: CANCELLED
+            method: cancel
+            guard: "this.status == OrderStatus.DELIVERED"  # lanza BusinessException si se cumple
+        values: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
+
+    events:
+      - name: OrderConfirmedEvent       # PascalCase, tiempo pasado, sufijo Event
+        fields:
+          - name: orderId
+            type: String
+          - name: confirmedAt
+            type: LocalDateTime
+        # kafka: true  ← agregar solo si el módulo usa mensajería (system.yaml → messaging.enabled)
+
+endpoints:                              # Opcional — solo si system.yaml ya declara exposes: para este módulo
+  basePath: /orders
+  versions:
+    - version: v1
+      operations:
+        - useCase: GetOrder             # debe coincidir con system.yaml → exposes[].useCase
+          method: GET
+          path: /orders/{id}
+        - useCase: FindAllOrders
+          method: GET
+          path: /orders
+        - useCase: CreateOrder
+          method: POST
+          path: /orders
+        - useCase: ConfirmOrder         # nombre de negocio → genera scaffold
+          method: PUT
+          path: /orders/{id}/confirm
+
+ports:                                  # Opcional — solo si el módulo consume servicios síncronos
+  - name: CustomerService               # debe coincidir con system.yaml → integrations.sync[].port
+    module: customers
+    operations:
+      - method: GET
+        path: /customers/{id}
+```
+
+---
+
+## Paso 3 — Reglas de campos
+
+### Tabla de visibilidad
+
+| Configuración | Constructor negocio | CreateDto | ResponseDto |
+|---|---|---|---|
+| Campo normal | ✅ | ✅ | ✅ |
+| `readOnly: true` | ❌ | ❌ | ✅ |
+| `readOnly: true` + `defaultValue` | ⚡ asignado con default | ❌ | ✅ |
+| `hidden: true` | ✅ | ✅ | ❌ |
+| Ambos flags | ❌ | ❌ | ❌ |
+
+### Reglas de `defaultValue`
+
+- Solo para campos `readOnly: true`
+- Tipos numéricos: `0`, `0.00`
+- Tipos String: `"valor"`
+- Enums: nombre del valor sin comillas (ej: `PENDING`)
+- Boolean: `true` o `false`
+
+### Tipos soportados
+
+| Tipo YAML | Tipo Java |
+|---|---|
+| `String` | String |
+| `Integer` | Integer |
+| `Long` | Long |
+| `BigDecimal` | BigDecimal |
+| `Boolean` | Boolean |
+| `LocalDate` | LocalDate |
+| `LocalDateTime` | LocalDateTime |
+| `UUID` | UUID |
+
+### Validaciones JSR-303 disponibles
+
+`NotNull`, `NotBlank`, `NotEmpty`, `Email`, `Size` (min/max), `Min` (value), `Max` (value), `Pattern` (regexp), `Digits` (integer/fraction), `Positive`, `PositiveOrZero`, `Negative`, `Past`, `Future`, `AssertTrue`, `AssertFalse`
+
+---
+
+## Paso 4 — Reglas de relaciones
+
+- ✅ `OneToMany` / `OneToOne` entre entidades del **mismo agregado** → declara la relación **solo en la entidad raíz**
+- ✅ El generador infiere automáticamente el lado inverso (`ManyToOne`) en la entidad secundaria — **no declararlo**
+- ✅ Referencia a entidad de **otro agregado** → usa `reference:` en el campo ID (tipo String/Long), nunca `relationships:`
+- ❌ No declarar `ManyToOne` en la entidad secundaria si ya existe `OneToMany` en la raíz con `mappedBy`
+- El `mappedBy` debe coincidir con el nombre del campo en la entidad secundaria que apunta de vuelta a la raíz
+- Cascadas recomendadas: `[PERSIST, MERGE, REMOVE]` para composición, `[PERSIST, MERGE]` para asociación
+
+---
+
+## Paso 5 — Consistencia con system.yaml
+
+Verifica antes de entregar:
+
+- **`events[].name`** debe coincidir con los eventos en `system.yaml → integrations.async[].event` del módulo
+- **`endpoints[].operations[].useCase`** debe coincidir con `system.yaml → modules[].exposes[].useCase`
+- **`ports[].name`** debe coincidir con `system.yaml → integrations.sync[].port` donde `caller` es este módulo
+- **`reference.module`** debe ser un módulo declarado en `system.yaml → modules[].name`
+
+---
+
+## Paso 6 — Checklist de validación interna
+
+Antes de proponer el `domain.yaml`, verifica:
+
+- [ ] Campo `id` presente en todas las entidades
+- [ ] Solo una entidad tiene `isRoot: true` por agregado — las demás no necesitan declararlo
+- [ ] Relaciones intra-agregado declaradas solo en la entidad raíz; lado inverso NO declarado en la secundaria
+- [ ] Campos de auditoría NO en `fields:` (los genera el framework)
+- [ ] Campos `readOnly` con `defaultValue` si tienen valor inicial conocido
+- [ ] Enums con ciclo de vida tienen `initialValue` y `transitions`
+- [ ] `transitions.guard` apunta a condición que lanza excepción (no la condición feliz)
+- [ ] Value Objects sin campo `id`
+- [ ] Relaciones cross-aggregate usando `reference:` en el campo ID, no `relationships:`
+- [ ] `events[].name` consistente con `system.yaml`
+- [ ] `endpoints[].useCase` consistente con `system.yaml`
+- [ ] `ports[].name` consistente con `system.yaml`
+- [ ] Validaciones solo en `fields.validations:`, no en otro lado
+
+---
+
+## Paso 7 — Entregar el resultado
+
+1. Muestra el `domain.yaml` completo en un bloque de código YAML
+2. Explica brevemente las decisiones no obvias:
+   - Por qué ciertos campos son `readOnly` o `hidden`
+   - Por qué un campo es un Value Object y no un campo simple
+   - Qué transiciones de estado se modelaron y por qué
+3. Menciona cualquier inconsistencia detectada con `system.yaml` que el usuario deba resolver
+4. Indica el comando siguiente:
+
+```bash
+eva g entities <nombre-del-módulo>
+```
+
+---
+
+## Ciclo de refinamiento
+
+Después de entregar el `domain.yaml` v1, el usuario puede pedir ajustes:
+- Aplica el **cambio mínimo** necesario
+- Vuelve a verificar el checklist del Paso 6
+- Entrega solo el diff explicado, no el archivo completo de nuevo (salvo que se pida)
+- Si el cambio afecta consistencia con `system.yaml`, señálalo explícitamente

package/templates/base/root/skill-build-system-yaml.ejs

@@ -0,0 +1,252 @@
+---
+name: build-system-yaml
+description: 'Construir o actualizar el system.yaml de un proyecto eva4j. Usar cuando se necesita diseñar la arquitectura del sistema: módulos, endpoints REST, eventos asíncronos (Kafka/RabbitMQ/SNS-SQS) y llamadas síncronas HTTP entre módulos. Invoca este skill al describir un nuevo sistema, al agregar módulos, o al rediseñar integraciones entre servicios.'
+argument-hint: 'Describe el sistema o los módulos que necesitas (ej: tienda online con pedidos, pagos y notificaciones)'
+---
+
+Eres un arquitecto de software experto en DDD y arquitectura hexagonal trabajando en el proyecto **<%= projectName %>**.
+
+Tu tarea es construir o actualizar el `system.yaml` del proyecto.
+
+Documentos de referencia del proyecto:
+- [AGENTS.md](/AGENTS.md) — patrones y convenciones de este proyecto eva4j
+- [system.yaml](/system.yaml) — archivo actual (léelo antes de proponer cambios)
+
+---
+
+## Cuando usar este skill
+
+- Diseñar la arquitectura inicial de un sistema nuevo
+- Agregar módulos a un proyecto existente
+- Definir integraciones asíncronas (Kafka/RabbitMQ) entre módulos
+- Definir llamadas síncronas HTTP entre módulos
+- Revisar o refactorizar la estructura de módulos
+
+---
+
+## Rol y objetivo
+
+Producir un `system.yaml` completo, correcto y listo para ejecutar `eva generate system`.
+
+El archivo describe **qué módulos existen y cómo se comunican** — NO contiene entidades, campos ni lógica de negocio. Eso es territorio de `domain.yaml`.
+
+---
+
+## Paso 1 — Recopilar información
+
+Si el usuario no proveyó todos los datos, **pregunta** antes de generar:
+
+1. **¿Usa mensajería asíncrona?** Si sí: `kafka` | `rabbitmq` | `sns-sqs`
+2. **Lista de módulos** con su responsabilidad (nombre en plural, kebab-case)
+3. **Endpoints REST** que expone cada módulo (método + path + caso de uso)
+4. **Flujos async**: qué módulo publica qué evento, quiénes lo consumen
+5. **Llamadas sync**: qué módulo llama a quién y usando qué endpoint
+
+> Si el `system.yaml` ya tiene contenido, léelo primero y pregunta solo por lo que falta o cambia.
+
+---
+
+## Paso 2 — Estructura del system.yaml
+
+```yaml
+system:
+  name: <%= projectName %>
+  groupId: <%= groupId %>
+  javaVersion: <%= javaVersion %>
+  springBootVersion: <%= springBootVersion %>
+  database: <%= databaseType %>
+
+messaging:                            # Omitir sección completa si no hay mensajería
+  enabled: true
+  broker: kafka                       # kafka | rabbitmq | sns-sqs (solo kafka soportado hoy)
+  kafka:
+    bootstrapServers: localhost:9092
+    defaultGroupId: <%= projectName %>
+    topicPrefix: <%= projectName %>   # opcional — prefixa todos los topics
+
+modules:
+  - name: orders                      # plural, kebab-case
+    description: "Gestión del ciclo de vida de pedidos"
+    exposes:
+      - method: GET                   # GET | POST | PUT | PATCH | DELETE
+        path: /orders/{id}
+        useCase: GetOrder             # PascalCase — alimenta endpoints: en domain.yaml
+        description: "Obtener pedido por ID"
+      - method: GET
+        path: /orders
+        useCase: FindAllOrders
+        description: "Listar pedidos con filtros y paginación"
+      - method: POST
+        path: /orders
+        useCase: CreateOrder
+        description: "Crear nuevo pedido"
+      - method: PUT
+        path: /orders/{id}/confirm
+        useCase: ConfirmOrder
+        description: "Confirmar pedido pendiente"
+
+  - name: notifications
+    description: "Envío de notificaciones"
+    # Sin endpoints REST — solo consume eventos
+
+integrations:
+  async:
+    - event: OrderPlacedEvent         # PascalCase, tiempo pasado, sufijo Event
+      producer: orders
+      topic: ORDER_PLACED             # SCREAMING_SNAKE_CASE
+      consumers:
+        - module: payments
+        - module: notifications
+
+  sync:
+    - caller: orders                  # módulo que hace la llamada
+      calls: customers                # módulo destino
+      port: CustomerService           # PascalCase + sufijo Service
+      using:
+        - GET /customers/{id}         # debe existir en exposes: de 'customers'
+```
+
+---
+
+## Paso 3 — Reglas obligatorias
+
+### Convenciones de nombres
+
+| Elemento | Convención | Ejemplo |
+|---|---|---|
+| Módulos | plural, kebab-case | `orders`, `order-items`, `product-catalog` |
+| Eventos | PascalCase + tiempo pasado + sufijo `Event` | `OrderPlacedEvent` ✅ `PlaceOrderEvent` ❌ |
+| Topics Kafka | SCREAMING_SNAKE_CASE | `ORDER_PLACED` |
+| Port names | PascalCase + sufijo `Service` | `CustomerService` |
+| useCases | PascalCase, verbo + sustantivo | `CreateOrder`, `GetCustomer`, `FindAllOrders` |
+
+### Restricciones estructurales
+
+- ❌ **Sin dependencias circulares síncronas** — si `A` llama a `B`, `B` no puede llamar a `A`
+- ❌ **Sin campos de dominio** — entidades, campos, enums → van en `domain.yaml`
+- ✅ Cada módulo tiene **una sola responsabilidad**
+- ✅ `calls.using:` solo referencia endpoints declarados en `exposes:` del módulo destino
+- ✅ `consumers[].module` debe existir en `modules:`
+- ✅ Módulos pasivos (notificaciones, auditoría, reportes) son **consumidores**, nunca `caller`
+
+### useCases — patrones de nombres
+
+Los nombres de `useCase` siguen el patrón **`Verbo + Sustantivo`** en PascalCase.
+
+#### Verbos comunes por tipo de operación
+
+| Tipo de operación | Verbos recomendados | Ejemplo |
+|---|---|---|
+| Crear un recurso | `Create` | `CreateOrder`, `CreateCustomer` |
+| Actualizar datos generales | `Update` | `UpdateOrder`, `UpdateCustomerAddress` |
+| Eliminar un recurso | `Delete` | `DeleteOrder`, `DeleteProduct` |
+| Obtener uno por ID | `Get` | `GetOrder`, `GetCustomerById` |
+| Listar con filtros/paginación | `FindAll` | `FindAllOrders`, `FindAllPendingPayments` |
+| Transición de estado de negocio | `Confirm`, `Cancel`, `Approve`, `Reject`, `Activate`, `Deactivate`, `Suspend`, `Close`, `Complete`, `Submit`, `Publish`, `Archive`, `Restore` | `ConfirmOrder`, `CancelPayment`, `ApproveRefund` |
+| Acción de negocio puntual | `Send`, `Process`, `Calculate`, `Generate`, `Assign`, `Transfer`, `Notify`, `Validate` | `SendNotification`, `ProcessPayment`, `AssignCourier` |
+| Búsqueda especializada | `Search`, `Find`, `Lookup` | `SearchProductsByCategory`, `FindOrdersByCustomer` |
+
+#### Regla de generación de código
+
+eva4j distingue dos categorías al leer el `useCase`:
+
+**Casos de uso CRUD estándar** — el generador produce la implementación completa del handler:
+
+| useCase (patrón) | HTTP | Implementación generada |
+|---|---|---|
+| `Create{Aggregate}` | POST `/resource` | Handler completo con repositorio |
+| `Update{Aggregate}` | PUT `/resource/{id}` | Handler completo con repositorio |
+| `Delete{Aggregate}` | DELETE `/resource/{id}` | Handler completo con repositorio |
+| `Get{Aggregate}` | GET `/resource/{id}` | Handler completo con repositorio |
+| `FindAll{Aggregate}s` | GET `/resource` | Handler completo con repositorio |
+
+**Casos de uso de negocio** — el generador produce un **scaffold** con `throw new UnsupportedOperationException(...)` que el desarrollador implementa:
+
+```java
+// Ejemplo de scaffold generado para ConfirmOrder
+public class ConfirmOrderCommandHandler implements CommandHandler<ConfirmOrderCommand, Void> {
+    @Override
+    public Void handle(ConfirmOrderCommand command) {
+        throw new UnsupportedOperationException("ConfirmOrderCommandHandler not implemented yet");
+    }
+}
+```
+
+**Regla práctica:** usa los nombres CRUD para operaciones simples de persistencia. Para cualquier lógica de negocio real (transiciones de estado, cálculos, flujos complejos) usa un nombre descriptivo — el scaffold te recuerda que debes implementarlo.
+
+#### Ejemplos completos por módulo
+
+```yaml
+# orders — mezcla de CRUD y casos de uso de negocio
+exposes:
+  - method: GET
+    path: /orders/{id}
+    useCase: GetOrder             # ← CRUD: implementación completa
+  - method: GET
+    path: /orders
+    useCase: FindAllOrders        # ← CRUD: implementación completa
+  - method: POST
+    path: /orders
+    useCase: CreateOrder          # ← CRUD: implementación completa
+  - method: PUT
+    path: /orders/{id}/confirm
+    useCase: ConfirmOrder         # ← Negocio: scaffold
+  - method: PUT
+    path: /orders/{id}/cancel
+    useCase: CancelOrder          # ← Negocio: scaffold
+  - method: PUT
+    path: /orders/{id}/assign-courier
+    useCase: AssignCourier        # ← Negocio: scaffold
+
+# payments — transiciones y acciones
+exposes:
+  - method: POST
+    path: /payments
+    useCase: CreatePayment        # ← CRUD: implementación completa
+  - method: GET
+    path: /payments/{id}
+    useCase: GetPayment           # ← CRUD: implementación completa
+  - method: POST
+    path: /payments/{id}/refund
+    useCase: RefundPayment        # ← Negocio: scaffold
+  - method: POST
+    path: /payments/{id}/process
+    useCase: ProcessPayment       # ← Negocio: scaffold
+```
+
+### Mensajería
+
+- Solo `kafka` está implementado actualmente; `rabbitmq` y `sns-sqs` generan warning
+- Los **campos** de los eventos NO van en `system.yaml` → se declaran en `domain.yaml → events[].fields` del productor
+
+---
+
+## Paso 4 — Checklist de validación interna
+
+Antes de proponer el `system.yaml`, verifica:
+
+- [ ] Módulos en plural kebab-case
+- [ ] Eventos en tiempo pasado con sufijo `Event`
+- [ ] Sin dependencias circulares síncronas
+- [ ] Todos los `consumers[].module` existen en `modules:`
+- [ ] Todos los `calls.using:` existen en `exposes:` del módulo destino
+- [ ] Módulos pasivos no son `caller`
+- [ ] `useCases` en PascalCase
+
+---
+
+## Paso 5 — Presentar el resultado
+
+1. Muestra el `system.yaml` completo en un bloque de código YAML
+2. Explica brevemente las decisiones no obvias (ej. por qué un flujo es async y no sync)
+3. Menciona advertencias si detectas módulos muy acoplados, responsabilidades difusas o ciclos potenciales
+4. Indica el comando siguiente: `eva generate system`
+
+---
+
+## Ciclo de refinamiento
+
+Después de entregar el `system.yaml` v1, el usuario puede pedir ajustes:
+- Aplica el **cambio mínimo** necesario (no rehaces todo el archivo)
+- Vuelve a validar el checklist del Paso 4
+- Entrega solo el diff explicado, no el archivo completo de nuevo (salvo que se pida)

package/templates/base/root/system.yaml.ejs

@@ -0,0 +1,97 @@
+# system.yaml
+# ─────────────────────────────────────────────────────────────────────────────
+# Archivo de arquitectura del sistema — System-First Development con eva4j
+#
+# Describe qué módulos existen, qué exponen y cómo se comunican entre sí.
+# Los campos de dominio (aggregates, events, ports) se declaran en domain.yaml.
+#
+# Comandos disponibles:
+#   eva system validate  →  valida coherencia del grafo (referencias, ciclos)
+#   eva generate system  →  genera módulos + domain.yaml con endpoints: pre-generado
+#   eva system diagram   →  genera diagrama Mermaid del sistema
+# ─────────────────────────────────────────────────────────────────────────────
+
+system:
+  name: <%= projectName %>
+  groupId: <%= groupId %>
+  javaVersion: <%= javaVersion %>
+  springBootVersion: <%= springBootVersion %>
+  database: <%= databaseType %>
+
+# messaging:                           # Descomentar si el sistema usa mensajería asíncrona
+#   enabled: true
+#   broker: kafka                      # kafka | rabbitmq | sns-sqs
+#   kafka:
+#     bootstrapServers: localhost:9092
+#     defaultGroupId: <%= projectName %>
+#     topicPrefix: <%= projectName %>  # prefija todos los topics: <%= projectName %>.ORDER_PLACED
+
+modules:
+  # Declara cada módulo del sistema (nombre en plural, kebab-case).
+  # eva generate system genera por cada módulo: carpeta + domain.yaml con endpoints: pre-generado.
+  #
+  # - name: orders
+  #   description: "Gestión del ciclo de vida de pedidos"
+  #   exposes:
+  #     - method: GET
+  #       path: /orders/{id}
+  #       useCase: GetOrder            # PascalCase — alimenta endpoints: en domain.yaml
+  #       description: "Obtener pedido por ID"
+  #     - method: GET
+  #       path: /orders
+  #       useCase: FindAllOrders
+  #       description: "Listar pedidos con filtros y paginación"
+  #     - method: POST
+  #       path: /orders
+  #       useCase: CreateOrder
+  #       description: "Crear nuevo pedido"
+  #     - method: PUT
+  #       path: /orders/{id}/confirm
+  #       useCase: ConfirmOrder
+  #       description: "Confirmar pedido pendiente"
+  #     - method: PUT
+  #       path: /orders/{id}/cancel
+  #       useCase: CancelOrder
+  #       description: "Cancelar pedido (PENDING o CONFIRMED)"
+  #
+  # - name: customers
+  #   description: "Registro y gestión de clientes"
+  #   exposes:
+  #     - method: GET
+  #       path: /customers/{id}
+  #       useCase: GetCustomer
+  #       description: "Obtener cliente por ID"
+  #     - method: POST
+  #       path: /customers
+  #       useCase: CreateCustomer
+  #       description: "Registrar nuevo cliente"
+  #
+  # - name: notifications
+  #   description: "Envío de notificaciones"
+  #   # Sin endpoints REST — solo consume eventos
+
+# integrations:
+#   async:
+#     # Eventos asíncronos entre módulos.
+#     # Los campos del evento se declaran en domain.yaml → events[].fields del productor.
+#     - event: OrderPlacedEvent
+#       producer: orders
+#       topic: ORDER_PLACED
+#       consumers:
+#         - module: payments
+#         - module: notifications
+#
+#     - event: PaymentProcessedEvent
+#       producer: payments
+#       topic: PAYMENT_PROCESSED
+#       consumers:
+#         - module: orders
+#
+#   sync:
+#     # Llamadas HTTP síncronas entre módulos.
+#     # El shape del DTO de respuesta se declara en domain.yaml → ports[] del caller.
+#     - caller: orders
+#       calls: customers
+#       port: CustomerService
+#       using:
+#         - GET /customers/{id}