核心资金事实：MySQL 事务 + Worker 轮询技术方案

1. 决策与边界

2. 什么是“核心资金事实”

“资金事实”是能够改变用户应得金额、可用余额、冻结余额或 BeeX 对外付款义务的数据。它和页面展示、缓存、通知不是同一个层级。

3. 不可破坏的资金不变量

1. 一笔业务只入账一次：所有资金动作都有稳定业务幂等键，数据库唯一约束是最后一道防线。
2. 余额守恒：pending + available + frozen + riskHold 的每次变化必须与账本 delta 和 before/after 对得上。
3. 状态只能按允许方向推进：通过 CAS（WHERE status = expected）更新，禁止无条件覆盖。
4. 金额统一用整数 minor unit：数据库和服务端计算使用 BIGINT，不使用 float/double。按 BeeX 当前约定，展示前再由统一金额组件换算和向下取整。
5. 规则按下单时间命中：佣金比例、平台佣金基数上限、活动规则以 ordered_at 命中生效版本并形成快照，之后修改配置不改变历史订单。
6. 外部调用不占用资金事务：事务内只落事实和任务，事务外调用第三方，返回后再开事务确认结果。
7. 允许重复执行，不允许重复生效：Worker、Webhook 和 MQ 都按至少一次处理设计，不假设“恰好执行一次”。
8. 通知不阻塞资金提交：飞书、Push、BI、SLS 全部在事务提交后处理，失败可重试但不得回滚已确认的资金事实。

余额变动通用断言
newBalance = oldBalance + delta
newBalance >= 0                         -- 除非明确采用负债模型
UNIQUE(ref_type, ref_id, ledger_type)   -- 同一业务动作只写一次账
wallet update + ledger insert           -- 必须处于同一 MySQL 事务

4. 总体架构

flowchart LR
  PLATFORM["TikTok / Shopee / Lazada / Traveloka"] -->|"轮询原始订单"| WORKER["Worker :7020"]
  WORKER --> NORMALIZE["平台适配与标准化\n事务外完成"]
  NORMALIZE --> TX["单订单短事务"]
  TX --> ORDERS[("affiliate_orders")]
  TX --> COMM[("commission_records")]
  TX --> COUPON[("coupon_reservations")]
  TX --> WALLET[("user_wallets + wallet_ledger")]
  TX --> OUTBOX[("outbox_event")]
  SETTLE["结算 Worker"] -->|"扫描到期记录"| COMM
  SETTLE --> WALLET
  PAYOUT["提现 Worker"] --> PAYTASK[("payout task / transaction")]
  PAYOUT -->|"事务外调用"| XENDIT["Xendit"]
  XENDIT -->|"Webhook / Query"| WEBHOOK["Webhook :7030"]
  WEBHOOK --> PAYTASK
  WEBHOOK --> WALLET
  OUTBOX --> RELAY["Outbox Relay"]
  RELAY --> SIDE["飞书 / Push / BI / 可选 MQ"]
      

平台订单同步不是一个跨网络的大事务。Worker 先在事务外调用平台 API、解析数据，再把每个订单交给独立短事务处理。一个订单失败只影响自己，不能让整个分页批次回滚；页面、通知和 MQ 也不进入这段资金事务。

5. 数据模型与职责

6. 平台订单入库：一个订单一个事务

sequenceDiagram
  participant P as 平台 API
  participant W as Order Sync Worker
  participant S as FinancialOrderIngestService
  participant DB as MySQL
  participant O as Outbox Relay
  W->>P: 拉取一页订单（事务外）
  P-->>W: 原始订单列表
  loop 每个订单独立处理
    W->>S: processOne(normalizedOrder)
    S->>DB: BEGIN
    S->>DB: upsert affiliate_orders（平台订单唯一键）
    S->>DB: 解析并锁定归因/规则快照
    S->>DB: upsert commission_records
    S->>DB: 预占 coupon_reservations
    S->>DB: 锁 user_wallets，写 pending + wallet_ledger
    S->>DB: 写 outbox_event
    S->>DB: COMMIT
  end
  O->>DB: 事务后轮询 Outbox
      

