one-pipe-system/openspec/changes/update-package-management-api/specs/shop-package-allocation/spec.md

Shop Package Allocation Specification Delta

MODIFIED Requirements

Requirement: Shop Package Allocation Data Model

单套餐分配的数据模型SHALL新增系列关联字段和分配者信息字段，以支持更完整的分配关系追溯。

字段定义:

• id (number) - 分配ID
• package_id (number) - 套餐ID
• package_code (string) - 套餐编码
• package_name (string) - 套餐名称
• series_id (number) - 套餐系列ID
• series_name (string) - 套餐系列名称
• shop_id (number) - 被分配的店铺ID
• shop_name (string) - 被分配的店铺名称
• allocator_shop_id (number) - 分配者店铺ID，0表示平台分配
• allocator_shop_name (string) - 分配者店铺名称
• series_allocation_id (number, nullable) - 关联的系列分配ID（可选）
• cost_price (number) - 该代理的成本价（分）
• status (number) - 状态 (1:启用, 2:禁用)
• created_at (string) - 创建时间
• updated_at (string) - 更新时间

查询参数 (ShopPackageAllocationQueryParams):

• page (number, optional) - 页码
• page_size (number, optional) - 每页数量
• shop_id (number, optional) - 被分配的店铺ID
• package_id (number, optional) - 套餐ID
• series_allocation_id (number, optional) - 系列分配ID
• allocator_shop_id (number, optional) - 分配者店铺ID
• status (number, optional) - 状态

Scenario: 创建单套餐分配时包含系列信息

• GIVEN 平台管理员登录系统
• AND 系统中存在ID为10的套餐，该套餐属于系列ID为2，系列名称为"标准流量系列"
• AND 系统中存在ID为100的店铺
• WHEN 创建单套餐分配:
  • package_id: 10
  • shop_id: 100
  • cost_price: 15000
• THEN 系统SHALL创建单套餐分配记录
• AND 响应数据中自动填充 series_id 为 2
• AND 响应数据中自动填充 series_name 为 "标准流量系列"
• AND 响应数据中 allocator_shop_id 为 0（平台分配）

Scenario: 创建单套餐分配并关联系列分配

• GIVEN 系统中存在ID为20的系列分配，关联系列ID为2，店铺ID为100
• AND 系列2下存在套餐ID为10
• WHEN 为店铺100创建套餐10的分配
• THEN 系统MAY自动关联系列分配，设置 series_allocation_id 为 20

Scenario: 查询单套餐分配列表并显示完整关联信息

• GIVEN 系统中存在多个单套餐分配
• WHEN 查询单套餐分配列表 (GET /api/admin/shop-package-allocations)
• THEN 系统SHALL返回所有分配记录
• AND 每条记录包含 series_id, series_name, allocator_shop_id, allocator_shop_name
• AND 如果存在关联的系列分配，series_allocation_id 不为空

Scenario: 按系列分配ID筛选单套餐分配

• GIVEN 系统中存在多个单套餐分配，部分关联了系列分配ID为20的系列分配
• WHEN 使用查询参数 series_allocation_id=20
• THEN 系统SHALL返回所有 series_allocation_id 为 20 的单套餐分配记录

Scenario: 按分配者店铺ID筛选单套餐分配

• GIVEN 系统中存在多个单套餐分配
• WHEN 使用查询参数 allocator_shop_id=50
• THEN 系统SHALL返回所有由店铺ID为50的代理商创建的单套餐分配记录

Scenario: 获取单套餐分配详情时显示完整信息

• GIVEN 系统中存在ID为100的单套餐分配
• WHEN 请求获取该分配的详情 (GET /api/admin/shop-package-allocations/100)
• THEN 响应数据SHALL包含所有字段，包括:
  • series_id, series_name - 套餐所属系列信息
  • allocator_shop_id, allocator_shop_name - 分配者信息
  • series_allocation_id - 关联的系列分配ID（如果存在）

RENAMED Requirements

• FROM: allocation_id
• TO: series_allocation_id

说明: 将字段名从 allocation_id 重命名为 series_allocation_id，使其语义更加明确，表示关联的系列分配ID。

REMOVED Requirements

Requirement: Calculated Cost Price Field

旧版的 calculated_cost_price 字段已被移除。

Reason: 该字段仅用于参考，增加了数据模型的复杂性，且前端很少使用。成本价信息应直接使用 cost_price 字段。

Migration: 移除所有使用 calculated_cost_price 字段的代码。如果需要查看原始成本价信息，可以通过关联的系列分配或套餐系列获取。

ADDED Requirements

Requirement: Series Information in Package Allocation

系统SHALL在单套餐分配响应数据中包含套餐所属系列的ID和名称。

Scenario: 创建分配时自动关联系列信息

• GIVEN 系统中存在套餐，且该套餐属于某个系列
• WHEN 创建单套餐分配
• THEN 系统SHALL自动从套餐数据中获取 series_id 和 series_name
• AND 填充到分配响应数据中

Requirement: Allocator Information Tracking in Package Allocation

系统SHALL记录单套餐分配的创建者（分配者）信息，包括分配者店铺ID和名称。

Scenario: 平台创建的单套餐分配标记为平台分配

• GIVEN 平台管理员登录系统
• WHEN 创建单套餐分配
• THEN 系统SHALL自动设置 allocator_shop_id 为 0
• AND allocator_shop_name 为 "平台" 或相应的平台标识

Scenario: 代理商创建的单套餐分配记录代理商信息

• GIVEN 代理商A登录系统，shop_id为50，shop_name为"代理商A"
• WHEN 创建单套餐分配给下级代理
• THEN 系统SHALL自动设置 allocator_shop_id 为 50
• AND allocator_shop_name 为 "代理商A"

Requirement: Query by Allocator Shop ID

系统SHALL支持按分配者店铺ID筛选单套餐分配列表。

Scenario: 查看平台创建的所有分配

• GIVEN 系统中存在多个单套餐分配
• WHEN 使用查询参数 allocator_shop_id=0
• THEN 系统SHALL返回所有由平台创建的单套餐分配记录

Scenario: 查看特定代理商创建的所有分配

• GIVEN 系统中存在多个单套餐分配
• WHEN 使用查询参数 allocator_shop_id=50
• THEN 系统SHALL返回所有由店铺ID为50的代理商创建的单套餐分配记录

Requirement: Query by Series Allocation ID

系统SHALL支持按系列分配ID筛选单套餐分配列表，以便查找由特定系列分配派生的所有单套餐分配。

Scenario: 查找系列分配的所有派生单套餐分配

• GIVEN 系统中存在系列分配ID为20的系列分配
• AND 该系列分配下有多个单套餐分配
• WHEN 使用查询参数 series_allocation_id=20
• THEN 系统SHALL返回所有关联该系列分配的单套餐分配记录