eva4j 1.0.12 → 1.0.13

package/DOMAIN_YAML_GUIDE.md

@@ -49,9 +49,9 @@ Las entidades de dominio generadas siguen estrictamente los principios de Domain
 - ✅ Protección de invariantes del dominio
 
 **✅ Constructores sin Validaciones Automáticas:**
-- Los constructores asignan valores directamente sin validaciones automáticas
-- Las validaciones se implementarán en un release futuro mediante configuración en domain.yaml
-- Por ahora, las validaciones deben implementarse manualmente en métodos de negocio según sea necesario
+- Los constructores asignan valores directamente sin validaciones de Bean Validation
+- Las validaciones JSR-303 se declaran en `domain.yaml` y se aplican en la capa de aplicación (Command y CreateDto), no en el dominio
+- Las reglas de invariantes de dominio deben implementarse manualmente en los métodos de negocio
 
 **📦 Inmutabilidad de Value Objects:**
 - Campos declarados como `final`
@@ -132,17 +132,28 @@ aggregates:
       # Enumeraciones del dominio
       - name: EnumName
         values: []
+    
+    events:
+      # Eventos de dominio que emite este agregado
+      - name: NombreEventoOcurrido
+        fields: []
+        # kafka: true  # opcional — genera publicación a Kafka vía MessageBroker
 ```
 
 ### Ubicación del archivo
 
 ```
 tu-proyecto/
-└── modules/
-    └── tu-modulo/
-        └── domain.yaml    ← Aquí
+└── src/
+    └── main/
+        └── java/
+            └── com/example/myapp/   ← packagePath (ej: com.example.myapp)
+                └── orders/          ← moduleName
+                    └── domain.yaml  ← Aquí
 ```
 
+Eva4j espera el `domain.yaml` dentro de la carpeta del módulo, que se encuentra bajo la ruta del package Java. Esta ubicación es creada automáticamente al ejecutar `eva add module <nombre>`.
+
 ---
 
 ## Definición de Agregados
@@ -257,6 +268,13 @@ fields:
 **Propiedades soportadas:**
 - `name`: Nombre del campo (obligatorio)
 - `type`: Tipo de dato Java (obligatorio)
+- `readOnly`: Excluye del constructor de negocio y CreateDto (ver [Control de Visibilidad](#control-de-visibilidad-de-campos))
+- `hidden`: Excluye del ResponseDto
+- `defaultValue`: Valor inicial para campos `readOnly` (ver [Ó `defaultValue`](#-defaultvalue-valor-inicial-para-campos-readonly))
+- `validations`: Anotaciones JSR-303 en Command y CreateDto
+- `reference`: Referencia semántica a otro agregado
+- `annotations`: Anotaciones JPA personalizadas
+- `isValueObject` / `isEmbedded`: Marcas explícitas de Value Object
 
 #### Detección automática de tipos
 
@@ -407,6 +425,7 @@ Eva4j permite controlar qué campos participan en constructores, DTOs de creaci
 |-------|---------------------|----------------------|-----------|-------------|
 | **Normal** | ✅ Incluido | ✅ Incluido | ✅ Incluido | ✅ Incluido |
 | **`readOnly: true`** | ❌ Excluido | ✅ Incluido | ❌ Excluido | ✅ Incluido |
+| **`readOnly` + `defaultValue`** | ⚡ Asignado con default | ✅ Incluido | ❌ Excluido | ✅ Incluido |
 | **`hidden: true`** | ✅ Incluido | ✅ Incluido | ✅ Incluido | ❌ Excluido |
 | **Ambos flags** | ❌ Excluido | ✅ Incluido | ❌ Excluido | ❌ Excluido |
 
@@ -488,6 +507,98 @@ public record OrderResponseDto(
 ) {}
 ```
 