6.1 事务外完成

• 调用 TikTok/Shopee/Lazada/Traveloka API、翻页、签名和 JSON 解析。
• 平台字段标准化：平台订单号、商品、金额、平台佣金、下单时间、平台更新时间、状态。
• 生成稳定本地 ID 和幂等业务键；不能使用本次运行随机数决定资金记录 ID。

6.2 事务内完成

1. 按 (platform, platform_order_id) upsert 订单；比较 platform_updated_at 和允许状态矩阵，旧消息不能覆盖新状态。
2. 根据 tracking/click/referral 解析归属用户；归因补正必须保留变更审计。
3. 以 ordered_at 命中佣金规则版本，计算平台佣金基数 M = min(platformCommission, GMV × maxCommissionBaseBps)，当前上限由配置版本控制。
4. 按 User 直邀关系生成用户返现和邀请人奖励。
5. 如有返佣基金等活动，按订单时序预占额度，防止多个未完成订单重复占用同一权益。
6. 写 commission_records=PENDING；若该平台状态已明确无效，则只保留审计记录，不增加 pending。
7. 锁用户钱包，增加 pending，并写唯一账本。
8. 写订单/收益变更 Outbox；提交后再发送飞书和 Push。

-- 数据库兜底：平台重复回传 100 次也只存在一个订单
UNIQUE KEY uk_platform_order (platform, platform_order_id)

-- 资金账本兜底：同一佣金记录的 PENDING 入账只成功一次
UNIQUE KEY uk_ledger_ref (ref_type, ref_id, type)

7. 佣金结算：扫描到期记录，逐条短事务释放

现有 CommissionSettlementService 的方向是正确的：默认每 5 分钟扫描一次、批量取 200 条、每条佣金通过自代理进入独立事务，先 CAS 再把钱包 pending 转 available。保留这个模式，不需要为了“实时”改成由 MQ 直接加钱。

sequenceDiagram
  participant W as Settlement Worker
  participant DB as MySQL
  W->>DB: 查询 PENDING 且 release_at <= now（limit 200）
  loop 每条 commission
    W->>DB: BEGIN
    W->>DB: UPDATE commission_records SET status=AVAILABLE WHERE id=? AND status=PENDING
    alt CAS 成功
      W->>DB: SELECT user_wallets FOR UPDATE
      W->>DB: pending -= amount, available += amount
      W->>DB: INSERT wallet_ledger（唯一业务键）
      W->>DB: INSERT outbox_event
      W->>DB: COMMIT
    else 已被其它实例处理
      W->>DB: ROLLBACK / no-op
    end
  end
      

UPDATE commission_records
SET status = 'AVAILABLE', settled_at = NOW()
WHERE id = :commissionId
  AND status = 'PENDING'
  AND release_at <= NOW();

-- affectedRows = 1 才有资格继续改钱包；0 表示已处理或已失效。

8. 取消、退款与追偿

退款要根据佣金当前所在阶段采用不同动作，不能一律删除记录，也不能只改订单状态。详细状态与平台映射见《联盟订单退货、退款与收益撤销闭环》。

stateDiagram-v2
  [*] --> PENDING
  PENDING --> AVAILABLE: 到结算时间且订单有效
  PENDING --> INVALID: 取消/退款
  PENDING --> FROZEN: 退款处理中/部分退款
  FROZEN --> PENDING: 退款驳回或撤回
  FROZEN --> INVALID: 确认退款
  AVAILABLE --> RECOVERY_REVIEW: 退款发生在收益释放后
  RECOVERY_REVIEW --> MANUAL_RESOLVED: 财务/运营受审计处理
      

9. 提现与 Xendit：三段式执行

sequenceDiagram
  participant A as API / Admin
  participant DB as MySQL
  participant W as Payout Worker
  participant X as Xendit
  participant H as Xendit Webhook
  A->>DB: Tx1 验证规则和支付密码，冻结余额，创建提现单与付款任务
  DB-->>A: COMMIT（PAYOUT_PENDING）
  W->>DB: 短事务领取任务，写 lease/attempt，COMMIT
  W->>X: 事务外 POST payout，Idempotency-Key=withdrawId
  X-->>W: 接受 / 明确失败 / 超时未知
  W->>DB: Tx2 保存 providerRef 与本次结果
  X->>H: Webhook 最终状态
  H->>DB: Tx3 webhook 去重 + CAS 状态 + 扣 frozen 或解冻 + 账本
      

