eva4j 1.0.12 → 1.0.14

package/AGENTS.md

@@ -451,11 +451,223 @@ aggregates:
           - ACTIVE
           - INACTIVE
           - SUSPENDED
+    
+    events:
+      - name: UserRegisteredEvent
+        fields:
+          - name: userId
+            type: String
+        # 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
+
+### Value Objects con Métodos
+
+Los Value Objects pueden declarar métodos de negocio directamente en `domain.yaml`:
+
+```yaml
+valueObjects:
+  - name: Money
+    fields:
+      - name: amount
+        type: BigDecimal
+      - name: currency
+        type: String
+    methods:
+      - name: add
+        returnType: Money
+        parameters:
+          - name: other
+            type: Money
+        body: "return new Money(this.amount.add(other.getAmount()), this.currency);"
+      - name: isPositive
+        returnType: boolean
+        parameters: []
+        body: "return this.amount.compareTo(BigDecimal.ZERO) > 0;"
+```
+
+### Enums con Ciclo de Vida (Transitions)
+
+Cuando un enum representa estados de negocio, declara `transitions` e `initialValue`:
+
+```yaml
+enums:
+  - name: OrderStatus
+    initialValue: PENDING        # Auto-inicializa en constructor; 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]
+```
+
+Genera automáticamente **en la entidad raíz**: `confirm()`, `ship()`, `cancel()`, helpers `isPending()`, `isConfirmed()`, `canConfirm()`, `canCancel()`.  
+Genera automáticamente **en el enum**: `VALID_TRANSITIONS`, `canTransitionTo()`, `transitionTo()` (lanza `InvalidStateTransitionException` si la transición no es válida).
+
+**Nota:** El campo con `initialValue` se trata como `readOnly: true` — no aparece en el constructor de negocio ni en el `CreateDto`.
+
+### Eventos de Dominio (`events[]`)
+
+```yaml
+aggregates:
+  - name: Order
+    entities: [...]
+    events:
+      - name: OrderConfirmed
+        fields:
+          - name: orderId
+            type: String
+          - name: confirmedAt
+            type: LocalDateTime
+```
+
+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 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
+
+Cuando una entidad tiene `hasSoftDelete: true`, eva4j genera eliminación lógica en lugar de física.
+
+### Configuración en domain.yaml
+
+```yaml
+entities:
+  - name: product
+    isRoot: true
+    tableName: products
+    hasSoftDelete: true          # ✅ Activa soft delete
+    audit:
+      enabled: true
+    fields:
+      - name: id
+        type: String
+      - name: name
+        type: String
+```
+
+### Comportamiento generado
+
+```java
+// Entidad JPA — filtrado automático con @SQLRestriction
+@Entity
+@SQLRestriction("deleted_at IS NULL")
+public class ProductJpa extends AuditableEntity {
+    @Column(name = "deleted_at")
+    private LocalDateTime deletedAt;
+}
 ```
 
+```java
+// Entidad de dominio — método de negocio
+public class Product {
+    private LocalDateTime deletedAt;
+
+    public void softDelete() {
+        if (this.deletedAt != null) {
+            throw new IllegalStateException("Product is already deleted");
+        }
+        this.deletedAt = LocalDateTime.now();
+    }
+
+    public boolean isDeleted() {
+        return this.deletedAt != null;
+    }
+}
+```
+
+### Reglas para Agentes
+
+- **NUNCA** usar `repository.deleteById()` cuando hay soft delete
+- **SIEMPRE** usar `entity.softDelete()` + `repository.save(entity)`
+- **NUNCA** exponer `deletedAt` en ResponseDtos
+- **SIEMPRE** usar `@SQLRestriction("deleted_at IS NULL")` en la entidad JPA
+
 ---
 
