junhong_cmp_fiber/openspec/changes/unified-export-task-system/proposal.md

Why

当前系统已有设备与单卡导入任务，但缺少统一的异步导出任务能力，随着数据规模持续增长，直接同步导出会带来超时、内存占用和用户体验问题。现在需要先落地可复用的“导出任务骨架”，为后续多个业务场景复用，避免重复建设。

What Changes

• feature-001-unified-export-task-center：新增全局导出任务中心，统一创建、查询、详情、取消导出任务。
• feature-002-export-format-selectable：创建导出任务时支持用户选择 xlsx/csv 格式。
• feature-003-scene-plugin-support：首批支持 device、iot_card 两个导出场景，并设计为可扩展插件式接入。
• feature-004-async-shard-export：导出采用 Asynq 异步执行，支持分片处理与进度回写，面向大数据量场景。
• feature-005-export-oss-delivery：导出产物上传 OSS，任务详情直接返回可下载 URL（默认有效期 24 小时）。
• feature-006-export-task-cancel：支持取消待处理/执行中的导出任务，并在 Worker 侧协作停止。
• 架构遵循 Handler -> Service -> Store -> Model 分层，导出能力以通用引擎 + 场景策略方式实现。

Capabilities

New Capabilities

• unified-export-task-system：统一导出任务系统能力，覆盖全局任务入口、异步分片导出、OSS 交付、详情直出下载 URL 与任务取消。

Modified Capabilities

• 无

Impact

• 影响模块：
  • internal/routes：新增导出任务全局路由。
  • internal/handler：新增导出任务 Handler。
  • internal/service：新增导出任务编排服务与场景策略注册。
  • internal/store：新增导出任务与分片任务存储。
  • internal/task 与 pkg/queue：新增导出 dispatch/shard/finalize/cancel 相关任务处理。
  • pkg/constants：新增导出任务类型、状态、Redis Key 常量。
• 影响 API：
  • 新增全局导出任务创建/列表/详情/取消接口（按 scene 过滤展示）。
• 影响数据与基础设施：
  • 新增导出主任务与分片任务表。
  • 复用现有 OSS 能力与 Asynq 队列能力。
• 性能考虑：
  • 使用分片、流式写出、批量进度更新、Keyset 分页策略，避免大数据量导出时超时与内存峰值。
• 验证计划：
  • 按项目约束采用 PostgreSQL MCP + Postman/curl 的手工验证，覆盖创建任务、分片执行、下载 URL 获取、取消任务等关键流程。