eva4j 1.0.11 → 1.0.13

package/docs/commands/GENERATE_TEMPORAL_ACTIVITY.md

@@ -0,0 +1,174 @@
+# Command `generate temporal-activity` (alias: `g temporal-activity`)
+
+## 📋 Description
+
+Generates a Temporal activity with its interface (port) and Spring implementation, then registers the activity stub inside a chosen `*WorkFlowImpl.java`.
+
+## 🎯 Purpose
+
+Create a single, focused unit of work that can be executed and retried independently by the Temporal server. Activities are the building blocks invoked by workflows — each activity handles one side-effect (database write, HTTP call, email, etc.) and can be categorised as **Light** (fast, < 30 s) or **Heavy** (long-running, up to 2 min) to route it to the appropriate worker queue.
+
+## 📝 Syntax
+
+```bash
+eva generate temporal-activity <module>
+eva g temporal-activity <module>    # Short alias
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `module` | Yes | Target module where the activity **interface** lives |
+
+> **Interactive prompts (4 steps):**
+> 1. **Activity name** — e.g., `send-confirmation-email` or `SendConfirmationEmail`
+> 2. **Category** — `LightActivity` (< 30 s, `LIGHT_TASK_QUEUE`) or `HeavyActivity` (up to 2 min, `HEAVY_TASK_QUEUE`)
+> 3. **Workflow to register in** — lists all `*WorkFlowImpl.java` found across all modules; select the one that will invoke this activity
+
+## 💡 Examples
+
+### Example 1: Light activity for e-mail notifications
+
+```bash
+eva g temporal-activity notification
+# Prompted:
+#   Activity name:  send-confirmation-email
+#   Category:       LightActivity
+#   Workflow:       order/ProcessOrderWorkFlowImpl.java
+```
+
+**Generates:**
+- `notification/application/ports/SendConfirmationEmailActivity.java` — `@ActivityInterface`
+- `notification/infrastructure/adapters/activities/SendConfirmationEmailActivityImpl.java` — `@Component` implementing `LightActivity`
+- Patches `order/application/usecases/ProcessOrderWorkFlowImpl.java` with a stub field
+
+### Example 2: Heavy activity for file processing
+
+```bash
+eva g temporal-activity documents
+# Prompted:
+#   Activity name:  generate-pdf-report
+#   Category:       HeavyActivity
+#   Workflow:       documents/ProcessDocumentWorkFlowImpl.java
+```
+
+**Generates:**
+- `documents/application/ports/GeneratePdfReportActivity.java`
+- `documents/infrastructure/adapters/activities/GeneratePdfReportActivityImpl.java` — implements `HeavyActivity`
+- Patches `ProcessDocumentWorkFlowImpl.java` with a `heavyActivityOptions` stub
+
+### Example 3: Multiple activities on the same workflow
+
+Run the command multiple times with different names to build up a workflow's activity set:
+
+```bash
+eva g temporal-activity order   # ValidateStockActivity → LightActivity
+eva g temporal-activity order   # ChargePaymentActivity → HeavyActivity
+eva g temporal-activity order   # SendReceiptActivity   → LightActivity
+```
+
+Each run adds a new stub field in the selected `WorkFlowImpl` without touching existing ones.
+
+## 📦 Generated Code Structure
+
+### Activity Interface — `SendConfirmationEmailActivity.java`
+
+```java
+package com.example.project.notification.application.ports;
+
+import io.temporal.activity.ActivityInterface;
+import io.temporal.activity.ActivityMethod;
+
+@ActivityInterface
+public interface SendConfirmationEmailActivity {
+
+    /**
+     * @ActivityMethod(name = "SendConfirmationEmail") ensures a globally unique
+     * method name, preventing TypeAlreadyRegisteredException when multiple
+     * activity types are registered on the same worker.
+     */
+    @ActivityMethod(name = "SendConfirmationEmail")
+    void execute(String flowId);
+}
+```
+
+> **Why `name = "..."`?**  
+> Without an explicit name, Temporal defaults every activity method to `"Execute"`. If the same worker hosts two activity interfaces both with `execute()`, Temporal throws `TypeAlreadyRegisteredException`. The generated unique name prevents this.
+
+### Activity Implementation — `SendConfirmationEmailActivityImpl.java`
+
+```java
+package com.example.project.notification.infrastructure.adapters.activities;
+
+import com.example.project.notification.application.ports.SendConfirmationEmailActivity;
+import com.example.project.shared.domain.interfaces.LightActivity;
+import org.springframework.stereotype.Component;
+
+/**
+ * Implements LightActivity — Spring DI injects this into TemporalConfig
+ * via List<LightActivity>, automatically registering it on LIGHT_TASK_QUEUE.
+ * No manual TemporalConfig.java patching is required.
+ */
+@Component
+public class SendConfirmationEmailActivityImpl
+        implements SendConfirmationEmailActivity, LightActivity {
+
+    @Override
+    public void execute(String flowId) {
+        // TODO: implement activity logic
+    }
+}
+```
+
+### WorkFlowImpl — Auto-patched Stub Field
+
+```java
+// Added inside ProcessOrderWorkFlowImpl by the command:
+private final SendConfirmationEmailActivity sendConfirmationEmailActivity =
+        Workflow.newActivityStub(SendConfirmationEmailActivity.class, lightActivityOptions);
+```
+
+For a `HeavyActivity`, `heavyActivityOptions` is used instead.
+
+## 🏗️ Queue & Registration Architecture
+
+```
+Spring Boot startup
+        │
+        ▼
+TemporalConfig.workerFactory()
+        │
+        ├─ workflowWorker (FLOW_QUEUE)
+        │       └─ registerWorkflowImplementationTypes(ProcessOrderWorkFlowImpl.class)
+        │
+        ├─ lightWorker (LIGHT_TASK_QUEUE)
+        │       └─ registerActivitiesImplementations(List<LightActivity> beans...)
+        │                       ↑
+        │              SendConfirmationEmailActivityImpl @Component
+        │
+        └─ heavyWorker (HEAVY_TASK_QUEUE)
+                └─ registerActivitiesImplementations(List<HeavyActivity> beans...)
+                                ↑
+                       GeneratePdfReportActivityImpl @Component
+```
+
+**Key points:**
+- Activities are registered automatically via **Spring DI list injection** — adding `@Component` + marker interface is sufficient.
+- The workflow stub field routes execution to the correct queue through `lightActivityOptions` / `heavyActivityOptions`.
+- `TemporalConfig.java` is **not** patched for activities (only for workflows).
+
+## 📊 Light vs Heavy — Decision Guide
+
+| Criterion | LightActivity | HeavyActivity |
+|-----------|--------------|---------------|
+| Max execution time | 30 seconds | 2 minutes |
+| Typical use cases | Cache lookups, email dispatch, simple DB writes | PDF generation, external API calls, image processing |
+| Retry timeout | 30 s per attempt | 120 s per attempt |
+| Worker queue | `LIGHT_TASK_QUEUE` | `HEAVY_TASK_QUEUE` |
+| Options variable in WorkFlowImpl | `lightActivityOptions` | `heavyActivityOptions` |
+
+## ✅ Prerequisites
+
+- `eva add temporal-client` must have been run
+- At least one workflow must exist in the project (created via `eva g temporal-flow`) — the command lists them in the interactive prompt

package/docs/commands/GENERATE_TEMPORAL_FLOW.md

@@ -0,0 +1,237 @@
+# Command `generate temporal-flow` (alias: `g temporal-flow`)
+
+## 📋 Description
+
+Generates a complete Temporal workflow with interface, implementation and service facade, then automatically registers the workflow in the existing `TemporalConfig.java`.
+
+## 🎯 Purpose
+
+Create the scaffolding for a new Temporal workflow (orchestration unit) within a module. Follows the Saga pattern with compensation support and provides both async and sync invocation modes via the generated service facade.
+
+## 📝 Syntax
+
+```bash
+eva generate temporal-flow <module>
+eva g temporal-flow <module>    # Short alias
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `module` | Yes | Target module name (e.g., `order`, `payment`) |
+
+> **Interactive prompt:** When the module is provided, the CLI asks for the **workflow name**. You can write it in `kebab-case` (`process-order`) or `PascalCase` (`ProcessOrder`) — both are accepted and normalised to PascalCase internally.
+
+## 💡 Examples
+
+### Example 1: Order processing workflow
+
+```bash
+eva g temporal-flow order
+# Prompted for workflow name: process-order  (or ProcessOrder)
+```
+
+**Generates:**
+- `application/usecases/ProcessOrderWorkFlow.java` — `@WorkflowInterface`
+- `application/usecases/ProcessOrderWorkFlowImpl.java` — implementation with Saga
+- `application/usecases/ProcessOrderWorkFlowService.java` — Spring service facade
+- Patches `shared/infrastructure/configurations/TemporalConfig.java` to register `ProcessOrderWorkFlowImpl`
+
+### Example 2: Payment workflow
+
+```bash
+eva g temporal-flow payment
+# Prompted for workflow name: process-payment
+```
+
+**Generates:**
+- `application/usecases/ProcessPaymentWorkFlow.java`
+- `application/usecases/ProcessPaymentWorkFlowImpl.java`
+- `application/usecases/ProcessPaymentWorkFlowService.java`
+- Patches `TemporalConfig.java`
+
+### Example 3: Multiple workflows in the same module
+
+You can run the command again with a different name to add more workflows:
+
+```bash
+eva g temporal-flow order
+# process-order → generates ProcessOrder files
+
+eva g temporal-flow order
+# refund-order  → generates RefundOrder files
+```
+
+Each run appends a new `registerWorkflowImplementationTypes(...)` entry to `TemporalConfig.java` without duplicating existing registrations.
+
+## 📦 Generated Code Structure
+
+### WorkFlow Interface — `ProcessOrderWorkFlow.java`
+
+```java
+package com.example.project.order.application.usecases;
+
+import io.temporal.workflow.QueryMethod;
+import io.temporal.workflow.SignalMethod;
+import io.temporal.workflow.WorkflowInterface;
+import io.temporal.workflow.WorkflowMethod;
+
+@WorkflowInterface
+public interface ProcessOrderWorkFlow {
+
+    @WorkflowMethod
+    void start(String input);
+
+    @SignalMethod
+    void confirm();
+
+    @QueryMethod
+    String getStatus();
+}
+```
+
+### WorkFlow Implementation — `ProcessOrderWorkFlowImpl.java`
+
+```java
+package com.example.project.order.application.usecases;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.common.RetryOptions;
+import io.temporal.workflow.Saga;
+import io.temporal.workflow.SignalMethod;
+import io.temporal.workflow.QueryMethod;
+import io.temporal.workflow.Workflow;
+
+import java.time.Duration;
+
+public class ProcessOrderWorkFlowImpl implements ProcessOrderWorkFlow {
+
+    private Saga.Options sagaOptions = new Saga.Options.Builder()
+        .setParallelCompensation(false)
+        .build();
+
+    private Saga saga = new Saga(sagaOptions);
+
+    // Light activities (<30 s) — routed to LIGHT_TASK_QUEUE
+    private final ActivityOptions lightActivityOptions = ActivityOptions.newBuilder()
+        .setStartToCloseTimeout(Duration.ofSeconds(30))
+        .setTaskQueue("LIGHT_TASK_QUEUE")
+        .setRetryOptions(
+            RetryOptions.newBuilder()
+                .setMaximumAttempts(2)
+                .setInitialInterval(Duration.ofSeconds(1))
+                .setMaximumInterval(Duration.ofSeconds(10))
+                .setBackoffCoefficient(2.0)
+                .build()
+        ).build();
+
+    // Heavy activities (up to 2 min) — routed to HEAVY_TASK_QUEUE
+    private final ActivityOptions heavyActivityOptions = ActivityOptions.newBuilder()
+        .setStartToCloseTimeout(Duration.ofSeconds(120))
+        .setTaskQueue("HEAVY_TASK_QUEUE")
+        .setRetryOptions(
+            RetryOptions.newBuilder()
+                .setMaximumAttempts(2)
+                .setInitialInterval(Duration.ofSeconds(1))
+                .setMaximumInterval(Duration.ofSeconds(10))
+                .setBackoffCoefficient(2.0)
+                .build()
+        ).build();
+
+    private String status = "PENDING";
+
+    @Override
+    public void start(String workFlowId) {
+        try {
+            //todo: workflow logic
+        } catch (Exception e) {
+            saga.compensate();
+        }
+    }
+
+    @Override
+    public void confirm() {
+        // Handle confirmation signal
+    }
+
+    @Override
+    public String getStatus() {
+        return status;
+    }
+}
+```
+
+### WorkFlow Service Facade — `ProcessOrderWorkFlowService.java`
+
+```java
+package com.example.project.order.application.usecases;
+
+import com.example.project.shared.domain.annotations.ApplicationComponent;
+import io.temporal.client.WorkflowClient;
+import io.temporal.client.WorkflowOptions;
+import org.springframework.beans.factory.annotation.Value;
+
+import java.util.UUID;
+
+@ApplicationComponent
+public class ProcessOrderWorkFlowService {
+
+    private final WorkflowClient workflowClient;
+
+    @Value("${temporal.flow-queue}")
+    private String flowQueue;
+
+    // ... constructor injection
+
+    /** Fire and forget — returns the workflow ID immediately */
+    public String startAsync(String input) {
+        String workflowId = "ProcessOrderWorkFlow-" + UUID.randomUUID();
+        ProcessOrderWorkFlow workflow = workflowClient.newWorkflowStub(
+                ProcessOrderWorkFlow.class,
+                WorkflowOptions.newBuilder()
+                        .setWorkflowId(workflowId)
+                        .setTaskQueue(flowQueue)
+                        .build());
+        WorkflowClient.start(workflow::start, input);
+        return workflowId;
+    }
+
+    /** Blocking — waits until the workflow finishes */
+    public void startSync(String input) {
+        String workflowId = "ProcessOrderWorkFlow-" + UUID.randomUUID();
+        ProcessOrderWorkFlow workflow = workflowClient.newWorkflowStub(
+                ProcessOrderWorkFlow.class,
+                WorkflowOptions.newBuilder()
+                        .setWorkflowId(workflowId)
+                        .setTaskQueue(flowQueue)
+                        .build());
+        workflow.start(input);
+    }
+
+    public void confirm(String workflowId) { /* signal */ }
+    public String getStatus(String workflowId) { /* query */ return null; }
+}
+```
+
+### TemporalConfig.java — Auto-patched Entry
+
+```java
+// registered automatically by eva g temporal-flow
+workflowWorker.registerWorkflowImplementationTypes(ProcessOrderWorkFlowImpl.class);
+```
+
+## 🏗️ Queue Architecture
+
+| Queue | Purpose |
+|-------|---------|
+| `FLOW_QUEUE` | Workflow orchestration (WorkFlowImpl runs here) |
+| `LIGHT_TASK_QUEUE` | Fast activities (< 30 s), injected via `lightActivityOptions` |
+| `HEAVY_TASK_QUEUE` | Long-running activities (up to 2 min), injected via `heavyActivityOptions` |
+
+Activity stubs created inside the workflow must pass the matching options object — see [GENERATE_TEMPORAL_ACTIVITY.md](./GENERATE_TEMPORAL_ACTIVITY.md).
+
+## ✅ Prerequisites
+
+- `eva add temporal-client` must have been run before this command
+- The target `<module>` must already exist (`eva add module <module>`)