+#### 🎯 `defaultValue` - Valor Inicial para campos `readOnly`
+
+Permite asignar un valor inicial predecible a un campo `readOnly` directamente en `domain.yaml`. El generador emite la asignación en el **constructor de creación** de la entidad de dominio y añade `@Builder.Default` en la entidad JPA.
+
+**Restricción:** Solo aplica a campos `readOnly: true`. Si se usa sin `readOnly`, eva4j emite un warning y lo ignora.
+
+**Casos de uso típicos:**
+- Estado inicial de enums (`PENDING`, `ACTIVE`, `DRAFT`)
+- Contadores que comienzan en cero
+- Totales/acumuladores antes de cálculos
+- Flags booleanos con estado conocido al crear
+
+**Sintaxis:**
+```yaml
+fields:
+  - name: totalAmount
+    type: BigDecimal
+    readOnly: true
+    defaultValue: "0.00"        # ✅ BigDecimal literal
+
+  - name: itemCount
+    type: Integer
+    readOnly: true
+    defaultValue: 0              # ✅ Integer literal
+
+  - name: status
+    type: OrderStatus
+    readOnly: true
+    defaultValue: PENDING        # ✅ Enum value (sin comillas)
+
+  - name: isActive
+    type: Boolean
+    readOnly: true
+    defaultValue: true           # ✅ Boolean literal
+```
+
+**Código generado en la entidad de dominio:**
+```java
+// Constructor de creación — defaultValues asignados automáticamente
+public Order(String orderNumber, String customerId) {
+    this.orderNumber = orderNumber;
+    this.customerId = customerId;
+    this.totalAmount = new BigDecimal("0.00");  // ← defaultValue
+    this.itemCount = 0;                          // ← defaultValue
+    this.status = OrderStatus.PENDING;           // ← defaultValue
+    this.isActive = true;                        // ← defaultValue
+}
+
+// Constructor completo (reconstrucción desde BD) — sin defaultValues
+public Order(String id, String orderNumber, String customerId,
+             BigDecimal totalAmount, Integer itemCount,
+             OrderStatus status, Boolean isActive, ...) {
+    // Todos los campos asignados desde parámetros
+}
+```
+
+**Código generado en la entidad JPA:**
+```java
+@Builder.Default
+private BigDecimal totalAmount = new BigDecimal("0.00");
+
+@Builder.Default
+private Integer itemCount = 0;
+
+@Enumerated(EnumType.STRING)
+@Builder.Default
+private OrderStatus status = OrderStatus.PENDING;
+```
+
+**Tipos Java soportados y su forma de emisión:**
+
+| Tipo | Ejemplo YAML | Literal Java emitido |
+|------|-------------|----------------------|
+| `String` | `defaultValue: hello` | `"hello"` |
+| `Integer` | `defaultValue: 0` | `0` |
+| `Long` | `defaultValue: 0` | `0L` |
+| `Boolean` | `defaultValue: false` | `false` |
+| `BigDecimal` | `defaultValue: "0.00"` | `new BigDecimal("0.00")` |
+| `LocalDateTime` | `defaultValue: now` | `LocalDateTime.now()` |
+| `LocalDate` | `defaultValue: now` | `LocalDate.now()` |
+| `Instant` | `defaultValue: now` | `Instant.now()` |
+| `UUID` | `defaultValue: random` | `UUID.randomUUID()` |
+| Enum | `defaultValue: ACTIVE` | `EnumType.ACTIVE` |
+
+**Compatibilidad con otros flags:**
+
+| Combinación | Constructor Creación | JPA Builder | CreateDto | ResponseDto |
+|------------|:-------------------:|:-----------:|:---------:|:-----------:|
+| `readOnly` + `defaultValue` | ⚡ Asignado con default | `@Builder.Default` | ❌ | ✅ |
+| `readOnly` + `hidden` + `defaultValue` | ⚡ Asignado con default | `@Builder.Default` | ❌ | ❌ |
+| `defaultValue` sin `readOnly` | *Ignorado (warning)* | *Ignorado* | — | — |
+
 #### 🙈 `hidden: true` - Campos Sensibles/Internos
 
 Marca campos que **NO deben exponerse** en respuestas de API pero sí pueden recibirse en creación.
@@ -1253,11 +1364,57 @@ valueObjects:
         type: String
 ```
 
+### Value Objects con métodos de negocio
+
+Los Value Objects pueden declarar métodos de negocio directamente en el `domain.yaml`. Estos se generan como métodos públicos en la clase del Value Object.
+
+```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;"
+```
+
+**Código generado:**
+```java
+public Money add(Money other) {
+    return new Money(this.amount.add(other.getAmount()), this.currency);
+}
+
+public boolean isPositive() {
+    return this.amount.compareTo(BigDecimal.ZERO) > 0;
+}
+```
+
+**Propiedades de un método:**
+
+| Propiedad | Descripción |
+|-----------|-------------|
+| `name` | Nombre del método |
+| `returnType` | Tipo de retorno Java |
+| `parameters` | Array de `{ name, type }` |
+| `body` | Cuerpo del método (string Java) |
+
 ---
 
 ## Enums
 
-### Definición
+### Definición básica
 
 ```yaml
 enums:
@@ -1314,6 +1471,199 @@ enums:
 
 ---
 
