eva4j 1.0.13 → 1.0.15

package/DOMAIN_YAML_GUIDE.md

@@ -13,6 +13,8 @@
 - [Validaciones JSR-303](#validaciones-jsr-303)
 - [Relaciones](#relaciones)
 - [Tipos de Datos](#tipos-de-datos)
+- [Sección endpoints](#sección-endpoints)
+- [Sección listeners](#sección-listeners)
 - [Ejemplos Completos](#ejemplos-completos)
 
 ---
@@ -134,10 +136,17 @@ aggregates:
         values: []
     
     events:
-      # Eventos de dominio que emite este agregado
+      # Eventos de dominio que emite este agregado (dentro del agregado)
       - name: NombreEventoOcurrido
         fields: []
-        # kafka: true  # opcional — genera publicación a Kafka vía MessageBroker
+
+# listeners: — eventos externos que CONSUME este módulo (nivel raíz)
+listeners:
+  - event: ExternalEvent           # Nombre del evento (PascalCase + Event)
+    producer: other-module         # Módulo que lo produce
+    topic: TOPIC_NAME              # Topic Kafka (obligatorio en módulos standalone)
+    useCase: HandleExternalEvent   # Caso de uso que maneja el evento
+    fields: []                     # Payload del Integration Event recibido
 ```
 
 ### Ubicación del archivo
@@ -1279,6 +1288,100 @@ CREATE TABLE reviews (
 
 ---
 
+## Soft Delete
+
+Cuando una entidad tiene `hasSoftDelete: true`, eva4j genera **eliminación lógica** en lugar de física: el registro no se borra de la base de datos, sino que se marca con un timestamp `deletedAt`.
+
+### Configuración en domain.yaml
+
+```yaml
+aggregates:
+  - name: Order
+    entities:
+      - name: order
+        isRoot: true          # ← OBLIGATORIO: solo aplica en la raíz del agregado
+        tableName: orders
+        hasSoftDelete: true   # ✅ Activa soft delete
+        audit:
+          enabled: true
+        fields:
+          - name: id
+            type: String
+          - name: orderNumber
+            type: String
+
+      - name: orderItem       # ← Entidad secundaria
+        tableName: order_items
+        # hasSoftDelete: true ← ❌ INCORRECTO — se ignora con warning
+        #                         Las secundarias se eliminan físicamente
+        #                         vía CASCADE desde la raíz
+```
+
+> **Regla de alcance:** `hasSoftDelete` **solo es válido en la entidad raíz** (`isRoot: true`). Ponerlo en una entidad secundaria emite un warning y es ignorado.
+
+### Por qué solo en la raíz
+
+En DDD, una entidad secundaria como `OrderItem` no tiene existencia independiente — su ciclo de vida lo controla el agregado raíz. Nunca se elimina directamente: se elimina removiéndola de la colección del raíz y JPA gestiona el `DELETE` físico vía `cascade`. Aplicar `@SQLRestriction` en una entidad secundaria rompería las relaciones: los items "eliminados" desaparecerían silenciosamente del `@OneToMany`, creando inconsistencias difíciles de detectar.
+
+### Qué genera el flag
+
+**Entidad de dominio:**
+```java
+public class Order {
+    private LocalDateTime deletedAt;     // ← Inyectado automáticamente
+
+    public void softDelete() {
+        if (this.deletedAt != null) {
+            throw new IllegalStateException("Order is already deleted");
+        }
+        this.deletedAt = java.time.LocalDateTime.now();
+    }
+
+    public boolean isDeleted() {
+        return this.deletedAt != null;
+    }
+}
+```
+
+**Entidad JPA:**
+```java
+@SQLRestriction("deleted_at IS NULL")   // ← Filtra automáticamente en TODAS las queries
+@Entity
+@Table(name = "orders")
+public class OrderJpa extends AuditableEntity {
+    private LocalDateTime deletedAt;     // ← Columna deleted_at
+}
+```
+
+**DeleteCommandHandler:**
+```java
+// Soft delete: busca → marca → guarda (nunca deleteById)
+Order order = repository.findById(id)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+order.softDelete();
+repository.save(order);
+```
+
+### Campos excluidos automáticamente
+
+| Artefacto | `deletedAt` incluido | Motivo |
+|---|---|---|
+| Constructor completo (reconstrucción desde BD) | ✅ | Necesario para hidratar el estado |
+| Constructor de creación (nuevo objeto) | ❌ | Inicia siempre como `null` |
+| `CreateDto` / `CreateCommand` | ❌ | No se crea un objeto ya eliminado |
+| `ResponseDto` | ❌ | Metadato interno, no se expone en API |
+| `toJpa()` en el mapper | ✅ | Persiste el timestamp cuando se llama `softDelete()` |
+
+### Notas importantes
+
+- ✅ Compatible con `audit: { enabled: true }` y `audit: { trackUser: true }` — se pueden combinar
+- ✅ `@SQLRestriction` hace invisibles los registros eliminados en **todas** las queries automáticamente, sin necesidad de filtros manuales
+- ✅ `deletedAt` **no debe** definirse manualmente en `fields` — el generador lo inyecta
+- ❌ `hasSoftDelete: true` en una entidad secundaria es ignorado con warning
+- ❌ Cuando `hasSoftDelete: true`, usar `repository.deleteById()` genera un `DeleteCommandHandler` incorrecto — el generador lo previene automáticamente
+
+---
+
 ## Value Objects
 
 Los Value Objects son objetos inmutables que representan conceptos del dominio sin identidad propia.
@@ -1594,7 +1697,7 @@ aggregates:
             type: LocalDateTime
       
       - name: OrderShippedEvent
-        kafka: true                      # opcional — genera publicación a Kafka
+        topic: ORDER_SHIPPED             # opcional — override del topic auto-derivado
         fields:
           - name: orderId
             type: String
@@ -1604,11 +1707,16 @@ aggregates:
 
 ### Propiedades de un evento
 
-| Propiedad | Tipo | Descripción |
-|-----------|------|-------------|
-| `name` | String | Nombre de la clase del evento (PascalCase) |
-| `fields` | Array | Campos que transporta el evento |
-| `kafka` | Boolean | Si `true`, genera llamada a `messageBroker.send{EventName}()` |
+| Propiedad | Tipo | Obligatorio | Descripción |
+|-----------|------|-------------|-------------|
+| `name` | String | ✅ | Nombre de la clase del evento (PascalCase) |
+| `fields` | Array | ✅ | Campos que transporta el evento |
+| `triggers` | Array\<String\> | ➖ | Nombres de métodos de transición que publican este evento. El generador emite `raise(new XEvent(...))` automáticamente. |
+| `topic` | String | ➖ | **Override del topic Kafka.** Por defecto el generador quita el sufijo `Event` del nombre de la clase: `ProductPublishedEvent` → `PRODUCT_PUBLISHED`. Úsalo cuando el consumer en `listeners[]` de otro módulo declara un topic diferente al auto-derivado. |
+
+> **Regla de derivación de topic:** `ProductPublishedEvent` → quita `Event` → `ProductPublished` → SCREAMING_SNAKE → `PRODUCT_PUBLISHED`. Esto garantiza que el producer y el consumer coincidan cuando el consumer declara `topic: PRODUCT_PUBLISHED` en `listeners[]`.
+
+> **`kafka: true`** ya no es necesario — si el proyecto tiene `kafka-client` instalado, todos los eventos se cablearán automáticamente al ejecutar `eva g entities`.
 
 ### Archivos generados
 
@@ -1643,7 +1751,7 @@ public class OrderDomainEventHandler {
 
     @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
     public void handle(OrderShippedEvent event) {
-        messageBroker.sendOrderShippedEvent(event);  // kafka: true
+        messageBroker.sendOrderShippedEvent(event);
     }
 }
 ```
@@ -1664,6 +1772,316 @@ public void confirm() {
 
 ---
 
+## Sección listeners
+
+La sección `listeners:` declara los eventos externos que **consume** este módulo. Es el complemento de `events:` (producción): mientras que `events:` vive _dentro_ del agregado porque pertenece al modelo de dominio, `listeners:` vive en el **nivel raíz** del `domain.yaml` porque es una responsabilidad de integración/infraestructura.
+
+> **Requiere broker instalado.** El generador solo produce archivos de listener cuando `eva add kafka-client` ha sido ejecutado en el proyecto. Sin broker, la sección es ignorada.
+
+### Sintaxis
+
+```yaml
+# Nivel raíz — sibling de aggregates:
+listeners:
+  - event: PaymentApprovedEvent    # PascalCase + sufijo Event
+    producer: payments             # Módulo que produce el evento (referencia documental)
+    topic: PAYMENT_APPROVED        # Topic Kafka — obligatorio en módulos standalone
+    useCase: ConfirmOrder          # Caso de uso invocado al consumir (PascalCase)
+    fields:                        # Payload del Integration Event recibido
+      - name: orderId
+        type: String
+      - name: approvedAt
+        type: LocalDateTime
+      - name: details
+        type: PaymentDetails       # Campo objeto → declarado en nestedTypes:
+    nestedTypes:                   # Opcional: records auxiliares para campos objeto
+      - name: paymentDetails       # camelCase → PascalCase en el record generado
+        fields:
+          - name: paymentId
+            type: String
+          - name: amount
+            type: BigDecimal
+```
+
+### Propiedades
+
+| Propiedad | Requerido | Descripción |
+|-----------|-----------|-------------|
+| `event` | ✅ | Nombre del evento en PascalCase, con sufijo `Event` |
+| `producer` | ✅ | Módulo que produce el evento (solo referencia documental, no genera código) |
+| `topic` | ✅ | Topic Kafka. Si existe `system.yaml`, el generador puede inferirlo de `integrations.async[].topic`; en módulos **standalone** es obligatorio declararlo explícitamente. |
+| `useCase` | ✅ | Nombre del caso de uso que maneja el evento (PascalCase) |
+| `fields` | ✅ | Campos del payload recibido; genera el record `IntegrationEvent` y tipifica el Command despachado |
+| `nestedTypes` | ❌ | Records auxiliares para campos de tipo objeto en `fields:`. Cada entrada genera un `.java` record en `application/events/`. |
+
+### Archivos generados
+
+Para cada entrada en `listeners:`, eva4j genera **5 archivos** (más un record por cada entrada en `nestedTypes:`):
+
+| # | Archivo | Ubicación | Descripción |
+|---|---------|-----------|-------------|
+| 0 | `{NestedName}.java` *(por nestedType)* | `application/events/` | Record auxiliar para campos objeto |
+| 1 | `{Name}IntegrationEvent.java` | `application/events/` | Record contrato tipado (documentación + tests) |
+| 2 | `{Name}KafkaListener.java` | `infrastructure/kafkaListener/` | `@KafkaListener` — deserializa y despacha |
+| 3 | `kafka.yaml` *(todas las envs)* | `resources/parameters/*/` | Topic registrado bajo `topics:` |
+| 4 | `{UseCase}Command.java` | `application/commands/` | Comando tipado despachado desde el listener |
+| 5 | `{UseCase}CommandHandler.java` | `application/usecases/` | Stub del handler (implementar la lógica aquí) |
+
+### Código generado
+
+**`PaymentDetails.java`** — `application/events/` (de `nestedTypes:`)
+```java
+public record PaymentDetails(
+    String paymentId,
+    BigDecimal amount
+) {}
+```
+
+**`PaymentApprovedIntegrationEvent.java`** — `application/events/`
+```java
+public record PaymentApprovedIntegrationEvent(
+    String orderId,
+    LocalDateTime approvedAt,
+    PaymentDetails details
+) {}
+```
+
+**`ConfirmOrderCommand.java`** — `application/commands/`
+```java
+import com.example.orders.application.events.PaymentDetails;
+
+public record ConfirmOrderCommand(
+    String orderId,
+    LocalDateTime approvedAt,
+    PaymentDetails details
+) implements Command {}
+```
+
+**`PaymentApprovedKafkaListener.java`** — `infrastructure/kafkaListener/`
+```java
+import com.example.orders.application.events.PaymentDetails;
+
+@Component
+public class PaymentApprovedKafkaListener {
+
+    private final UseCaseMediator useCaseMediator;
+    private final ObjectMapper objectMapper;
+
+    @Value("${topics.payment-approved}")
+    private String paymentApprovedTopic;
+
+    public PaymentApprovedKafkaListener(UseCaseMediator useCaseMediator,
+                                        ObjectMapper objectMapper) {
+        this.useCaseMediator = useCaseMediator;
+        this.objectMapper = objectMapper;
+    }
+
+    @KafkaListener(topics = "${topics.payment-approved}")
+    public void handle(EventEnvelope<Map<String, Object>> event, Acknowledgment ack) {
+        String orderId = objectMapper.convertValue(event.data().get("orderId"), String.class);
+        LocalDateTime approvedAt = objectMapper.convertValue(
+                event.data().get("approvedAt"), LocalDateTime.class);
+        PaymentDetails details = objectMapper.convertValue(
+                event.data().get("details"), PaymentDetails.class);
+        useCaseMediator.dispatch(new ConfirmOrderCommand(orderId, approvedAt, details));
+        ack.acknowledge();
+    }
+}
+```
+
+**`ConfirmOrderCommandHandler.java`** — `application/usecases/`
+```java
+@ApplicationComponent
+public class ConfirmOrderCommandHandler implements CommandHandler<ConfirmOrderCommand> {
+
+    @Override
+    public void handle(ConfirmOrderCommand command) {
+        // TODO: implement ConfirmOrder business logic
+        throw new UnsupportedOperationException("ConfirmOrderCommandHandler not yet implemented");
+    }
+}
+```
+
+### Deserialización — cómo funciona
+
+El consumidor Kafka recibe un `EventEnvelope<Map<String, Object>>`. El listener generado extrae cada campo con `objectMapper.convertValue()`, que maneja:
+
+- Primitivos y strings: `convertValue(map.get("field"), String.class)`
+- Fechas: `convertValue(map.get("date"), LocalDateTime.class)` — requiere el módulo Jackson JavaTime
+- Objetos / nested types: `convertValue(map.get("details"), PaymentDetails.class)` — funciona automáticamente para Java records
+- Listas: `convertValue(map.get("items"), typeFactory.constructCollectionType(List.class, ItemType.class))`
+
+### `nestedTypes:` — cuándo usarlo
+
+Usar `nestedTypes:` cuando uno de los `fields:` es un objeto estructurado (no un tipo Java primitivo). Cada entrada genera un Java record en `application/events/` que se importa automáticamente tanto en el `KafkaListener` como en el `Command`.
+
+El nombre se declara en `camelCase` y el generador lo normaliza a `PascalCase`:
+```yaml
+nestedTypes:
+  - name: paymentDetails    # → PaymentDetails.java
+    fields:
+      - name: paymentId
+        type: String
+      - name: amount
+        type: BigDecimal
+```
+
+`{Name}IntegrationEvent.java` **no necesita importar** los nested types porque vive en el mismo paquete `application/events/`.
+
+### Regla de resolución de `topic:`
+
+| Escenario | Comportamiento |
+|-----------|---------------|
+| Módulo standalone (solo `domain.yaml`) | `topic:` **obligatorio** — no hay otra fuente de verdad |
+| Proyecto con `system.yaml` | `topic:` puede omitirse; se infiere de `integrations.async[].topic` |
+| `topic:` declarado explícitamente con `system.yaml` | El valor declarado tiene **precedencia** sobre la inferencia |
+
+### Contraste: producción vs. consumo
+
+```
+domain.yaml
+├── aggregates:
+│   └── [Aggregate]
+│       └── events:      → Domain Events que PRODUCE (domain/models/events/)
+│
+├── listeners:           → Integration Events que CONSUME (infrastructure/kafkaListener/)
+│
+└── ports:               → Servicios HTTP que LLAMA    (infrastructure/adapters/{service}/)
+```
+
+---
+
+## Sección ports
+
+`ports:` es una sección de nivel raíz (sibling de `aggregates:` y `listeners:`) que declara los servicios HTTP síncronos que el módulo llama, implementados con Spring Cloud OpenFeign.
+
+**Regla de agrupación:** una **entrada** = un **método**. Entradas que comparten el mismo `service:` se generan en un único FeignClient.
+
+### Propiedades de una entrada en `ports[]`
+
+| Propiedad | Tipo | Obligatorio | Descripción |
+|-----------|------|-------------|-------------|
+| `name` | String | ✅ | Nombre del método (camelCase) |
+| `service` | String | ✅ | Nombre del servicio/interfaz (PascalCase). Agrupa métodos en un FeignClient |
+| `target` | String | ❌ | Módulo destino — referencia documental; no afecta la generación |
+| `baseUrl` | String | ❌* | URL base del servicio. Declarar solo en la **primera entrada** del `service:` |
+| `http` | String | ✅ | Verbo HTTP + path: `GET /resource/{id}`, `POST /resource`, etc. |
+| `fields` | Array | ❌ | Campos de la respuesta → genera `{MethodPascal}ResponseDto.java` |
+| `body` | Array | ❌ | Campos del cuerpo de la petición (solo POST/PUT/PATCH) → genera `{MethodPascal}RequestDto.java` |
+| `returnList` | Boolean | ❌ | `true` → retorno `List<{MethodPascal}ResponseDto>`. Default: `false` |
+| `nestedTypes` | Array | ❌ | Records auxiliares para campos de tipo objeto en `body:` o `fields:` |
+
+*Si se omite `baseUrl` en todas las entradas de un `service:`, se emite un warning y se usa `http://localhost:8080`.
+
+### Reglas de uso
+
+- **`baseUrl:`** — declarar únicamente en la primera entrada del `service:`. Eva4j la registra en `parameters/{env}/urls.yaml` como `{module-kebab}.{service-kebab}.base-url`.
+- **`body:`** — válido solo en POST, PUT y PATCH. En GET/DELETE emite warning y se ignora.
+- **`returnList: true`** — el tipo de retorno pasa de `{Method}ResponseDto` a `List<{Method}ResponseDto>`.
+- **`fields:` omitido** → retorno `void` en la interfaz del puerto y en el FeignClient.
+- **`nestedTypes:`** — se generan como records separados en `application/dtos/`. Se deduplican por nombre dentro del mismo `service:`. Aplica tanto para campos en `body:` como en `fields:`.
+
+### Estructura mínima
+
+```yaml
+# Un solo método GET, respuesta simple
+ports:
+  - name: findScreeningById
+    service: ScreeningService
+    target: screenings
+    baseUrl: http://localhost:8081
+    http: GET /screenings/{id}
+    fields:
+      - name: id
+        type: String
+      - name: startTime
+        type: LocalDateTime
+```
+
+### Ejemplo con todos los patrones
+
+```yaml
+ports:
+  # GET con variable de ruta
+  - name: findScreeningById
+    service: ScreeningService
+    target: screenings
+    baseUrl: http://localhost:8081          # ← solo en la primera entrada del service
+    http: GET /screenings/{id}
+    fields:
+      - name: id
+        type: String
+      - name: startTime
+        type: LocalDateTime
+
+  # GET retornando lista
+  - name: findAvailableSeats
+    service: ScreeningService              # mismo service → mismo FeignClient
+    target: screenings
+    http: GET /screenings/{id}/seats
+    returnList: true                       # → List<FindAvailableSeatResponseDto>
+    fields:
+      - name: seatId
+        type: String
+      - name: seatType
+        type: String
+
+  # POST con body + nestedType + respuesta
+  - name: processPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    baseUrl: https://api.payments.example.com
+    http: POST /payments
+    body:
+      - name: amount
+        type: BigDecimal
+      - name: paymentMethod
+        type: PaymentMethodInput            # tipo objeto → declarar en nestedTypes:
+    nestedTypes:
+      - name: paymentMethodInput
+        fields:
+          - name: type
+            type: String
+          - name: cardToken
+            type: String
+    fields:
+      - name: paymentId
+        type: String
+      - name: status
+        type: String
+
+  # DELETE void (sin fields)
+  - name: cancelPayment
+    service: PaymentGateway
+    target: payment-gateway-external
+    http: DELETE /payments/{id}
+    # fields: omitido → retorno void
+```
+
+### Artefactos generados por `service:` único
+
+| Archivo | Descripción |
+|---------|-------------|
+| `domain/repositories/{ServiceName}.java` | Interfaz del puerto secundario |
+| `infrastructure/adapters/{service}/{ServiceName}FeignClient.java` | `@FeignClient` tipado |
+| `infrastructure/adapters/{service}/{ServiceName}FeignAdapter.java` | `@Component implements {ServiceName}` |
+| `infrastructure/adapters/{service}/{ServiceName}FeignConfig.java` | Configuración de timeouts |
+| `parameters/{env}/urls.yaml` | Propiedad `{module}.{service}.base-url` |
+
+### Artefactos generados por método
+
+| Archivo | Condición |
+|---------|-----------|
+| `application/dtos/{MethodPascal}ResponseDto.java` | Cuando `fields:` tiene elementos |
+| `application/dtos/{MethodPascal}RequestDto.java` | Cuando `body:` tiene elementos (POST/PUT/PATCH) |
+| `application/dtos/{NestedTypePascal}.java` | Por cada entrada en `nestedTypes:` |
+
+### Referencia
+
+Ver ejemplo completo en [`examples/domain-ports.yaml`](examples/domain-ports.yaml).
+
+---
+
 ## Relaciones
 
 eva4j soporta relaciones JPA bidireccionales completas con generación automática del lado inverso.
@@ -2441,6 +2859,154 @@ 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{PluralAggregate}` | 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          ← estándar (completo)
+  usecases/
+    CreateOrderCommandHandler.java   ← estándar
+    DeleteOrderCommandHandler.java   ← estándar
+    ConfirmOrderCommandHandler.java  ← scaffold
+    GetOrderQueryHandler.java        ← estándar
+    FindAllOrdersQueryHandler.java   ← estándar
+  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)
@@ -2860,7 +3426,7 @@ eva4j generate entities <module-name>
 - Control de visibilidad de campos (`readOnly`, `hidden`, `defaultValue`)
 - Referencias cross-agregado (`reference:`)
 - Domain Events (`events:` con soporte opcional de Kafka)
-- Soft delete a nivel de módulo (configurado en `eva add module`)
+- Soft delete por entidad raíz (`hasSoftDelete: true` en `isRoot: true`) ✅ Implementado
 
 ### 🚧 Próximamente