9.1 Tx1：申请与冻结

1. 校验支付密码、KYC、收款账户、最低/最高金额、每日次数/金额和风控。
2. 锁定 user_wallets，执行 available -= amount、frozen += amount。
3. 写 WITHDRAW_FREEZE 账本。
4. 创建 withdraw_requests 和一条 READY/PENDING 的持久化 payout task。
5. 同事务提交；此时钱没有付给用户，但已不能被再次提现。

9.2 事务外：调用 Xendit

• Worker 用 withdraw_id 作为 Xendit external/idempotency key。
• 调用前先持久化 attempt，调用时不持有钱包锁和 MySQL 长事务。
• 明确失败才进入可解冻判断；超时、断网、502 等“结果未知”不能直接重试，也不能直接解冻。
• 结果未知时先按 external ID 查询 Xendit；确认没有创建付款后，才允许用同一幂等键重试。

9.3 Tx2/Tx3：确认结果

stateDiagram-v2
  [*] --> REQUESTED
  REQUESTED --> REJECTED: 人工拒绝并解冻
  REQUESTED --> PAYOUT_PENDING: 审核通过/免审核
  PAYOUT_PENDING --> PROCESSING: Xendit 已接受
  PAYOUT_PENDING --> PROVIDER_UNKNOWN: 超时或结果未知
  PROVIDER_UNKNOWN --> PROCESSING: 查询到已创建
  PROVIDER_UNKNOWN --> PAYOUT_PENDING: 确认未创建，可安全重试
  PROCESSING --> PAID: 成功 Webhook
  PROCESSING --> FUNDS_HELD: Xendit 余额不足等可恢复错误
  FUNDS_HELD --> PROCESSING: 安全重试
  PAYOUT_PENDING --> FAILED: 明确未扣款失败并解冻
  PROCESSING --> FAILED: 明确终态失败并解冻
      

10. Worker 轮询机制

10.1 平台订单同步

1. 每个平台、国家和任务使用独立 job key；当前 TikTok、Shopee、Lazada、Traveloka 等默认约 15 分钟轮询。
2. Redis 分布式锁避免多个 Worker 同时扫同一平台，但锁失效后即使重复执行，MySQL 幂等仍必须保证正确。
3. 使用 watermark + 重叠时间窗。每次从“上次成功时间减去一段 overlap”开始拉，接住平台延迟回传和状态补发。
4. 按页拉取；每个订单独立提交；一页处理完再保存 page checkpoint。进程中途退出最多重放这一页。
5. 定期执行更大 lookback 的补偿扫描，不能只靠一个永远向前的 cursor，否则晚到订单会永久漏掉。

10.2 本地到期任务

佣金释放、活动过期、提现重试直接扫描 MySQL 当前状态，不需要把“未来某个时间执行”的命令长期押在 MQ 中。

SELECT id
FROM commission_records
WHERE status = 'PENDING'
  AND release_at <= NOW()
ORDER BY release_at, id
LIMIT 200;

-- 每条记录再进入独立事务做 CAS，查询结果本身不代表拥有处理权。

10.3 多 Worker 水平扩容

早期可继续用分布式锁控制单任务单实例。任务量增长后，对 payout 等执行任务增加数据库 lease：

BEGIN;
SELECT id FROM payout_tasks
WHERE status IN ('READY','RETRY')
  AND next_attempt_at <= NOW()
  AND (lease_until IS NULL OR lease_until < NOW())
ORDER BY next_attempt_at, id
FOR UPDATE SKIP LOCKED
LIMIT 50;

UPDATE payout_tasks
SET status='PROCESSING', lease_owner=:workerId,
    lease_until=DATE_ADD(NOW(), INTERVAL 2 MINUTE), attempt_count=attempt_count+1
WHERE id IN (...);
COMMIT;

