5.1 KiB
package-lifecycle 当前行为
Purpose
描述套餐状态流转与批量操作追踪的当前行为。
Requirements
Requirement: 套餐状态流转
系统 SHALL 按当前套餐和套餐使用状态控制上架、订购、激活、失效与到期处理。
Scenario: 套餐状态流转
- GIVEN 套餐或使用记录处于允许的前置状态
- WHEN 执行状态操作
- THEN 仅发生一次允许的状态变化；不满足前置状态时返回业务错误
Requirement: 批量操作可追踪
系统 SHALL 为同步批量分配和调价直接返回处理结果；对异步批量订购返回任务标识并提供状态查询。
Scenario: 批量操作可追踪
- GIVEN 操作者提交非空且有权处理的资源集合
- WHEN 创建批量操作
- THEN 同步操作直接返回结果；异步订购返回任务标识且可查询处理状态
Requirement: 授权页面禁止重复选择套餐
系统 SHALL 使代理系列授权页面能够区分目标店铺已授权和未授权套餐；已授权套餐 MUST 以不可新增的状态返回，首次创建系列授权和既有系列新增套餐均适用。
Scenario: 首次创建前查询候选套餐
- WHEN 操作者选择目标店铺和套餐系列以创建系列授权
- THEN 系统返回可用于选择的候选套餐及其授权状态，前端可阻止选择已授权套餐
Scenario: 既有授权新增套餐前查询候选套餐
- WHEN 操作者为已有系列授权添加套餐
- THEN 系统返回同一店铺和系列的候选套餐及其授权状态，且不改变现有套餐管理提交接口的调价和删除语义
Requirement: 套餐使用记录价格快照
系统 SHALL 在创建套餐使用记录时分别快照套餐成本价与零售价：paid_amount（成本价）SHALL 取订单 seller_cost_price（销售成本价，即卖家店铺向平台结算的成本），retail_amount（零售价）SHALL 取订单 total_amount（零售总价）。成本价与实付金额在个人客户场景下不相等时，paid_amount MUST 使用成本价而非实付金额。
Scenario: 个人客户购买时快照成本价与零售价
- WHEN 个人客户为资产购买套餐，店铺成本价 10900 分，零售价 15900 分，客户实付 15900 分
- THEN 创建的套餐使用记录
paid_amount = 10900，retail_amount = 15900
Scenario: 代理钱包自购时快照成本价与零售价
- WHEN 代理以钱包支付为自有资产购买套餐，成本价 7000 分，零售价 9900 分
- THEN 创建的套餐使用记录
paid_amount = 7000，retail_amount = 9900
Scenario: 赠送套餐时快照零成本价与零售价
- WHEN 平台赠送套餐，零售价 9900 分，成本价 0 分
- THEN 创建的套餐使用记录
paid_amount = 0，retail_amount = 9900
可达操作索引
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
套餐管理
GET /api/admin/packages（套餐列表）；POST /api/admin/packages（创建套餐）；DELETE /api/admin/packages/{id}（删除套餐）；GET /api/admin/packages/{id}（获取套餐详情）；PUT /api/admin/packages/{id}（更新套餐）；PATCH /api/admin/packages/{id}/retail-price（修改零售价（代理））；PATCH /api/admin/packages/{id}/shelf（更新套餐上架状态）；PATCH /api/admin/packages/{id}/status（更新套餐状态）。
套餐系列管理
GET /api/admin/package-series（套餐系列列表）；POST /api/admin/package-series（创建套餐系列）；DELETE /api/admin/package-series/{id}（删除套餐系列）；GET /api/admin/package-series/{id}（获取套餐系列详情）；PUT /api/admin/package-series/{id}（更新套餐系列）；PATCH /api/admin/package-series/{id}/status（更新套餐系列状态）。
套餐使用记录
GET /api/admin/package-usage/{id}/daily-records（获取套餐流量详单）。
代理系列授权
GET /api/admin/shop-series-grants（查询代理系列授权列表）；GET /api/admin/shop-series-grants/package-options（查询代理系列授权套餐候选项）；POST /api/admin/shop-series-grants（创建代理系列授权）；DELETE /api/admin/shop-series-grants/{id}（删除代理系列授权）；GET /api/admin/shop-series-grants/{id}（查询代理系列授权详情）；PUT /api/admin/shop-series-grants/{id}（更新代理系列授权）；PUT /api/admin/shop-series-grants/{id}/packages（管理授权套餐，支持新增、更新和删除）。
批量套餐分配
PATCH /api/admin/shop-package-allocations/{id}/expiry-base（修改套餐分配生效条件覆盖）；POST /api/admin/shop-package-batch-allocations（批量分配套餐）。
批量套餐调价
POST /api/admin/shop-package-batch-pricing（批量调价）。
批量订购套餐
GET /api/admin/asset-package-batch-orders（查询资产套餐批量订购任务列表）；POST /api/admin/asset-package-batch-orders（创建资产套餐批量订购任务）；GET /api/admin/asset-package-batch-orders/{id}（查询资产套餐批量订购任务详情）。