feat: 新增导出

openspec/changes/add-export-task-management/design.md

@@ -0,0 +1,73 @@
+## Context
+
+`docs/api.md` 定义了统一导出任务接口，支持 `device` 和 `iot_card` 两个场景，导出格式支持 `xlsx` / `csv`。前端需要提供两个业务列表的导出入口，以及一个可复用的导出任务管理视角，用于查看任务进度、查看详情、下载结果和取消任务。
+
+现有项目使用 Vue 3 + TypeScript + Element Plus，API 按业务模块放在 `src/api/modules`，类型放在 `src/types/api`，按钮权限通过 `useAuth` 和 `v-permission` 接入。
+
+## Goals / Non-Goals
+
+- Goals: 提供统一导出任务 API 封装、可复用创建弹窗、资产管理下导出列表页面、IoT 卡和设备列表导出入口、按钮权限控制。
+- Goals: 创建导出任务时传入当前列表检索条件快照，避免用户修改筛选条件后影响已经提交的任务。
+- Non-Goals: 不实现后端导出任务调度、文件生成、对象存储上传或 JWT 鉴权逻辑。
+- Non-Goals: 不替换现有导入任务页面，也不将导出任务与导入任务合并成同一个页面。
+- Non-Goals: 不在前端根据 `file_key` 拼接下载地址，下载必须使用详情接口返回的 `download_url`。
+
+## Decisions
+
+- Decision: 新增独立能力 `export-task-management`，不复用导入任务能力命名。
+- Rationale: 导出任务接口、状态流转、下载逻辑和业务入口与导入任务不同，独立能力更容易扩展到更多导出场景。
+
+- Decision: 创建导出任务弹窗做成业务无关组件，只通过 props 接收 `scene`、`query`、`format`、标题和说明文案。
+- Rationale: IoT 卡管理和设备管理只需传入不同场景与当前筛选条件，后续其他业务列表可以复用同一组件。
+
+- Decision: 导出列表页面做成可按 `scene` 筛选的管理视角，而不是为 `device` 和 `iot_card` 各建一套页面。
+- Rationale: `GET /api/admin/export-tasks` 已提供 `scene` 过滤，统一列表能减少重复代码，也支持未来新增默认场景视角。
+
+- Decision: 下载操作先调用 `GET /api/admin/export-tasks/{id}`，再使用详情中的 `download_url`。
+- Rationale: 文档说明下载地址仅在已完成任务详情中返回且有效期 24 小时，列表中的 `file_key` 不应被前端直接用于下载。
+
+- Decision: 权限编码按业务入口隔离。
+- Rationale: 创建任务属于来源业务列表权限，导出任务列表中的详情、下载、取消属于导出任务管理权限，避免用户拥有某个列表导出权限后自动获得管理全部导出任务的权限。
+
+## Data Model
+
+- `scene`: `device` / `iot_card`。
+- `format`: `xlsx` / `csv`。
+- `status`: `1` 待处理、`2` 处理中、`3` 已完成、`4` 失败、`5` 已取消。
+- `query`: 任意对象，保存发起导出时的业务列表筛选条件快照。
+
+## Permission Codes
+
+- `iot_card:export`: IoT 卡管理页导出按钮。
+- `devices:export`: 设备管理页导出按钮。
+- `export_task:list`: 导出列表页面访问和查询入口。
+- `export_task:detail`: 导出列表行详情操作。
+- `export_task:download`: 导出列表行下载操作。
+- `export_task:cancel`: 导出列表行取消操作。
+
+最终权限编码以产品/后端权限配置为准；如需调整，应在实施前同步更新本提案与任务。
+
+## Risks / Trade-offs
+
+- Risk: 业务列表筛选字段与后端导出任务 `query` 支持字段不一致。
+- Mitigation: 复用列表请求参数构造逻辑，并在提测时分别验证 `iot_card` 和 `device` 场景。
+
+- Risk: 下载地址有效期为 24 小时，用户在旧页面点击下载时可能失效。
+- Mitigation: 每次下载前重新调用详情接口获取最新可用的 `download_url`。
+
+- Risk: 取消处理中任务时后端可能只是标记 `cancel_requested`，不是立即变成已取消。
+- Mitigation: 取消成功后刷新列表并展示后端返回的状态和提示信息。
+
+## Migration Plan
+
+1. 增加 API、类型、路由、菜单和组件。
+2. 在 IoT 卡管理和设备管理接入导出弹窗。
+3. 新增导出列表页面并接入详情、下载、取消操作。
+4. 接入权限编码并验证不同权限组合。
+5. 如后端权限菜单需要同步，按上述权限编码补齐配置。
+
+## Open Questions
+
+- 导出格式是否需要在第一版开放给用户选择，还是固定 `xlsx`。
+- 权限编码是否采用本设计建议，还是需对齐后端已有权限命名。
+- 导出列表是否需要默认按当前入口过滤场景，还是资产管理下统一列表默认展示全部场景。