-## 🚨 Errores Comunes a Evitar
+## ⏱️ Temporal Workflows
+
+Cuando se agrega soporte de Temporal con `eva add temporal-client`, se genera infraestructura para workflows duraderos.
+
+### Archivos generados por `eva g temporal-flow <module>`
+
+```
+[module]/
+├── application/workflows/
+│   ├── OrderWorkflow.java          # Interface (@WorkflowInterface)
+│   └── OrderWorkflowImpl.java      # Implementación (determinista)
+└── infrastructure/temporal/
+    ├── activities/
+    │   ├── OrderActivity.java          # Interface (@ActivityInterface)
+    │   └── OrderActivityImpl.java      # Implementación (con I/O)
+    └── workers/
+        └── OrderWorker.java            # Registro del worker
+```
+
+### Principios clave
+
+- Los **Workflows deben ser deterministas** — sin `Math.random()`, `new Date()`, ni I/O
+- Toda operación con efectos secundarios (DB, HTTP, emails) va en **Activities**
+- Los **Use Cases** orquestan los workflows; las **Activities** ejecutan infraestructura
+- Configuración de conexión en `resources/parameters/{env}/temporal.yaml`
+
+### Templates relacionados en eva4j
+
+- `templates/temporal-flow/` — workflow interface e implementación
+- `templates/temporal-activity/` — activity interface, implementación y worker
+
+---
+
+## �🚨 Errores Comunes a Evitar
 
 ### ❌ NO Crear Constructor Vacío en Dominio
 
@@ -566,6 +778,7 @@ Los campos en domain.yaml soportan las siguientes propiedades:
 | `enumValues` | Array | `[]` | Valores inline de enum |
 | **`readOnly`** | Boolean | `false` | **Excluye del constructor de negocio y CreateDto** |
 | **`hidden`** | Boolean | `false` | **Excluye del ResponseDto** |
+| **`defaultValue`** | String/Number/Boolean | `null` | **Valor inicial en el constructor de creación (solo para `readOnly`)** |
 | **`validations`** | Array | `[]` | **Anotaciones JSR-303 en el Command y CreateDto** |
 | **`reference`** | Object | `null` | **Declara referencia semántica a otro agregado (genera comentario Javadoc)** |
 
@@ -601,9 +814,57 @@ fields:
 |-------|---------------------|-----------|-------------|
 | Normal | ✅ | ✅ | ✅ |
 | `readOnly: true` | ❌ | ❌ | ✅ |
+| `readOnly` + `defaultValue` | ⚡ Asignado con default | ❌ | ✅ |
 | `hidden: true` | ✅ | ✅ | ❌ |
 | Ambos flags | ❌ | ❌ | ❌ |
 
+#### 🎯 `defaultValue` - Valor Inicial para campos `readOnly`
+
+Cuando un campo `readOnly` tiene un valor inicial predecible (ej: contadores, estados iniciales), se puede declarar en `domain.yaml` con `defaultValue`. El generador emite la asignación en el **constructor de creación** del dominio y `@Builder.Default` en la entidad JPA.
+
+```yaml
+fields:
+  - name: totalAmount
+    type: BigDecimal
+    readOnly: true
+    defaultValue: "0.00"        # ✅ Acumulador inicializado
+
+  - name: status
+    type: OrderStatus
+    readOnly: true
+    defaultValue: PENDING        # ✅ Estado inicial del enum
+
+  - name: itemCount
+    type: Integer
+    readOnly: true
+    defaultValue: 0              # ✅ Contador inicializado
+```
+
+```java
+// Constructor de creación — defaultValues aplicados
+public Order(String orderNumber, String customerId) {
+    this.orderNumber = orderNumber;
+    this.customerId = customerId;
+    this.totalAmount = new BigDecimal("0.00");  // ← defaultValue
+    this.status = OrderStatus.PENDING;           // ← defaultValue
+    this.itemCount = 0;                          // ← defaultValue
+}
+```
+
+```java
+// JPA — @Builder.Default para respetar el valor en el builder
+@Builder.Default
+private BigDecimal totalAmount = new BigDecimal("0.00");
+
+@Enumerated(EnumType.STRING)
+@Builder.Default
+private OrderStatus status = OrderStatus.PENDING;
+```
+
+**Restricción:** `defaultValue` **solo aplica** a campos con `readOnly: true`. Usarlo en un campo no-readOnly genera un warning y es ignorado.
+
+---
+
 **Ejemplo práctico:**
 ```yaml
 entities:
@@ -626,6 +887,87 @@ entities:
         hidden: true
 ```
 