+### Enums con Transiciones de Estado
+
+Cuando un enum representa un ciclo de vida de negocio, puede declarar `transitions` e `initialValue`. Eva4j genera automáticamente los métodos de transición, guards, helpers de consulta y el mapa de transiciones válidas.
+
+#### Sintaxis
+
+```yaml
+enums:
+  - name: OrderStatus
+    initialValue: PENDING        # ← Estado inicial (se asigna en el constructor de creación)
+    transitions:
+      - from: PENDING
+        to: CONFIRMED
+        method: confirm
+
+      - from: CONFIRMED
+        to: SHIPPED
+        method: ship
+
+      - from: SHIPPED
+        to: DELIVERED
+        method: deliver
+
+      - from: [PENDING, CONFIRMED]   # múltiples estados origen
+        to: CANCELLED
+        method: cancel
+        guard: "this.status == OrderStatus.DELIVERED"  # lanza BusinessException si se cumple
+
+    values:
+      - PENDING
+      - CONFIRMED
+      - SHIPPED
+      - DELIVERED
+      - CANCELLED
+```
+
+#### Propiedades de transición
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `from` | String \| Array | Estado(s) de origen válidos |
+| `to` | String | Estado destino |
+| `method` | String | Nombre del método que ejecuta la transición |
+| `guard` | String | Condición Java que lanza `BusinessException` si se cumple (opcional) |
+
+#### Qué genera
+
+**En el enum (`OrderStatus.java`):**
+```java
+public enum OrderStatus {
+    PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED;
+
+    private static final Map<OrderStatus, Set<OrderStatus>> VALID_TRANSITIONS;
+    // ... mapa estático inicializado
+
+    public boolean canTransitionTo(OrderStatus target) { ... }
+    public OrderStatus transitionTo(OrderStatus target) { ... } // lanza InvalidStateTransitionException
+}
+```
+
+**En la entidad raíz (`Order.java`):**
+```java
+// El constructor de creación NO recibe status (se auto-inicializa a PENDING)
+public Order(String orderNumber, String customerId) {
+    this.orderNumber = orderNumber;
+    this.customerId = customerId;
+    this.status = OrderStatus.PENDING;  // ← initialValue aplicado
+}
+
+// Métodos de transición generados
+public void confirm() { this.status = this.status.transitionTo(OrderStatus.CONFIRMED); }
+public void ship()    { this.status = this.status.transitionTo(OrderStatus.SHIPPED); }
+public void deliver() { this.status = this.status.transitionTo(OrderStatus.DELIVERED); }
+public void cancel() {
+    if (this.status == OrderStatus.DELIVERED) {
+        throw new BusinessException("Cannot execute 'cancel': business rule violated");
+    }
+    this.status = this.status.transitionTo(OrderStatus.CANCELLED);
+}
+
+// Helpers de consulta de estado
+public boolean isPending()   { return this.status == OrderStatus.PENDING; }
+public boolean isConfirmed() { return this.status == OrderStatus.CONFIRMED; }
+// ... uno por cada valor del enum
+
+// Helpers de disponibilidad de transición
+public boolean canConfirm() { return this.status.canTransitionTo(OrderStatus.CONFIRMED); }
+public boolean canCancel()  { return this.status.canTransitionTo(OrderStatus.CANCELLED); }
+// ... uno por cada método de transición
+```
+
+**Nota:** El campo con `initialValue` se trata implícitamente como `readOnly: true` — no aparece en el constructor de negocio ni en el `CreateDto`.
+
+---
+
+## Eventos de Dominio
+
+Los eventos de dominio representan hechos significativos que ocurren dentro del agregado. Eva4j genera las clases de evento y el handler para publicarlos automáticamente tras commit de transacción.
+
+### Sintaxis
+
+```yaml
+aggregates:
+  - name: Order
+    entities:
+      - name: order
+        isRoot: true
+        tableName: orders
+        fields:
+          - name: id
+            type: String
+          - name: orderNumber
+            type: String
+    
+    events:
+      - name: OrderConfirmedEvent        # PascalCase, idealmente en pasado
+        fields:
+          - name: orderId
+            type: String
+          - name: confirmedAt
+            type: LocalDateTime
+      
+      - name: OrderShippedEvent
+        kafka: true                      # opcional — genera publicación a Kafka
+        fields:
+          - name: orderId
+            type: String
+          - name: trackingNumber
+            type: String
+```
+
+### 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}()` |
+
+### Archivos generados
+
+Para cada evento, eva4j genera dos archivos:
+
+**1. `OrderConfirmedEvent.java`** — en `domain/models/events/`
+```java
+public final class OrderConfirmedEvent extends DomainEvent {
+    private final String orderId;
+    private final LocalDateTime confirmedAt;
+
+    public OrderConfirmedEvent(String aggregateId, String orderId, LocalDateTime confirmedAt) {
+        super(aggregateId);
+        this.orderId = orderId;
+        this.confirmedAt = confirmedAt;
+    }
+
+    public String getOrderId() { return orderId; }
+    public LocalDateTime getConfirmedAt() { return confirmedAt; }
+}
+```
+
+**2. `OrderDomainEventHandler.java`** — en `application/usecases/`
+```java
+@Component
+public class OrderDomainEventHandler {
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    public void handle(OrderConfirmedEvent event) {
+        // Lógica post-commit — ej: notificaciones, métricas
+    }
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    public void handle(OrderShippedEvent event) {
+        messageBroker.sendOrderShippedEvent(event);  // kafka: true
+    }
+}
+```
+
+### Cómo publicar un evento
+
+Los eventos se publican desde métodos de negocio de la entidad raíz usando el método heredado `raise()`:
+
+```java
+// En Order.java (entidad de dominio)
+public void confirm() {
+    this.status = this.status.transitionTo(OrderStatus.CONFIRMED);
+    raise(new OrderConfirmedEvent(this.id, this.id, LocalDateTime.now()));
+}
+```
+
+> **Nota:** `raise()` es provisto por la clase base de dominio. La publicación real ocurre tras el commit de la transacción gracias a `@TransactionalEventListener(AFTER_COMMIT)`.
+
+---
+
 ## Relaciones
 
 eva4j soporta relaciones JPA bidireccionales completas con generación automática del lado inverso.
