# 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** 避免重复推导，确保计算口径一致

---