huang
fe4c545308
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m55s
6.8 KiB
6.8 KiB
Context
当前项目已具备成熟的异步导入任务能力（设备导入、单卡导入）与对象存储能力，但导出能力尚未形成统一任务系统。面对未来超大数据量，直接同步导出会引发请求超时、内存峰值高、用户等待时间不可控等问题。
本次变更要先建立“通用导出任务骨架”，并以 device 与 iot_card 作为首批场景验证架构可扩展性；导出字段与具体查询细节后续按场景迭代补充。
约束条件：
- 必须遵循
Handler -> Service -> Store -> Model分层。 - 必须使用 Asynq 异步任务机制。
- 禁止外键约束，任务主从关系通过 ID 字段维护。
- 常量、状态枚举、Redis Key 必须定义在
pkg/constants/，禁止硬编码。
Goals / Non-Goals
Goals:
- 提供全局导出任务中心，统一任务创建、列表、详情、取消。
- 支持
xlsx/csv两种格式选择。 - 支持异步分片执行，满足大数据量导出性能需求。
- 导出产物上传 OSS，并在任务详情直接返回可下载 URL（默认 24h）。
- 设计可扩展场景机制，首批支持
device、iot_card。
Non-Goals:
- 本阶段不定义最终导出字段清单与前端展示细节。
- 本阶段不实现跨场景聚合导出（仅单场景任务）。
- 本阶段不实现复杂运营能力（如任务重跑、任务克隆、批量取消）。
Decisions
决策1：统一导出引擎 + 场景策略注册
选择：采用“通用导出任务引擎 + 场景策略（Strategy）+ 执行模板（Template Method）”模式。
理由：
- 避免设备导出、单卡导出重复实现任务编排、分片、上传、状态流转。
- 后续新增导出场景仅需注册策略（查询器、表头、行映射），无需改核心引擎。
备选方案：每个场景单独实现导出任务链路。
放弃原因：重复代码多，后续维护成本高，难以统一性能与取消语义。
决策2：三段式异步任务流水线
选择：Asynq 任务拆分为 dispatch -> shard -> finalize 三段。
执行语义：
dispatch：按查询规模创建分片子任务并入队。shard：每个分片独立查询与写文件，上传 OSS，回写分片状态。finalize：聚合分片结果，生成主任务最终结果（file_key/download_url）。
理由：
- 分片并行可线性提升吞吐。
- 分片失败可独立重试，不影响已完成分片。
- finalize 统一收口，便于生成一致的下载结果。
决策3：任务数据模型拆分主任务与分片任务
选择：新增两张表（不建外键）：
tb_export_task（主任务）tb_export_shard_task（分片任务）
关键字段：
- 主任务：
task_no、scene、format、status、progress、cancel_requested、file_key、error_message、started_at、completed_at。 - 分片任务：
task_id、shard_no、status、cursor_start/cursor_end、row_count、file_key、error_message。
事务设计：
dispatch中“创建分片记录 + 分片任务入队标记”在事务内完成，避免分片记录与队列状态不一致。shard与finalize使用状态条件更新保证幂等（如WHERE status = expected）。
决策4：下载信息仅在详情接口返回，且直出可下载 URL
选择：
- 任务列表仅返回任务元信息，不返回下载 URL。
- 任务详情在
status=已完成时返回可直接下载的download_url，有效期默认 24 小时。
理由：
- 减少列表接口的预签名生成开销。
- 与用户已确认的交互模式一致。
决策5：取消机制采用“控制面标记 + Worker 协作停止”
选择：
- 取消接口将主任务标记为“取消请求”（
cancel_requested=true）。 dispatch/shard/finalize在关键节点检查取消标记，命中即停止并回写取消状态。
理由：
- 兼容已运行任务，避免强杀导致的中间态脏数据。
- 实现简单且可控，符合当前 Asynq 使用方式。
权衡：
- 取消不是“瞬时终止”，而是“尽快停止”；单个分片运行中的小批次会执行到检查点再退出。
决策6：性能基线采用 Keyset 分页 + 流式写出
选择：
- 分片数据读取使用 Keyset 分页（
id > last_id），避免深分页性能衰减。 - 文件写出采用流式写出策略，避免全量数据载入内存。
- 进度按批回写（例如每 N 行）降低数据库写放大。
理由：
- 满足未来超大数据量导出场景。
- 控制数据库与 Worker 资源占用，减少峰值风险。
决策7：依赖注入与模块边界
选择：
- Handler 仅做参数解析、权限前置与统一响应。
- Service 注入
ExportTaskStore、ExportShardTaskStore、queue.Client、storage.Service、SceneRegistry。 - Worker 通过
pkg/queue/handler.go统一注册导出相关处理器。
理由：
- 与现有导入任务模式保持一致，降低接入复杂度。
- 强化模块边界，便于后续场景扩展。
Risks / Trade-offs
-
[风险] 分片大小配置不合理导致队列拥塞或分片过小
→ 缓解：分片大小与并发度配置化；增加任务监控指标与告警阈值。 -
[风险] xlsx 在极大数据量场景下生成耗时高
→ 缓解：允许用户选择csv；必要时按分片生成多文件并由 finalize 打包归档。 -
[风险] 取消与 finalize 并发竞争造成状态抖动
→ 缓解：统一使用状态条件更新，finalize 前再次检查cancel_requested。 -
[权衡] 详情接口实时生成预签名 URL 会增加一次存储调用
→ 接受：仅详情触发，调用频率低，收益大于成本。
Migration Plan
- 新增导出任务常量、状态枚举、任务类型、Redis Key 生成函数。
- 新增导出主任务与分片任务模型、Store、数据库迁移。
- 新增全局导出任务 Handler/Service/Route（创建、列表、详情、取消）。
- 新增导出 Worker 处理器并注册 Asynq 任务类型（dispatch/shard/finalize）。
- 接入首批场景策略：
device、iot_card（先完成骨架与最小可运行实现）。 - 更新接口文档生成器与业务文档，补充手工验证步骤。
回滚策略：
- 若上线后发现异常，可先关闭导出任务入口（路由开关/权限收敛），保留已生成文件不影响现网核心交易链路。
- 数据库迁移按标准 down 脚本回滚新增表与字段。
Open Questions
- 是否需要在任务列表返回“最近一次下载 URL 过期时间”用于前端提示（当前方案不返回，仅详情返回）？
- 分片默认大小与队列权重的初始值是否按环境差异化配置（开发/生产）？