junhong_cmp_fiber/openspec/changes/add-commission-clawback-records/design.md

Context

现有退款佣金回扣是「整单全额失效」：退款 Outbox 事件 refund.commission.deduct.requested 触发 ProcessCommissionDeduction，由 deductAllCommission 对每条已发放佣金调用 deductSingleCommission，把原佣金记录状态由 3 改为 4、扣减佣金钱包并写 commission_deduct 负数流水，审计动作 refund.invalidate_commission。该路径已正确实现两件本 Change 要复用的事实：加锁顺序「申请行 → 尝试行 → 钱包行」，以及「先释放待审提现冻结、再扣减余额」。动机见 proposal.md - Why。

约束：

• 佣金钱包 CHECK chk_agent_wallet_available_balance 的 commission 分支为 frozen_balance <= GREATEST(balance, 0)（迁移 000209）。扣减前若仍有未释放冻结，GREATEST 随余额下降而塌陷，先扣款即违约。
• 提现尝试表 tb_commission_withdrawal_request_attempt 无 status 列；未结算的唯一事实是 released_at IS NULL，释放金额事实是 attempt.amount。
• 退款状态：1 待审批 / 2 已通过 / 3 已拒绝 / 4 已退回 / 5 原路处理中 / 6 渠道明确失败。仅 2 是稳定成功终态；3/4/6 可重提，重提复用同一退款行且可修改退款金额与冻结实收金额。
• 企业微信通过后撤销不改变 status，只置 anomaly_flag = 1、failure_reason = 'revoked_after_approved'，因此「已通过但存在审批异常」与「正常的已通过」在状态上不可区分。
• 原路渠道明确成功路径不产生任何 Outbox 事件，只回写退款行与订单。

Goals / Non-Goals

Goals:

• 用 PRD 2.14 语义整体替换全额失效实现，原佣金记录保持不变。
• 退款回溯准入由退款申请状态与方式唯一决定，不依赖失败分类标记或新增事件。
• 金额可按分精确复现：比例、向下取整、末条起向前补差、累计上限。
• 幂等有数据库权威兜底，commission_deducted 明确降级为投影。
• 回溯在提现冻结约束下可安全落库，允许佣金余额为负。
• 回溯事实可在佣金明细列表、详情与导出中按既有数据范围核对。

Non-Goals:

• 不修改既有迁移；新增 Schema 变化一律使用新的成对迁移。
• 不重构 internal/service/refund 的模块结构，也不改动人工处置链路（ResolveCommissionRecord 的 99 → 4 失效）与提现资格、审批语义。
• 不新增退款完成类独立事件，不新增运行时开关。
• 不修改 GetStats / GetDailyStats 与首页统计口径：回溯不计入净佣金，本期只保证回溯明细在列表、详情与导出中可见。
• 不回填存量：已按旧语义处理过（commission_deducted = true）的退款单不重新回溯，其原佣金保持既有的已失效状态，不补建回溯明细。
• 换货回溯、统一时间筛选、员工代收款账单、代理自充与商户池不在范围。

Decisions

1. 回溯准入由退款申请状态与方式决定

仅当 refund.status = 2（已通过）且 anomaly_flag = 0 且（非原路方式 或 channel_refund_status = 2）时生成回溯。其余状态返回可重试错误，不写明细、不置完成事实。

• anomaly_flag = 0 是必需条件，不是可选加固：applyRevokedAfterApproved 只置异常标记、不改状态，因此「企业微信通过后撤销」的退款单仍是 status = 2；原路场景下渠道后续成功仍会把 status 由 5 推到 2（applyResult 的谓词只含 status = 5）。仅用 status = 2 会把这两种情况误判为可回溯，直接违反「撤销不得回溯」。
• 不含失败分类：RefundFailureReasonIsDefinitive 的取值面向「尝试是否终结」，与「退款是否真正完成」正交；成功退款的 failure_reason 为空，按分类判定会把成功退款判为不可回溯。该函数保留但 MUST NOT 进入回溯准入。
• 不依赖独立完成事件键：原路与客户收款信息两种完成的区别已由 status 与 channel_refund_status 表达，status = 2 是唯一稳定终态。
• 备选（否决）：在渠道明确失败时回溯。被否决，因为 3/4/6 可重提并修改金额，按 (refund_id, original_commission_id) 幂等会使第二次成功退款无法补回溯，金额必然错误。
• 渠道明确失败后重提并最终成功：status 由 5/6 重新走到 2，此时才生成一次回溯，金额取最终成功金额。

