eva4j 1.0.9 → 1.0.11

package/AGENTS.md

@@ -543,6 +543,79 @@ public record UserResponseDto(
 | Instant | Instant | Timestamp UTC |
 | UUID | UUID | Identificador único |
 
+### Propiedades de Campo
+
+Los campos en domain.yaml soportan las siguientes propiedades:
+
+| Propiedad | Tipo | Default | Descripción |
+|-----------|------|---------|-------------|
+| `name` | String | - | Nombre del campo (obligatorio) |
+| `type` | String | - | Tipo de dato Java (obligatorio) |
+| `annotations` | Array | `[]` | Anotaciones JPA personalizadas |
+| `isValueObject` | Boolean | `false` | Marca explícita de Value Object |
+| `isEmbedded` | Boolean | `false` | Marca explícita de @Embedded |
+| `enumValues` | Array | `[]` | Valores inline de enum |
+| **`readOnly`** | Boolean | `false` | **Excluye del constructor de negocio y CreateDto** |
+| **`hidden`** | Boolean | `false` | **Excluye del ResponseDto** |
+| **`validations`** | Array | `[]` | **Anotaciones JSR-303 en el Command y CreateDto** |
+
+#### Flags de Visibilidad: `readOnly` y `hidden`
+
+**`readOnly: true`** - Campos calculados/derivados
+- ❌ Excluido de: Constructor de negocio, CreateDto
+- ✅ Incluido en: Constructor completo, ResponseDto
+- **Uso:** Totales calculados, contadores, campos derivados
+
+```yaml
+fields:
+  - name: totalAmount
+    type: BigDecimal
+    readOnly: true        # Calculado de la suma de items
+```
+
+**`hidden: true`** - Campos sensibles/internos
+- ❌ Excluido de: ResponseDto
+- ✅ Incluido en: Constructor de negocio, CreateDto
+- **Uso:** Passwords, tokens, secrets, información sensible
+
+```yaml
+fields:
+  - name: passwordHash
+    type: String
+    hidden: true          # No exponer en API
+```
+
+**Matriz de comportamiento:**
+
+| Campo | Constructor Negocio | CreateDto | ResponseDto |
+|-------|---------------------|-----------|-------------|
+| Normal | ✅ | ✅ | ✅ |
+| `readOnly: true` | ❌ | ❌ | ✅ |
+| `hidden: true` | ✅ | ✅ | ❌ |
+| Ambos flags | ❌ | ❌ | ❌ |
+
+**Ejemplo práctico:**
+```yaml
+entities:
+  - name: order
+    fields:
+      - name: orderNumber
+        type: String                # ✅ Normal - en todos lados
+      
+      - name: totalAmount
+        type: BigDecimal
+        readOnly: true              # ⚙️ Calculado - no en constructor
+      
+      - name: processingToken
+        type: String
+        hidden: true                # 🔒 Sensible - no en respuesta
+      
+      - name: internalFlag
+        type: Boolean
+        readOnly: true              # 🔐 Calculado Y sensible
+        hidden: true
+```
+
 ### Tipos de Relaciones
 
 - `OneToOne` - Relación uno a uno
@@ -572,15 +645,18 @@ public record UserResponseDto(
 ### Al Generar Mappers
 
 1. **NUNCA** mapear campos de auditoría (createdAt, updatedAt, createdBy, updatedBy)
-2. **SIEMPRE** filtrar campos antes de usar `.builder()`
-3. **SIEMPRE** mapear bidireccionalidad en relaciones
+2. **NUNCA** mapear campos readOnly en métodos de creación (fromCommand, fromDto)
+3. **NUNCA** mapear campos hidden en métodos de respuesta (toDto, toResponseDto)
+4. **SIEMPRE** filtrar campos antes de usar `.builder()`
+5. **SIEMPRE** mapear bidireccionalidad en relaciones
 
 ### Al Generar DTOs
 
 1. **NUNCA** exponer `createdBy` y `updatedBy` en respuestas
-2. **SIEMPRE** exponer `createdAt` y `updatedAt`
-3. **SIEMPRE** usar Java Records para DTOs
-4. **SIEMPRE** filtrar campos al crear contextos de template
+2. **NUNCA** incluir campos `readOnly` en CreateDto
+3. **NUNCA** incluir campos `hidden` en ResponseDto
+4. **SIEMPRE** usar Java Records para DTOs
+5. **SIEMPRE** filtrar campos según flags de visibilidad
 
 ---
 
@@ -677,13 +753,18 @@ Al generar o modificar código, verificar:
 - [ ] Métodos de negocio con **validaciones explícitas**
 - [ ] Entidades JPA con **Lombok y herencia correcta**
 - [ ] Mappers **excluyen campos de auditoría**
+- [ ] Mappers **excluyen campos readOnly en creación**
+- [ ] Mappers **excluyen campos hidden en respuestas**
 - [ ] 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`
+- [ ] Validaciones JSR-303 **solo en Command y CreateDto, nunca en dominio**
 
 ---
 
-**Última actualización:** 2026-02-11  
+**Última actualización:** 2026-02-21  
 **Versión de eva4j:** 1.x  
 **Estado:** Documento de referencia para agentes IA

package/DOMAIN_YAML_GUIDE.md

@@ -10,6 +10,7 @@
 - [Entidades](#entidades)
 - [Value Objects](#value-objects)
 - [Enums](#enums)
+- [Validaciones JSR-303](#validaciones-jsr-303)
 - [Relaciones](#relaciones)
 - [Tipos de Datos](#tipos-de-datos)
 - [Ejemplos Completos](#ejemplos-completos)
@@ -396,6 +397,398 @@ fields:
 
 ---
 
+### Control de Visibilidad de Campos
+
+Eva4j permite controlar qué campos participan en constructores, DTOs de creación y DTOs de respuesta mediante dos flags opcionales: **`readOnly`** y **`hidden`**.
+
+#### 📋 Matriz de Comportamiento
+
+| Campo | Constructor Negocio | Constructor Completo | CreateDto | ResponseDto |
+|-------|---------------------|----------------------|-----------|-------------|
+| **Normal** | ✅ Incluido | ✅ Incluido | ✅ Incluido | ✅ Incluido |
+| **`readOnly: true`** | ❌ Excluido | ✅ Incluido | ❌ Excluido | ✅ Incluido |
+| **`hidden: true`** | ✅ Incluido | ✅ Incluido | ✅ Incluido | ❌ Excluido |
+| **Ambos flags** | ❌ Excluido | ✅ Incluido | ❌ Excluido | ❌ Excluido |
+
+#### 🔒 `readOnly: true` - Campos Calculados/Derivados
+
+Marca campos que **se calculan internamente** y no deben pasarse como parámetros en constructores o DTOs de creación.
+
+**Casos de uso típicos:**
+- Totales calculados (suma de items)
+- Contadores automáticos
+- Campos derivados de otros datos
+- Timestamps calculados
+
+**Sintaxis:**
+```yaml
+fields:
+  - name: totalAmount
+    type: BigDecimal
+    readOnly: true          # ✅ No en constructor ni CreateDto
+```
+
+**Ejemplo completo:**
+```yaml
+entities:
+  - name: order
+    isRoot: true
+    tableName: orders
+    audit:
+      enabled: true
+    fields:
+      - name: id
+        type: String
+      - name: orderNumber
+        type: String
+      - name: customerId
+        type: String
+      # Campo readOnly - calculado de los items
+      - name: totalAmount
+        type: BigDecimal
+        readOnly: true
+      # Campo readOnly - contador de items
+      - name: itemCount
+        type: Integer
+        readOnly: true
+```
+
+**Código generado:**
+```java
+// Constructor de negocio - SIN fields readOnly
+public Order(String orderNumber, String customerId) {
+    this.orderNumber = orderNumber;
+    this.customerId = customerId;
+    // totalAmount e itemCount NO están aquí
+}
+
+// Constructor completo - CON fields readOnly (reconstrucción desde DB)
+public Order(String id, String orderNumber, String customerId,
+             BigDecimal totalAmount, Integer itemCount, 
+             LocalDateTime createdAt, LocalDateTime updatedAt) {
+    // Todos los campos incluidos
+}
+
+// CreateDto - SIN fields readOnly
+public record CreateOrderDto(
+    String orderNumber,
+    String customerId
+    // totalAmount e itemCount NO están aquí
+) {}
+
+// ResponseDto - CON fields readOnly (mostrar valores calculados)
+public record OrderResponseDto(
+    String id,
+    String orderNumber,
+    String customerId,
+    BigDecimal totalAmount,    // ✅ Incluido
+    Integer itemCount,         // ✅ Incluido
+    LocalDateTime createdAt,
+    LocalDateTime updatedAt
+) {}
+```
+
+#### 🙈 `hidden: true` - Campos Sensibles/Internos
+
+Marca campos que **NO deben exponerse** en respuestas de API pero sí pueden recibirse en creación.
+
+**Casos de uso típicos:**
+- Passwords/hashes de seguridad
+- Tokens internos
+- Secrets y claves de API
+- Información sensible (SSN, datos privados)
+- Flags de control interno
+
+**Sintaxis:**
+```yaml
+fields:
+  - name: passwordHash
+    type: String
+    hidden: true           # ✅ No en ResponseDto
+```
+
+**Ejemplo completo:**
+```yaml
+entities:
+  - name: user
+    isRoot: true
+    tableName: users
+    audit:
+      enabled: true
+      trackUser: true
+    fields:
+      - name: id
+        type: String
+      - name: username
+        type: String
+      - name: email
+        type: String
+      # Campo hidden - NO en ResponseDto
+      - name: passwordHash
+        type: String
+        hidden: true
+      # Campo hidden - token interno
+      - name: resetPasswordToken
+        type: String
+        hidden: true
+```
+
+**Código generado:**
+```java
+// Constructor de negocio - CON fields hidden
+public User(String username, String email, 
+            String passwordHash, String resetPasswordToken) {
+    this.username = username;
+    this.email = email;
+    this.passwordHash = passwordHash;
+    this.resetPasswordToken = resetPasswordToken;
+}
+
+// CreateDto - CON fields hidden (para recibirlos en creación)
+public record CreateUserDto(
+    String username,
+    String email,
+    String passwordHash,         // ✅ Se puede recibir
+    String resetPasswordToken    // ✅ Se puede recibir
+) {}
+
+// ResponseDto - SIN fields hidden (proteger datos sensibles)
+public record UserResponseDto(
+    String id,
+    String username,
+    String email,
+    LocalDateTime createdAt,
+    LocalDateTime updatedAt
+    // passwordHash y resetPasswordToken NO están aquí
+) {}
+```
+
+#### 🔐 Combinando Ambos Flags
+
+Puedes combinar `readOnly` y `hidden` para campos que son **calculados internamente Y sensibles**.
+
+**Ejemplo:**
+```yaml
+fields:
+  - name: isLocked
+    type: Boolean
+    readOnly: true     # Calculado internamente
+    hidden: true       # NO exponer en API
+```
+
+**Resultado:**
+- ❌ NO en constructor de negocio (es readOnly)
+- ❌ NO en CreateDto (es readOnly)
+- ❌ NO en ResponseDto (es hidden)
+- ✅ SÍ en constructor completo (para reconstrucción desde DB)
+
+#### 📘 Ejemplo Completo: Sistema de Órdenes
+
+```yaml
+aggregates:
+  - name: Order
+    entities:
+      - name: order
+        isRoot: true
+        tableName: orders
+        audit:
+          enabled: true
+          trackUser: true
+        fields:
+          - name: id
+            type: String
+          
+          # Campos normales
+          - name: orderNumber
+            type: String
+          - name: customerId
+            type: String
+          - name: status
+            type: String
+          
+          # Campos readOnly (calculados)
+          - name: totalAmount
+            type: BigDecimal
+            readOnly: true               # Suma de items
+          - name: itemCount
+            type: Integer
+            readOnly: true               # Cuenta de items
+          
+          # Campo hidden (interno)
+          - name: processingToken
+            type: String
+            hidden: true                 # Token de procesamiento interno
+          
+          # Campo readOnly + hidden (calculado e interno)
+          - name: riskScore
+            type: Integer
+            readOnly: true
+            hidden: true                 # Puntaje de riesgo interno
+```
+
+**Constructor de negocio generado:**
+```java
+public Order(String orderNumber, String customerId, 
+             String status, String processingToken) {
+    // totalAmount, itemCount, riskScore NO están (readOnly)
+    // processingToken SÍ está (solo hidden, no readOnly)
+}
+```
+
+**CreateOrderDto generado:**
+```java
+public record CreateOrderDto(
+    String orderNumber,
+    String customerId,
+    String status,
+    String processingToken    // ✅ hidden pero SÍ en create
+    // totalAmount, itemCount, riskScore NO están (readOnly)
+) {}
+```
+
+**OrderResponseDto generado:**
+```java
+public record OrderResponseDto(
+    String id,
+    String orderNumber,
+    String customerId,
+    String status,
+    BigDecimal totalAmount,   // ✅ readOnly pero SÍ en response
+    Integer itemCount,        // ✅ readOnly pero SÍ en response
+    LocalDateTime createdAt,
+    LocalDateTime updatedAt
+    // processingToken NO está (hidden)
+    // riskScore NO está (hidden)
+) {}
+```
+
+#### ⚡ Comportamiento por Defecto
+
+Si no especificas `readOnly` ni `hidden`:
+- ✅ El comportamiento actual se mantiene sin cambios
+- ✅ Campos normales aparecen en todos lados
+- ✅ Solo los campos de auditoría (`createdBy`, `updatedBy`) se excluyen automáticamente de ResponseDto
+
+```yaml
+# Sin flags - comportamiento estándar
+fields:
+  - name: productName
+    type: String          # ✅ En constructor, CreateDto Y ResponseDto
+```
+
+#### 📚 Ver También
+
+- **Ejemplo completo:** [examples/domain-field-visibility.yaml](../examples/domain-field-visibility.yaml)
+- **Campos de auditoría:** Los campos `createdAt`, `updatedAt`, `createdBy`, `updatedBy` siguen su propio comportamiento especial definido en la sección de Auditoría
+
+---
+
+### Validaciones JSR-303
+
+Eva4j soporta anotaciones Bean Validation (JSR-303/Jakarta Validation) en campos del `domain.yaml`. Las validaciones se generan **únicamente en la capa de aplicación**: en el `Create<Aggregate>Command` y en los `Create<Entity>Dto` de entidades secundarias. **No se aplican a entidades de dominio** ni a campos con `readOnly: true`.
+
+El import `jakarta.validation.constraints.*` se agrega automáticamente cuando se detecta al menos una validación en los campos del comando.
+
+#### Sintaxis
+
+```yaml
+fields:
+  - name: email
+    type: String
+    validations:
+      - type: NotBlank
+        message: "Email es requerido"
+      - type: Email
+        message: "Email inválido"
+
+  - name: age
+    type: Integer
+    validations:
+      - type: Min
+        value: 18
+        message: "Edad mínima 18 años"
+      - type: Max
+        value: 120
+
+  - name: username
+    type: String
+    validations:
+      - type: Size
+        min: 3
+        max: 50
+        message: "Username entre 3 y 50 caracteres"
+
+  - name: code
+    type: String
+    validations:
+      - type: Pattern
+        regexp: "^[A-Z]{3}-[0-9]{4}$"
+        message: "Formato inválido"
+
+  - name: price
+    type: BigDecimal
+    validations:
+      - type: Digits
+        integer: 10
+        fraction: 2
+```
+
+#### Propiedades por Tipo
+
+| Propiedad | Tipos que la usan | Descripción |
+|-----------|-------------------|-------------|
+| `type` | Todos | Nombre de la anotación (`NotNull`, `NotBlank`, `Email`, `Min`, `Max`, `Size`, `Pattern`, `Digits`, `Positive`, `Negative`, `Past`, `Future`, etc.) |
+| `message` | Todos (opcional) | Mensaje de error personalizado |
+| `value` | `Min`, `Max` | Valor límite numérico |
+| `min` | `Size` | Tamaño mínimo |
+| `max` | `Size` | Tamaño máximo |
+| `regexp` | `Pattern` | Expresión regular |
+| `integer` | `Digits` | Máximo de dígitos enteros |
+| `fraction` | `Digits` | Máximo de dígitos decimales |
+| `inclusive` | `DecimalMin`, `DecimalMax` | Si el límite es inclusivo |
+
+#### Anotaciones sin parámetros (solo `type` requerido)
+
+`NotNull`, `NotBlank`, `NotEmpty`, `Email`, `Positive`, `PositiveOrZero`, `Negative`, `NegativeOrZero`, `Past`, `PastOrPresent`, `Future`, `FutureOrPresent`, `AssertTrue`, `AssertFalse`
+
+#### Código generado
+
+Para un campo con validaciones:
+
+```yaml
+- name: email
+  type: String
+  validations:
+    - type: Email
+      message: "Email inválido"
+    - type: NotBlank
+      message: "Email es requerido"
+```
+
+Se genera en `CreateUserCommand.java`:
+
+```java
+import jakarta.validation.constraints.*;
+
+public record CreateUserCommand(
+    @Email(message = "Email inválido")
+    @NotBlank(message = "Email es requerido")
+    String email,
+    ...
+) implements Command {
+}
+```
+
+#### Reglas de aplicación
+
+- ✅ **Sí** se aplican en `Create<Aggregate>Command`
+- ✅ **Sí** se aplican en `Create<Entity>Dto` (entidades secundarias)
+- ❌ **No** se aplican a entidades de dominio (`Order.java`, etc.)
+- ❌ **No** se aplican a campos con `readOnly: true` (ya están excluidos del command)
+- ❌ **No** se aplican a campos con `hidden: true` si también son `readOnly: true`
+
+---
+
 ### Auditoría Automática
 
 eva4j soporta dos niveles de auditoría automática de entidades: