feat(s3): domain model — CollectionOrder aggregate, state machine, events, ports (STA-120)

Closes STA-120

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Puneethkumarck

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionCompletedEvent.java

@@ -0,0 +1,20 @@
+package com.stablecoin.payments.onramp.domain.event;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.UUID;
+
+public record CollectionCompletedEvent(
+        UUID collectionId,
+        UUID paymentId,
+        UUID correlationId,
+        BigDecimal collectedAmount,
+        String currency,
+        String paymentRail,
+        String psp,
+        String pspReference,
+        Instant collectedAt
+) {
+
+    public static final String TOPIC = "fiat.collected";
+}

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionFailedEvent.java

@@ -0,0 +1,16 @@
+package com.stablecoin.payments.onramp.domain.event;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record CollectionFailedEvent(
+        UUID collectionId,
+        UUID paymentId,
+        UUID correlationId,
+        String reason,
+        String errorCode,
+        Instant failedAt
+) {
+
+    public static final String TOPIC = "fiat.collection.failed";
+}

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionInitiatedEvent.java

@@ -0,0 +1,19 @@
+package com.stablecoin.payments.onramp.domain.event;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.UUID;
+
+public record CollectionInitiatedEvent(
+        UUID collectionId,
+        UUID paymentId,
+        UUID correlationId,
+        BigDecimal amount,
+        String currency,
+        String paymentRail,
+        String psp,
+        Instant initiatedAt
+) {
+
+    public static final String TOPIC = "fiat.collection.initiated";
+}

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/RefundCompletedEvent.java

@@ -0,0 +1,18 @@
+package com.stablecoin.payments.onramp.domain.event;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.UUID;
+
+public record RefundCompletedEvent(
+        UUID refundId,
+        UUID collectionId,
+        UUID paymentId,
+        BigDecimal refundAmount,
+        String currency,
+        String pspRefundRef,
+        Instant completedAt
+) {
+
+    public static final String TOPIC = "fiat.refund.completed";
+}

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/RefundInitiatedEvent.java

@@ -0,0 +1,18 @@
+package com.stablecoin.payments.onramp.domain.event;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.UUID;
+
+public record RefundInitiatedEvent(
+        UUID refundId,
+        UUID collectionId,
+        UUID paymentId,
+        BigDecimal refundAmount,
+        String currency,
+        String reason,
+        Instant initiatedAt
+) {
+
+    public static final String TOPIC = "fiat.refund.initiated";
+}

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/model/AccountType.java

@@ -0,0 +1,8 @@
+package com.stablecoin.payments.onramp.domain.model;
+
+public enum AccountType {
+    IBAN,
+    ACH_ROUTING,
+    SORT_CODE,
+    PIX_KEY
+}

fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/model/BankAccount.java

@@ -0,0 +1,24 @@
+package com.stablecoin.payments.onramp.domain.model;
+
+public record BankAccount(
+        String accountNumberHash,
+        String bankCode,
+        AccountType accountType,
+        String country
+) {
+
+    public BankAccount {
+        if (accountNumberHash == null || accountNumberHash.isBlank()) {
+            throw new IllegalArgumentException("Account number hash is required");
+        }
+        if (bankCode == null || bankCode.isBlank()) {
+            throw new IllegalArgumentException("Bank code is required");
+        }
+        if (accountType == null) {
+            throw new IllegalArgumentException("Account type is required");
+        }
+        if (country == null || country.isBlank()) {
+            throw new IllegalArgumentException("Country is required");
+        }
+    }
+}