huang
61155952a7
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m56s
- 新增数据库迁移：为 shop_package_allocation 表添加 shelf_status 字段 - 更新模型/DTO：ShopPackageAllocation 增加 ShelfStatus 字段及相关枚举 - 更新套餐分配 Service：支持上架/下架状态管理逻辑 - 更新套餐 Store/Service：根据 shelf_status 过滤可售套餐 - 更新购买验证 Service：引入上架状态校验逻辑 - 归档 OpenSpec 变更：2026-03-02-agent-allocation-shelf-status - 同步更新主规范文档：allocation-shelf-status、package-management、purchase-validation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
# Capability: 代理可售套餐查询
|
||
|
||
## Purpose
|
||
|
||
本 capability 定义代理用户如何通过统一的套餐管理接口查询可售套餐，系统如何自动过滤并返回代理专属字段（成本价、返佣信息等）。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 代理查询可售套餐列表
|
||
|
||
系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。**响应中的 `shelf_status` 字段 MUST 返回代理自己分配记录的值（`allocation.shelf_status`），而非套餐的全局值（`package.shelf_status`）。**
|
||
|
||
#### Scenario: 代理查询自动过滤为已分配套餐
|
||
- **WHEN** 代理用户调用 `GET /api/admin/packages`
|
||
- **THEN** 系统通过 JOIN `tb_shop_package_allocation` 自动过滤，只返回该代理被分配的套餐
|
||
|
||
#### Scenario: 平台用户查询返回所有套餐
|
||
- **WHEN** 平台用户调用 `GET /api/admin/packages`
|
||
- **THEN** 系统返回所有套餐（不应用代理权限过滤），shelf_status 返回 `tb_package.shelf_status`
|
||
|
||
#### 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: 代理查询时 shelf_status 返回分配记录的值
|
||
- **GIVEN** `tb_package.shelf_status=1`（平台上架），代理自己的 `allocation.shelf_status=2`（代理下架）
|
||
- **WHEN** 代理调用 `GET /api/admin/packages`
|
||
- **THEN** 响应中该套餐的 `shelf_status=2`（返回代理自己的状态）
|
||
|
||
#### Scenario: 代理查询时不按 package.shelf_status 过滤
|
||
- **GIVEN** `tb_package.shelf_status=2`（平台下架），但代理的 `allocation.shelf_status=1`（代理上架）
|
||
- **WHEN** 代理调用 `GET /api/admin/packages`
|
||
- **THEN** 该套餐仍出现在结果中（代理侧状态独立），shelf_status 返回 1
|
||
|
||
---
|
||
|
||
### Requirement: 代理查询可售套餐详情
|
||
|
||
系统 SHALL 通过统一的套餐详情接口（`/api/admin/packages/:id`）为代理用户返回套餐详细信息，包含完整的价格信息。**响应中的 `shelf_status` MUST 返回代理自己分配记录的值。**
|
||
|
||
#### Scenario: 代理查询已分配套餐详情
|
||
- **WHEN** 代理查询一个已被分配的套餐详情
|
||
- **THEN** 系统返回套餐完整信息，包含：cost_price（成本价）、建议售价、利润空间、价格来源，以及代理自己的 shelf_status
|
||
|
||
#### 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
|