openspec/changes/add-export-task-management/proposal.md

@@ -0,0 +1,44 @@
+# Change: 新增统一导出任务管理
+
+## Why
+
+资产管理中的 IoT 卡与设备列表需要按当前检索条件执行全量导出，直接在前端同步导出容易超时且无法追踪进度。`docs/api.md` 已定义统一导出任务接口，需要在后台管理端补齐创建导出任务、查看任务列表、查看详情、下载结果和取消任务的前端能力。
+
+同时，导出入口会覆盖多个业务列表和后续可扩展的导出视角，必须做成可复用的弹窗与任务管理能力，并按现有 RBAC 体系为所有按钮和操作补充权限编码。
+
+## What Changes
+
+- 在资产管理下新增“导出管理”，并在其下新增“导出列表”页面。
+- 新增统一导出任务前端 API 与类型契约，对接：
+  - `GET /api/admin/export-tasks`
+  - `POST /api/admin/export-tasks`
+  - `GET /api/admin/export-tasks/{id}`
+  - `POST /api/admin/export-tasks/{id}/cancel`
+- 新增可复用的创建导出任务弹窗，打开时说明“导出规则基于列表中的检索条件全量导出”。
+- 在 IoT 卡管理页增加导出按钮，默认创建 `scene=iot_card` 的导出任务。
+- 在设备管理页增加导出按钮，默认创建 `scene=device` 的导出任务。
+- 导出列表支持分页、场景、状态、创建时间范围筛选，列表数据调用导出任务列表接口，详情/下载调用详情接口，取消操作调用取消接口。
+- 所有新增按钮和行操作均需要接入权限编码，不允许无权限用户看到或触发对应操作。
+
+## Impact
+
+- Affected specs:
+  - `export-task-management`
+- Affected code:
+  - `src/api/modules/exportTask.ts`
+  - `src/types/api/exportTask.ts`
+  - `src/types/api/index.ts`
+  - `src/api/modules/index.ts`
+  - `src/router/routesAlias.ts`
+  - `src/router/routes/asyncRoutes.ts`
+  - `src/views/asset-management/iot-card-management/index.vue`
+  - `src/views/asset-management/device-list/index.vue`
+  - `src/views/asset-management/export-task-management/export-task-list/index.vue`
+  - `src/components/business/ExportTaskCreateDialog.vue`
+  - 菜单与国际化文案配置文件
+- Dependencies:
+  - 依赖后端按 `docs/api.md` 提供导出任务接口和 JWT 鉴权。
+  - 依赖现有 `useAuth` / `v-permission` 权限基础设施。
+  - 导出创建时传入的 `query` 需要与对应业务列表接口的检索参数保持一致。
+- Breaking changes:
+  - 无。新增页面、按钮、API 模块和类型均为增量能力。

openspec/changes/add-export-task-management/specs/export-task-management/spec.md

