eva4j 1.0.13 → 1.0.14

package/AGENTS.md

@@ -457,9 +457,13 @@ aggregates:
         fields:
           - name: userId
             type: String
-        # kafka: true  # opcional — publica a Kafka tras commit
+        # Nota: el flag kafka: true ya no es necesario.
+        # Si el proyecto tiene un broker instalado (eva add kafka-client),
+        # eva g entities cablea automáticamente todos los eventos declarados.
 ```
 
+El `domain.yaml` también soporta una sección `endpoints:` opcional (sibling de `aggregates:`) para declarar los endpoints REST. Ver sección [⚡ Características Avanzadas](#-características-avanzadas-del-domainyaml) para detalles.
+
 ---
 
 ## ⚡ Características Avanzadas del domain.yaml
@@ -523,26 +527,51 @@ aggregates:
   - name: Order
     entities: [...]
     events:
-      - name: OrderConfirmedEvent
+      - name: OrderConfirmed
         fields:
           - name: orderId
             type: String
           - name: confirmedAt
             type: LocalDateTime
-        kafka: true              # opcional — genera publicación a MessageBroker
 ```
 
-Genera `OrderConfirmedEvent.java` (en `domain/models/events/`) que extiende `DomainEvent`, y `OrderDomainEventHandler.java` (en `application/usecases/`) con `@TransactionalEventListener(AFTER_COMMIT)`.
+Genera `OrderConfirmed.java` (en `domain/models/events/`) que extiende `DomainEvent`, y `OrderDomainEventHandler.java` (en `application/usecases/`) con `@TransactionalEventListener(AFTER_COMMIT)`.
+
+**Auto-wiring de broker:** Si el proyecto tiene un broker de mensajería instalado (`eva add kafka-client`), `eva g entities` genera automáticamente la capa de Integration Events para **todos** los eventos declarados — sin necesidad de ejecutar `eva g kafka-event` por separado:
+
+| Archivo generado | Descripción |
+|---|---|
+| `application/events/OrderConfirmedIntegrationEvent.java` | Record broker-facing (Integration Event) |
+| `application/ports/MessageBroker.java` | Puerto broker-agnóstico (creado/actualizado) |
+| `infrastructure/adapters/kafkaMessageBroker/…` | Adaptador Kafka (creado/actualizado) |
+| `shared/…/kafkaConfig/KafkaConfig.java` | Bean `NewTopic` (actualizado) |
+| `parameters/*/kafka.yaml` | Configuración de topic (actualizada) |
+
+**Domain Event vs Integration Event:**
+- **Domain Event** (`domain/models/events/OrderConfirmed.java`) — señal interna del bounded context. Nunca depende de infraestructura.
+- **Integration Event** (`application/events/OrderConfirmedIntegrationEvent.java`) — proyección para el broker. Cambiar de Kafka a RabbitMQ solo requiere cambiar el adaptador `MessageBroker`; los Domain Events no se modifican nunca.
+
+El `DomainEventHandler` mapea un Domain Event a un Integration Event:
+```java
+@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+public void onOrderConfirmed(OrderConfirmed event) {
+    messageBroker.publishOrderConfirmedIntegrationEvent(
+        new OrderConfirmedIntegrationEvent(event.getOrderId(), event.getConfirmedAt())
+    );
+}
+```
 
 Publicar desde la entidad raíz usando `raise()` heredado:
 
 ```java
 public void confirm() {
     this.status = this.status.transitionTo(OrderStatus.CONFIRMED);
-    raise(new OrderConfirmedEvent(this.id, this.id, LocalDateTime.now()));
+    raise(new OrderConfirmed(this.id, LocalDateTime.now()));
 }
 ```
 
+**Nota:** el flag `kafka: true` por evento ya no es necesario — todos los eventos se cablearán automáticamente cuando haya un broker instalado.
+
 ---
 
 ## �️ Soft Delete
@@ -956,7 +985,18 @@ private String customerId;
 2. **SI** el módulo requiere ciclo de vida → usar `transitions` + `initialValue` en el enum
 3. **SI** un valor tiene lógica de negocio → declararlo como `valueObject` con `methods`
 4. **SI** ocurren hechos relevantes de negocio → declarar `events[]` en el agregado
