ai-contract-platform/project-docs/V2-batch-download-2026-06-25.md

AI 合同平台 V2 - 批量下载功能闭环记录

日期：2026-06-25

背景

对照《AI 合同平台 V2 重构版开发方案》Phase 6 合同仓库与生命周期，本轮实现批量下载功能，让用户能够一次性下载多个附件。

目标

• 支持多文件批量打包下载。
• 使用 zipfile 打包。
• 打包时记录审计事件。

已完成内容

后端 API

文件：

• yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/contracts.py
• yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/main.py

新增模型：

• BatchDownloadRequest: file_ids, actor_name
• BatchDownload: file_ids, content_base64, file_count

新增接口：

• POST /api/v1/files/batch-download: 批量下载，返回 base64 编码的 zip 文件

实现逻辑：

1. 遍历请求中的 file_ids。
2. 对每个文件记录下载审计事件。
3. 使用 zipfile 将所有文件打包。
4. 返回 base64 编码的 zip 内容。

前端 API 代理

文件：

• yuqei-contract-platform/apps/contract-web/src/app/api/contract-platform/files/batch-download/route.ts

验证结果

后端测试：

python -m compileall yuqei-contract-platform/services/contract-api/src/yuqei_contract_api
python -m pytest yuqei-contract-platform/services/contract-api/tests -q

结果：25 passed

后续建议

1. 前端文件列表页面增加批量选择和批量下载按钮。
2. 限制批量下载文件数量和总大小，避免性能问题。
3. 大文件场景考虑流式下载。