junhong_cmp_fiber/docs/unified-export-task-system/手工验证清单.md

统一导出任务手工验证清单

验证工具与原则

• 数据库结构与数据状态：使用 PostgreSQL MCP（只读）
• 接口契约验证：使用 Postman 或 curl
• 明确约束：不新增自动化测试文件（*_test.go）

A. 创建导出任务

• POST /api/admin/export-tasks，scene=device，format=xlsx
• POST /api/admin/export-tasks，scene=iot_card，format=csv
• 非法 scene（如 order）返回参数错误
• 非法 format（如 pdf）返回参数错误

B. 列表与过滤

• GET /api/admin/export-tasks?page=1&page_size=20 默认分页生效
• scene 过滤生效（device / iot_card）
• status 过滤生效（1~5）
• start_time/end_time 时间过滤生效
• page_size > 100 时被限制到 100

C. 详情与下载

• 未完成任务详情不返回 download_url
• 已完成任务详情返回 download_url
• download_url 有效期固定 24 小时
• 过期后再次访问详情可刷新新链接

D. 取消语义

• 待处理任务可取消，状态立即变为已取消
• 处理中任务可提交取消请求（cancel_requested=true）
• 已完成/已失败/已取消任务再次取消被拒绝
• 重复取消处理中任务幂等返回

E. 异步链路（dispatch -> shard -> finalize）

• 创建任务后 export:dispatch 被消费
• 分片任务写入 tb_export_shard_task
• export:shard 执行后分片状态更新，产物写入 OSS
• export:finalize 汇总后主任务状态收敛
• 分片失败时主任务最终失败，错误信息可追踪

F. 数据权限与可见性

• 平台用户可见全量任务
• 代理仅可见其店铺范围任务
• 越权访问详情统一返回：无权限操作该资源或资源不存在

G. 数据库核查项（PostgreSQL MCP）

• tb_export_task 表存在，字段与注释完整
• tb_export_shard_task 表存在，字段与注释完整
• 关键索引存在并生效（任务号唯一索引、task_id+status、scene+status+created_at）