feat: 新增代理分配套餐上架状态（shelf_status）功能

- 新增数据库迁移：为 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>

openspec/specs/agent-available-packages/spec.md

@@ -8,7 +8,7 @@
 
 ### Requirement: 代理查询可售套餐列表
 
-系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。
+系统 SHALL 通过统一的套餐列表接口（`/api/admin/packages`）为代理用户自动过滤可售套餐。代理用户查询时，系统 MUST 只返回被分配的套餐，响应 MUST 包含成本价、利润空间、返佣信息等代理专属字段。**响应中的 `shelf_status` 字段 MUST 返回代理自己分配记录的值（`allocation.shelf_status`），而非套餐的全局值（`package.shelf_status`）。**
 
 #### Scenario: 代理查询自动过滤为已分配套餐
 - **WHEN** 代理用户调用 `GET /api/admin/packages`
@@ -16,7 +16,7 @@
 
 #### Scenario: 平台用户查询返回所有套餐
 - **WHEN** 平台用户调用 `GET /api/admin/packages`
-- **THEN** 系统返回所有套餐（不应用代理权限过滤）
+- **THEN** 系统返回所有套餐（不应用代理权限过滤），shelf_status 返回 `tb_package.shelf_status`
 
 #### Scenario: 响应包含代理专属字段
 - **WHEN** 代理用户查询套餐列表
@@ -30,19 +30,25 @@
 - **WHEN** 代理指定套餐系列 ID 筛选
 - **THEN** 系统只返回该系列下已分配的套餐
 
-#### Scenario: 只返回启用且上架的套餐
-- **WHEN** 代理查询可售套餐
-- **THEN** 系统只返回 status=1（启用）且 shelf_status=1（上架）的套餐
+#### 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`）为代理用户返回套餐详细信息，包含完整的价格信息。
+系统 SHALL 通过统一的套餐详情接口（`/api/admin/packages/:id`）为代理用户返回套餐详细信息，包含完整的价格信息。**响应中的 `shelf_status` MUST 返回代理自己分配记录的值。**
 
 #### Scenario: 代理查询已分配套餐详情
 - **WHEN** 代理查询一个已被分配的套餐详情
-- **THEN** 系统返回套餐完整信息，包含：成本价、建议售价、利润空间、价格来源（系列分配）
+- **THEN** 系统返回套餐完整信息，包含：cost_price（成本价）、建议售价、利润空间、价格来源，以及代理自己的 shelf_status
 
 #### Scenario: 代理查询未分配的套餐
 - **WHEN** 代理查询一个未被分配的套餐详情

openspec/specs/allocation-shelf-status/spec.md

@@ -0,0 +1,58 @@
+# Capability: 分配记录独立上下架
+
+## Purpose
+
+本 capability 定义代理对自己分配到的套餐的独立上下架能力。代理可以独立控制自己客户侧的套餐可见性，互不影响。同时约束分配记录 status 修改的所有者校验规则。
+
+## Requirements
+
+### Requirement: 分配记录独立上下架
+
+系统 SHALL 在 `tb_shop_package_allocation` 表维护 `shelf_status` 字段（1-上架, 2-下架），允许代理独立控制自己分配到的套餐在客户侧的可见性，不影响其他代理和平台的同一套餐状态。
+
+#### Scenario: 新建分配记录默认上架
+- **WHEN** 平台或上级代理为某店铺创建套餐分配记录
+- **THEN** `allocation.shelf_status` 默认为 1（上架）
+
+#### Scenario: 代理下架自己的套餐
+- **GIVEN** 代理A拥有套餐P的分配记录，shelf_status=1
+- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`，传入 shelf_status=2
+- **THEN** 系统更新代理A的 `allocation.shelf_status=2`，套餐P在代理A的客户侧不可见
+- **AND** 代理B的同一套餐分配记录 shelf_status 不受影响
+- **AND** `tb_package.shelf_status` 不受影响
+
+#### Scenario: 代理上架自己的套餐
+- **GIVEN** 代理A的分配记录 shelf_status=2
+- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`，传入 shelf_status=1
+- **THEN** 系统更新代理A的 `allocation.shelf_status=1`
+
+#### Scenario: 代理上架已被全局禁用的套餐
+- **GIVEN** `tb_package.status=2`（套餐全局禁用），代理A的 allocation.shelf_status=2
+- **WHEN** 代理A尝试将 shelf_status 设置为1（上架）
+- **THEN** 系统返回错误 "套餐已禁用，无法上架"
+
+#### Scenario: 调用者无分配记录时无法操作
+- **GIVEN** 代理A没有套餐P的分配记录
+- **WHEN** 代理A调用 `PATCH /api/admin/packages/:id/shelf`（套餐ID为P）
+- **THEN** 系统返回错误 "该套餐未分配给您，无法操作上下架"
+
+---
+
+### Requirement: 分配记录 status 修改需所有者校验
+
+系统 MUST 验证调用者是分配记录的创建者（allocator），才允许修改该记录的 `status`（启用/禁用）。
+
+#### Scenario: 平台用户修改任意分配记录的 status
+- **GIVEN** 平台用户调用 `PUT /api/admin/shop-package-allocations/:id/status`
+- **WHEN** 分配记录存在
+- **THEN** 允许修改，不限制 allocator
+
+#### Scenario: 代理修改自己创建的分配记录的 status
+- **GIVEN** 代理A创建了"代理A→代理B"的分配记录（allocator_shop_id = A的shop_id）
+- **WHEN** 代理A调用修改该记录的 status
+- **THEN** 允许修改
+
+#### Scenario: 代理修改别人分配给自己的记录的 status
+- **GIVEN** 平台或代理A创建了"→代理B"的分配记录（allocator_shop_id != B的shop_id）
+- **WHEN** 代理B调用修改该记录的 status
+- **THEN** 系统返回错误 "无权限操作该资源或资源不存在"

