# agent-retail-price Specification

## Purpose
TBD - created by archiving change client-api-data-model-fixes. Update Purpose after archive.
## Requirements
### Requirement: 分配零售价字段定义

系统 MUST 在 `ShopPackageAllocation` 新增 `retail_price bigint NOT NULL DEFAULT 0` 字段。

#### Scenario: 新字段存在且非空
- **WHEN** 执行分配记录建表或迁移
- **THEN** `retail_price` MUST 为非空整型字段，默认值为 `0`

---

### Requirement: 分配创建默认零售价规则

系统 MUST 在创建分配记录时将 `retail_price` 自动设置为对应 `Package.SuggestedRetailPrice`。

#### Scenario: 创建分配自动带出建议零售价
- **WHEN** 平台给代理创建套餐分配记录
- **THEN** 新记录的 `retail_price` MUST 等于该套餐的 `suggested_retail_price`

---

### Requirement: 零售价约束规则

系统 MUST 强制校验：`retail_price >= cost_price`。

#### Scenario: 零售价低于成本价
- **WHEN** 代理设置 `retail_price < cost_price`
- **THEN** 系统 MUST 拒绝保存并返回价格约束错误

### Requirement: 成本价分配锁定规则

当某分配存在下级分配记录时，系统 MUST 禁止修改该分配的 `cost_price`。

#### Scenario: 存在下级分配时修改成本价
- **WHEN** 上级分配记录已被继续分配到下级店铺
- **THEN** 系统 MUST 拒绝对该记录的 `cost_price` 修改

---

### Requirement: 代理零售价可调与存量迁移

系统 MUST 提供独立接口 `PATCH /api/admin/packages/:id/retail-price` 供代理修改自己分配记录的 `retail_price`（在约束范围内）；系统 MUST 对存量数据执行迁移：将 `retail_price` 批量更新为对应套餐的 `SuggestedRetailPrice`。

#### Scenario: 代理调整自己的零售价
- **WHEN** 代理修改自己分配记录的 `retail_price` 且满足价格约束
- **THEN** 系统 MUST 允许更新

#### Scenario: 存量数据回填零售价
- **WHEN** 执行本次数据迁移
- **THEN** 系统 MUST 将历史 `ShopPackageAllocation.retail_price` 批量更新为对应套餐的 `SuggestedRetailPrice`
