# Capability: 代理可售套餐查询

## Purpose

本 capability 定义代理用户如何通过统一的套餐管理接口查询可售套餐，系统如何自动过滤并返回代理专属字段（成本价、返佣信息等）。

## Requirements

### Requirement: 代理查询可售套餐列表

系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。

#### Scenario: 代理查询自动过滤为已分配套餐
- **WHEN** 代理用户调用 `GET /api/admin/packages`
- **THEN** 系统通过 JOIN `tb_shop_package_allocation` 自动过滤，只返回该代理被分配的套餐

#### Scenario: 平台用户查询返回所有套餐
- **WHEN** 平台用户调用 `GET /api/admin/packages`
- **THEN** 系统返回所有套餐（不应用代理权限过滤）

#### Scenario: 响应包含代理专属字段
- **WHEN** 代理用户查询套餐列表
- **THEN** 每个套餐包含：cost_price（成本价）、profit_margin（利润空间）、current_commission_rate（当前返佣比例）

#### Scenario: 响应包含梯度返佣信息
- **WHEN** 代理用户查询套餐列表，且该系列启用了梯度返佣
- **THEN** 响应包含 tier_info：enabled、current_sales（本周期销量）、current_tier_id（当前档位）、next_threshold（下一档阈值）、next_rate（下一档返佣比例）

#### Scenario: 按系列筛选
- **WHEN** 代理指定套餐系列 ID 筛选
- **THEN** 系统只返回该系列下已分配的套餐

#### Scenario: 只返回启用且上架的套餐
- **WHEN** 代理查询可售套餐
- **THEN** 系统只返回 status=1（启用）且 shelf_status=1（上架）的套餐

---

### Requirement: 代理查询可售套餐详情

系统 SHALL 通过统一的套餐详情接口（`/api/admin/packages/:id`）为代理用户返回套餐详细信息，包含完整的价格信息。

#### Scenario: 代理查询已分配套餐详情
- **WHEN** 代理查询一个已被分配的套餐详情
- **THEN** 系统返回套餐完整信息，包含：成本价、建议售价、利润空间、价格来源（系列分配）

#### Scenario: 代理查询未分配的套餐
- **WHEN** 代理查询一个未被分配的套餐详情
- **THEN** 系统返回 404 或权限错误（数据权限过滤生效）

---

### Requirement: 删除独立的 my-packages 接口

系统 SHALL 删除以下独立接口及相关代码：
- `GET /api/admin/my-packages`
- `GET /api/admin/my-packages/:id`
- `GET /api/admin/my-series-allocations`

功能 MUST 通过统一的 `/api/admin/packages` 接口实现，依赖数据权限自动过滤机制。

#### Scenario: 调用已删除的接口返回404
- **WHEN** 代理调用 `GET /api/admin/my-packages`
- **THEN** 系统返回 404 Not Found