eva4j 1.0.11 → 1.0.12

package/AGENTS.md

@@ -387,19 +387,28 @@ void assignUser(User user) {  // package-private
 
 ```bash
 # Crear proyecto
-eva4j create my-app
+eva create my-app
 
 # Agregar módulo
-eva4j add module users
+eva add module users
 
 # Generar entidades desde YAML
-eva4j g entities users
+eva g entities users
 
 # Generar use case
-eva4j g usecase users ActivateUser
+eva g usecase users ActivateUser
 
 # Generar resource (REST)
-eva4j g resource users
+eva g resource users
+
+# Agregar cliente Temporal
+eva add temporal-client
+
+# Generar workflow Temporal
+eva g temporal-flow users
+
+# Generar actividad Temporal
+eva g temporal-activity users
 ```
 
 ### Estructura de domain.yaml
@@ -558,6 +567,7 @@ Los campos en domain.yaml soportan las siguientes propiedades:
 | **`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** |
+| **`reference`** | Object | `null` | **Declara referencia semántica a otro agregado (genera comentario Javadoc)** |
 
 #### Flags de Visibilidad: `readOnly` y `hidden`
 

package/DOMAIN_YAML_GUIDE.md

@@ -683,6 +683,57 @@ fields:
 
 ---
 
+### Referencias entre Agregados (`reference:`)
+
+La propiedad `reference:` declara explícitamente que un campo es un puntero intencional a la raíz de otro agregado. El campo sigue siendo un tipo primitivo (`String`, `Long`, etc.) — **no se genera ningún `@ManyToOne`**.
+
+#### Sintaxis
+
+```yaml
+fields:
+  - name: customerId
+    type: String
+    reference:
+      aggregate: Customer   # Nombre del agregado referenciado (PascalCase) — obligatorio
+      module: customers     # Módulo donde vive el agregado — opcional
+  - name: productId
+    type: String
+    reference:
+      aggregate: Product
+      module: catalog
+```
+
+#### Comportamiento
+
+- El tipo Java **no cambia** — sigue siendo `String`, `Long`, UUID, etc.
+- JPA genera `@Column` normal — **sin** `@ManyToOne` ni `@JoinColumn`.
+- En la entidad de dominio y en la entidad JPA se genera un **comentario Javadoc** que documenta la referencia.
+- `module:` es opcional: puede omitirse si el agregado referenciado está en el mismo módulo.
+- Si `reference:` está malformado (falta `aggregate`), eva4j lanza un error descriptivo.
+
+#### Código Generado
+
+```java
+// domain/models/entities/Order.java
+/** Cross-aggregate reference → Customer (module: customers) */
+private String customerId;
+```
+
+```java
+// infrastructure/database/entities/OrderJpa.java
+@Column(name = "customer_id")
+/** Cross-aggregate reference → Customer (module: customers) */
+private String customerId;
+```
+
+#### Por qué no usar `@ManyToOne` entre agregados
+
+En DDD cada agregado es una unidad transaccional independiente. Un `@ManyToOne` cruzando límites crea un único grafo JPA que viola los límites transaccionales y crea dependencias de carga invisibles. La referencia por ID es el patrón correcto: el handler que necesite los datos del otro agregado los obtiene explícitamente via su propio repositorio.
+
+- **Ejemplo completo:** [examples/domain-multi-aggregate.yaml](../examples/domain-multi-aggregate.yaml)
+
+---
+
 ### 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`.

package/FUTURE_FEATURES.md

@@ -12,7 +12,7 @@ Este documento describe las mejoras planificadas para futuras versiones de eva4j
 - [Soft Delete Completo](#3-soft-delete-completo)
 
 ### � Media Prioridad
-- [Paginación en Queries](#4-paginación-en-queries)
+- [Paginación en Queries](#4-paginación-en-queries) ✅
 - [Optimistic Locking](#5-optimistic-locking)
 - [Read Models Separados](#6-read-models-separados-proyecciones)
 - [Enums con Comportamiento y Transiciones](#7-enums-con-comportamiento-y-transiciones) ✅
@@ -27,6 +27,10 @@ Este documento describe las mejoras planificadas para futuras versiones de eva4j
 ### ✅ Implementado
 - [Auditoría de Tiempo y Usuario](#13-auditoría-implementada)
 - [Validaciones JSR-303](#14-validaciones-jsr-303-implementado)
+- [Enums con Comportamiento y Transiciones](#7-enums-con-comportamiento-y-transiciones)
+- [Generación Incremental / Diff](#10-generación-incremental--diff)
+- [Paginación en Queries](#4-paginación-en-queries)
+- [Aggregate Boundaries por ID](#2-aggregate-boundaries-por-id-implementado)
 
 ---
 
@@ -175,15 +179,15 @@ public class OrderEventListener {
 
 ---
 
-## 2. Aggregate Boundaries por ID
+## 2. Aggregate Boundaries por ID ✅
 
 ### Descripción
 
-En DDD, las referencias entre agregados distintos deben realizarse **por ID**, nunca con `@ManyToOne` cruzado. Hoy eva4j genera referencias JPA directas entre todos los agregados del mismo módulo, creando un único grafo de entidades JPA en vez de agregados independientes.
+Eva4j ya genera correctamente el patrón DDD de referencia por ID: los campos que apuntan a otro agregado se generan como tipos primitivos (`String`, `Long`, etc.) sin ningún `@ManyToOne` cruzado. Esta feature añade **declaración semántica explícita** mediante la propiedad `reference:` en el campo, que permite documentar la intención en el YAML y generar un comentario Javadoc en el código.
 
-Esto impide escalar los agregados de forma independiente y crea dependencias de carga que violan los límites transaccionales.
+Sin `reference:`, un campo `customerId: String` es indistinguible de cualquier otro `String`. Con `reference:`, el generador sabe que es un puntero intencional al agregado `Customer` del módulo `customers`.
 
-### Sintaxis Propuesta
+### Sintaxis
 
 ```yaml
 aggregates:
@@ -197,8 +201,8 @@ aggregates:
           - name: customerId
             type: String
             reference:
-              aggregate: Customer
-              module: customers
+              aggregate: Customer   # Nombre del agregado (PascalCase) — obligatorio
+              module: customers     # Módulo donde vive el agregado — opcional
           - name: productId
             type: String
             reference:
@@ -206,36 +210,45 @@ aggregates:
               module: catalog
 ```
 
+### Comportamiento
+
+- El tipo Java **no cambia** — sigue siendo `String`, `Long`, etc.
+- JPA genera `@Column` normal — **sin** `@ManyToOne` ni `@JoinColumn`.
+- Se genera un **comentario Javadoc** en la entidad de dominio y en la entidad JPA.
+- `module:` es opcional: se puede omitir si el agregado referenciado está en el mismo módulo.
+- Si `reference:` está malformado (falta `aggregate`), eva4j lanza un error descriptivo.
+
 ### Código Generado
 
 ```java
 // domain/models/entities/Order.java
-public class Order {
-    private String id;
-    private String customerId;  // Solo el ID, nunca Customer customer
-    private String productId;
-}
+/** Cross-aggregate reference → Customer (module: customers) */
+private String customerId;
+
+/** Cross-aggregate reference → Product (module: catalog) */
+private String productId;
 ```
 
 ```java
-public class GetOrderWithCustomerQueryHandler {
-    private final OrderRepository orderRepository;
-    private final CustomerServiceClient customerClient;
-
-    public OrderWithCustomerDto handle(GetOrderWithCustomerQuery query) {
-        Order order = orderRepository.findById(query.orderId()).orElseThrow();
-        CustomerSummary customer = customerClient.findById(order.getCustomerId());
-        return new OrderWithCustomerDto(order, customer);
-    }
-}
+// infrastructure/database/entities/OrderJpa.java
+@Column(name = "customer_id")
+/** Cross-aggregate reference → Customer (module: customers) */
+private String customerId;
+
+@Column(name = "product_id")
+/** Cross-aggregate reference → Product (module: catalog) */
+private String productId;
 ```
 
-### Advertencia generada cuando se detecta cross-aggregate
+### Archivos Modificados
 
-```
-⚠️  WARNING: Order.customer uses a direct JPA reference to Customer aggregate.
-   Consider using customerId (reference by ID) instead.
-```
+| Archivo | Cambio |
+|---|---|
+| `src/utils/yaml-to-entity.js` | ✅ Destructura y valida `reference:` en `parseProperty()` |
+| `templates/aggregate/AggregateRoot.java.ejs` | ✅ Genera comentario Javadoc en campos con `reference` |
+| `templates/aggregate/JpaAggregateRoot.java.ejs` | ✅ Genera comentario Javadoc en campos con `reference` |
+| `templates/aggregate/JpaEntity.java.ejs` | ✅ Genera comentario Javadoc en campos con `reference` |
+| `examples/domain-multi-aggregate.yaml` | ✅ Actualizado con `reference:` en `productId` y `warehouseId` |
 
 ---
 
@@ -320,74 +333,86 @@ public ResponseEntity<Void> restore(@PathVariable String id) {
 
 ---
 
-## 4. Paginación en Queries
+## 4. Paginación en Queries ✅
 
 ### Descripción
 
-Actualmente `ListQueryHandler` devuelve `List<T>` completo sin límite. En producción, cualquier colección que pueda crecer sin límite debe estar paginada. Esto también implica soporte para filtros dinámicos y ordenamiento.
+Implementado como **paginación siempre activa** en todos los módulos generados. `GET /` ya no devuelve `List<T>` sin límite — devuelve un `PagedResponse<T>` propio con `content`, `page`, `size`, `totalElements` y `totalPages`. Sin flags ni configuración adicional en `domain.yaml`.
 
-### Sintaxis Propuesta
+### Implementación Realizada
 
-```yaml
-aggregates:
-  - name: Order
-    queries:
-      - name: FindAllOrders
-        paginated: true
-        filters:
-          - field: status
-            type: OrderStatus
-          - field: customerId
-            type: String
-        sort:
-          defaultField: createdAt
-          defaultDirection: DESC
+#### PagedResponse — `shared/application/dtos/PagedResponse.java`
+
+Record genérico generado una vez por proyecto en la capa shared. Desacoplado de Spring Data `Page<T>` para no exponer internals de Spring en la API:
+
+```java
+public record PagedResponse<T>(
+    List<T> content,
+    int page,
+    int size,
+    long totalElements,
+    int totalPages
+) {
+    public static <T> PagedResponse<T> of(
+            List<T> content, int page, int size, long totalElements) {
+        int totalPages = size == 0 ? 1 : (int) Math.ceil((double) totalElements / size);
+        return new PagedResponse<>(content, page, size, totalElements, totalPages);
+    }
+}
 ```
 
-### Código Generado
+#### Query con parámetros de paginación
 
 ```java
 public record FindAllOrdersQuery(
-    OrderStatus status,
-    String customerId,
     int page,
     int size,
     String sortBy,
     String sortDirection
-) {}
+) implements Query<PagedResponse<OrderResponseDto>> {}
 ```
 
+#### Handler paginado
+
 ```java
-public Page<OrderResponseDto> handle(FindAllOrdersQuery query) {
-    Pageable pageable = PageRequest.of(
-        query.page(), query.size(),
-        Sort.by(Sort.Direction.fromString(query.sortDirection()), query.sortBy())
-    );
-    Page<Order> orders = orderRepository.findAll(
-        OrderSpecifications.build(query.status(), query.customerId()), pageable
-    );
-    return orders.map(mapper::toDto);
+public PagedResponse<OrderResponseDto> handle(FindAllOrdersQuery query) {
+    Sort sort = Sort.by(Sort.Direction.fromString(query.sortDirection()), query.sortBy());
+    Pageable pageable = PageRequest.of(query.page(), query.size(), sort);
+    Page<Order> page = repository.findAll(pageable);
+    List<OrderResponseDto> content = page.getContent().stream().map(mapper::toDto).toList();
+    return PagedResponse.of(content, page.getNumber(), page.getSize(), page.getTotalElements());
 }
 ```
 
-```java
-public class OrderSpecifications {
-    public static Specification<OrderJpa> build(OrderStatus status, String customerId) {
-        return Specification
-            .where(hasStatus(status))
-            .and(hasCustomerId(customerId));
-    }
-    private static Specification<OrderJpa> hasStatus(OrderStatus status) {
-        return (root, query, cb) ->
-            status == null ? null : cb.equal(root.get("status"), status);
-    }
-    private static Specification<OrderJpa> hasCustomerId(String customerId) {
-        return (root, query, cb) ->
-            customerId == null ? null : cb.equal(root.get("customerId"), customerId);
-    }
+#### Endpoint REST
+
+```bash
+# Defaults: page=0, size=20, sortBy=id, sortDirection=ASC
+GET /api/v1/orders?page=0&size=10&sortBy=createdAt&sortDirection=DESC
+
+# Respuesta
+{
+  "content": [...],
+  "page": 0,
+  "size": 10,
+  "totalElements": 87,
+  "totalPages": 9
 }
 ```
 
+#### Archivos modificados
+
+| Archivo | Cambio |
+|---|---|
+| `templates/shared/application/dtos/PagedResponse.java.ejs` | ✅ Nuevo template shared |
+| `src/generators/shared-generator.js` | ✅ Método `generatePagedResponse()` |
+| `src/commands/generate-entities.js` | ✅ Llama `generatePagedResponse` en cada `g entities` |
+| `templates/crud/ListQuery.java.ejs` | ✅ Parámetros de paginación |
+| `templates/crud/ListQueryHandler.java.ejs` | ✅ `PageRequest` + `PagedResponse` |
+| `templates/aggregate/AggregateRepository.java.ejs` | ✅ `Page<X> findAll(Pageable)` |
+| `templates/aggregate/AggregateRepositoryImpl.java.ejs` | ✅ Implementación `jpaRepository.findAll(pageable).map(...)` |
+| `templates/crud/Controller.java.ejs` | ✅ `@RequestParam` page/size/sortBy/sortDirection |
+
 ---
 
 ## 5. Optimistic Locking
@@ -709,50 +734,50 @@ domain.yaml:41:7  error  Relationship type "OneToFew" is not valid.
 
 ---
 
-## 10. Generación Incremental / Diff
+## 10. Generación Incremental / Diff ✅
 
 ### Descripción
 
-Actualmente `eva4j g entities` regenera **todos** los archivos, sobreescribiendo cualquier modificación manual. Este es el mayor bloqueador para adopción en proyectos reales donde el desarrollador personaliza la lógica generada.
+Implementado como **safe mode con checksums SHA-256**. `eva4j g entities` (y `g usecase`, `g resource`) detecta si un archivo generado fue modificado manualmente después de su generación y lo omite automáticamente en re-ejecuciones. El flag `--force` permite sobreescribir cuando se desea regenerar intencionalmente.
 
-### Estrategias Propuestas
+### Implementación Realizada
 
-#### Opción A: Archivos base + archivos de extensión
+#### ChecksumManager — `src/utils/checksum-manager.js`
 
-```
-order/application/mappers/
-├── OrderApplicationMapperBase.java    <- regenerado siempre
-└── OrderApplicationMapper.java        <- creado una vez, el dev lo personaliza
-```
+Almacena hashes SHA-256 de cada archivo escrito en un archivo `.eva4j-checksums.json` por módulo (junto al `domain.yaml`). Métodos clave:
+- `wasModified(destPath, generatedContent)` — compara hash en disco vs hash almacenado
+- `recordWrite(destPath, content)` — registra hash del archivo recién escrito
+- `save()` — persiste la base de datos de checksums
 
-```java
-// OrderApplicationMapperBase.java — regenerado en cada g entities
-public abstract class OrderApplicationMapperBase {
-    public Order fromCommand(CreateOrderCommand command) { /* generado */ }
-    public OrderResponseDto toDto(Order entity) { /* generado */ }
-}
-
-// OrderApplicationMapper.java — creado una sola vez
-@Component
-public class OrderApplicationMapper extends OrderApplicationMapperBase {
-    // Override opcional de métodos base
-    // Métodos adicionales del proyecto aquí
-}
-```
-
-#### Opción B: Flag --safe en el CLI
+#### Safe mode en `renderAndWrite()` — `src/utils/template-engine.js`
 
 ```bash
-# Regenera solo archivos que NO fueron modificados manualmente
-eva4j g entities order --safe
+# Comportamiento por defecto (safe mode)
+eva4j g entities orders
 
 # Output:
-# OK  Order.java                       -- regenerado (sin cambios previos)
-# OK  OrderJpa.java                    -- regenerado (sin cambios previos)
-# SKIP OrderApplicationMapper.java     -- omitido (modificado manualmente)
-# SKIP CreateOrderCommandHandler.java  -- omitido (modificado manualmente)
+# ✅ Order.java                        -- regenerado (sin cambios previos)
+# ✅ OrderJpa.java                     -- regenerado (sin cambios previos)
+# ⚠️  SKIP OrderApplicationMapper.java -- omitido (modificado manualmente — use --force to overwrite)
+# ⚠️  SKIP CreateOrderCommandHandler.java -- omitido (modificado manualmente)
+
+# Con --force: sobreescribe todo
+eva4j g entities orders --force
 ```
 
+#### Comandos con safe mode integrado
+
+| Comando | Estado |
+|---|---|
+| `eva4j g entities <module>` | ✅ Integrado |
+| `eva4j g usecase <module> <name>` | ✅ Integrado |
+| `eva4j g resource <module>` | ✅ Integrado |
+| `eva4j create` / `eva4j add module` | ⚠️ Out of scope (archivos de scaffolding inicial, no se re-ejecutan) |
+
+#### Nota sobre portabilidad
+
+`.eva4j-checksums.json` está en `.gitignore` por diseño — es estado local de la máquina de desarrollo. En un `git clone` fresco, la primera re-ejecución regenerará todos los archivos (comportamiento correcto en ese contexto).
+
 ---
 
 ## 11. Comando `eva4j doctor`
@@ -942,27 +967,109 @@ private Integer age;
 
 ---
 
+## 15. Transactional Outbox Pattern
+
+### Descripción
+
+El **Transactional Outbox Pattern** es la evolución natural de los Domain Events implementados (ítem 1). Resuelve el caso donde el proceso muere después del commit de BD pero antes de que `ApplicationEventPublisher` llegue a publicar al broker externo — en ese escenario, el evento se pierde silenciosamente.
+
+El patrón garantiza **at-least-once delivery**: los eventos son almacenados en la misma transacción que el agregado y un proceso separado los publica de forma resiliente.
+
+Los Domain Events ya implementados (`ApplicationEventPublisher` + `@TransactionalEventListener(AFTER_COMMIT)`) son suficientes para la mayoría de sistemas. Esta feature es necesaria para dominios críticos: pagos, auditoría regulatoria, inventario en tiempo real.
+
+**Nota:** El puerto `MessageBroker` ya generado no requiere cambios — solo se añade la capa de persistencia intermedia.
+
+### Flujo del Patrón
+
+```
+BD Transaction:
+  → INSERT INTO orders ...
+  → INSERT INTO outbox_events (type, payload, published=false)  ← misma TX
+  → COMMIT
+
+Proceso resiliente (polling o CDC con Debezium):
+  → SELECT * FROM outbox_events WHERE published = false
+  → Publica a Kafka / RabbitMQ / SNS
+  → UPDATE outbox_events SET published = true
+```
+
+### Sintaxis Propuesta en domain.yaml
+
+```yaml
+aggregates:
+  - name: Order
+    events:
+      - name: OrderPlaced
+        kafka: true
+        delivery: at-least-once        # ← activa Outbox Pattern para este evento
+        fields:
+          - name: customerId
+            type: String
+```
+
+### Código Generado (Outbox Table + Publisher)
+
+```java
+@Entity
+@Table(name = "outbox_events")
+public class OutboxEvent {
+    @Id
+    private String id;
+    private String aggregateType;
+    private String aggregateId;
+    private String eventType;
+    @Column(columnDefinition = "TEXT")
+    private String payload;       // JSON serializado del evento
+    private boolean published = false;
+    private LocalDateTime createdAt;
+    private LocalDateTime publishedAt;
+}
+```
+
+```java
+// OutboxEventPublisher — proceso de polling (cada 5s via @Scheduled)
+@Component
+public class OutboxEventPublisher {
+    @Scheduled(fixedDelay = 5000)
+    @Transactional
+    public void publishPendingEvents() {
+        List<OutboxEvent> pending = outboxRepository.findByPublishedFalse();
+        pending.forEach(event -> {
+            messageBroker.publishRaw(event.getEventType(), event.getPayload());
+            event.markPublished();
+        });
+    }
+}
+```
+
+### Prerrequisito
+
+Domain Events (ítem 1) implementados y funcionando — este ítem solo añade persistencia intermedia, no reemplaza la arquitectura existente.
+
+---
+
 ## Resumen de Prioridades
 
 | # | Característica | Prioridad | Complejidad | Estado |
 |---|---|---|---|---|
-| 1 | Domain Events | � Alta | � Alta | � Pendiente |
-| 2 | Aggregate Boundaries por ID | � Alta | � Media | � Pendiente |
-| 3 | Soft Delete Completo | � Alta | � Baja | � Parcial |
-| 4 | Paginación en Queries | � Media | � Media | � Pendiente |
-| 5 | Optimistic Locking | � Media | � Baja | � Pendiente |
-| 6 | Read Models / Proyecciones | � Media | � Alta | � Pendiente |
+| 1 | Domain Events | Alta | Alta | ✅ Implementado |
+| 2 | Aggregate Boundaries por ID | Alta | Media | ✅ Implementado |
+| 3 | Soft Delete Completo | Alta | Baja | Parcial |
+| 4 | Paginación en Queries | Impl. | -- | ✅ Implementado |
+| 5 | Optimistic Locking | Media | Baja | Pendiente |
+| 6 | Read Models / Proyecciones | Media | Alta | Pendiente |
 | 7 | Enums con Transiciones | Impl. | -- | ✅ Implementado |
-| 8 | Specifications Pattern | � Media | � Media | � Pendiente |
-| 9 | JSON Schema para domain.yaml | � Tooling | � Media | � Pendiente |
-| 10 | Generacion Incremental | � Tooling | � Alta | � Pendiente |
-| 11 | eva4j doctor | � Tooling | � Media | � Pendiente |
-| 12 | Tests Completos | � Tooling | � Media | � Pendiente |
+| 8 | Specifications Pattern | Media | Media | Pendiente |
+| 9 | JSON Schema para domain.yaml | Tooling | Media | Pendiente |
+| 10 | Generacion Incremental | Tooling | -- | ✅ Implementado |
+| 11 | eva4j doctor | Tooling | Media | Pendiente |
+| 12 | Tests Completos | Tooling | Media | Pendiente |
 | 13 | Auditoria completa | Impl. | -- | ✅ Implementado |
 | 14 | Validaciones JSR-303 | Impl. | -- | ✅ Implementado |
+| 15 | Transactional Outbox Pattern | Alta | Alta | Pendiente |
 
 ---
 
-**Ultima actualizacion:** 2026-02-22
+**Ultima actualizacion:** 2026-02-25
 **Version de eva4j:** 1.x
 **Estado:** Documento de planificacion y referencia