-5. **DESPUÉS** de generar el `domain.yaml` → ejecutar `eva g entities <module>`
+5. **SI** el módulo expone endpoints REST específicos → declarar `endpoints:` con versiones y operaciones
+6. **DESPUÉS** de generar el `domain.yaml` → ejecutar `eva g entities <module>`
+
+### Al Usar `endpoints:` en domain.yaml
+
+1. **SIEMPRE** declarar `endpoints:` cuando el API REST tiene comportamientos custom (confirmar, cancelar, activar, etc.)
+2. **NUNCA** usar `endpoints:` si solo necesitas CRUD estándar — el flujo interactivo es más simple
+3. **SIEMPRE** usar PascalCase para los nombres de `useCase` (ej: `ConfirmOrder`, no `confirmOrder`)
+4. **CONOCER** cuáles son los 5 use cases estándar por aggregate: `Create{E}`, `Update{E}`, `Delete{E}`, `Get{E}`, `FindAll{E}s` — estos generan implementación completa
+5. **SABER** que cualquier otro nombre genera un **scaffold** con `UnsupportedOperationException` — el desarrollador debe implementar el handler
+6. **APLICAR** la regla anti-duplicado: si el mismo useCase aparece en v1 y v2, se genera solo una vez
+7. **NOMBRAR** los controladores según la convención: `{Aggregate}{VersionCapitalized}Controller` (ej: `OrderV1Controller`)
 
 ### Al Generar Código de Dominio
 
@@ -1188,10 +1228,12 @@ Al generar o modificar código, verificar:
 - [ ] Enum con ciclo de vida → usar `transitions` + `initialValue`, no setters manuales
 - [ ] Value Object con comportamiento → declarar `methods` en lugar de lógica en entidad
 - [ ] Evento de dominio → declarar en `events[]`, publicar con `raise()` en método de negocio
-- [ ] Evento con Kafka → agregar `kafka: true` al evento
+- [ ] Evento con broker → **no** usar `kafka: true`; si `eva add kafka-client` está instalado, `eva g entities` auto-cablea todos los eventos
+- [ ] Distinguir entre Domain Event (`domain/models/events/X.java`) e Integration Event (`application/events/XIntegrationEvent.java`) — cambios de broker solo afectan al adaptador `MessageBroker`
+- [ ] Endpoints REST específicos → declarar `endpoints:` con versiones y operaciones; usar nombres estándar para implementación completa
 
 ---
 
-**Última actualización:** 2026-03-02  
-**Versión de eva4j:** 1.0.12  
+**Última actualización:** 2026-03-11  
+**Versión de eva4j:** 1.0.13  
 **Estado:** Documento de referencia para agentes IA

package/DOMAIN_YAML_GUIDE.md

