修正数据

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

@@ -0,0 +1,103 @@
+# 统一导出任务功能总结
+
+## 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`