Merge pull request #10 from kivo2/clean-comments

Clean comments

Author: kivo2

common/src/main/java/com/example/common/enums/SagaStatus.java

@@ -1,18 +1,5 @@
 package com.example.common.enums;
 
-/**
- * Lifecycle states for a Saga workflow instance.
- *
- * <p>State transitions:
- *
- * <p>STARTED → RUNNING → COMPLETED ↘ FAILED (permanent business failure — no retry) ↘ PENDING_RETRY
- * (transient failure — will retry) ↘ PERMANENTLY_FAILED (max retries exhausted)
- *
- * <p>KEY DISTINCTION: FAILED = business rule prevented completion (out of stock, card declined) No
- * retry — retrying won't help PERMANENTLY_FAILED = transient failure exhausted all retries Needs
- * manual intervention or customer action PENDING_RETRY = transient failure, retry scheduled at
- * next_retry_at
- */
 public enum SagaStatus {
   STARTED,
   RUNNING,

common/src/main/java/com/example/common/enums/SagaStep.java

@@ -1,12 +1,5 @@
 package com.example.common.enums;
 
-/**
- * Ordered steps in the checkout workflow.
- *
- * <p>Forward steps (Phase 1-3): RESERVE_INVENTORY → AUTHORIZE_PAYMENT → CREATE_ORDER → COMPLETED
- *
- * <p>Compensating steps (Phase 4): RELEASE_INVENTORY, REFUND_PAYMENT, CANCEL_ORDER
- */
 public enum SagaStep {
   // Forward steps
   RESERVE_INVENTORY,
@@ -17,7 +10,7 @@ public enum SagaStep {
   COMPLETED,
   FAILED,
 
-  // Compensating steps (Phase 4)
+  // Compensating steps
   RELEASE_INVENTORY,
   REFUND_PAYMENT,
   CANCEL_ORDER

common/src/main/java/com/example/common/exceptions/DuplicateOrderException.java

@@ -2,15 +2,6 @@
 
 import java.util.UUID;
 
-/**
- * Thrown when an order already exists for this saga in a conflicting state.
- *
- * <p>NOTE: This is different from idempotency. Idempotency means: "I already did this work
- * successfully, here's the result." DuplicateOrderException means: "An order exists for this saga
- * but something is wrong."
- *
- * <p>FAILURE SCENARIO: "Order creation fails (duplicate order)"
- */
 public class DuplicateOrderException extends PermanentWorkerException {
 
   public DuplicateOrderException(UUID sagaId) {

common/src/main/java/com/example/common/exceptions/InsufficientStockException.java

@@ -1,16 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Thrown when requested quantity exceeds available stock.
- *
- * <p>PERMANENT failure — retrying won't restock the warehouse.
- *
- * <p>FAILURE SCENARIO: "Inventory check fails (out of stock)" FAILURE SCENARIO: "Inventory
- * partially available (some items in stock, some not)"
- *
- * <p>The message should identify which product(s) failed and why. Example: "Insufficient stock for
- * prod_1: requested=5, available=2"
- */
 public class InsufficientStockException extends PermanentWorkerException {
 
   public InsufficientStockException(String productId, int requested, int available) {

common/src/main/java/com/example/common/exceptions/PaymentDeclinedException.java

@@ -1,15 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Thrown when a payment is declined by the payment provider.
- *
- * <p>PERMANENT failure — retrying a declined card won't approve it. The customer needs to use a
- * different payment method.
- *
- * <p>FAILURE SCENARIO: "Payment declined (insufficient funds)"
- *
- * <p>Simulate by using token: "tok_declined"
- */
 public class PaymentDeclinedException extends PermanentWorkerException {
 
   public PaymentDeclinedException(String token) {

common/src/main/java/com/example/common/exceptions/PermanentWorkerException.java

@@ -1,13 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Permanent failure — retrying will NOT help.
- *
- * <p>When the orchestrator catches this, it marks the saga FAILED immediately. No retry is
- * scheduled. The customer needs to take action.
- *
- * <p>Subclasses: InsufficientStockException, PaymentDeclinedException, DuplicateOrderException
- */
 public class PermanentWorkerException extends WorkerException {
 
   public PermanentWorkerException(String message) {

common/src/main/java/com/example/common/exceptions/TransientWorkerException.java

@@ -1,14 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Transient failure — retrying MAY help.
- *
- * <p>When the orchestrator catches this, it schedules a retry with exponential backoff. If max
- * retries are exhausted, the saga moves to PERMANENTLY_FAILED.
- *
- * <p>Use this for: DB timeouts, network blips, service temporarily unavailable, any infrastructure
- * failure that is expected to resolve on its own.
- */
 public class TransientWorkerException extends WorkerException {
 
   public TransientWorkerException(String message) {

common/src/main/java/com/example/common/exceptions/WorkerException.java

@@ -1,22 +1,5 @@
 package com.example.common.exceptions;
 
-/**
- * Base class for all worker exceptions.
- *
- * <p>FAILURE TYPE TAXONOMY:
- *
- * <p>PermanentWorkerException (extends this) → Business rule failure. Retrying will NOT help. →
- * Examples: out of stock, card declined, duplicate order → Orchestrator action: mark saga FAILED
- * immediately
- *
- * <p>TransientWorkerException (extends this) → Temporary infrastructure failure. Retrying MAY help.
- * → Examples: DB connection timeout, network blip, service unavailable → Orchestrator action:
- * schedule retry with exponential backoff
- *
- * <p>This distinction is the core of Phase 2 retry semantics. Getting it wrong means either: -
- * Retrying a declined card (wastes time, confuses customer) - Not retrying a DB timeout (loses a
- * valid checkout)
- */
 public abstract class WorkerException extends RuntimeException {
 
   protected WorkerException(String message) {

common/src/main/java/com/example/common/interfaces/InventoryWorker.java

@@ -5,21 +5,6 @@
 
 import com.example.common.dto.StartCheckoutRequest;
 
-/**
- * Contract for the Inventory Worker.
- *
- * <p>Phase 2: Implemented as a direct Spring bean call (in-process). Phase 3a: Implemented as a
- * Kafka command/event exchange.
- *
- * <p>The contract stays the same across phases — only the transport changes.
- *
- * <p>IDEMPOTENCY CONTRACT: If reserveInventory is called twice with the same sagaId, the second
- * call MUST be a no-op. It should detect the existing reservation and return without modifying
- * inventory quantities a second time.
- *
- * <p>ATOMICITY CONTRACT: Either ALL items are reserved or NONE are. Never partially reserve. Check
- * all items first, then reserve all if possible.
- */
 public interface InventoryWorker {
 
   /**

common/src/main/java/com/example/common/interfaces/OrderWorker.java

@@ -5,14 +5,6 @@
 
 import com.example.common.dto.StartCheckoutRequest;
 
-/**
- * Contract for the Order Worker.
- *
- * <p>Phase 2: Direct Spring bean call. Phase 3a: Kafka command/event exchange.
- *
- * <p>IDEMPOTENCY CONTRACT: If createOrder is called twice with the same sagaId, the second call
- * returns the existing orderId without creating a duplicate order record.
- */
 public interface OrderWorker {
 
   /**