@@ -13,6 +13,7 @@
 - [Validaciones JSR-303](#validaciones-jsr-303)
 - [Relaciones](#relaciones)
 - [Tipos de Datos](#tipos-de-datos)
+- [Sección endpoints](#sección-endpoints)
 - [Ejemplos Completos](#ejemplos-completos)
 
 ---
@@ -2441,6 +2442,155 @@ private List<AddressJpa> addresses = new ArrayList<>();
 
 ---
 
+## Sección endpoints
+
+La sección `endpoints:` es **opcional** y se declara como clave hermana de `aggregates:` en el YAML. Cuando está presente, controla **qué use cases y controladores REST se generan**. Cuando está ausente, el generador usa el flujo interactivo tradicional (5 CRUD fijos por aggregate root).
+
+### Comportamiento condicional
+
+| Condición | Comportamiento |
+|-----------|---------------|
+| `endpoints:` **ausente** | Pregunta interactiva "¿Generar CRUD?" → genera 5 use cases estándar |
+| `endpoints:` **presente** | Genera automáticamente solo los use cases declarados en `operations[]` |
+
+### Sintaxis
+
+```yaml
+# Sección endpoints: sibling de aggregates:
+endpoints:
+  basePath: /orders            # Ruta base (incluida en @RequestMapping "/api/{version}{basePath}")
+  versions:
+    - version: v1              # Versión del API (ej: v1, v2, v1-beta)
+      operations:
+        - method: GET          # HTTP method (GET, POST, PUT, PATCH, DELETE)
+          path: /{id}          # Path relativo al basePath (/ para la raíz)
+          useCase: GetOrder    # Nombre del use case (PascalCase)
+          description: "Obtener pedido por ID"   # Descripción para Swagger
+```
+
+### Campos de `endpoints:`
+
+| Campo | Tipo | Requerido | Descripción |
+|-------|------|-----------|-------------|
+| `basePath` | String | Sí | Ruta base del recurso (ej: `/orders`) |
+| `versions` | Array | Sí | Lista de versiones de API |
+| `versions[].version` | String | Sí | Identificador de versión (ej: `v1`) |
+| `versions[].operations` | Array | Sí | Lista de endpoints a generar |
+| `operations[].method` | String | Sí | Verbo HTTP: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
+| `operations[].path` | String | Sí | Path relativo (ej: `/`, `/{id}`, `/{id}/confirm`) |
+| `operations[].useCase` | String | Sí | Nombre del use case en PascalCase |
+| `operations[].description` | String | No | Descripción para la anotación `@Operation` de Swagger |
+
+### Tipo inferido (`type`)
+
+El tipo del use case se infiere automáticamente del método HTTP:
+
+| HTTP method | Tipo inferido | Genera |
+|-------------|--------------|--------|
+| `GET` | `query` | `{UseCaseName}Query` + `{UseCaseName}QueryHandler` |
+| `POST`, `PUT`, `PATCH`, `DELETE` | `command` | `{UseCaseName}Command` + `{UseCaseName}CommandHandler` |
+
+### Use cases estándar vs. scaffold
+
+| Categoría | Nombres Match | Generado |
+|-----------|---------------|---------|
+| **Estándar** | `Create{Aggregate}`, `Update{Aggregate}`, `Delete{Aggregate}`, `Get{Aggregate}`, `FindAll{Aggregate}s` | Implementación completa con lógica de repositorio |
+| **Scaffold** | Cualquier otro nombre (`ConfirmOrder`, `ActivateProduct`, etc.) | Clase con `// TODO` — el desarrollador completa la lógica |
+
+Los use cases estándar reutilizan los templates CRUD existentes (implementación idéntica al flujo sin `endpoints:`). Los scaffolds generan archivos con `UnsupportedOperationException` y comentarios guía.
+
+### Regla anti-duplicado (multi-versión)
+
+Cuando el mismo `useCase` aparece en múltiples versiones (ej: `CreateProduct` en v1 y v2), el generador crea el Command/Query + Handler **solo una vez** (en la primera versión donde aparece). Los controladores de las versiones posteriores importan y referencian el mismo use case sin regenerarlo.
+
+```yaml
+endpoints:
+  basePath: /products
+  versions:
+    - version: v1
+      operations:
+        - { method: POST, path: /, useCase: CreateProduct }   # ← genera CreateProductCommand + Handler
+
+    - version: v2
+      operations:
+        - { method: POST, path: /, useCase: CreateProduct }   # ← NO regenera, solo referencia en V2Controller
+        - { method: PUT, path: /{id}/activate, useCase: ActivateProduct }  # ← nuevo scaffold
+```
+
+### Nombres de controladores generados
+
+Con `endpoints:`, el controlador se nombra `{Aggregate}{VersionCapitalized}Controller`:
+
+| Aggregate | Version | Clase generada | Archivo |
+|-----------|---------|---------------|---------|
+| `Order` | `v1` | `OrderV1Controller` | `controllers/order/v1/OrderV1Controller.java` |
+| `Product` | `v2` | `ProductV2Controller` | `controllers/product/v2/ProductV2Controller.java` |
+
+> Sin `endpoints:`, el controlador se llama `{Aggregate}Controller` y usa la versión ingresada en el prompt.
+
+### Ejemplo básico (una versión)
+
+```yaml
+aggregates:
+  - name: Order
+    entities:
+      - name: order
+        isRoot: true
+        tableName: orders
+        fields:
+          - { name: id, type: String }
+          - { name: orderNumber, type: String }
+          - { name: status, type: OrderStatus, readOnly: true }
+
+    enums:
+      - name: OrderStatus
+        initialValue: PENDING
+        values: [PENDING, CONFIRMED, SHIPPED, CANCELLED]
+
+endpoints:
+  basePath: /orders
+  versions:
+    - version: v1
+      operations:
+        - { method: GET,    path: /{id}, useCase: GetOrder,    description: "Obtener pedido" }
+        - { method: GET,    path: /,     useCase: FindAllOrders, description: "Listar pedidos" }
+        - { method: POST,   path: /,     useCase: CreateOrder, description: "Crear pedido" }
+        - { method: DELETE, path: /{id}, useCase: DeleteOrder, description: "Eliminar pedido" }
+        - { method: PUT,    path: /{id}/confirm, useCase: ConfirmOrder, description: "Confirmar pedido" }
+```
+
+**Archivos generados:**
+```
+application/
+  commands/
+    CreateOrderCommand.java          ← estándar (completo)
+    DeleteOrderCommand.java          ← estándar (completo)
+    ConfirmOrderCommand.java         ← scaffold (TODO)
+  queries/
+    GetOrderQuery.java               ← estándar (completo)
+    FindAllOrdersQuery.java          ← NOTA: no es estándar (estándar sería FindAllOrders s)
+                                       → scaffold (TODO)
+  usecases/
+    CreateOrderCommandHandler.java   ← estándar
+    DeleteOrderCommandHandler.java   ← estándar
+    ConfirmOrderCommandHandler.java  ← scaffold
+    GetOrderQueryHandler.java        ← estándar
+    FindAllOrdersQueryHandler.java   ← scaffold
+  dtos/
+    OrderResponseDto.java
+  mappers/
+    OrderApplicationMapper.java
+infrastructure/rest/controllers/order/
+  v1/
+    OrderV1Controller.java           ← controller con 5 métodos declarados
+```
+
+### Ejemplo multi-versión
+
+Ver [`examples/domain-endpoints-versioned.yaml`](examples/domain-endpoints-versioned.yaml) para un ejemplo completo con v1 y v2, incluyendo la regla anti-duplicado y scaffolds.
+
+---
+
 ## Ejemplos Completos
 
 ### Ejemplo 1: E-Commerce (Order)

package/bin/eva4j.js

@@ -16,6 +16,8 @@ const generateRecordCommand = require('../src/commands/generate-record');
 const generateEntitiesCommand = require('../src/commands/generate-entities');
 const generateTemporalFlowCommand = require('../src/commands/generate-temporal-flow');
 const generateTemporalActivityCommand = require('../src/commands/generate-temporal-activity');
+const generateSystemCommand = require('../src/commands/generate-system');
+const evaluateSystemCommand = require('../src/commands/evaluate-system');
 const infoCommand = require('../src/commands/info');
 const detachCommand = require('../src/commands/detach');
 
@@ -254,6 +256,16 @@ program
       return;
     }
 
+    if (type === 'system') {
+      try {
+        await generateSystemCommand();
+      } catch (error) {
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+      }
+      return;
+    }
+
     console.error(chalk.red(`❌ Unknown type: ${type}`));
     console.log(chalk.yellow('\nUsage:'));
     console.log(chalk.gray('  eva4j generate usecase <name> <module>'));
@@ -265,6 +277,7 @@ program
     console.log(chalk.gray('  eva4j generate resource <module>'));
     console.log(chalk.gray('  eva4j generate record'));
     console.log(chalk.gray('  eva4j generate entities <module>'));
+    console.log(chalk.gray('  eva4j generate system'));
     console.log(chalk.gray('\nExamples:'));
     console.log(chalk.gray('  eva4j generate usecase create-provider provider'));
     console.log(chalk.gray('  eva4j g http-exchange user-service-port user'));
@@ -274,10 +287,26 @@ program
     console.log(chalk.gray('  eva4j g temporal-activity order register-order'));
     console.log(chalk.gray('  eva4j g resource product'));
     console.log(chalk.gray('  eva4j g record  # Reads JSON from clipboard'));
-    console.log(chalk.gray('  eva4j g entities order  # Generates from domain.yaml\n'));
+    console.log(chalk.gray('  eva4j g entities order  # Generates from domain.yaml'));
+    console.log(chalk.gray('  eva4j g system          # Bootstrap from system.yaml\n'));
     process.exit(1);
   });
 
+// Evaluate command
+program
+  .command('evaluate <type>')
+  .description('Validate and visualize project artifacts. type: system')
+  .option('--port <port>', 'Port for the web server (default: 3000)')
+  .option('--output <path>', 'Output path for the HTML report (default: ./system-report.html)')
+  .action(async (type, options) => {
+    try {
+      await evaluateSystemCommand(type, options);
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Info command
 program
   .command('info')
@@ -322,6 +351,7 @@ program.on('--help', () => {
   console.log(chalk.gray('  $ eva4j g record'));
   console.log(chalk.gray('  $ eva4j detach user'));
   console.log(chalk.gray('  $ eva4j info'));
+  console.log(chalk.gray('  $ eva4j evaluate system'));
   console.log('');
   console.log(chalk.blue('For more information, visit:'));
   console.log(chalk.gray('  https://github.com/your-repo/eva4j'));