one-pipe-system/openspec/changes/add-admin-task-and-audit-log-file-download/design.md

Design: 后台任务页与操作审计日志文件下载入口

Context

当前项目已经具备对象存储上传与下载地址获取能力：

• StorageService.getUploadUrl() 已用于上传导入文件
• StorageService.batchDownloadUrls() 已封装 POST /api/admin/storage/batch-download-urls

但在后台实际业务入口上，下载链路还没有被接起来：

• IoT 卡任务页和设备任务页只有“失败数据”等操作，没有“下载原始导入文件”
• 共享的资产操作审计日志组件虽然会显示 文件存储键，但只能看见 file_key 字符串，不能直接下载

此外，操作审计日志组件是共享组件，同时用于：

• 资产详情页
• IoT 卡列表中的操作审计日志弹窗
• 设备列表中的操作审计日志弹窗

这意味着“下载文件”能力既要复用统一实现，又要允许三个入口使用不同权限编码。

Goals / Non-Goals

• Goals:
  • 为 IoT 卡任务页增加原始导入文件下载入口
  • 为设备任务页增加原始导入文件下载入口
  • 为三个后台审计日志入口增加基于 file_key 的内联下载入口
  • 为以上 5 个入口分别施加独立权限控制
  • 复用现有 batch-download-urls 接口完成下载
• Non-Goals:
  • 不改造对象存储上传流程
  • 不增加批量下载多个文件的 UI
  • 不扩展到 C 端页面
  • 不在本次提案中统一所有历史权限命名差异

Decisions

• Decision: 所有“下载文件”入口统一通过 POST /api/admin/storage/batch-download-urls 获取下载 URL

  • Rationale: 现有基础设施已经覆盖私有文件下载，不需要新增独立接口；单文件下载可直接以 file_keys: [file_key] 方式复用批量接口。

• Decision: 任务页“下载文件”继续放在现有操作列中，而不是新增文件列

  • Rationale: IoT 卡任务页和设备任务页已经有行级操作模式；把下载文件放入操作列，和“失败数据”等现有动作一致，改动面更小。

• Decision: 审计日志中的“下载文件”必须紧跟在 文件存储键 / file_key 值后，而不是放到日志行外层操作区

  • Rationale: 需求明确指出“如果变更内容出现了文件存储键，后面也要跟上下载文件”，因此入口应与该字段形成强绑定。

• Decision: 共享 OperationLogsCard 作为唯一实现，但下载权限由调用入口传入

  • Rationale: 三个审计日志入口复用同一组件，如果把权限写死在组件内部，就无法满足“3 个不同权限编码”的要求。

• Decision: 本提案默认新增权限编码建议如下

  • 任务页：
    • iot_card_task:download_file
    • device_task:download_file
  • 审计日志入口：
    • asset_info:download_log_file
    • iot_card:download_log_file
    • device:download_log_file
  • Rationale: 任务页下载权限与现有同页行级动作前缀保持一致；日志下载权限与各自入口页面前缀保持一致，便于角色配置时理解来源。

• Decision: 不在本次变更中顺带统一 IoT 卡任务页历史上的 lot_task:* / iot_card_task:* 前缀差异

  • Rationale: 当前需求只要求增加下载文件权限入口；若同时做权限前缀清理，会把提案扩大为权限命名治理，超出本次范围。

• Decision: 当 file_key 缺失、为空或下载 URL 获取失败时，页面只提示失败，不影响列表或日志正常渲染

  • Rationale: 下载属于增强能力，不应把原有任务列表和审计日志变成硬依赖下载服务的阻塞页面。

Risks / Trade-offs

• 任务列表前端类型当前未显式声明 file_key，实施时若接口已返回但类型未补齐，容易出现“功能依赖字段存在但类型缺口”的问题。
• OperationLogsCard 的 props 和渲染逻辑一旦调整，会同时影响资产详情页、IoT 卡列表弹窗和设备列表弹窗，需要联动验证。
• IoT 卡任务页现存 lot_task:bulk_import 与 iot_card_task:* 并存，新增权限虽可落地，但会继续保留命名历史包袱。

Migration Plan

1. 明确导入任务记录的 file_key 契约，并补齐前端类型。
2. 在 IoT 卡任务页和设备任务页的操作列增加“下载文件”。
3. 为两个任务页接入各自独立的下载权限编码。
4. 扩展共享 OperationLogsCard，在 file_key 场景渲染内联“下载文件”入口。
5. 由资产详情页、IoT 卡列表、设备列表分别传入对应的日志下载权限编码。
6. 联调验证 5 个入口的权限隔离与下载行为。

Open Questions

• IoT 卡任务新增下载权限默认建议使用 iot_card_task:download_file。如果后端权限树仍希望完全沿用 lot_task:* 前缀，需要在评审阶段确认是否改为 lot_task:download_file。
• 当前导入任务列表接口是否已经返回 file_key 需要评审确认；若未返回，则实施范围需要同步包含接口契约补齐。