one-pipe-system/openspec/changes/update-series-grant-package-contract/design.md

Context

代理系列授权详情返回完整的 packages[]，套餐列表接口返回可选套餐候选。前端创建授权时需要从候选套餐中选择初始套餐，详情和套餐管理页面则需要同时展示候选套餐信息与已授权状态。

Goals / Non-Goals

• Goals:
  • 以 package_id 为唯一键合并套餐候选和授权详情。
  • 在创建前校验初始套餐数量为 1～100 且不重复。
  • 使用 remove=true 表达后续删除，保持接口响应结构不变。
• Non-Goals:
  • 不修改后端接口路径或响应字段结构。
  • 不在前端复制后端的成本价、生效条件或套餐状态计算规则。
  • 不新增独立的套餐删除 API 调用。

Decisions

• 套餐候选状态以 package_id 合并：详情返回的套餐标记为已授权，候选列表中不存在于详情的套餐标记为未授权。
• 创建请求始终携带 packages，数量范围为 1～100；每个 package_id 只能出现一次。
• 后续新增或调价沿用 PUT /api/admin/shop-series-grants/{id}/packages，删除项只提交 { package_id, remove: true }。
• 成功响应直接按后端返回的完整授权详情刷新页面，不根据请求内容自行拼装最终响应。

Risks / Trade-offs

• 套餐候选接口分页或搜索结果可能不包含已授权套餐，合并时必须保留详情中的已授权项，避免误显示为未授权。
• 用户一次选择超过 100 个套餐时前端应提前阻止提交，同时仍依赖后端校验作为最终约束。

Migration Plan

1. 更新类型和 API 请求约束。
2. 更新创建页、授权详情页和套餐列表页的候选合并及套餐操作逻辑。
3. 使用接口响应重新加载授权详情，验证创建、调价、删除和空候选场景。

Open Questions

• 套餐候选接口的分页大小是否允许一次返回全部候选；若不允许，页面需要继续使用远程搜索加载候选。