huang
d977000a66
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m40s
- 归档 OpenSpec 变更到 archive 目录 - 创建 2 个新的主规范文件：commission-trigger 和 order-commission-snapshot - 实现订单佣金快照字段和支付自动触发 - 确保事务一致性，所有佣金操作在同一事务内完成 - 提取成本价计算为公共工具函数
40 lines
1.8 KiB
Markdown
40 lines
1.8 KiB
Markdown
# 佣金计算链路修复 - 设计
|
||
|
||
## 目标
|
||
|
||
1. 订单创建时就写入后续佣金计算所需的关键字段快照。
|
||
2. 订单支付成功后（首次成功支付）自动 enqueue 佣金计算异步任务。
|
||
3. 佣金计算具备可重复执行的幂等语义（订单佣金已计算则跳过）。
|
||
|
||
## 关键字段来源（你已确认）
|
||
|
||
以购买校验结果为准：
|
||
- `allocation`：来自 `PurchaseValidationResult.Allocation`
|
||
- `SeriesID`：`allocation.SeriesID`
|
||
- `SellerShopID`：`allocation.ShopID`（该分配记录对应的“售卖/收益归属店铺”）
|
||
- `SellerCostPrice`：根据 allocation 的基础返佣规则从订单金额推导（与成本价差计算一致的口径）
|
||
|
||
说明：这里的 SellerCostPrice 是为了支持“成本价差佣金”计算，作为链路上的稳定快照，避免后续配置变更影响历史订单。
|
||
|
||
## 支付成功后触发佣金计算
|
||
|
||
- 触发点：订单支付成功且为首次成功支付（由“订单激活幂等提案”提供门闸）。
|
||
- 触发动作：enqueue `commission:calculate`，payload 为 `order_id`。
|
||
- 入队失败策略：
|
||
- 不回滚支付成功（避免影响主链路）
|
||
- 保持 `commission_status = pending`，允许后续重试（例如后台补偿任务/人工触发/定时任务扫描）
|
||
|
||
## 事务一致性（可选）
|
||
|
||
当前佣金计算服务使用了 `Transaction` 包裹，但内部 Store 若未使用同一个 `tx`，一致性会被破坏。
|
||
|
||
推荐方案之一：
|
||
- 为各 Store 增加 `WithDB(tx)` 或在方法中接收 `db *gorm.DB` 参数，确保写入走同一个事务 `tx`。
|
||
|
||
## 验收标准
|
||
|
||
- 创建订单后，订单表中 `series_id/seller_shop_id/seller_cost_price` 等字段正确写入。
|
||
- 首次支付成功后，会 enqueue 佣金计算任务（可通过日志/测试验证）。
|
||
- 佣金任务重复执行不重复发放（已计算则跳过）。
|
||
|