# Change: 统一公共状态与异步任务交互 ## Why 设备批量分配、批量订购和导出页面目前可能分别处理加载、失败、进度和任务恢复,容易产生不同的状态语义和重试行为。需要建立一套可复用的公共交互规则,让用户在不同批量操作页面获得一致的反馈,并避免页面刷新或切换后重复创建任务。 ## What Changes - 为设备批量分配、批量订购和导出页面统一加载中、空数据、无权限、接口失败和重试状态。 - 统一异步任务的五态语义:待处理、处理中、已完成、已失败、已取消。 - 统一任务进度数据展示:任务状态、总数、成功数、失败数和失败明细。 - 明确部分成功的表达方式:任务进入已完成状态,通过成功数和失败数表达部分成功,不新增部分成功状态。 - 创建任务成功后保存 `task_id`,页面刷新或重新进入时恢复原任务详情,不重复创建任务。 - 对待处理和处理中任务按 2 秒、3 秒、5 秒递增轮询,之后最大间隔 10 秒;进入终态后停止轮询。 - 页面不可见时暂停轮询,恢复可见后立即刷新一次。 - 统一 403、瞬时接口失败和任务失败的用户反馈及重试规则。 - 为 `GET /api/admin/export-tasks` 和 `GET /api/admin/export-tasks/{id}` 增加兼容性字段契约:`task_id`、`total_count`、`success_count`、`failed_count`、`error_code`、`error_summary`、`updated_at`;原字段不删除、不改名。 ## Impact - Affected specs: - `async-task-interaction` - `export-task-management` - Affected code: - 批量分配页面及其设备、IOT 卡任务提交逻辑 - 批量订购页面及其任务提交逻辑 - 导出任务 API 类型和导出任务列表/详情页面 - 可复用异步任务状态、轮询和任务恢复逻辑 - 统一错误、空数据、无权限和重试状态组件或页面状态配置 - Dependencies: - 后端批量分配、批量订购和导出接口必须返回可关联的 `task_id`,并提供按 `task_id` 查询任务详情的能力。 - 后端导出接口按本提案新增兼容字段,且继续保留现有字段。 - Breaking changes: - 无。导出接口仅新增兼容字段;前端统一交互规则不改变既有任务创建接口的必填参数。