修正数据

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

@@ -0,0 +1,54 @@
+## 0. 验证准备（手工验证基线）
+
+- [x] 0.1 梳理导出任务手工验证清单（创建/列表/详情下载/取消/分片执行），明确使用 PostgreSQL MCP + Postman/curl 验证（不新增自动化测试）
+- [x] 0.2 准备验证数据样本：`device` 与 `iot_card` 两个场景各至少一组小数据与一组大数据
+- [x] 0.3 定义验收记录模板（请求参数、响应、数据库快照、OSS 文件 Key、日志关键字段）
+
+## 1. 导出任务数据模型与迁移
+
+- [x] 1.1 新增导出任务相关常量：任务类型、状态枚举、格式枚举、场景枚举、Redis Key 生成函数（全部放 `pkg/constants/`）
+- [x] 1.2 设计并实现 `tb_export_task` 与 `tb_export_shard_task` 的 Model/DTO（无外键，仅 ID 关联）
+- [x] 1.3 编写数据库迁移文件（up/down），创建导出主任务与分片任务表及必要索引
+- [x] 1.4 实现导出任务 Store（创建、分页查询、详情查询、状态流转、进度更新、取消标记、条件更新幂等）
+- [x] 1.5 使用 PostgreSQL MCP 验证迁移结果与索引生效，记录表结构与关键字段
+
+## 2. 全局导出任务管理接口
+
+- [x] 2.1 新增全局导出任务路由与 Handler：创建、列表、详情、取消（统一响应格式 `{code,msg,data,timestamp}`）
+- [x] 2.2 新增导出任务 Service 编排：参数校验、场景校验、格式校验、任务号生成、任务入队
+- [x] 2.3 实现列表按 `scene/status/time` 过滤和分页（默认 20，最大 100）
+- [x] 2.4 实现权限与可见性控制：仅返回当前用户有权限的任务，越权访问统一拒绝
+- [x] 2.5 更新文档生成器注册（`cmd/api/docs.go`、`cmd/gendocs/main.go`）并更新路由文档描述
+- [ ] 2.6 用 Postman/curl 手工验证接口契约（正常与异常参数、越权场景、分页过滤）
+
+## 3. 异步导出执行引擎（dispatch/shard/finalize）
+
+- [x] 3.1 新增 Asynq 任务载荷结构与任务类型注册：`export:dispatch`、`export:shard`、`export:finalize`
+- [x] 3.2 实现 dispatch 处理器：读取任务配置、生成分片记录、分片任务入队、状态推进
+- [x] 3.3 实现 shard 处理器：按分片查询数据、流式写出文件、上传 OSS、回写分片结果
+- [x] 3.4 实现 finalize 处理器：汇总分片结果、更新主任务最终状态、写入产物信息
+- [x] 3.5 增加幂等保护与重试安全：状态条件更新、重复消费防重、失败重试不重复产出
+- [ ] 3.6 手工验证异步链路：创建任务后观察状态从待处理到完成/失败的完整流转
+
+## 4. 场景策略注册与首批场景接入
+
+- [x] 4.1 实现场景策略注册中心（Scene Registry），约定统一接口：查询器、表头定义、行映射器
+- [x] 4.2 接入 `device` 导出策略骨架（先实现最小可运行数据输出）
+- [x] 4.3 接入 `iot_card` 导出策略骨架（先实现最小可运行数据输出）
+- [x] 4.4 实现场景级数据权限收敛：导出结果必须遵循对应场景既有权限规则
+- [ ] 4.5 手工验证两个场景导出任务均可独立创建、执行并产出文件
+
+## 5. 详情下载链接与任务取消能力
+
+- [x] 5.1 在任务详情接口中接入 `download_url` 生成逻辑（仅 `status=已完成` 返回）
+- [x] 5.2 下载链接有效期固定为 24 小时，过期后重新访问详情可刷新新链接
+- [x] 5.3 实现取消接口：支持待处理/处理中任务，已完成/已失败/已取消任务拒绝取消
+- [x] 5.4 在 dispatch/shard/finalize 增加取消检查点，命中后协作停止并更新为已取消
+- [ ] 5.5 手工验证取消场景：待处理取消、处理中取消、重复取消、取消后不再继续执行
+
+## 6. 文档与收尾验收
+
+- [x] 6.1 补充导出任务功能文档（`docs/{feature-id}/`），说明接口、状态机、分片策略、取消语义、下载规则
+- [x] 6.2 更新 README 与 API 使用示例（全局任务入口 + `scene` 过滤展示约定）
+- [ ] 6.3 进行全链路手工验收：`device`、`iot_card` 各完成一次 `xlsx` 与 `csv` 导出
+- [ ] 6.4 输出验收记录：接口响应样例、数据库状态快照、OSS 文件 key、下载 URL 有效期验证