@@ -0,0 +1,146 @@
+## ADDED Requirements
+
+### Requirement: Export Task API Integration
+
+The admin frontend SHALL provide a typed API integration for unified export tasks using the REST contract from `docs/api.md`.
+
+#### Scenario: Query export tasks with filters
+
+- **GIVEN** 用户打开导出列表页面
+- **WHEN** 用户按分页、场景、状态或创建时间范围查询导出任务
+- **THEN** 系统 MUST call `GET /api/admin/export-tasks`
+- **AND** 系统 MUST support optional query parameters `page`, `page_size`, `scene`, `status`, `start_time`, and `end_time`
+- **AND** 系统 MUST parse `data.page`, `data.size`, `data.total`, and `data.items` from the response
+
+#### Scenario: Create export task
+
+- **GIVEN** 用户在业务列表中确认创建导出任务
+- **WHEN** 系统提交导出任务
+- **THEN** 系统 MUST call `POST /api/admin/export-tasks`
+- **AND** 请求体 MUST include required `scene` and `format`
+- **AND** 请求体 MAY include `query` containing the current list filter conditions
+- **AND** 系统 MUST handle the response fields `task_id`, `task_no`, `status`, `status_name`, and `message`
+
+#### Scenario: Fetch export task detail
+
+- **GIVEN** 用户需要查看或下载某个导出任务
+- **WHEN** 系统读取任务详情
+- **THEN** 系统 MUST call `GET /api/admin/export-tasks/{id}` with the numeric task id
+- **AND** 系统 MUST support detail fields including progress, row counts, shard counts, `file_key`, `error_message`, timestamps, `download_url`, and `download_expires_at`
+- **AND** 系统 MUST treat `download_url` as available only when the task is completed and the backend returns it
+
+#### Scenario: Cancel export task
+
+- **GIVEN** 用户取消待处理或处理中的导出任务
+- **WHEN** 系统提交取消请求
+- **THEN** 系统 MUST call `POST /api/admin/export-tasks/{id}/cancel`
+- **AND** 系统 MUST handle `task_id`, `status`, `status_name`, `cancel_requested`, and `message` from the response
+
+### Requirement: Reusable Export Task Creation Dialog
+
+The admin frontend SHALL provide a reusable dialog for creating export tasks from business list pages.
+
+#### Scenario: Explain full export rule before task creation
+
+- **GIVEN** 用户点击业务列表中的导出按钮
+- **WHEN** 导出弹窗打开
+- **THEN** 弹窗 MUST clearly state that export rules are based on the current list search conditions and export the full matched result set
+- **AND** 弹窗 MUST NOT imply that only the current page rows will be exported
+
+#### Scenario: Create IoT card export task from IoT card management
+
+- **GIVEN** 用户在 IoT 卡管理页设置了列表检索条件
+- **AND** 当前用户具备 IoT 卡导出权限
+- **WHEN** 用户确认创建导出任务
+- **THEN** 系统 MUST submit `scene="iot_card"`
+- **AND** 系统 MUST submit the current IoT card list filter conditions as `query`
+
+#### Scenario: Create device export task from device management
+
+- **GIVEN** 用户在设备管理页设置了列表检索条件
+- **AND** 当前用户具备设备导出权限
+- **WHEN** 用户确认创建导出任务
+- **THEN** 系统 MUST submit `scene="device"`
+- **AND** 系统 MUST submit the current device list filter conditions as `query`
+
+#### Scenario: Snapshot current filters at submission time
+
+- **GIVEN** 用户修改业务列表筛选条件并重新搜索
+- **WHEN** 用户随后打开弹窗并确认导出
+- **THEN** 系统 MUST use the latest applied search conditions in the export task `query`
+- **AND** 已提交任务的 `query` MUST NOT change when the user later edits the page filters
+
+### Requirement: Asset Export Task List Page
+
+The admin frontend SHALL add an export task list under Asset Management > Export Management for viewing and operating export tasks.
+
+#### Scenario: Render export management navigation
+
+- **GIVEN** 当前用户具备导出任务列表访问权限
+- **WHEN** 系统渲染资产管理菜单
+- **THEN** 系统 MUST provide an Export Management group under Asset Management
+- **AND** 系统 MUST provide an Export List entry under that group
+- **AND** 导出列表路由 MUST load the export task list page
+
+#### Scenario: Display export task rows
+
+- **GIVEN** 导出任务列表接口返回任务记录
+- **WHEN** 页面渲染表格
+- **THEN** 页面 MUST display task number, scene, status name, progress, format, total rows, processed rows, shard counts, file key, error message, and task timestamps when present
+- **AND** 页面 MUST use stable empty placeholders for missing optional fields
+
+#### Scenario: View task detail from row action
+
+- **GIVEN** 用户具备导出任务详情权限
+- **WHEN** 用户点击某条任务的详情操作
+- **THEN** 系统 MUST call the task detail API for that row
+- **AND** 页面 MUST present the returned task detail without losing the current list filters and pagination state
+
+#### Scenario: Download completed task from row action
+
+- **GIVEN** 某条导出任务状态为已完成
+- **AND** 当前用户具备导出任务下载权限
+- **WHEN** 用户点击下载操作
+- **THEN** 系统 MUST call the task detail API to obtain `download_url`
+- **AND** 系统 MUST open or download the file using the returned `download_url`
+- **AND** 系统 MUST NOT construct a download URL from `file_key` on the frontend
+
+#### Scenario: Cancel cancellable task from row action
+
+- **GIVEN** 某条导出任务状态为待处理或处理中
+- **AND** 当前用户具备导出任务取消权限
+- **WHEN** 用户确认取消该任务
+- **THEN** 系统 MUST call the cancel API for that task
+- **AND** 系统 MUST refresh the list or update the row using the backend response
+
+#### Scenario: Hide unavailable row actions
+
+- **GIVEN** 某条导出任务状态为已完成、失败或已取消
+- **WHEN** 页面渲染该行操作
+- **THEN** 页面 MUST NOT show the cancel action for that row
+- **AND** 页面 MUST show the download action only when the task is completed and the user has download permission
+
+### Requirement: Export Task Permissions
+
+The admin frontend MUST gate every export-task-related button and row action with explicit permission codes.
+
+#### Scenario: Hide business export buttons without permission
+
+- **GIVEN** 当前用户 lacks the IoT card export permission
+- **WHEN** 用户打开 IoT 卡管理页
+- **THEN** 页面 MUST NOT display the IoT card export button
+- **AND** 缺少设备导出权限时，设备管理页 MUST NOT display the device export button
+
+#### Scenario: Hide export task management operations without permission
+
+- **GIVEN** 当前用户可以访问导出列表但 lacks download or cancel permissions
+- **WHEN** 页面渲染导出任务行操作
+- **THEN** 页面 MUST NOT display the download action without download permission
+- **AND** 页面 MUST NOT display the cancel action without cancel permission
+
+#### Scenario: Keep permissions isolated by entry point
+
+- **GIVEN** 当前用户具备 `iot_card` 导出权限但不具备 `device` 导出权限
+- **WHEN** 用户分别访问 IoT 卡管理页和设备管理页
+- **THEN** IoT 卡管理页 MAY display its export button
+- **AND** 设备管理页 MUST NOT display its export button because of the IoT card permission

