one-pipe-system/openspec/changes/update-package-allocation-expiry-base-override/specs/shop-package-allocation/spec.md

ADDED Requirements

Requirement: Package Allocation Expiry Base Override Contract

The shop package allocation contract SHALL support an explicit expiry_base_override when creating or updating an allocation. The allowed request values MUST be null, from_purchase, and from_realname.

Scenario: Create allocation following the package default

• GIVEN 用户在套餐授权/分配弹框选择“跟随套餐默认”
• WHEN 用户创建店铺套餐分配
• THEN 系统 MUST call POST /api/admin/shop-package-allocations
• AND 请求 MUST explicitly contain expiry_base_override: null
• AND 系统 MUST NOT omit expiry_base_override to represent following the default

Scenario: Create allocation with purchase activation override

• GIVEN 用户在套餐授权/分配弹框选择“购买即生效”
• WHEN 用户创建店铺套餐分配
• THEN 请求 MUST contain expiry_base_override: "from_purchase"

Scenario: Create allocation with realname activation override

• GIVEN 用户在套餐授权/分配弹框选择“实名即生效”
• WHEN 用户创建店铺套餐分配
• THEN 请求 MUST contain expiry_base_override: "from_realname"

Requirement: Package Allocation Expiry Base Update

The system SHALL update an existing package allocation's expiry-base override through PATCH /api/admin/shop-package-allocations/{id}/expiry-base with a body containing expiry_base_override.

Scenario: Update allocation expiry base override

• GIVEN 用户正在编辑已分配套餐的生效条件
• WHEN 用户选择“购买即生效”或“实名即生效”并保存
• THEN 系统 MUST call PATCH /api/admin/shop-package-allocations/{id}/expiry-base
• AND 请求体 MUST contain the selected expiry_base_override

Scenario: Restore allocation to package default

• GIVEN 用户正在编辑已分配套餐的生效条件
• WHEN 用户选择“跟随套餐默认”并保存
• THEN 请求体 MUST explicitly contain expiry_base_override: null

Requirement: Package Allocation Expiry Base Resolution Response

The package allocation response SHALL provide default_expiry_base, expiry_base_override, and effective_expiry_base, together with their corresponding Chinese name fields. The frontend MUST render the returned effective value and name without calculating it from other fields.

Scenario: Display distinct expiry base values

• WHEN 前端加载或更新店铺套餐分配记录
• THEN 前端类型 MUST support default_expiry_base、expiry_base_override、effective_expiry_base
• AND 前端类型 MUST support the corresponding Chinese name fields
• AND 页面 MUST distinguish the default value, override value, and effective value

Scenario: Use backend effective expiry base

• GIVEN 分配响应同时返回默认值和覆盖值
• WHEN 页面展示最终生效条件
• THEN 页面 MUST display the backend returned effective_expiry_base_name
• AND 前端 MUST NOT calculate or replace the effective value from the default value and override value

Requirement: Package Allocation Expiry Base Applies Prospectively

The package allocation expiry-base override SHALL apply only to future new orders. The allocation creation and editing UI MUST inform the user that purchased packages are unaffected.

Scenario: Inform user before changing allocation expiry base

• WHEN 用户在已分配套餐编辑弹框查看或修改生效条件
• THEN 页面 MUST display 仅影响后续新订单，不影响已购买套餐

Scenario: Preserve purchased package behavior

• WHEN 用户创建、更新或恢复套餐分配的生效条件
• THEN 前端 MUST NOT attempt to update existing purchased packages or historical orders