Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Puneethkumarck merged 1 commit into from
Mar 8, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions ...p/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionCompletedEvent.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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";

@coderabbitai coderabbitai Bot Mar 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Topic naming inconsistent with other events.

All other events use fiat.{entity}.{action} pattern:

  • fiat.collection.initiated
  • fiat.collection.failed
  • fiat.refund.initiated
  • fiat.refund.completed

This one uses fiat.collected — breaks the convention and complicates consumer topic subscription patterns.

Proposed fix 
-    public static final String TOPIC = "fiat.collected";
+    public static final String TOPIC = "fiat.collection.completed";
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
public static final String TOPIC = "fiat.collected";
public static final String TOPIC = "fiat.collection.completed";
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionCompletedEvent.java`
at line 19, The TOPIC constant in CollectionCompletedEvent (public static final
String TOPIC) breaks the project's event naming convention by using
"fiat.collected"; change its value to follow the fiat.{entity}.{action} pattern
(e.g., "fiat.collection.completed") and update any references/consumers that use
CollectionCompletedEvent.TOPIC so they subscribe/publish to the new topic
string; ensure tests or config that assert topic names are updated accordingly.

}
16 changes: 16 additions & 0 deletions ...ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionFailedEvent.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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";
}
19 changes: 19 additions & 0 deletions ...p/src/main/java/com/stablecoin/payments/onramp/domain/event/CollectionInitiatedEvent.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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";
}
18 changes: 18 additions & 0 deletions ...-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/RefundCompletedEvent.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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";
}
18 changes: 18 additions & 0 deletions ...-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/RefundInitiatedEvent.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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,

@coderabbitai coderabbitai Bot Mar 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Avoid publishing free-form refund reasons on the event bus.

Line 13 exposes reason as an arbitrary String. If this carries operator notes or customer-entered text, it will be replicated to every subscriber and retained in Kafka. Prefer a bounded reason code/enum in the event payload and keep detailed notes inside the aggregate or persistence layer.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/RefundInitiatedEvent.java`
at line 13, The event currently exposes an unbounded String field named reason
in RefundInitiatedEvent; replace it with a bounded code/enum (e.g., add a
RefundReason enum and change the RefundInitiatedEvent constructor/field from
String reason to RefundReason reasonCode) so only predefined reason codes are
published, and move any free-form operator or customer notes into the
aggregate/persistence layer (or keep them only on the command/DB model). Update
serialization/consumers to use the new RefundReason type and consider a
migration/compatibility path (e.g., keep the old String as deprecated or map
legacy strings to enum values) to avoid breaking subscribers.

Instant initiatedAt
) {
Comment on lines +7 to +15

@coderabbitai coderabbitai Bot Mar 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Enforce event invariants in the record constructor.

This record currently accepts null IDs/timestamp, blank currency/reason, and non-positive amounts. That allows malformed domain events to escape onto Kafka before any adapter-level validation catches them.

Proposed fix 
 package com.stablecoin.payments.onramp.domain.event;
 
 import java.math.BigDecimal;
 import java.time.Instant;
+import java.util.Objects;
 import java.util.UUID;
 
 public record RefundInitiatedEvent(
         UUID refundId,
         UUID collectionId,
@@
         String reason,
         Instant initiatedAt
 ) {
+    public RefundInitiatedEvent {
+        Objects.requireNonNull(refundId, "refundId must not be null");
+        Objects.requireNonNull(collectionId, "collectionId must not be null");
+        Objects.requireNonNull(paymentId, "paymentId must not be null");
+        Objects.requireNonNull(refundAmount, "refundAmount must not be null");
+        Objects.requireNonNull(currency, "currency must not be null");
+        Objects.requireNonNull(reason, "reason must not be null");
+        Objects.requireNonNull(initiatedAt, "initiatedAt must not be null");
+
+        if (refundAmount.signum() <= 0) {
+            throw new IllegalArgumentException("refundAmount must be positive");
+        }
+        if (currency.isBlank()) {
+            throw new IllegalArgumentException("currency must not be blank");
+        }
+        if (reason.isBlank()) {
+            throw new IllegalArgumentException("reason must not be blank");
+        }
+    }
 
     public static final String TOPIC = "fiat.refund.initiated";
 }
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@fiat-on-ramp/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/event/RefundInitiatedEvent.java`
around lines 7 - 15, The RefundInitiatedEvent record currently allows null or
invalid values; add a compact canonical constructor for RefundInitiatedEvent
that validates refundId, collectionId, paymentId, and initiatedAt are non-null,
refundAmount is non-null and > 0, and currency and reason are non-null/non-blank
(trimmed length > 0); throw IllegalArgumentException (or NullPointerException
for nulls) with clear messages when invariants fail so malformed events cannot
be created and emitted to Kafka.


public static final String TOPIC = "fiat.refund.initiated";
}
8 changes: 8 additions & 0 deletions ...p/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/model/AccountType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
package com.stablecoin.payments.onramp.domain.model;

public enum AccountType {
IBAN,
ACH_ROUTING,
SORT_CODE,
PIX_KEY
}
24 changes: 24 additions & 0 deletions ...p/fiat-on-ramp/src/main/java/com/stablecoin/payments/onramp/domain/model/BankAccount.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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");
}
}
}
Loading
Loading