openspec/changes/add-export-task-management/tasks.md

@@ -0,0 +1,51 @@
+## 1. Proposal Review
+
+- [x] 1.1 确认导出按钮权限编码：IoT 卡管理使用 `iot_card:export`，设备管理使用 `devices:export`。
+- [x] 1.2 确认导出任务管理权限编码：使用 `export_task:list`、`export_task:detail`、`export_task:download`、`export_task:cancel`。
+- [x] 1.3 确认导出格式默认 `xlsx`，并允许用户在弹窗中切换 `xlsx` / `csv`。
+- [x] 1.4 确认 IoT 卡和设备列表现有筛选参数作为导出任务 `query` 传给后端。
+
+## 2. API And Types
+
+- [x] 2.1 新增导出任务状态、场景、格式、列表项、详情、创建请求、取消响应等 TypeScript 类型。
+- [x] 2.2 新增 `ExportTaskService`，实现列表、创建、详情、取消接口。
+- [x] 2.3 在 API 和类型入口文件导出新增模块。
+- [x] 2.4 对齐统一响应结构 `code`、`msg`、`timestamp`、`data` 和分页结构 `page`、`size`、`total`、`items`。
+
+## 3. Reusable Export Dialog
+
+- [x] 3.1 新增可复用创建导出任务弹窗组件，支持传入 `scene`、当前列表查询条件和默认导出格式。
+- [x] 3.2 弹窗中明确展示导出规则说明：导出规则基于列表中的检索条件全量导出。
+- [x] 3.3 提交时调用创建导出任务接口，并在成功后提示任务已创建。
+- [x] 3.4 确保弹窗确认按钮和触发按钮均受对应权限控制。
+
+## 4. Business Entry Points
+
+- [x] 4.1 在 IoT 卡管理页增加导出按钮，打开弹窗时默认 `scene=iot_card`，并传入当前筛选条件快照。
+- [x] 4.2 在设备管理页增加导出按钮，打开弹窗时默认 `scene=device`，并传入当前筛选条件快照。
+- [x] 4.3 确保重置筛选、分页切换、重新搜索后导出使用最新检索条件。
+
+## 5. Export Task List Page
+
+- [x] 5.1 在资产管理下新增“导出管理”分组和“导出列表”路由、菜单、路由别名。
+- [x] 5.2 导出列表支持分页、场景、状态、创建开始时间、创建结束时间筛选。
+- [x] 5.3 表格展示任务编号、场景、状态、进度、格式、行数、分片、错误信息和时间字段；列表不展示文件 key。
+- [x] 5.4 任务编号支持点击进入导出任务详情页，行操作支持下载已完成任务、取消待处理/处理中任务。
+- [x] 5.5 下载操作必须先调用详情接口获取 `download_url`，且仅在已完成任务可用。
+- [x] 5.6 取消操作必须调用取消接口，并在成功后刷新列表。
+
+## 6. Permissions And UX
+
+- [x] 6.1 为所有新增按钮和行操作添加权限编码检查。
+- [x] 6.2 无权限时不显示对应入口，不依赖禁用态作为唯一保护。
+- [x] 6.3 对创建、详情、下载、取消失败提供稳定错误提示，不破坏列表渲染。
+
+## 7. Verification
+
+- [x] 7.1 验证 IoT 卡管理页可按当前筛选条件创建 `iot_card` 导出任务。
+- [x] 7.2 验证设备管理页可按当前筛选条件创建 `device` 导出任务。
+- [x] 7.3 验证导出列表分页和筛选参数与接口契约一致，且文件 key 不在列表字段中展示。
+- [x] 7.4 验证点击任务编号进入详情页，已完成任务可通过详情接口获取下载地址并下载。
+- [x] 7.5 验证待处理/处理中任务可取消，已完成/失败/已取消任务不可取消。
+- [x] 7.6 验证所有新增按钮和操作在无权限时不可见。
+- [x] 7.7 运行类型检查和相关 lint；新增文件 lint 通过，整仓构建受既有 TypeScript 债务阻塞。