eva4j 1.0.11 → 1.0.13

package/docs/commands/GENERATE_USECASE.md

@@ -1,282 +1,216 @@
-# Command `generate usecase` (alias: `g usecase`)
-
-## 📋 Description
-
-Generates CQRS use cases (Commands or Queries) with their respective handlers, following the Command Query Responsibility Segregation pattern.
-
-## 🎯 Purpose
-
-Create individual use cases for specific business operations, maintaining clear separation between write operations (Commands) and read operations (Queries).
-
-## 📝 Syntax
-
-```bash
-eva4j generate usecase <UseCaseName> --type <command|query>
-eva4j g usecase <UseCaseName> --type <command|query>    # Short alias
-```
-
-### Parameters
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `UseCaseName` | Yes | Name of the use case (PascalCase, e.g., UpdateCustomer, GetOrderById) |
-| `--type` | Yes | Type of use case: `command` (write) or `query` (read) |
-
-## 💡 Examples
-
-### Example 1: Update Command
-
-```bash
-eva4j g usecase UpdateCustomer --type command
-```
-
-**Generates:**
-- `application/commands/UpdateCustomerCommand.java` - Command with request data
-- `application/commands/UpdateCustomerCommandHandler.java` - Handler with business logic
-
-### Example 2: Delete Command
-
-```bash
-eva4j g usecase DeleteOrder --type command
-```
-
-**Generates:**
-- `application/commands/DeleteOrderCommand.java`
-- `application/commands/DeleteOrderCommandHandler.java`
-
-### Example 3: Custom Query
-
-```bash
-eva4j g usecase GetCustomerByEmail --type query
-```
-
-**Generates:**
-- `application/queries/GetCustomerByEmailQuery.java`
-- `application/queries/GetCustomerByEmailQueryHandler.java`
-
-### Example 4: Search Query
-
-```bash
-eva4j g usecase SearchProducts --type query
-```
-
-**Generates:**
-- `application/queries/SearchProductsQuery.java`
-- `application/queries/SearchProductsQueryHandler.java`
-
-## 📦 Generated Code Structure
-
-### Command Example
-
-**UpdateCustomerCommand.java:**
-```java
-package com.example.project.customer.application.commands;
-
-import lombok.AllArgsConstructor;
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-@Data
-@NoArgsConstructor
-@AllArgsConstructor
-public class UpdateCustomerCommand {
-    private Long id;
-    // Add your fields here
-}
-```
-
-**UpdateCustomerCommandHandler.java:**
-```java
-package com.example.project.customer.application.commands;
-
-import com.example.project.customer.domain.models.Customer;
-import com.example.project.customer.domain.repositories.CustomerRepository;
-import lombok.RequiredArgsConstructor;
-import org.springframework.stereotype.Service;
-import org.springframework.transaction.annotation.Transactional;
-
-@Service
-@RequiredArgsConstructor
-public class UpdateCustomerCommandHandler {
-    
-    private final CustomerRepository repository;
-    
-    @Transactional
-    public void handle(UpdateCustomerCommand command) {
-        // TODO: Implement update logic
-        Customer customer = repository.findById(command.getId())
-            .orElseThrow(() -> new RuntimeException("Customer not found"));
-        
-        // Update customer fields
-        
-        repository.save(customer);
-    }
-}
-```
-
-### Query Example
-
-**GetCustomerByEmailQuery.java:**
-```java
-package com.example.project.customer.application.queries;
-
-import lombok.AllArgsConstructor;
-import lombok.Data;
-import lombok.NoArgsConstructor;
-
-@Data
-@NoArgsConstructor
-@AllArgsConstructor
-public class GetCustomerByEmailQuery {
-    private String email;
-}
-```
-
-**GetCustomerByEmailQueryHandler.java:**
-```java
-package com.example.project.customer.application.queries;
-
-import com.example.project.customer.domain.models.Customer;
-import com.example.project.customer.domain.repositories.CustomerRepository;
-import lombok.RequiredArgsConstructor;
-import org.springframework.stereotype.Service;
-import org.springframework.transaction.annotation.Transactional;
-
-@Service
-@RequiredArgsConstructor
-public class GetCustomerByEmailQueryHandler {
-    
-    private final CustomerRepository repository;
-    
-    @Transactional(readOnly = true)
-    public Customer handle(GetCustomerByEmailQuery query) {
-        // TODO: Implement query logic
-        return repository.findByEmail(query.getEmail())
-            .orElseThrow(() -> new RuntimeException("Customer not found"));
-    }
-}
-```
-
-## ✨ Features
-
-### Commands (Write Operations)
-- ✅ **@Transactional** - Ensures data consistency
-- ✅ **Repository injection** - Domain repository ready
-- ✅ **TODO comments** - Guides implementation
-- ✅ **Lombok annotations** - Reduces boilerplate
-
-### Queries (Read Operations)
-- ✅ **@Transactional(readOnly = true)** - Optimized for reads
-- ✅ **Repository injection** - Domain repository ready
-- ✅ **Return type flexibility** - Can return entities or DTOs
-- ✅ **Clean structure** - Follows CQRS pattern
-
-## 🎯 Common Use Cases
-
-### Customer Module
-```bash
-eva4j g usecase UpdateCustomer --type command
-eva4j g usecase DeactivateCustomer --type command
-eva4j g usecase GetCustomerByEmail --type query
-eva4j g usecase SearchCustomers --type query
-eva4j g usecase CountActiveCustomers --type query
-```
-
-### Order Module
-```bash
-eva4j g usecase UpdateOrderStatus --type command
-eva4j g usecase CancelOrder --type command
-eva4j g usecase AddOrderItem --type command
-eva4j g usecase GetOrdersByCustomer --type query
-eva4j g usecase GetOrdersByDateRange --type query
-```
-
-### Product Module
-```bash
-eva4j g usecase UpdateProductPrice --type command
-eva4j g usecase UpdateStock --type command
-eva4j g usecase DeactivateProduct --type command
-eva4j g usecase SearchProductsByCategory --type query
-eva4j g usecase GetLowStockProducts --type query
-```
-
-## 🔄 CQRS Pattern Guidelines
-
-### Commands (Writes)
-- **Purpose:** Change system state
-- **Transaction:** Required (`@Transactional`)
-- **Return:** Usually `void` or entity ID
-- **Examples:** Create, Update, Delete, Activate, Deactivate
-
-### Queries (Reads)
-- **Purpose:** Retrieve data without side effects
-- **Transaction:** Read-only (`@Transactional(readOnly = true)`)
-- **Return:** Entity, DTO, or List
-- **Examples:** Get, List, Search, Count, Find
-
-## 🚀 Next Steps
-
-After generating a use case:
-
-1. **Implement the logic:**
-   - Edit the handler class
-   - Add business validations
-   - Implement the actual operation
-
-2. **Add to controller (if needed):**
-   ```java
-   @PostMapping("/update")
-   public ResponseEntity<Void> update(@RequestBody UpdateCustomerCommand command) {
-       handler.handle(command);
-       return ResponseEntity.ok().build();
-   }
-   ```
-
-3. **Add validations to command:**
-   ```java
-   @NotNull
-   private Long id;
-   
-   @NotBlank
-   @Size(max = 100)
-   private String name;
-   ```
-
-4. **Create DTOs if needed:**
-   - Create response DTOs for queries
-   - Create mappers between entities and DTOs
-
-## ⚠️ Prerequisites
-
-- Be in a project created with `eva4j create`
-- Module must exist (created with `eva4j add module`)
-- Working directory should be the project root
-
-## 🔍 Validations
-
-The command validates:
-- ✅ Valid eva4j project
-- ✅ Use case name is in PascalCase
-- ✅ Type is either `command` or `query`
-- ✅ Module exists in the project
-
-## 📚 See Also
-
-- [generate-entities](./GENERATE_ENTITIES.md) - Generate complete CRUD
-- [generate-resource](./GENERATE_RESOURCE.md) - Generate REST controller
-- [add-module](./ADD_MODULE.md) - Create modules
-
-## 🐛 Troubleshooting
-
-**Error: "Invalid use case name"**
-- Solution: Use PascalCase naming (e.g., `UpdateCustomer`, not `updateCustomer` or `update-customer`)
-
-**Error: "Type must be command or query"**
-- Solution: Always specify `--type command` or `--type query`
-
-**Files not created in correct location**
-- Solution: Run command from project root directory
-- Check that you're in a valid eva4j project
-
-**Repository not found after generation**
-- Solution: Generate entities first with `eva4j g entities`, or create repository interface manually
+# Command `generate usecase` (alias: `g usecase`)
+
+## Description
+
+Generates CQRS use cases (Commands or Queries) with their handlers, following the Command Query Responsibility Segregation pattern.
+
+## Purpose
+
+Create individual use cases for specific business operations, maintaining clear separation between write operations (Commands) and read operations (Queries).
+
+## Syntax
+
+```bash
+eva generate usecase <module> [name]
+eva g usecase <module> [name]    # Short alias
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `module` | Yes | Module where the use case will be created (e.g., `user`, `order`) |
+| `name` | No | Use case name in kebab-case or PascalCase — prompted if omitted |
+
+> **Interactive prompts:**
+> 1. **Use case name** — if not provided as argument (e.g., `create-user`, `find-user-by-id`)
+> 2. **Type** — `Command` (write) or `Query` (read)
+
+## Examples
+
+### Example 1: Create command
+
+```bash
+eva g usecase user create-user
+# Prompted for type → Command
+```
+
+Generates:
+- `application/commands/CreateUserCommand.java`
+- `application/usecases/CreateUserCommandHandler.java`
+
+### Example 2: Find query
+
+```bash
+eva g usecase user find-user-by-id
+# Prompted for type → Query
+```
+
+Generates:
+- `application/queries/FindUserByIdQuery.java`
+- `application/usecases/FindUserByIdQueryHandler.java`
+- `application/dtos/FindUserByIdResponseDto.java`
+
+### Example 3: Module-specific commands
+
+```bash
+eva g usecase order cancel-order         # Command
+eva g usecase product update-stock       # Command
+eva g usecase order find-orders-by-customer  # Query
+```
+
+## Generated Code Structure
+
+### Command
+
+**CreateUserCommand.java** (`application/commands/`):
+```java
+package com.example.project.user.application.commands;
+
+public record CreateUserCommand(
+    // TODO: add command fields
+) {
+}
+```
+
+**CreateUserCommandHandler.java** (`application/usecases/`):
+```java
+package com.example.project.user.application.usecases;
+
+import com.example.project.user.application.commands.CreateUserCommand;
+import com.example.project.shared.domain.annotations.ApplicationComponent;
+
+@ApplicationComponent
+public class CreateUserCommandHandler {
+
+    public CreateUserCommandHandler() {
+    }
+
+    public void handle(CreateUserCommand command) {
+        //todo: implement use case
+    }
+}
+```
+
+### Query
+
+**FindUserByIdQuery.java** (`application/queries/`):
+```java
+package com.example.project.user.application.queries;
+
+public record FindUserByIdQuery(
+    // TODO: add query fields
+) {
+}
+```
+
+**FindUserByIdQueryHandler.java** (`application/usecases/`):
+```java
+package com.example.project.user.application.usecases;
+
+import com.example.project.user.application.queries.FindUserByIdQuery;
+import com.example.project.user.application.dtos.FindUserByIdResponseDto;
+import com.example.project.shared.domain.annotations.ApplicationComponent;
+
+@ApplicationComponent
+public class FindUserByIdQueryHandler {
+
+    public FindUserByIdQueryHandler() {
+    }
+
+    public FindUserByIdResponseDto handle(FindUserByIdQuery query) {
+        //todo: implement use case
+        return null;
+    }
+}
+```
+
+**FindUserByIdResponseDto.java** (`application/dtos/`):
+```java
+package com.example.project.user.application.dtos;
+
+public record FindUserByIdResponseDto(
+    // TODO: add response fields
+) {
+}
+```
+
+## Key Design Decisions
+
+- **Pure Java records** — Commands and Queries are immutable records (no Lombok)
+- **`@ApplicationComponent`** — Custom annotation from `shared` that marks handlers for Spring DI; not `@Service`
+- **Handlers in `application/usecases/`** — All handlers live here regardless of type (Command or Query)
+- **Commands in `application/commands/`** — Command record classes
+- **Queries in `application/queries/`** — Query record classes
+- **DTOs in `application/dtos/`** — Response DTOs (queries only)
+
+## CQRS Pattern Guidelines
+
+### Commands (Writes)
+- **Purpose:** Change system state
+- **Return:** `void` or minimal confirmation
+- **Examples:** Create, Update, Delete, Activate, Deactivate
+
+### Queries (Reads)
+- **Purpose:** Retrieve data without side effects
+- **Return:** ResponseDto or `List<ResponseDto>`
+- **Examples:** FindById, FindAll, Search
+
+## Common Use Cases
+
+### User Module
+```bash
+eva g usecase user create-user         # Command
+eva g usecase user update-user         # Command
+eva g usecase user deactivate-user     # Command
+eva g usecase user find-user-by-id     # Query
+eva g usecase user find-user-by-email  # Query
+```
+
+### Order Module
+```bash
+eva g usecase order place-order              # Command
+eva g usecase order cancel-order             # Command
+eva g usecase order find-order-by-id         # Query
+eva g usecase order find-orders-by-customer  # Query
+```
+
+### Product Module
+```bash
+eva g usecase product update-price     # Command
+eva g usecase product update-stock     # Command
+eva g usecase product find-by-category # Query
+eva g usecase product get-low-stock    # Query
+```
+
+## Next Steps After Generation
+
+1. **Add fields to the record:**
+   ```java
+   public record CreateUserCommand(
+       String name,
+       String email
+   ) { }
+   ```
+
+2. **Implement the handler:**
+   ```java
+   public void handle(CreateUserCommand command) {
+       User user = new User(command.name(), command.email());
+       userRepository.save(user);
+   }
+   ```
+
+3. **Wire into a Controller or another Handler** — inject the handler via constructor and call `handler.handle(command)`.
+
+## Prerequisites
+
+- Be in a project created with `eva create`
+- Module must exist (`eva add module <module>`)
+- Run the command from the project root
+
+## See Also
+
+- [generate-entities](./GENERATE_ENTITIES.md) — Generate complete domain model from YAML
+- [generate-resource](./GENERATE_RESOURCE.md) — REST controller with 5 CRUD endpoints
+- [add-module](./ADD_MODULE.md) — Create a new module

package/docs/commands/INDEX.md

@@ -79,6 +79,28 @@ Commands for integrating with external services and messaging systems.
   - Kafka dependencies installation
   - Base configuration
 
+### ⏳ Temporal / Workflow Commands
+
+Commands for integrating with [Temporal](https://temporal.io/) for durable workflow orchestration.
+
+- **add temporal-client** - Add Temporal SDK and worker infrastructure
+  - *Documentation coming soon*
+  - Temporal SDK dependency
+  - Worker configuration (FLOW_QUEUE, LIGHT_TASK_QUEUE, HEAVY_TASK_QUEUE)
+  - Docker Compose service for local development
+
+- **[generate temporal-flow](./GENERATE_TEMPORAL_FLOW.md)** (`g temporal-flow`) - Create a Temporal workflow
+  - `@WorkflowInterface` with signal and query methods
+  - Saga implementation with compensation
+  - Spring service facade (async & sync)
+  - Auto-registers in `TemporalConfig.java`
+
+- **[generate temporal-activity](./GENERATE_TEMPORAL_ACTIVITY.md)** (`g temporal-activity`) - Create a Temporal activity
+  - `@ActivityInterface` with unique `@ActivityMethod` name
+  - `LightActivity` or `HeavyActivity` marker for queue routing
+  - Auto-registered via Spring DI (no manual config patching)
+  - Registers stub in the chosen `WorkFlowImpl`
+
 ### 🚀 Deployment & Scaling Commands
 
 Commands for transitioning from monolith to microservices.
@@ -117,6 +139,11 @@ Commands for transitioning from monolith to microservices.
 2. [generate kafka-event](./GENERATE_KAFKA_EVENT.md) - Event publishing
 3. [generate kafka-listener](./GENERATE_KAFKA_LISTENER.md) - Event consumption
 
+### Orchestrating Workflows
+1. [add temporal-client](./INDEX.md) - Install Temporal infrastructure
+2. [generate temporal-flow](./GENERATE_TEMPORAL_FLOW.md) - Define workflow
+3. [generate temporal-activity](./GENERATE_TEMPORAL_ACTIVITY.md) - Implement activities
+
 ### Scaling to Microservices
 1. [detach](./DETACH.md) - Extract module
 2. [generate http-exchange](./GENERATE_HTTP_EXCHANGE.md) - Service communication
@@ -191,13 +218,15 @@ Commands for transitioning from monolith to microservices.
 All generate commands support short aliases for faster development:
 
 ```bash