@@ -2498,22 +2848,26 @@ eva4j generate entities <module-name>
 ### ✅ Soportado
 
 - Agregados con entidad raíz y secundarias
-- Value Objects embebidos
-- Enums con valores
-- Relaciones OneToMany, ManyToOne, OneToOne
+- Value Objects embebidos (con `methods` opcionales)
+- Enums simples y con transiciones de estado (`transitions`, `initialValue`)
+- Relaciones OneToMany, ManyToOne, OneToOne (bidireccionales automáticas)
 - Tipos primitivos y de fecha Java
-- Colecciones de primitivos y VOs
+- Colecciones de primitivos y VOs (`List<T>`)
 - IDs: String (UUID), Long/Integer (IDENTITY)
 - Cascade y Fetch personalizados
+- Validaciones JSR-303 en Command y CreateDto
+- Auditoría automática (`audit.enabled`, `audit.trackUser`)
+- 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`)
 
 ### 🚧 Próximamente
 
-- Validaciones JSR-303
-- Auditoría automática
-- Soft delete
-- Query methods personalizados
-- Índices y constraints
-- Herencia de entidades
+- Query methods personalizados en repositorios
+- Índices y constraints de BD declarados en YAML
+- Herencia de entidades JPA
+- Soporte de `Instant` como tipo de campo (actualmente solo para `defaultValue`)
 
 ---
 
@@ -2529,7 +2883,7 @@ R: Los enums son globales al módulo, solo usa el nombre: `type: OrderStatus`
 R: Sí, pero debes definirlo en cada agregado (por ahora).
 
 **P: ¿Qué pasa si regenero el código?**  
-R: Se sobrescriben los archivos. Modifica solo en templates, no en código generado.
+R: Eva4j usa checksums SHA-256 para detectar archivos que fueron modificados manualmente. Los archivos con cambios manuales **no se sobreescriben** — se muestra un aviso y se omiten. Usa `--force` para forzar la sobreescritura de todos los archivos.
 
 **P: ¿Puedo personalizar las entidades generadas?**  
 R: Sí, modifica las plantillas en `templates/aggregate/`.
@@ -2538,10 +2892,9 @@ R: Sí, modifica las plantillas en `templates/aggregate/`.
 
 ## Recursos Adicionales
 
-- [Guía de Implementación](IMPLEMENTATION_SUMMARY.md)
-- [Guía de Testing](TESTING_GUIDE.md)
 - [Referencia Rápida](QUICK_REFERENCE.md)
-- [Documentación DDD](https://martinfowler.com/bliki/DomainDrivenDesign.html)
+- [Guía de Agentes IA](AGENTS.md)
+- [Características Futuras](FUTURE_FEATURES.md)
 
 ---
 

package/FUTURE_FEATURES.md

@@ -967,6 +967,98 @@ private Integer age;
 
 ---
 
+## 16. `defaultValue` para campos `readOnly` (Implementado)
+
+Permite especificar un valor inicial para campos `readOnly` directamente en `domain.yaml`. El valor se emite en el **constructor de creación** de la entidad de dominio y como field initializer con `@Builder.Default` en la entidad JPA.
+
+### Sintaxis
+
+```yaml
+entities:
+  - name: order
+    fields:
+      - name: status
+        type: OrderStatus
+        readOnly: true
+        defaultValue: PENDING          # Enum value
+      
+      - name: totalAmount
+        type: BigDecimal
+        readOnly: true
+        defaultValue: "0.00"           # BigDecimal literal
+      
+      - name: itemCount
+        type: Integer
+        readOnly: true
+        defaultValue: 0                # Integer literal
+      
+      - name: isActive
+        type: Boolean
+        readOnly: true
+        defaultValue: true             # Boolean literal
+```
+
+### Código Generado — Dominio
+
+```java
+// Constructor de creación — defaultValue asignado automáticamente
+public Order(String orderNumber, String customerId) {
+    this.orderNumber = orderNumber;
+    this.customerId = customerId;
+    // readOnly fields initialized with defaultValue:
+    this.status = OrderStatus.PENDING;
+    this.totalAmount = new BigDecimal("0.00");
+    this.itemCount = 0;
+    this.isActive = true;
+}
+```
+
+### Código Generado — JPA
+
+```java
+@Builder.Default
+private OrderStatus status = OrderStatus.PENDING;
+
+@Builder.Default
+private BigDecimal totalAmount = new BigDecimal("0.00");
+
+@Builder.Default
+private Integer itemCount = 0;
+```
+
+### Tipos soportados
+
+| Tipo Java | Ejemplo YAML | Java emitido |
+|-----------|-------------|---------------|
+| `String` | `defaultValue: hello` | `"hello"` |
+| `Integer` / `Long` | `defaultValue: 0` | `0` / `0L` |
+| `Boolean` | `defaultValue: false` | `false` |
+| `BigDecimal` | `defaultValue: "0.00"` | `new BigDecimal("0.00")` |
+| `LocalDateTime` | `defaultValue: now` | `LocalDateTime.now()` |
+| `LocalDate` | `defaultValue: now` | `LocalDate.now()` |
+| `Instant` | `defaultValue: now` | `Instant.now()` |
+| `UUID` | `defaultValue: random` | `UUID.randomUUID()` |
+| Enum | `defaultValue: ACTIVE` | `EnumType.ACTIVE` |
+
+### Reglas
+
+- `defaultValue` **solo es válido** en campos con `readOnly: true`. Si se usa en un campo no-readOnly, se emite un warning y se ignora.
+- El campo **sigue siendo readOnly** — no aparece en el constructor de negocio ni en `CreateDto`.
+- En campos con `autoInit` (enum con `initialValue`), `defaultValue` es ignorado — `autoInit` tiene precedencia.
+
+### Archivos Modificados
+
+| Archivo | Cambio |
+|---|---|
+| `src/utils/yaml-to-entity.js` | ✅ `computeJavaDefaultValue()` + `defaultValue` en `parseProperty()` |
+| `templates/aggregate/AggregateRoot.java.ejs` | ✅ Emite `this.field = defaultValue` en constructor de creación |
+| `templates/aggregate/DomainEntity.java.ejs` | ✅ Mismo cambio para entidades secundarias |
+| `templates/aggregate/JpaAggregateRoot.java.ejs` | ✅ `@Builder.Default` + field initializer |
+| `templates/aggregate/JpaEntity.java.ejs` | ✅ Mismo cambio para entidades JPA secundarias |
+| `examples/domain-field-visibility.yaml` | ✅ Ejemplos con `defaultValue` en campos readOnly |
+
+---
+
 ## 15. Transactional Outbox Pattern
 
 ### Descripción
@@ -1067,9 +1159,10 @@ Domain Events (ítem 1) implementados y funcionando — este ítem solo añade p
 | 13 | Auditoria completa | Impl. | -- | ✅ Implementado |
 | 14 | Validaciones JSR-303 | Impl. | -- | ✅ Implementado |
 | 15 | Transactional Outbox Pattern | Alta | Alta | Pendiente |
+| 16 | `defaultValue` para campos `readOnly` | Impl. | -- | ✅ Implementado |
 
 ---
 
-**Ultima actualizacion:** 2026-02-25
+**Ultima actualizacion:** 2026-03-04
 **Version de eva4j:** 1.x
 **Estado:** Documento de planificacion y referencia