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

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;
 }