huang
d977000a66
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m40s
- 归档 OpenSpec 变更到 archive 目录 - 创建 2 个新的主规范文件：commission-trigger 和 order-commission-snapshot - 实现订单佣金快照字段和支付自动触发 - 确保事务一致性，所有佣金操作在同一事务内完成 - 提取成本价计算为公共工具函数
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# order-commission-snapshot Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change fix-commission-calculation-trigger-and-snapshot. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: 订单创建时填充佣金快照字段
|
||
|
||
系统 SHALL 在订单创建时填充佣金计算所需的关键字段快照，确保后续佣金计算不受配置变更影响。
|
||
|
||
**快照字段**：
|
||
- `series_id`：套餐系列 ID
|
||
- `seller_shop_id`：售卖/收益归属店铺 ID
|
||
- `seller_cost_price`：卖家成本价（用于成本价差佣金计算）
|
||
|
||
**字段来源**：基于购买校验结果（`PurchaseValidationResult`）
|
||
- `series_id` ← `allocation.SeriesID`
|
||
- `seller_shop_id` ← `allocation.ShopID`
|
||
- `seller_cost_price` ← 根据 allocation 的基础返佣规则从订单金额推导
|
||
|
||
#### Scenario: 订单创建时写入佣金快照
|
||
|
||
- **WHEN** 用户购买套餐，订单创建成功，购买校验返回 `allocation` 数据
|
||
- **THEN** 订单表中 `series_id`、`seller_shop_id`、`seller_cost_price` 字段已正确填充
|
||
- **AND** 字段值来源于购买校验结果，而非订单提交参数
|
||
|
||
#### Scenario: 缺少 allocation 数据时的处理
|
||
|
||
- **WHEN** 订单创建时购买校验结果中缺少 `allocation` 数据
|
||
- **THEN** 系统记录警告日志，订单佣金快照字段保持 NULL 或默认值
|
||
- **AND** 订单 `commission_status` 标记为 `pending`（待计算），允许后续补偿
|
||
|
||
#### Scenario: 后续佣金计算使用快照字段
|
||
|
||
- **WHEN** 佣金计算任务执行时读取订单数据
|
||
- **THEN** 系统使用订单表中的快照字段（`series_id`、`seller_shop_id`、`seller_cost_price`）
|
||
- **AND** 不再实时查询套餐配置或返佣规则，避免配置变更影响历史订单
|
||
|
||
---
|
||
|
||
### Requirement: 成本价推导方法复用
|
||
|
||
系统 SHALL 提供统一的成本价推导方法，确保订单创建和佣金计算使用相同的计算口径。
|
||
|
||
**方法职责**：
|
||
- 输入：订单金额、allocation 数据（包含返佣规则）
|
||
- 输出：卖家成本价（seller_cost_price）
|
||
- 逻辑：与"成本价差佣金"计算保持一致
|
||
|
||
#### Scenario: 订单创建时调用成本价推导
|
||
|
||
- **WHEN** 订单创建服务填充 `seller_cost_price` 字段
|
||
- **THEN** 系统调用统一的成本价推导方法，基于订单金额和 allocation 数据计算
|
||
- **AND** 推导结果写入订单表 `seller_cost_price` 字段
|
||
|
||
#### Scenario: 佣金计算时复用相同逻辑
|
||
|
||
- **WHEN** 佣金计算服务执行成本价差计算
|
||
- **THEN** 系统使用订单快照中的 `seller_cost_price`（已在创建时推导）
|
||
- **AND** 避免重复推导，确保计算口径一致
|
||
|
||
---
|
||
|