one-pipe-system/openspec/changes/update-batch-series-binding-contract/proposal.md

Change: 更新批量套餐系列绑定接口契约

Why

当前批量设置套餐系列的两个接口仍然主要按“显式已选列表”思路使用：

• PATCH /api/admin/devices/series-binding
• PATCH /api/admin/iot-cards/series-binding

但最新业务要求这两个接口的使用方式需要尽量对齐现有“批量分配”流程，支持按列表、范围、筛选条件三种方式选择目标资产，而不是只能依赖表格勾选后的 ID/ICCID 列表。

如果接口契约不统一，前端无法复用批量分配/批量回收的选择模型，设备管理和单卡管理也会继续保留两套不同的批量操作交互与参数拼装逻辑。

What Changes

• 为设备批量套餐系列绑定接口补充与批量操作一致的目标选择模型：
  • 支持 selection_type=list|range|filter
  • 支持 device_ids、virtual_no_start / virtual_no_end、以及设备筛选条件三类入参
  • 在设备筛选条件中的“店铺名称”选择器复用 GET /api/admin/shops/cascade?exclude_self=true 级联店铺查询接口，并按最后一级节点提交 shop_id
  • 保留 series_id=0 作为清除套餐系列绑定的语义
  • 保留旧版兼容：未传 selection_type 时按 device_ids 处理
• 为单卡批量套餐系列绑定接口补充与单卡批量分配/回收一致的目标选择模型：
  • 支持 selection_type=list|range|filter
  • 支持 iccids、iccid_start / iccid_end、以及单卡筛选条件三类入参
  • 保留 series_id=0 作为清除套餐系列绑定的语义
  • 保留旧版兼容：未传 selection_type 时按 iccids 处理
• 两个接口均保持现有 PATCH 路径不变
• 两个接口继续返回批处理结果摘要与失败明细，不在本提案中引入新的异步任务机制或新的资源路径

Impact

• Affected specs:
  • device-series-binding
  • iot-card-series-binding
• Affected code:
  • src/api/modules/device.ts
  • src/api/modules/card.ts
  • src/api/modules/shop.ts
  • src/types/api/device.ts
  • src/types/api/card.ts
  • src/views/asset-management/device-list/index.vue
  • src/views/asset-management/iot-card-management/index.vue
• Reference docs:
  • docs/mvp/批量分配套餐系列.md
  • docs/1-24下午-新功能.md