+### Validaciones JSR-303 (`validations`)
+
+Se declaran en el campo y se aplican **únicamente** en el `Command` y `CreateDto` de la capa de aplicación. **Nunca** en las entidades de dominio.
+
+```yaml
+fields:
+  - name: email
+    type: String
+    validations:
+      - type: NotBlank
+        message: "Email es requerido"
+      - type: Email
+        message: "Email inválido"
+
+  - name: username
+    type: String
+    validations:
+      - type: Size
+        min: 3
+        max: 50
+        message: "Username entre 3 y 50 caracteres"
+
+  - name: age
+    type: Integer
+    validations:
+      - type: Min
+        value: 18
+      - type: Max
+        value: 120
+
+  - name: price
+    type: BigDecimal
+    validations:
+      - type: Positive
+```
+
+**Anotaciones disponibles:** `NotNull`, `NotBlank`, `NotEmpty`, `Email`, `Size` (min/max), `Min` (value), `Max` (value), `Pattern` (regexp), `Digits` (integer/fraction), `Positive`, `PositiveOrZero`, `Negative`, `Past`, `Future`, `AssertTrue`, `AssertFalse`.
+
+**Código generado en `CreateUserCommand.java`:**
+```java
+public record CreateUserCommand(
+    @NotBlank(message = "Email es requerido")
+    @Email(message = "Email inválido")
+    String email,
+
+    @Size(min = 3, max = 50, message = "Username entre 3 y 50 caracteres")
+    String username
+) implements Command {}
+```
+
+### Referencias entre Agregados (`reference`)
+
+Declara explícitamente que un campo es un ID de otro agregado. El tipo Java **no cambia** — sigue siendo `String`, `Long`, etc. — pero se genera un comentario Javadoc que documenta la dependencia. **No genera `@ManyToOne`** (correcto en DDD: cada agregado es una unidad transaccional independiente).
+
+```yaml
+fields:
+  - name: customerId
+    type: String
+    reference:
+      aggregate: Customer    # Nombre del agregado referenciado (PascalCase)
+      module: customers      # Módulo donde vive (opcional si es el mismo módulo)
+
+  - name: productId
+    type: String
+    reference:
+      aggregate: Product
+      module: catalog
+```
+
+**Código generado:**
+```java
+// En Order.java (domain entity)
+/** Cross-aggregate reference → Customer (module: customers) */
+private String customerId;
+
+// En OrderJpa.java
+@Column(name = "customer_id")
+/** Cross-aggregate reference → Customer (module: customers) */
+private String customerId;
+```
+
 ### Tipos de Relaciones
 
 - `OneToOne` - Relación uno a uno
@@ -637,6 +979,25 @@ entities:
 
 ## 🎯 Mejores Prácticas para Agentes
 
+### Al Generar domain.yaml (Flujo SDD)
+
+1. **SIEMPRE** incluir campo `id` en todas las entidades
+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. **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
 
 1. **NUNCA** crear constructor vacío en entidades de dominio
@@ -722,13 +1083,13 @@ HTTP Response (sin createdBy/updatedBy)
 
 ## 🧪 Testing
 
-### Tests de Dominio
+### Tests de Dominio (Unidad Pura)
 
 ```java
 @Test
 void shouldCreateUserWithValidData() {
     User user = new User("john", "john@example.com");
-    
+
     assertEquals("john", user.getUsername());
     assertEquals("john@example.com", user.getEmail());
 }
@@ -736,13 +1097,82 @@ void shouldCreateUserWithValidData() {
 @Test
 void shouldValidateBusinessRules() {
     User user = new User("john", "john@example.com");
-    
+
     assertThrows(IllegalArgumentException.class, () -> {
         user.changeEmail("invalid-email");
     });
 }
 ```
 