11. 幂等、并发与锁

11.1 锁顺序

所有资金事务统一锁顺序，减少死锁：先锁/更新业务根记录（订单、佣金、提现），再锁权益记录，最后按 user_id 排序锁钱包，随后只做 ledger/outbox insert。禁止某条路径先锁钱包、再回头锁同一订单的佣金记录。

11.2 隔离级别

不把正确性寄托在默认隔离级别上。首阶段保留当前 MySQL/Spring 隔离配置，依靠显式 FOR UPDATE、唯一键和 CAS；是否从 REPEATABLE READ 调整为 READ COMMITTED，要经过死锁、幻读和回归测试后单独决策。

12. Outbox 与 MQ 的边界

资金事务可以在提交前写一条 Outbox，但 Outbox 表示“资金事实已提交后，需要通知外部”，不是资金本身。

13. 对账与自愈

事务和幂等是第一道保障，对账是发现代码缺陷、人工改库、平台延迟与第三方未知状态的第二道保障。对账不能只生成报表，还要定义可自动修复和必须人工处理的边界。

14. 监控与告警

飞书告警必须带：环境、国家数据中心、任务、平台、业务 ID、用户联盟码、request/trace ID、首次失败时间、重试次数和可执行的排查链接。不要只发“任务失败”。

15. 国家数据中心隔离

flowchart TB
  subgraph ID["Indonesia Data Center"]
    IDAPI["API / WA / Webhook"]
    IDW["Worker"]
    IDDB[("ID MySQL")]
    IDX["ID 平台与 Xendit 账号"]
    IDAPI --> IDDB
    IDW --> IDDB
    IDW --> IDX
  end
  subgraph MY["Malaysia Data Center"]
    MYAPI["API / WA / Webhook"]
    MYW["Worker"]
    MYDB[("MY MySQL")]
    MYX["MY 平台与支付账号"]
    MYAPI --> MYDB
    MYW --> MYDB
    MYW --> MYX
  end
      

• 印尼、马来等国家是完全不同的数据中心、数据库、Worker、平台凭证和支付账户，不存在跨国家数据库事务。
• country_code 只用于数据自描述、审计、备份与迁移检查，不意味着把多个国家业务混在一套数据库里运行。
• 资金对账、游标、告警和幂等键均按本数据中心独立管理；跨国 BI 只能读取脱敏汇总，不参与资金写入。

16. 当前实现与目标差距

17. 分阶段改造

18. 验收用例

• 同一平台订单重复回放 100 次，订单、佣金、活动预占和每种钱包 ledger 都只有一份。
• 两个 Worker 同时结算同一 commission，只有一个 CAS 成功，pending/available 只变化一次。
• 单订单事务在写 commission 后人为抛异常，订单资金事实、钱包和 Outbox 全部回滚，不留下半成品。
• 平台订单乱序回放 PENDING→COMPLETED→旧 PENDING，最终状态不能倒退。
• 活动额度只够一单时，两单并发下单只有先锁到权益的一单预占成功；退款后额度可顺延。
• 结算后退款：不自动扣 available、不形成 debt；只创建唯一追偿风险记录并阻断提现，重复回放不重复创建。
• 部分退款或正金额快照下降：订单进入 FROZEN，佣金停止释放；退款驳回后恢复。
• Shopee 稀疏回放金额为 0：保留原金额，不误判为部分退款。
• 历史退款追扫在 24 小时内覆盖最近 120 天，不因退款发生较晚而漏单。
• 提现申请接口超时重试，不会重复冻结。
• Xendit 已成功但 Worker 在保存响应前崩溃，重启后通过 external ID 查询恢复为 PROCESSING/PAID，不会再次付款。
• 重复、乱序 Webhook 不会重复扣 frozen 或重复解冻。
• 飞书/MQ 全部关闭时，订单、佣金、钱包、提现仍然正确；恢复后 Outbox 可以补发通知。
• Redis 锁主动过期、两个 Worker 重复扫描时，资金结果仍然正确。
• 钱包-账本、佣金-pending、提现-frozen 三类对账能发现人工制造的差异，并阻断危险自动修复。