openspec/specs/package-management/spec.md

@@ -197,19 +197,39 @@
 
 ### Requirement: 上架/下架套餐
 
-系统 SHALL 允许管理员切换套餐的上架状态。只有启用状态的套餐才能上架。
+系统 SHALL 通过 `PATCH /api/admin/packages/:id/shelf` 接口允许不同角色切换套餐上下架状态。**操作目标因调用者角色而不同**：平台/超管修改 `tb_package.shelf_status`（全局状态），代理修改自己的 `tb_shop_package_allocation.shelf_status`（代理独立状态）。只有启用状态的套餐才能上架。
 
-#### Scenario: 上架启用的套餐
-- **WHEN** 管理员将启用且下架的套餐设置为上架
-- **THEN** 系统更新上架状态为上架(1)
+#### Scenario: 平台管理员上架启用的套餐
+- **WHEN** 平台/超管将启用且下架的套餐设置为上架
+- **THEN** 系统更新 `tb_package.shelf_status=1`
 
-#### Scenario: 尝试上架禁用的套餐
-- **WHEN** 管理员尝试上架一个禁用的套餐
+#### Scenario: 平台管理员尝试上架禁用的套餐
+- **WHEN** 平台/超管尝试上架一个 status=2（禁用）的套餐
 - **THEN** 系统返回错误 "禁用的套餐不能上架，请先启用"
 
-#### Scenario: 下架套餐
-- **WHEN** 管理员将上架的套餐设置为下架
-- **THEN** 系统更新上架状态为下架(2)
+#### Scenario: 平台管理员下架套餐
+- **WHEN** 平台/超管将上架的套餐设置为下架
+- **THEN** 系统更新 `tb_package.shelf_status=2`，只影响平台自营渠道
+
+#### Scenario: 代理上架自己分配的套餐
+- **GIVEN** 代理拥有该套餐的分配记录，且 `tb_package.status=1`（启用）
+- **WHEN** 代理调用接口设置 shelf_status=1
+- **THEN** 系统更新该代理的 `allocation.shelf_status=1`，不修改 `tb_package.shelf_status`
+
+#### Scenario: 代理下架自己分配的套餐
+- **GIVEN** 代理拥有该套餐的分配记录，allocation.shelf_status=1
+- **WHEN** 代理调用接口设置 shelf_status=2
+- **THEN** 系统更新该代理的 `allocation.shelf_status=2`，不影响其他代理
+
+#### Scenario: 代理尝试上架全局禁用的套餐
+- **GIVEN** `tb_package.status=2`（禁用）
+- **WHEN** 代理尝试将 shelf_status 设置为1
+- **THEN** 系统返回错误 "套餐已禁用，无法上架"
+
+#### Scenario: 代理操作未分配的套餐
+- **GIVEN** 代理没有该套餐的分配记录
+- **WHEN** 代理调用接口操作该套餐的上下架
+- **THEN** 系统返回错误 "该套餐未分配给您，无法操作上下架"
 
 #### Scenario: 状态未变化
 - **WHEN** 管理员设置的上架状态与当前状态相同

openspec/specs/package-purchase-validation/spec.md

@@ -24,18 +24,36 @@
 
 ### Requirement: 验证套餐状态
 
-创建订单前系统 MUST 验证套餐处于可购买状态。
+创建订单前系统 MUST 验证套餐处于可购买状态。**校验逻辑因购买场景而不同**：通过代理渠道购买时检查代理分配记录的 shelf_status，通过平台自营渠道购买时检查套餐全局 shelf_status。`Package.status`（启用/禁用）为全局开关，任何场景下都必须检查。
 
-#### Scenario: 套餐启用且上架
-- **WHEN** 套餐 status=1 且 shelf_status=1
-- **THEN** 验证通过
+#### Scenario: 代理渠道 - 套餐启用且代理上架
+- **GIVEN** `Package.status=1`（启用），卖家代理的 `allocation.shelf_status=1`（上架）
+- **WHEN** 客户通过该代理下单购买套餐
+- **THEN** 套餐状态校验通过
 
-#### Scenario: 套餐已禁用
-- **WHEN** 套餐 status=2
+#### Scenario: 代理渠道 - 套餐已禁用
+- **GIVEN** `Package.status=2`（禁用）
+- **WHEN** 客户通过任意代理下单购买套餐
 - **THEN** 验证失败，返回 "套餐已禁用"
 
-#### Scenario: 套餐已下架
-- **WHEN** 套餐 shelf_status=2
+#### Scenario: 代理渠道 - 代理已下架套餐
+- **GIVEN** `Package.status=1`（启用），卖家代理的 `allocation.shelf_status=2`（代理下架）
+- **WHEN** 客户通过该代理下单购买套餐
+- **THEN** 验证失败，返回 "套餐已下架"
+
+#### Scenario: 代理渠道 - 平台下架不影响代理销售
+- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=2`（平台下架），卖家代理的 `allocation.shelf_status=1`（代理上架）
+- **WHEN** 客户通过该代理下单购买套餐
+- **THEN** 套餐状态校验通过（平台 shelf_status 不参与代理渠道校验）
+
+#### Scenario: 平台自营渠道 - 套餐启用且平台上架
+- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=1`（平台上架）
+- **WHEN** 客户通过平台自营渠道下单购买套餐
+- **THEN** 套餐状态校验通过
+
+#### Scenario: 平台自营渠道 - 套餐已下架
+- **GIVEN** `Package.status=1`（启用），`Package.shelf_status=2`（平台下架）
+- **WHEN** 客户通过平台自营渠道下单购买套餐
 - **THEN** 验证失败，返回 "套餐已下架"
 
 ---