feat(procurement): implement sample fulfillment and settled fee workflow

common-event-contract/src/main/java/com/baiyue/common/event/BusinessFeeSourceChangedV1.java

@@ -56,6 +56,7 @@ public record BusinessFeeSourceChangedV1(
     String reviewStatus,
     String publicationStatus,
     String sourceStatus,
-    String sourceHash
+    String sourceHash,
+    WalletSettlementReference walletSettlement
 ) {
 }

common-event-contract/src/main/java/com/baiyue/common/event/WalletCommandCompletedV1.java

@@ -15,7 +15,9 @@ public record WalletCommandCompletedV1(
     BigDecimal amount,
     String errorCode,
     String errorMessage,
-    Instant completedAt
+    Instant completedAt,
+    String walletHoldId,
+    String walletLedgerId
 ) {
     public static final int VERSION = 1;
 }

common-event-contract/src/main/java/com/baiyue/common/event/WalletCommandRequestedV1.java

@@ -3,7 +3,13 @@ package com.baiyue.common.event;
 import java.math.BigDecimal;
 import java.time.Instant;
 
-/** 海外业务向国内 Finance 发起的客户资金冻结、结算或释放指令。 */
+/**
+ * 海外业务向 Finance 发起的客户资金指令。
+ * FREEZE 的 amount 为预留金额；SETTLE 全额结算；RELEASE 释放原冻结。
+ * SETTLE_ACTUAL 的 amount 为最终正额 CNY 实扣，原子补差或释放余款，原冻结金额保留。
+ * 实际零元使用 RELEASE，不发送零元结算。结算和释放按原业务冻结身份关联。
+ * REFUND 使用独立业务退款号并携带 originalLedgerId，关联原成功消费，不创建充值。
+ */
 public record WalletCommandRequestedV1(
     String operation,
     long customerId,
@@ -12,7 +18,8 @@ public record WalletCommandRequestedV1(
     BigDecimal amount,
     String remark,
     String idempotencyKey,
-    Instant requestedAt
+    Instant requestedAt,
+    String originalLedgerId
 ) {
     public static final int VERSION = 1;
 }

common-event-contract/src/main/java/com/baiyue/common/event/WalletSettlementReference.java

@@ -0,0 +1,4 @@
+package com.baiyue.common.event;
+
+/** Finance-issued identity of a successful consumption, carried by its immutable fee source. */
+public record WalletSettlementReference(String commandEventId, String holdId, String ledgerId) { }