# 04 — 固化前端接口交互契约与展示数据验收

**What to build:** 交付可由设备管理页直接消费的 CSV 批量分配接口交互契约：受控上传、两个独立命令提交、任务轮询和结果展示需要的字段、状态与安全错误语义保持完整一致；通过接口文档和真实链路联调，确保前端无需依赖隐含规则即可呈现部分成功和逐行失败。

**Blocked by:** 02 — 完成 CSV 批量分配代理接口闭环；03 — 完成 CSV 批量分配套餐系列接口闭环。

**Status:** ready-for-agent

**架构通道：** Infrastructure（接口契约与前端消费验证）。

**完整业务边界：** 本票收口前端调用接口时需要遵守的上传、独立命令、轮询、终态停止和结果展示数据契约，以及相应接口文档和集成验收。Query 投影只读提供页面展示数据，不承担状态写入。

**明确不迁移：** 不开发或改造任何前端页面、弹框、静态模板或目标选择器；不迁移原有页面勾选、ID 列表、号段或筛选入口；不新增后端模板下载接口、失败结果文件下载接口或可同时修改代理和系列的通用操作。

- [ ] 两个命令保持独立请求字段和语义：上传后仅提交 `file_key`，分配代理只提交正 `shop_id`，分配系列只提交正 `series_id`；不使用 multipart，也不提供可同时修改代理与系列的通用操作。
- [ ] 接口文档明确 CSV 的受控上传用途、`.csv`/10MB 限制、UTF-8 单列表头、长设备号按字符串处理、文件级与行级错误差异，以及前端提交时的防重与重试语义；本票不实现模板或预览页面。
- [ ] 任务创建与详情响应完整提供任务号、命令、目标摘要、状态及中文名称、进度、总数、成功/幂等/失败数、失败明细和时间；终态可据此停止轮询，部分成功不会被接口语义误标为整体失败。
- [ ] HTTP 集成测试和接口联调覆盖 CSV 上传、平台与代理权限、部分成功、文件级失败、入队失败和安全错误语义，保证页面展示不依赖数据库查询或隐含规则。