2. 消费门禁与周期性补偿

• 消费端在准入不满足时返回可重试错误，交由既有 Outbox 重试；订单佣金未终态时同样返回可重试错误，不写明细、不置位。
• 既有补偿扫描 commissionDelivery.Recover 保留启动时执行，并新增周期性任务：@every 1m、asynq.MaxRetry(3)、asynq.Timeout(10m)、asynq.Unique(10m)、独立队列，形态与 TaskTypeRefundChannelRecovery 一致；新增任务类型常量与 QueueForTaskType 映射及其 Handler。
• 补偿扫描判据保持 status = 2 AND commission_deducted = false（不新增列条件），因为「撤销」与「无需回溯」都在第 3 条被收敛为已闭合并置位，扫描不会对它们空转。
• 备选（否决）：让扫描排除 anomaly_flag = 1。被否决——那样异常的退款单永远没有闭合事实，扫描与投递在每轮都会重复处理同一批记录。

3. 后处理闭合的三种结果

commission_deducted 的语义统一为「该退款单的佣金回溯后处理是否已闭合（含无需回溯与转人工）」，只在以下三种结果之一成立时置位，且置位使用 WHERE commission_deducted = false 条件保护：

结果	条件	资金	审计
已生成回溯	准入满足且存在可回溯佣金	插入明细、扣钱包、写负数流水	新动作码 refund.clawback_commission，资源含回溯明细
无需回溯	准入满足、原订单佣金已终态且确认无佣金	无	新动作码 refund.clawback_not_required
转人工不回溯	准入不满足且 anomaly_flag = 1	无	复用既有 refund.anomaly_flagged 语义

• 准入不满足且非异常（待审批、原路处理中、渠道明确失败）时返回可重试错误，不置位、不写审计，等待退款推进。

• 撤销发生在回溯已生成之后时，不自动冲销已落库的回溯事实（资金已实际发生），按异常转人工处理；回收走人工更正，不新增自动反向流水。

• 「原订单佣金已终态」的判据（两个条件同时成立）：

  1. 订单佣金流程已离开「待计算」（order.commission_status != 1）；
  2. 该订单不存在任何未终态佣金记录（tb_commission_record.status IN (1 已冻结, 2 解冻中, 99 待人工修正)）。

• 仅用条件 1 是错误判据：order.commission_status = 3（待人工处理）只表示「存在 99 记录」，而人工处置（shop_commission.ResolveCommissionRecord）把 99 改成已发放/已失效后不回写订单状态，订单会长期停留在 3。只看订单状态会把「待人工修正」误判为终态，进而在「无已发放佣金」时提前闭合为「无需回溯」并置位；此后投影早退 + 补偿扫描只扫 commission_deducted = false，该订单后续入账的佣金将永久不再回溯，违反本 Change 的 Spec「MUST NOT 提前判定为无需回溯」。

• 收敛条件（保证不会永久等待，依据全仓 tb_commission_record.status 写点实测）：该表的状态写点只有两类——

  • 创建：internal/service/commission_calculation/service.go:181/:241/:554 写入已发放 3，:220/:581 写入待人工修正 99；internal/service/recharge_order/service.go:418 写入已发放 3；
  • 更新：internal/service/commission_calculation/service.go:689-693（入账置 3）与 internal/service/shop_commission/service.go:751/:781（人工处置置 4 或置 3）。

  即当前代码从不写入 1（已冻结）或 2（解冻中），这两个值是仅供历史数据读取与名称映射的遗留枚举；把它们纳入未终态集合是防御性判断（历史遗留的 1/2 行确实不是已结算事实），而非新的等待来源。因此现实中的等待只可能由 99 引起，且 99 一旦被人工处置即收敛：处置为已发放(3) → 生成回溯；处置为已失效(4) → 确认无佣金可回溯并闭合。

• 该判据不满足时返回可重试错误（CodeServiceUnavailable），不写明细、不置位。

