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

Package Series Management Specification Delta

MODIFIED Requirements

Requirement: Package Series Data Model

套餐系列的数据模型SHALL支持一次性佣金配置，包括固定佣金、梯度佣金、强制充值、时效类型等高级功能。

字段定义:

• id (number) - 系列ID
• series_code (string) - 系列编码，唯一标识
• series_name (string) - 系列名称
• description (string, optional) - 系列描述
• enable_one_time_commission (boolean) - 是否启用一次性佣金
• one_time_commission_config (SeriesOneTimeCommissionConfig, optional) - 一次性佣金配置对象
• status (number) - 状态 (1:启用, 2:禁用)
• created_at (string) - 创建时间
• updated_at (string) - 更新时间

一次性佣金配置结构 (SeriesOneTimeCommissionConfig):

• enable (boolean) - 是否启用一次性佣金
• commission_type (string) - 佣金类型: "fixed"(固定) | "tiered"(梯度)
• commission_amount (number, optional) - 固定佣金金额（分），commission_type=fixed时使用
• threshold (number) - 触发阈值（分）
• trigger_type (string) - 触发类型: "first_recharge"(首次充值) | "accumulated_recharge"(累计充值)
• tiers (OneTimeCommissionTier[], optional) - 梯度配置列表，commission_type=tiered时使用
• enable_force_recharge (boolean) - 是否启用强充
• force_amount (number, optional) - 强充金额（分）
• force_calc_type (string, optional) - 强充计算类型: "fixed"(固定) | "dynamic"(动态)
• validity_type (string) - 时效类型: "permanent"(永久) | "fixed_date"(固定日期) | "relative"(相对时长)
• validity_value (string, optional) - 时效值（日期字符串或月数）

梯度档位结构 (OneTimeCommissionTier):

• threshold (number) - 达标阈值
• dimension (string) - 统计维度: "sales_count"(销量) | "sales_amount"(销售额)
• amount (number) - 佣金金额（分）
• stat_scope (string, optional) - 统计范围: "self"(仅自己) | "self_and_sub"(自己+下级)

Scenario: 创建套餐系列并启用固定一次性佣金

• GIVEN 管理员登录系统
• WHEN 创建套餐系列时提供以下配置:
  • series_code: "SERIES001"
  • series_name: "标准流量系列"
  • enable_one_time_commission: true
  • one_time_commission_config:
    • enable: true
    • commission_type: "fixed"
    • commission_amount: 5000 (50元)
    • threshold: 10000 (100元)
    • trigger_type: "first_recharge"
    • validity_type: "permanent"
• THEN 系统SHALL创建套餐系列，并保存一次性佣金配置

Scenario: 创建套餐系列并启用梯度一次性佣金

• GIVEN 管理员登录系统
• WHEN 创建套餐系列时提供以下配置:
  • series_code: "SERIES002"
  • series_name: "高级流量系列"
  • enable_one_time_commission: true
  • one_time_commission_config:
    • enable: true
    • commission_type: "tiered"
    • threshold: 5000
    • trigger_type: "accumulated_recharge"
    • tiers: [ { threshold: 10, dimension: "sales_count", amount: 3000 }, { threshold: 50, dimension: "sales_count", amount: 8000 } ]
    • validity_type: "relative"
    • validity_value: "12" (12个月)
• THEN 系统SHALL创建套餐系列，并保存梯度佣金配置

Scenario: 查询启用一次性佣金的套餐系列

• GIVEN 系统中存在多个套餐系列，部分启用了一次性佣金
• WHEN 使用查询参数 enable_one_time_commission=true 查询列表
• THEN 系统SHALL返回所有启用一次性佣金的套餐系列

Scenario: 更新套餐系列的一次性佣金配置

• GIVEN 系统中存在ID为1的套餐系列
• WHEN 更新该系列时提供新的一次性佣金配置:
  • one_time_commission_config.commission_amount: 8000 (从5000更新到8000)
  • one_time_commission_config.enable_force_recharge: true
  • one_time_commission_config.force_amount: 20000
  • one_time_commission_config.force_calc_type: "fixed"
• THEN 系统SHALL更新套餐系列的一次性佣金配置，并返回更新后的数据

Scenario: 获取套餐系列详情时包含完整的一次性佣金配置

• GIVEN 系统中存在ID为1的套餐系列，已配置一次性佣金
• WHEN 请求获取该系列的详情 (GET /api/admin/package-series/1)
• THEN 系统SHALL返回包含完整 one_time_commission_config 对象的响应数据

ADDED Requirements

Requirement: One-Time Commission Query Filter

系统SHALL支持按一次性佣金启用状态筛选套餐系列列表。

Scenario: 按一次性佣金启用状态筛选

• GIVEN 系统中存在多个套餐系列
• WHEN 使用查询参数 enable_one_time_commission=true
• THEN 系统SHALL只返回 enable_one_time_commission 为 true 的套餐系列
• AND 分页信息正确反映筛选后的结果数量

Requirement: One-Time Commission Configuration Validation

系统SHALL验证一次性佣金配置的完整性和逻辑一致性。

Scenario: 固定佣金模式的验证

• GIVEN 管理员创建套餐系列
• WHEN commission_type 为 "fixed"
• THEN 系统SHALL要求 commission_amount 字段必填
• AND tiers 字段不应被使用

Scenario: 梯度佣金模式的验证

• GIVEN 管理员创建套餐系列
• WHEN commission_type 为 "tiered"
• THEN 系统SHALL要求 tiers 数组不为空
• AND 每个梯度档位的 threshold, dimension, amount 字段必填

Scenario: 强制充值配置的验证

• GIVEN 管理员创建套餐系列
• WHEN enable_force_recharge 为 true
• THEN 系统SHALL要求 force_amount 和 force_calc_type 字段必填

Scenario: 时效配置的验证

• GIVEN 管理员创建套餐系列
• WHEN validity_type 为 "fixed_date"
• THEN 系统SHALL要求 validity_value 字段必填，且格式为有效的日期字符串
• WHEN validity_type 为 "relative"
• THEN 系统SHALL要求 validity_value 字段必填，且为表示月数的数字字符串