# Capability: 分配配置版本管理

## Purpose

本 capability 定义如何管理套餐系列分配的返佣配置版本，确保订单创建时锁定配置，支持配置历史查询和审计。

## Requirements

### Requirement: 返佣配置变更时创建新版本

系统 SHALL 在代理修改套餐系列分配的返佣配置时，创建新的配置版本记录。旧版本 MUST 被标记为失效（设置 effective_to 时间戳），新版本 MUST 记录生效时间（effective_from）。

#### Scenario: 修改基础返佣配置时创建新版本
- **WHEN** 代理将基础返佣从20%修改为25%
- **THEN** 系统失效当前配置版本，创建新版本（version + 1）

#### Scenario: 修改梯度返佣开关时创建新版本
- **WHEN** 代理启用或禁用梯度返佣
- **THEN** 系统失效当前配置版本，创建新版本

#### Scenario: 仅修改非配置字段时不创建新版本
- **WHEN** 代理修改分配的状态（启用/禁用），但不修改返佣配置
- **THEN** 系统不创建新配置版本

#### Scenario: 新版本记录正确的生效时间
- **WHEN** 代理在2026-01-28 10:00:00修改返佣配置
- **THEN** 新版本的 effective_from 为 2026-01-28 10:00:00

#### Scenario: 旧版本记录正确的失效时间
- **WHEN** 代理在2026-01-28 10:00:00修改返佣配置
- **THEN** 旧版本的 effective_to 为 2026-01-28 10:00:00

---

### Requirement: 订单创建时锁定配置版本

系统 SHALL 在创建充值订单时，查询当前生效的配置版本并锁定到订单。订单 MUST 记录配置版本ID和配置快照（返佣模式、返佣值）。

#### Scenario: 订单创建时查询当前生效配置
- **WHEN** 下级客户在2026-01-28 10:30:00发起充值
- **THEN** 系统查询2026-01-28 10:30:00时生效的配置版本（effective_from <= 10:30:00 AND effective_to IS NULL）

#### Scenario: 订单锁定配置版本ID
- **WHEN** 订单创建时，查询到配置版本ID为123
- **THEN** 订单记录 allocation_config_id = 123

#### Scenario: 订单记录配置快照
- **WHEN** 订单创建时，配置为百分比200（20%）
- **THEN** 订单记录 locked_commission_mode = "percent", locked_commission_value = 200

#### Scenario: 配置变更后订单使用锁定的配置
- **WHEN** 订单创建后，代理修改了返佣配置
- **THEN** 订单仍然按照锁定的配置计算返佣

---

### Requirement: 查询历史配置版本

系统 SHALL 允许代理查询指定分配的所有历史配置版本，按生效时间倒序排列。

#### Scenario: 查询分配的配置版本历史
- **WHEN** 代理查询分配ID为123的配置版本历史
- **THEN** 系统返回该分配的所有版本记录，最新版本在最前

#### Scenario: 历史版本包含完整配置信息
- **WHEN** 查询历史配置版本
- **THEN** 每个版本包含：版本号、返佣模式、返佣值、梯度开关、生效时间、失效时间