4. 金额计算：分母、分子、分摊与舍入

全程 int64 分，乘法使用 math/big 或等价的 128 位中间量，禁止浮点与溢出。

• 分母 D = 本次退款的冻结实收金额（退款行，缺失时回落该次审批尝试记录）。D <= 0 时记录可恢复失败：不落库、不改余额、不置位，MUST NOT 用订单标价或申请金额替代。
• 分子 N = 原路成功时取渠道明确成功金额，其余方式取审批退款金额。
• 稳定顺序固定为 original_commission_id ASC；该顺序决定补差落点，必须固定，否则同一输入可能得出不同分摊结果。
• 逐条基准 base_i = min( floor(amount_i × N / D), 剩余_i )；剩余_i = amount_i − 该原佣金已生成的回溯累计。
• 应回溯总额 T = min( floor(Σamount_i × N / D), Σ剩余_i )。
• 补差 T − Σbase_i 自稳定顺序末条起向前分摊，每条不超过该条 剩余_i；若最末条不足以吸收全部余差则继续向前一条分摊，直至余差用尽。
• 全额退款（N = D）时 base_i = min(amount_i, 剩余_i)，自然退化为按剩余可回溯余额回溯。
• 备选（否决）：按比例算出总额后平均分配。被否决——会产生与各原佣金金额不成比例的扣减，且无法在分制下复现。

5. 新表 tb_commission_clawback_record

不复用 tb_commission_record：负数语义与本表的可提现判定、结算与统计查询完全隔离，避免污染既有 status = 3 AND amount > 0 一类终态判定。

字段：refund_id、original_commission_id、order_id、shop_id、amount（负数）、withdrawable（固定不可提现）、status（= 5）、balance_after（回溯后佣金钱包实际余额，可负）、原佣金与退款关键快照（佣金来源、订单号、退款单号）、created_at。

• 唯一约束 (refund_id, original_commission_id) 是唯一权威幂等键。
• 索引：店铺 + 时间（列表与数据范围）、original_commission_id（反向关联）、order_id（订单维度核对）。
• 备选（否决）：复用 tb_commission_record 并加 original_commission_id / refund_id 列。被否决——列表、统计、终态判定与导出全部要重新审计负数的语义，且「已发放」「回溯」会被读侧到处区分，回归面远大于两表合并。
• 代价：读侧必须两表 UNION ALL 合并分页（见第 8 条）。

6. 幂等三层与投影

1. 第 1 层（权威、DB 兜底）：回溯明细唯一约束 (refund_id, original_commission_id)。唯一冲突即视为已生成，不重复扣款。
2. 第 2 层（事务内互斥）：佣金行 FOR UPDATE + 佣金钱包 version 乐观锁（沿用既有）。
3. 第 3 层（投影、非幂等键）：commission_deducted 仅供 Outbox 消费结果判据与补偿扫描使用，MUST NOT 参与逐条幂等判定；置位加 WHERE commission_deducted = false 保护（现有实现缺此保护）。

7. 加锁顺序、释放顺序与原子边界

同一事务内顺序固定：

锁 提现申请行 (shop_id, status = 待审核, ORDER BY id ASC)   FOR UPDATE
锁 尝试行                                                FOR UPDATE, released_at IS NULL
    → 幂等置 released_at；释放额 = Σ attempt.amount（无尝试记录的存量申请取申请金额）
锁 佣金钱包行                                            FOR UPDATE
    → 解冻 frozen_balance（先于扣款，约束要求）
    → 置申请为已拒绝 + processed_at + 拒绝原因
    → 释放额 > 0 时写正向流水与拒绝审计
插入 回溯明细（唯一约束兜底）
扣减 balance（允许为负）
写 commission_deduct 负数流水
写回溯审计

• 加锁顺序全库统一为申请行 → 尝试行 → 钱包行，钱包永远最后加锁，避免与提现终态消费者形成死锁环。
• 保留既有 collectPendingWithdrawalRejects / applyPendingWithdrawalRejects / appendWithdrawalRejectAudit，不重写。
• 任一步失败整体回滚：不释放提现、不写部分明细或部分流水，可靠事件保留重试。事务内 MUST NOT 持有不可回滚的外部 I/O（ENG-TX-001）。