+### Object Mother Pattern
+
+```java
+// src/test/java/[package]/user/domain/UserMother.java
+public class UserMother {
+
+    public static User valid() {
+        return new User("john_doe", "john@example.com");
+    }
+
+    public static User withEmail(String email) {
+        return new User("john_doe", email);
+    }
+}
+```
+
+### Repositorio Fake (In-Memory)
+
+Para testear Use Cases sin base de datos:
+
+```java
+public class UserRepositoryFake implements UserRepository {
+    private final Map<String, User> store = new HashMap<>();
+
+    @Override
+    public User save(User user) {
+        store.put(user.getId(), user);
+        return user;
+    }
+
+    @Override
+    public Optional<User> findById(String id) {
+        return Optional.ofNullable(store.get(id));
+    }
+
+    public int count() { return store.size(); }
+}
+```
+
+### Tests de Use Cases
+
+```java
+class CreateUserCommandHandlerTest {
+    private final UserRepositoryFake userRepository = new UserRepositoryFake();
+    private final CreateUserCommandHandler handler =
+        new CreateUserCommandHandler(userRepository);
+
+    @Test
+    void shouldCreateUser() {
+        CreateUserCommand command = new CreateUserCommand("john", "john@example.com");
+
+        String userId = handler.handle(command);
+
+        assertNotNull(userId);
+        assertEquals(1, userRepository.count());
+    }
+}
+```
+
+### Estrategia por Capa
+
+| Capa | Tipo de Test | Framework |
+|------|--------------|-----------|
+| Domain entities | Unidad pura | JUnit 5 |
+| Use cases | Unidad con Fakes | JUnit 5 + Fake repos |
+| Application mappers | Unidad | JUnit 5 |
+| Repository implementations | Integración | Testcontainers |
+| REST controllers | Integración | MockMvc |
+
 ---
 
 ## 📖 Documentos Relacionados
@@ -758,23 +1188,52 @@ void shouldValidateBusinessRules() {
 
 Al generar o modificar código, verificar:
 
+**Entidades de Dominio:**
 - [ ] Entidades de dominio **sin constructor vacío**
 - [ ] Entidades de dominio **sin setters públicos**
 - [ ] Métodos de negocio con **validaciones explícitas**
+- [ ] Value Objects **inmutables**
+- [ ] Sin anotaciones JSR-303 en entidades de dominio
+
+**Entidades JPA:**
 - [ ] Entidades JPA con **Lombok y herencia correcta**
+- [ ] `@SQLRestriction("deleted_at IS NULL")` cuando `hasSoftDelete: true`
+- [ ] No incluye campos de auditoría heredados en `@Builder`
+
+**Mappers:**
 - [ ] Mappers **excluyen campos de auditoría**
 - [ ] Mappers **excluyen campos readOnly en creación**
 - [ ] Mappers **excluyen campos hidden en respuestas**
+- [ ] Relaciones bidireccionales con métodos `assign*()`
+
+**DTOs:**
 - [ ] DTOs de respuesta **sin createdBy/updatedBy**
 - [ ] DTOs de respuesta **sin campos hidden**
 - [ ] DTOs de creación **sin campos readOnly**
-- [ ] Relaciones bidireccionales con métodos `assign*()`
-- [ ] Value Objects **inmutables**
-- [ ] Configuración de auditoría cuando `trackUser: true`
+- [ ] Usando Java Records
+
+**Validaciones:**
 - [ ] Validaciones JSR-303 **solo en Command y CreateDto, nunca en dominio**
+- [ ] `@Valid` en parámetros de endpoints REST
+
+**Auditoría:**
+- [ ] Configuración de auditoría cuando `trackUser: true`
+- [ ] `@EnableJpaAuditing` con `auditorAwareRef = "auditorProvider"` en Application
+
+**Soft Delete (cuando aplica):**
+- [ ] Usar `entity.softDelete()` + `repository.save()` — nunca `deleteById()`
+- [ ] `deletedAt` no expuesto en ResponseDto
+
+**Características Avanzadas (cuando aplica):**
+- [ ] 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 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-02-21  
-**Versión de eva4j:** 1.x  
+**Última actualización:** 2026-03-11  
+**Versión de eva4j:** 1.0.13  
 **Estado:** Documento de referencia para agentes IA