# Capability: 店铺套餐系列分配管理

## Purpose

本 capability 定义代理如何为下级店铺分配套餐系列，以及平台如何为一级代理分配。分配时需要配置基础返佣和可选的梯度返佣。

## Requirements

### Requirement: 强充配置

系统 SHALL 在套餐系列分配中支持强充配置。仅累计充值触发时可选启用强充，首次充值触发时强充是必须的（无需配置）。

#### Scenario: 累计充值启用强充
- **WHEN** 创建系列分配，一次性佣金触发类型为累计充值，设置 enable_force_recharge = true，force_recharge_amount = 10000（100元）
- **THEN** 系统保存强充配置，下级客户每次充值/购买必须充值 100 元

#### Scenario: 累计充值不启用强充
- **WHEN** 创建系列分配，一次性佣金触发类型为累计充值，设置 enable_force_recharge = false
- **THEN** 系统保存配置，下级客户可以自由充值任意金额

#### Scenario: 首次充值无需设置强充
- **WHEN** 创建系列分配，一次性佣金触发类型为首次充值，阈值 10000（100元）
- **THEN** 系统使用阈值作为强充金额，无需单独配置 force_recharge_amount

#### Scenario: 强充金额为0表示使用阈值
- **WHEN** 创建系列分配，启用强充，force_recharge_amount = 0
- **THEN** 系统使用一次性佣金阈值作为强充金额

---

### Requirement: 为下级店铺分配套餐系列

系统 SHALL 允许代理为其直属下级店铺分配套餐系列。分配时 MUST 指定基础返佣配置（返佣模式和返佣值），MAY 启用一次性佣金和强充配置。分配者只能分配自己已被分配的套餐系列。

**API 接口 MUST 在请求和响应中包含强充配置字段**：
- `enable_force_recharge`：是否启用强充
- `force_recharge_amount`：强充金额（分，0 表示使用阈值）
- `force_recharge_trigger_type`：强充触发类型（1: 单次充值，2: 累计充值）

#### Scenario: 成功分配套餐系列
- **WHEN** 代理为直属下级店铺分配一个自己拥有的套餐系列，设置基础返佣为百分比200（20%）
- **THEN** 系统创建分配记录

#### Scenario: 分配时启用一次性佣金和强充
- **WHEN** 代理为下级分配系列，启用一次性佣金，触发类型为累计充值，阈值 100000（1000元），启用强充，强充金额 10000（100元）
- **THEN** 系统保存配置：enable_one_time_commission = true，trigger = "accumulated_recharge"，threshold = 100000，enable_force_recharge = true，force_recharge_amount = 10000

#### Scenario: API 请求包含强充配置字段
- **WHEN** 创建分配时，请求包含 enable_force_recharge = true，force_recharge_amount = 10000，force_recharge_trigger_type = 2
- **THEN** 系统接受并保存这些字段，响应中返回相同的配置

#### Scenario: API 响应包含强充配置字段
- **WHEN** 查询分配详情或列表
- **THEN** 响应 MUST 包含 enable_force_recharge、force_recharge_amount、force_recharge_trigger_type 字段

#### Scenario: 尝试分配未拥有的系列
- **WHEN** 代理尝试分配自己未被分配的套餐系列
- **THEN** 系统返回错误 "您没有该套餐系列的分配权限"

#### Scenario: 尝试分配给非直属下级
- **WHEN** 代理尝试分配给非直属下级店铺
- **THEN** 系统返回错误 "只能为直属下级分配套餐"

#### Scenario: 重复分配同一系列
- **WHEN** 代理尝试为同一下级店铺重复分配同一套餐系列
- **THEN** 系统返回错误 "该店铺已分配此套餐系列"

---

### Requirement: 查询套餐系列分配列表

系统 SHALL 提供分配列表查询，支持按下级店铺筛选、按套餐系列筛选、按状态筛选。**响应 MUST 包含强充配置字段**。

#### Scenario: 查询所有分配
- **WHEN** 代理查询分配列表，不带筛选条件
- **THEN** 系统返回该代理创建的所有分配记录，每条记录包含强充配置字段

#### Scenario: 按店铺筛选
- **WHEN** 代理指定下级店铺 ID 筛选
- **THEN** 系统只返回该店铺的分配记录，记录包含强充配置字段

#### Scenario: 响应包含强充配置
- **WHEN** 查询分配列表
- **THEN** 每条记录包含 enable_force_recharge、force_recharge_amount、force_recharge_trigger_type 字段

---

### Requirement: 更新套餐系列分配

系统 SHALL 允许代理更新分配的基础返佣配置、一次性佣金配置和强充配置。更新返佣配置时 MUST 创建新的配置版本。**API 请求 MUST 支持更新强充配置字段**。

#### Scenario: 更新基础返佣配置时创建新版本
- **WHEN** 代理将基础返佣从20%改为25%
- **THEN** 系统更新分配记录，并创建新配置版本

#### Scenario: 更新强充配置
- **WHEN** 代理将 enable_force_recharge 从 false 改为 true，设置 force_recharge_amount = 10000
- **THEN** 系统更新分配记录，后续下级客户需遵守新强充要求