8. 读侧最小面

• 列表支持 status 筛选透传（现有 DTO 与 service 均未透传，store 已支持）。
• 两表 UNION ALL 合并分页，筛选与数据范围在合并前各自应用。
• 排序与次序键：created_at DESC → id DESC → source ASC。两表自增 ID 空间相互独立，同一 created_at 下不同表的 id 只保证各自表内有序，因此 (created_at DESC, id DESC) 不是全序；必须再以 source ASC 作为末位次序键，才能在 created_at 与 id 完全相同的跨表记录上保证翻页不重不漏。
• 原佣金行返回 clawback_records 摘要；回溯行返回原始佣金标识、退款单号、负数金额、不可提现标识、回溯后余额、生成时间。
• 新增佣金明细详情接口，并同步可执行路由、cmd/api/docs.go 与 cmd/gendocs/main.go 装配；DTO 中文 description 与枚举名与 pkg/constants 一致（ENG-DTO-001）。
• 越权一律按既有佣金数据范围返回不存在或空结果，不泄露存在性。

9. 导出归属与粒度

• 本 Change 落地佣金明细导出场景：场景白名单、internal/exporter 注册、DTO oneof、DataSource 与列定义。
• 粒度为佣金记录：原佣金与回溯记录各占一行；入账后金额与回溯后余额取对应钱包变动提交后的实际余额，可为负；金额保持分，展示层转元不得改变负数或余额事实。
• 边界：佣金明细导出的粒度与列定义由本 Change 确定；add-export-time-filter-standards 只负责统一 start_time/end_time 与快照冻结。

10. 常量与审计

• 新增 CommissionStatusClawback = 5，GetCommissionRecordStatusName 增加「回溯」映射，并同步状态常量注释；tb_commission_record.status 无 CHECK 白名单，新增枚举值不需要改列约束。
• 新增回溯审计动作码 refund.clawback_commission 与 refund.clawback_not_required，主资源为退款单，并在 internal/infrastructure/audit/registry.go 注册。
• 旧 refund.invalidate_commission 保留常量与注册（历史审计仍可读），代码中不再有新调用点。

Risks / Trade-offs

• [两表合并分页复杂，易漏筛选或重复计数] → 合并前各自应用数据范围与筛选，统一排序键并显式以 source ASC 打破跨表 (created_at, id) 并列；在隔离库对翻页边界与总数做核对。
• [误用 status = 2 单条件会导致撤销退款被回溯] → 准入显式包含 anomaly_flag = 0，并以「撤销后不回溯」「原路在途不回溯」两个场景固定。
• [周期性补偿放大重复处理] → 幂等第 1 层由唯一约束兜底，第 3 层置位加条件保护；补偿只重投事件，不直接改资金。
• [math/big 中间量引入新代码路径] → 仅用于比例乘法，除法与求和保持 int64；用溢出边界用例固定。
• [存量已按旧语义处理的退款单与新语义并存] → 明确不回填；commission_deducted = true 的存量不进入补偿扫描，原佣金保持已失效是历史事实。
• [新导出场景未覆盖 AUG26-014 的时间筛选] → 列定义与粒度归本 Change，时间参数与快照冻结在 AUG26-014 落地；两者叠加不互相改变语义。

Migration Plan

新增成对迁移建表、唯一约束与索引；编号按 migrations/ 目录当前最大编号顺延，不预占、不修改既有迁移。回滚按 down 删除本 Change 新增的表与约束，不影响既有表与数据。

隔离库验证（ENG-TEST-001）：在维护者指定的 junhong_cmp_test PostgreSQL 与 Redis DB 6 上，以本地显式 DB_* 参数执行 ./scripts/migrate.sh 完成 up/down/up；仅创建与删除本 Change 自己的 fixture，不重置整库。验证覆盖全额与部分回溯、比例与补差、溢出行边界、累计不超过剩余、冻结实收非正可恢复失败、佣金未终态等待、终态确无佣金、原路在途不回溯、撤销不回溯、渠道失败重提后按最终金额回溯、重复消费、释放先于扣款与负余额不违约、原佣金不变、读侧合并分页与越权、导出负数余额。