-eva4j g entities <name>        # generate entities
-eva4j g usecase <name>         # generate usecase  
-eva4j g resource <name>        # generate resource
-eva4j g record <name>          # generate record
-eva4j g http <name>            # generate http-exchange
-eva4j g kafka-event <name>     # generate kafka-event
-eva4j g kafka-listener <name>  # generate kafka-listener
+eva g entities <name>           # generate entities
+eva g usecase <name>            # generate usecase  
+eva g resource <name>           # generate resource
+eva g record <name>             # generate record
+eva g http <name>               # generate http-exchange
+eva g kafka-event <name>        # generate kafka-event
+eva g kafka-listener <name>     # generate kafka-listener
+eva g temporal-flow <module>    # generate temporal-flow
+eva g temporal-activity <module># generate temporal-activity
 ```
 
 ---

package/examples/doctor-evaluation.yaml

@@ -5,7 +5,7 @@
 aggregates:
   - name: Evaluation
     entities:
-      - name: evaluation
+      - name: Evaluation
         isRoot: true
         tableName: evaluations
         auditable: true
@@ -28,7 +28,7 @@ aggregates:
             cascade: [ PERSIST, MERGE, REMOVE ]
             fetch: LAZY
 
-      - name: evaluationDoctor
+      - name: EvaluationDoctor
         auditable: true
         tableName: evaluation_doctors
         fields:
@@ -50,7 +50,7 @@ aggregates:
             type: List<Degrees>
 
 
-      - name: evaluationBranch
+      - name: EvaluationBranch
         tableName: evaluation_branchs
         auditable: true
         fields:

package/examples/domain-audit-complete.yaml

@@ -5,7 +5,7 @@
 aggregates:
   - name: Order
     entities:
-      - name: order
+      - name: Order
         isRoot: true
         tableName: orders
         audit:
@@ -67,7 +67,7 @@ aggregates:
 
   - name: Customer
     entities:
-      - name: customer
+      - name: Customer
         isRoot: true
         tableName: customers
         audit:

package/examples/domain-collections.yaml

@@ -5,7 +5,7 @@
 aggregates:
   - name: BlogPost
     entities:
-      - name: blogPost
+      - name: BlogPost
         isRoot: true
         tableName: blog_posts
         auditable: true
@@ -41,7 +41,7 @@ aggregates:
             cascade: [PERSIST, MERGE, REMOVE]
             fetch: LAZY
       
-      - name: comment
+      - name: Comment
         tableName: comments
         auditable: true
         fields:

package/examples/domain-ecommerce.yaml

@@ -5,7 +5,7 @@
 aggregates:
   - name: ShoppingCart
     entities:
-      - name: shoppingCart
+      - name: ShoppingCart
         isRoot: true
         tableName: shopping_carts
         auditable: true
@@ -39,7 +39,7 @@ aggregates:
             cascade: [PERSIST, MERGE, REMOVE]
             fetch: LAZY
       
-      - name: cartItem
+      - name: CartItem
         tableName: cart_items
         auditable: true
         fields: