# 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** 系统返回错误 "无权限操作该资源或资源不存在"