费用提交

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

@@ -1,4 +1,13 @@
 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) { }
+/** 成功扣款凭据；资金业务身份独立于费用对应的实际服务订单。 */
+public record WalletSettlementReference(String commandEventId, String holdId, String ledgerId,
+    @com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)
+    String walletBusinessType,
+    @com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)
+    String walletBusinessNo) {
+    /** 原有资金身份与服务订单一致的来源继续使用原三项凭据。 */
+    public WalletSettlementReference(String commandEventId, String holdId, String ledgerId) {
+        this(commandEventId, holdId, ledgerId, null, null);
+    }
+}

common-event-contract/src/main/java/com/baiyue/common/event/package-info.java

@@ -1,4 +1,11 @@
 /**
  * 国内与海外业务单元共享的稳定事件契约。
+ *
+ * <p>海外费用的 walletSettlement 引用成功扣款的 commandEventId、holdId、ledgerId。
+ * 独立资金流程另外携带 walletBusinessType、walletBusinessNo：人工费用为
+ * OVERSEAS_MANUAL_FEE / 来源费用ID-冻结次数，仓租为 STORAGE_RENT / 出库预占ID。
+ * 外层 businessType、businessNo 始终表示实际服务订单，不能替换为资金流程编号。
+ * Finance 同时核对冻结、实扣流水、成功指令结果及客户金额，一个 hold 只能关联一个费用来源。
+ * 资金身份与服务订单一致的既有引用省略这两个字段，保持既有快照哈希。</p>
  */
 package com.baiyue.common.event;