luo
2a8f4e40d6
4.4 KiB
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
- 增加 API、类型、路由、菜单和组件。
- 在 IoT 卡管理和设备管理接入导出弹窗。
- 新增导出列表页面并接入详情、下载、取消操作。
- 接入权限编码并验证不同权限组合。
- 如后端权限菜单需要同步，按上述权限编码补齐配置。
Open Questions
- 导出格式是否需要在第一版开放给用户选择，还是固定
xlsx。 - 权限编码是否采用本设计建议，还是需对齐后端已有权限命名。
- 导出列表是否需要默认按当前入口过滤场景，还是资产管理下统一列表默认展示全部场景。