junhong_cmp_fiber/docs/unified-export-task-system/功能总结.md

统一导出任务功能总结

1. 功能概览

本次交付新增统一导出任务系统，提供全局任务入口，支持：

• 创建导出任务（scene=device/iot_card，format=xlsx/csv）
• 导出任务列表与详情
• 导出任务取消（待处理/处理中）
• 异步三段式执行：dispatch -> shard -> finalize
• 分片产物与最终产物上传 OSS
• 详情接口直出下载链接（固定 24 小时）

2. 新增接口

• POST /api/admin/export-tasks：创建导出任务
• GET /api/admin/export-tasks：导出任务列表（支持 scene/status/time 过滤）
• GET /api/admin/export-tasks/:id：导出任务详情（已完成时返回 download_url）
• POST /api/admin/export-tasks/:id/cancel：取消导出任务

3. 状态机

3.1 主任务状态

• 1 待处理
• 2 处理中
• 3 已完成
• 4 已失败
• 5 已取消

3.2 分片状态

• 1 待处理
• 2 处理中
• 3 已成功
• 4 已失败
• 5 已取消

4. 核心设计

4.1 模型与迁移

新增两张表：

• tb_export_task：主任务
• tb_export_shard_task：分片任务

关键点：

• 无外键，仅使用 task_id 做逻辑关联
• 主任务保留进度、分片统计、权限快照、产物信息
• 分片任务保留游标范围、分片产物、执行状态

4.2 场景策略注册中心

新增 internal/exporter 场景注册中心与策略接口，首批接入：

• device 场景策略
• iot_card 场景策略

统一定义：

• Headers()：导出表头
• NextShardBoundary()：按 keyset 方式计算分片边界
• QueryRows()：按分片边界查询行数据

4.3 执行链路

• export:dispatch：构建分片并入队 export:shard
• export:shard：按分片查询数据、写文件、上传 OSS、回写分片结果
• export:finalize：汇总分片结果并生成最终文件，更新主任务状态

4.4 幂等与重试安全

• dispatch/shard/finalize 增加 Redis 锁，避免并发重复执行
• 分片状态条件更新，重复消费不会重复计数
• shard/finalize 利用 Asynq 重试上下文，在最终重试失败时才落库失败状态

4.5 取消语义

• 待处理：直接更新为已取消
• 处理中：仅设置 cancel_requested=true，由 Worker 检查点协作停止
• dispatch/shard/finalize 均增加取消检查点

4.6 下载链接

• 仅 status=已完成 返回 download_url
• 链接有效期固定 24h（常量 ExportDownloadURLExpire）
• URL 由详情接口实时生成，过期后再次访问可刷新

5. 权限与可见性

• 平台/超管：可见全部导出任务
• 代理：仅可见其店铺范围内创建的导出任务
• 详情越权统一返回：无权限操作该资源或资源不存在

6. 文档与生成器更新

已同步更新：

• 路由文档（新增 导出任务 Tag 的 4 个接口）
• 文档构建 Handler 集合（pkg/openapi/handlers.go 新增 ExportTask）
• OpenAPI 文件重新生成：docs/admin-openapi.yaml