4.1 KiB
4.1 KiB
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 有效期验证