#### Scenario: API 支持部分更新强充配置
- **WHEN** 更新请求只包含 enable_force_recharge = false，不包含其他强充字段
- **THEN** 系统更新 enable_force_recharge，其他强充字段保持不变

#### Scenario: 禁用强充
- **WHEN** 代理将 enable_force_recharge 从 true 改为 false
- **THEN** 系统更新分配记录，后续下级客户可以自由充值

#### Scenario: 更新不存在的分配
- **WHEN** 代理更新不存在的分配 ID
- **THEN** 系统返回 "分配记录不存在" 错误

---

### Requirement: 删除套餐系列分配

系统 SHALL 允许代理删除分配记录。如果有下级依赖此分配，MUST 禁止删除。

#### Scenario: 成功删除无依赖的分配
- **WHEN** 代理删除一个没有下级依赖的分配记录
- **THEN** 系统软删除该记录

#### Scenario: 尝试删除有下级依赖的分配
- **WHEN** 代理尝试删除一个已被下级使用的分配（下级基于此分配又分配给了更下级）
- **THEN** 系统返回错误 "存在下级依赖，无法删除"

---

### Requirement: 启用/禁用套餐系列分配

系统 SHALL 允许代理切换分配的启用状态。禁用后下级 MUST NOT 能使用该分配购买套餐。

#### Scenario: 禁用分配
- **WHEN** 代理将分配状态设为禁用
- **THEN** 系统更新状态，下级无法基于此分配购买套餐

#### Scenario: 启用分配
- **WHEN** 代理将禁用的分配设为启用
- **THEN** 系统更新状态，下级可以继续使用

---

### Requirement: 平台分配套餐系列

平台管理员 SHALL 能够为一级代理分配套餐系列，可配置强充要求。平台的成本价基准为 Package.suggested_cost_price。**API 接口 MUST 支持强充配置字段的输入和输出**。

#### Scenario: 平台为一级代理分配
- **WHEN** 平台管理员为一级代理分配套餐系列
- **THEN** 系统创建分配记录

#### Scenario: 平台配置强充要求
- **WHEN** 平台为一级代理分配系列，启用强充，force_recharge_amount = 10000
- **THEN** 系统保存强充配置，一级代理的客户需遵守强充要求

#### Scenario: API 请求和响应包含强充配置
- **WHEN** 平台创建或查询分配
- **THEN** 请求和响应都包含强充配置字段

---

## REMOVED Requirements

### Requirement: 梯度返佣配置

**❌ REMOVED** - 此 requirement 已废弃

**原内容**: 分配时 MAY 启用梯度返佣

**Reason**: 梯度返佣 (TierCommission) 功能与一次性梯度佣金 (OneTimeCommission.tiered) 功能重复，且梯度返佣未实现实际计算逻辑，仅保留基础返佣和一次性佣金两种机制。

**Migration**:
- 如果需要根据销售业绩给予额外奖励，请使用一次性佣金的梯度模式 (OneTimeCommissionConfig.type = "tiered")
- 一次性佣金支持按销售数量或销售金额设置多个梯度档位
- API 请求中删除 `enable_tier_commission` 和 `tier_config` 字段
- API 响应中不再包含 `enable_tier_commission` 字段

---

### Requirement: /shop-series-allocations 接口

**❌ REMOVED** - 此 requirement 已废弃

**Reason**: 已被 `/shop-series-grants` 完全替代。开发阶段干净重构，不保留兼容接口。

**删除范围**：
- `internal/handler/admin/shop_series_allocation.go`
- `internal/routes/shop_series_allocation.go`
- `internal/model/dto/shop_series_allocation.go`
- `internal/service/shop_series_allocation/`
- 从 `bootstrap/types.go`、`bootstrap/handlers.go`、`bootstrap/services.go`、`pkg/openapi/handlers.go`、`routes/admin.go` 移除引用

**保留**：`internal/store/postgres/shop_series_allocation_store.go`（被佣金计算、订单服务、Grant Service 使用）

---

### Requirement: /shop-package-allocations 接口

**❌ REMOVED** - 此 requirement 已废弃

**Reason**: 套餐分配已合并进 `/shop-series-grants` 的创建和套餐管理接口。开发阶段干净重构，不保留兼容接口。

**删除范围**：
- `internal/handler/admin/shop_package_allocation.go`
- `internal/routes/shop_package_allocation.go`
- `internal/model/dto/shop_package_allocation.go`
- `internal/service/shop_package_allocation/`
- 从 bootstrap、openapi/handlers、routes/admin 移除引用

**保留**：`internal/store/postgres/shop_package_allocation_store.go`（被多处使用）

---

### Requirement: 分配时配置 enable_one_time_commission 等字段

**❌ REMOVED** - 此 requirement 已废弃

**Reason**: `enable_one_time_commission`、`one_time_commission_trigger`、`one_time_commission_threshold` 三个字段从未被计算引擎读取，与 PackageSeries 的配置语义完全重复。

**Migration**：一次性佣金是否启用由 `PackageSeries.enable_one_time_commission` 控制；分配表中仅保留 `one_time_commission_amount`（固定模式天花板）、`commission_tiers_json`（梯度模式专属阶梯）和强充 3 个字段。
