junhong_cmp_fiber/openspec/changes/unified-export-task-system/tasks.md

0. 验证准备（手工验证基线）

• 0.1 梳理导出任务手工验证清单（创建/列表/详情下载/取消/分片执行），明确使用 PostgreSQL MCP + Postman/curl 验证（不新增自动化测试）
• 0.2 准备验证数据样本：device 与 iot_card 两个场景各至少一组小数据与一组大数据
• 0.3 定义验收记录模板（请求参数、响应、数据库快照、OSS 文件 Key、日志关键字段）

1. 导出任务数据模型与迁移

• 1.1 新增导出任务相关常量：任务类型、状态枚举、格式枚举、场景枚举、Redis Key 生成函数（全部放 pkg/constants/）
• 1.2 设计并实现 tb_export_task 与 tb_export_shard_task 的 Model/DTO（无外键，仅 ID 关联）
• 1.3 编写数据库迁移文件（up/down），创建导出主任务与分片任务表及必要索引
• 1.4 实现导出任务 Store（创建、分页查询、详情查询、状态流转、进度更新、取消标记、条件更新幂等）
• 1.5 使用 PostgreSQL MCP 验证迁移结果与索引生效，记录表结构与关键字段

2. 全局导出任务管理接口

• 2.1 新增全局导出任务路由与 Handler：创建、列表、详情、取消（统一响应格式 {code,msg,data,timestamp}）
• 2.2 新增导出任务 Service 编排：参数校验、场景校验、格式校验、任务号生成、任务入队
• 2.3 实现列表按 scene/status/time 过滤和分页（默认 20，最大 100）
• 2.4 实现权限与可见性控制：仅返回当前用户有权限的任务，越权访问统一拒绝
• 2.5 更新文档生成器注册（cmd/api/docs.go、cmd/gendocs/main.go）并更新路由文档描述
• 2.6 用 Postman/curl 手工验证接口契约（正常与异常参数、越权场景、分页过滤）

3. 异步导出执行引擎（dispatch/shard/finalize）

• 3.1 新增 Asynq 任务载荷结构与任务类型注册：export:dispatch、export:shard、export:finalize
• 3.2 实现 dispatch 处理器：读取任务配置、生成分片记录、分片任务入队、状态推进
• 3.3 实现 shard 处理器：按分片查询数据、流式写出文件、上传 OSS、回写分片结果
• 3.4 实现 finalize 处理器：汇总分片结果、更新主任务最终状态、写入产物信息
• 3.5 增加幂等保护与重试安全：状态条件更新、重复消费防重、失败重试不重复产出
• 3.6 手工验证异步链路：创建任务后观察状态从待处理到完成/失败的完整流转

4. 场景策略注册与首批场景接入

• 4.1 实现场景策略注册中心（Scene Registry），约定统一接口：查询器、表头定义、行映射器
• 4.2 接入 device 导出策略骨架（先实现最小可运行数据输出）
• 4.3 接入 iot_card 导出策略骨架（先实现最小可运行数据输出）
• 4.4 实现场景级数据权限收敛：导出结果必须遵循对应场景既有权限规则
• 4.5 手工验证两个场景导出任务均可独立创建、执行并产出文件

5. 详情下载链接与任务取消能力

• 5.1 在任务详情接口中接入 download_url 生成逻辑（仅 status=已完成 返回）
• 5.2 下载链接有效期固定为 24 小时，过期后重新访问详情可刷新新链接
• 5.3 实现取消接口：支持待处理/处理中任务，已完成/已失败/已取消任务拒绝取消
• 5.4 在 dispatch/shard/finalize 增加取消检查点，命中后协作停止并更新为已取消
• 5.5 手工验证取消场景：待处理取消、处理中取消、重复取消、取消后不再继续执行

6. 文档与收尾验收

• 6.1 补充导出任务功能文档（docs/{feature-id}/），说明接口、状态机、分片策略、取消语义、下载规则
• 6.2 更新 README 与 API 使用示例（全局任务入口 + scene 过滤展示约定）
• 6.3 进行全链路手工验收：device、iot_card 各完成一次 xlsx 与 csv 导出
• 6.4 输出验收记录：接口响应样例、数据库状态快照、OSS 文件 key、下载 URL 有效期验证