# 📋 诊断报告批量下载功能实现思路文档 ## 🎯 功能概述 在historylist页面的ActionPanel中添加批量下载按钮，实现诊断报告的批量下载功能。支持按日期查询、多选报告、分页显示、进度提示，适配Electron、Cordova、浏览器三端。 ## 📝 需求整理 ### 功能详细描述 - **功能入口**: historylist的右侧ActionPanel，即 `src/pages/patient/components/ActionPanel.tsx` 中提供一个批量下载按钮 - **用户操作**: 点击按钮后会打开批量下载Modal，在Modal中可以让用户选择开始时间和结束时间 - **时间选择**: Modal中提供日期时间选择器，让用户手动选择下载的时间范围 - **下载功能**: 调用downloadReportXlsx API下载用户选择时间范围内的所有报告为XLSX格式 - **进度提示**: 下载过程中显示进度提示 - **技术要求**: 可以参考诊断报告的pdf下载，适配三端，包括electron、cordova（android）、浏览器 ### 核心功能点 1. 在ActionPanel添加批量下载按钮（仅historylist页面显示） 2. 创建DiagnosticReportBatchDownloadModal组件 3. 实现日期时间范围选择功能 4. 实现批量下载逻辑，调用downloadReportXlsx API 5. 实现下载进度显示和错误处理 6. 跨平台适配（Electron/Cordova/浏览器） ## 🔌 涉及的API ### 报告相关API - **`getReportList(params: ReportQueryParams)`** - 接口: `POST /dr/api/v1/auth/report` - 参数: `{start_time?, end_time?, page?, page_size?}` - 返回: `ReportListResponse` - 用途: 分页查询报告列表（可选，用于调试或扩展） - **`downloadReportXlsx(params: {start_time, end_time})`** - 接口: `GET /dr/api/v1/auth/report/xls` - 参数: `{start_time: string, end_time: string}` (查询参数) - 返回: `Blob` (XLSX文件) - 用途: 批量下载指定时间范围内的报告为XLSX格式 ### 工具API（可选） - **`fetchDiagnosisReportContent(studyId: string)`** - 接口: `GET /dr/api/v1/auth/study/{id}/report_content` - 返回: `ReportContentResponse` - 用途: 获取单个报告的完整内容（可选，用于调试） - **`downloadDiagnosisReportPdf(studyId: string)`** - 接口: `GET /dr/api/v1/auth/study/{id}/report` - 返回: `Blob` (PDF文件) - 用途: 下载单个报告的PDF（参考实现） ## 🏗️ 架构设计 ### 核心组件关系 ``` ActionPanel (入口) ↓ DiagnosticReportBatchDownloadModal (UI容器) ↓ ├── DateRangePicker (日期选择) ├── DownloadProgress (下载进度) └── DiagnosticReportBatchDownloadService (业务逻辑) ↓ ├── DateRangeCalculator (日期范围计算) └── DownloadManager (跨平台下载) ``` ### 状态管理设计 ```typescript interface DiagnosticReportBatchDownloadState { modalVisible: boolean; downloading: boolean; progress: number; error?: string; startTime?: string; endTime?: string; } ``` ## 👥 功能参与者分析（从粗到细） ### UI层组件 - **ActionPanel.tsx**: 添加批量下载按钮，处理Modal显示 - **DiagnosticReportBatchDownloadModal**: 新建的批量下载Modal组件 - 日期时间选择器组件 - 下载进度显示组件 - 确认/取消按钮 ### 状态管理 - **Redux Slice**: 诊断报告批量下载相关的状态管理 - Modal显示状态（modalVisible: boolean） - 下载状态（downloading: boolean） - 下载进度（progress: number） - 错误信息（error?: string） - 日期范围（startTime, endTime） ### API层 - **downloadReportXlsx**: 诊断报告批量下载XLSX API - **getReportList**: 报告列表API（可选，用于验证） ### 服务层 - **downloadManager**: 跨平台下载管理器 - **DiagnosticReportBatchDownloadService**: 诊断报告批量下载业务逻辑服务 - 调用下载API - 处理进度和错误 ### 工具类 - **DateRangeValidator**: 日期范围验证工具 - **ProgressTracker**: 下载进度跟踪工具 - **FileNamer**: 文件命名生成工具 ## 📋 TODO List ### 新建文件 - [x] `src/components/DiagnosticReportBatchDownloadModal.tsx` - 诊断报告批量下载Modal组件 - [x] `src/states/patient/diagnosticReportBatchDownloadSlice.ts` - Redux状态管理 - [x] `src/services/diagnosticReportBatchDownloadService.ts` - 诊断报告批量下载业务逻辑 - [x] `src/utils/dateRangeValidator.ts` - 日期范围验证工具 - [x] `src/types/diagnosticReportBatchDownload.ts` - 诊断报告批量下载类型定义 ### 修改文件 - [x] `src/pages/patient/components/ActionPanel.tsx` - 添加诊断报告批量下载按钮和Modal触发 - [x] `src/API/report/ReportActions.ts` - 确保downloadReportXlsx API导出正确 - [x] `src/states/store.ts` - 添加diagnosticReportBatchDownload reducer ### 国际化 - [ ] 添加诊断报告批量下载Modal相关的i18n键值对 ## 📊 Mermaid 图表 ### 序列图 - 完整下载流程 ```mermaid sequenceDiagram participant U as 用户 participant AP as ActionPanel participant MODAL as DiagnosticReportBatchDownloadModal participant DRBS as DiagnosticReportBatchDownloadService participant RS as Redux Store participant AS as API Service participant DM as DownloadManager U->>AP: 点击诊断报告批量下载按钮 AP->>MODAL: 打开Modal MODAL->>RS: 设置modalVisible=true U->>MODAL: 选择开始时间和结束时间 MODAL->>RS: 更新日期范围 U->>MODAL: 点击下载按钮 MODAL->>DRBS: 调用批量下载服务 DRBS->>AS: 调用downloadReportXlsx API AS-->>DRBS: 返回XLSX数据 DRBS->>DM: 调用downloadManager下载 DM-->>DRBS: 下载进度更新 DRBS->>RS: 更新下载进度 RS-->>MODAL: 显示进度状态 DM-->>DRBS: 下载完成 DRBS->>RS: 下载完成 RS-->>MODAL: 显示完成提示 MODAL->>RS: 设置modalVisible=false ``` ### 流程图 - 用户操作流程 ```mermaid flowchart TD A[用户进入historylist页面] --> B{点击诊断报告批量下载按钮?} B -->|是| C[打开批量下载Modal] B -->|否| A C --> D[显示默认日期范围] D --> E{用户修改日期范围?} E -->|是| F[更新日期范围] E -->|否| G{点击下载按钮?} F --> G G -->|是| H[验证日期范围] G -->|否| D H --> I{日期范围有效?} I -->|否| J[显示日期错误提示] I -->|是| K[调用downloadReportXlsx API] J --> D K --> L{API成功?} L -->|是| M[显示下载进度] L -->|否| N[显示下载失败] M --> O[调用downloadManager下载] O --> P{下载成功?} P -->|是| Q[显示成功提示] P -->|否| R[显示失败提示] Q --> S[关闭Modal] R --> D N --> D S --> A ``` ### 类图 - 组件关系 ```mermaid classDiagram class ActionPanel { +handleDiagnosticReportBatchDownload() +render() } class DiagnosticReportBatchDownloadModal { +handleDateRangeChange() +handleDownload() +render() } class DiagnosticReportBatchDownloadService { +downloadReports(dateRange) } class DateRangeValidator { +validateRange(range) } class DownloadManager { +download(options) } class DiagnosticReportBatchDownloadSlice { +setModalVisible() +setDownloading() +setProgress() +setError() +setDateRange() } ActionPanel --> DiagnosticReportBatchDownloadModal DiagnosticReportBatchDownloadModal --> DiagnosticReportBatchDownloadService DiagnosticReportBatchDownloadModal --> DateRangeValidator DiagnosticReportBatchDownloadModal --> DiagnosticReportBatchDownloadSlice DiagnosticReportBatchDownloadService --> DownloadManager DiagnosticReportBatchDownloadService --> DiagnosticReportBatchDownloadSlice DiagnosticReportBatchDownloadService --> API ``` ## 🌊 交互泳道图 ``` 用户 ActionPanel DiagnosticReportBatchDownloadModal DiagnosticReportBatchDownloadService Redux Store API Service DownloadManager | | | | | | | |---点击诊断报告批量下载按钮------->| | | | | | | |---打开Modal------------>| | | | | | | |---设置modalVisible=true| | | | | | | |---更新modal状态----->| | | | | |<-----------------------|<--------------------| | | | |---显示Modal------------>| | | | | | | | | | | |---选择日期范围---------->| | | | | | | | |---更新日期范围-------->| | | | | | | |---保存日期范围------>| | | | | |<-----------------------|<--------------------| | | | | | | | | |---点击下载按钮---------->| | | | | | | | |---调用批量下载服务---->| | | | | | | |---调用downloadReportXlsx| | | | | | | |---API调用---------->| | | | | | |<--------------------| | | | | |<--------------------|---返回XLSX数据----->| | | | | |---调用downloadManager| | | | | | | | |---开始下载--------->| | | | | | | |---文件保存| | | | | | |<--------------------|<--------| | | | |<--------------------|---更新下载进度----->| | | | |---显示下载进度-------->| | | | | | | | | | | | | |<-----------------------|---下载完成---------->| | | | |---显示完成提示-------->| | | | | | |---关闭Modal------------>| | | | | | | |---设置modalVisible=false| | | ``` ## 💾 数据流 ### 下载阶段数据流 ``` 选中study列表 → DateRangeCalculator → 日期范围 → downloadReportXlsx API → XLSX数据 → DownloadManager → 文件保存 ↓ 进度更新 → Redux Store → ActionPanel显示 ``` ### 状态管理数据流 ``` 用户操作 → ActionPanel → BatchDownloadService → Redux Store → UI状态更新 ``` ## 📊 相关数据结构 ### 诊断报告批量下载相关类型 ```typescript // 日期范围 interface DateRange { start_time: string; end_time: string; } // 诊断报告批量下载状态 interface DiagnosticReportBatchDownloadState { downloading: boolean; progress: number; error?: string; startTime?: string; endTime?: string; } // Study数据结构（简化） interface StudyItem { StudyID: string; StudyDate?: string; StudyTime?: string; } ``` ### 现有数据结构复用 - `DownloadOptions`: 下载选项 - `DownloadResult`: 下载结果 - `ReportQueryParams`: 报告查询参数（用于API调用） ## 🚀 执行流程 ### 起点 用户在historylist页面的ActionPanel中点击批量下载按钮 ### 完整执行流程 1. **入口触发**: 用户点击ActionPanel中的批量下载按钮 2. **Modal打开**: ActionPanel触发打开DiagnosticReportBatchDownloadModal 3. **初始状态**: Modal显示默认的日期时间范围（例如最近7天） 4. **用户选择**: 用户可以修改开始时间和结束时间 5. **验证范围**: 点击下载前验证日期范围的有效性 6. **调用API**: 使用用户选择的日期范围调用downloadReportXlsx API 7. **开始下载**: 使用downloadManager进行跨平台文件下载 8. **进度显示**: Modal中实时显示下载进度状态 9. **完成处理**: 下载完成后显示成功提示，自动关闭Modal ### 异常处理流程 - 日期范围无效: 显示错误提示，要求用户重新选择日期范围 - API调用失败: 显示错误提示，用户可以重试 - 下载失败: 显示错误信息，用户可以重新选择日期范围重试 - 网络超时: 显示超时提示，支持重试 ## 🧪 测试方案 ### 功能测试场景 1. **正常下载流程** - ✅ 进入historylist页面，先选择一个或多个study - ✅ 点击"批量下载"按钮，按钮显示loading状态 - ✅ 自动计算选中study的日期范围 - ✅ 调用downloadReportXlsx API下载报告 - ✅ 下载完成后显示成功提示 - ✅ 文件成功保存到本地 2. **边界情况测试** - ✅ 未选中任何study时点击下载，显示错误提示 - ✅ 单个study下载功能正常 - ✅ 多个study下载功能正常 - ✅ study时间范围异常（结束时间早于开始时间） 3. **异常情况测试** - ✅ 网络错误时的错误提示 - ✅ API调用失败的错误处理 - ✅ 下载过程中断的错误处理 - ✅ 大文件下载超时处理 4. **跨平台测试** - ✅ Electron: 下载到指定目录 - ✅ 浏览器: 下载到默认下载目录 - ✅ Cordova: 移动端下载功能 ### 性能测试 - ✅ API调用响应时间 < 5秒 - ✅ 批量下载进度更新流畅 - ✅ 内存使用在合理范围内 ### 兼容性测试 - ✅ Chrome/Edge/Firefox浏览器 - ✅ Windows/Mac/Linux桌面端 - ✅ Android/iOS移动端 ## 🎨 UI设计 ### 现有UI基础 - 复用现有的ActionPanel按钮样式 - 复用现有的loading状态显示 - 复用现有的Toast/Notification组件 - 复用现有的错误提示组件 ### UI改动设计 #### ActionPanel按钮改动 - 在historylist页面添加"批量下载"按钮 - 按钮图标使用现有的下载图标 - 下载时按钮显示loading状态和禁用 - 下载完成后恢复正常状态 #### 进度提示设计 - 使用Toast组件显示下载进度 - 显示格式: "正在下载诊断报告..." - 成功后显示: "诊断报告下载完成" - 失败时显示: "下载失败: [错误信息]" #### 错误提示设计 - 未选中study: "请先选择要下载报告的检查项目" - API错误: "下载失败，请稍后重试" - 网络错误: "网络连接失败，请检查网络后重试" ## 🐛 潜在问题分析 ### 边界情况 1. **大文件下载**: XLSX文件可能很大，需要考虑内存使用 - 解决: 使用流式下载，显示准确进度 2. **网络超时**: 长列表查询或大文件下载可能超时 - 解决: 设置合理的超时时间，提供重试机制 3. **并发下载**: 用户可能同时下载多个文件 - 解决: 限制同时下载数量，队列处理 4. **权限问题**: 不同平台的文件写入权限 - 解决: 平台特定的错误处理和用户提示 ### 异常处理 1. **API错误**: 后端服务异常 - 处理: 统一的错误提示，支持重试 2. **网络中断**: 下载过程中网络断开 - 处理: 显示中断提示，支持断点续传（如可能） 3. **磁盘空间不足**: 下载目录空间不足 - 处理: 检查可用空间，提前提示 4. **文件名冲突**: 同名文件已存在 - 处理: 自动重命名或提示覆盖 ### 用户体验优化 1. **加载状态**: 查询和下载过程中的加载指示 2. **操作反馈**: 所有操作都有明确的用户反馈 3. **取消操作**: 支持随时取消正在进行的操作 4. **历史记录**: 可选功能，记录下载历史 --- ## 📝 实现计划总结 ### 核心文件清单 1. **状态管理**: `src/states/patient/diagnosticReportBatchDownloadSlice.ts` 2. **业务逻辑**: `src/services/diagnosticReportBatchDownloadService.ts` 3. **工具函数**: `src/utils/dateRangeCalculator.ts` 4. **类型定义**: `src/types/diagnosticReportBatchDownload.ts` 5. **UI改动**: `src/pages/patient/components/ActionPanel.tsx` ### 关键技术点 - Redux状态管理集成 - 日期范围自动计算 - 跨平台下载适配 - 进度显示和错误处理 - Toast/Notification提示 ### 开发优先级 1. 创建Redux状态管理和类型定义 2. 实现日期范围计算工具 3. 实现批量下载业务逻辑服务 4. 修改ActionPanel添加下载按钮 5. 完善错误处理和用户体验 6. 跨平台测试和优化 ### 人工测试步骤 1. 进入historylist页面 2. 点击ActionPanel中的"批量下载"按钮 3. 验证Modal正确打开并显示默认日期范围 4. 修改开始时间和结束时间 5. 点击下载按钮 6. 观察Modal中的下载进度显示 7. 等待下载完成，查看Modal中的完成提示 8. 验证Modal自动关闭 9. 验证文件是否成功下载到本地 10. 测试异常情况（无效日期范围、网络错误等） 这个文档提供了完整的实现思路和详细的技术方案，为后续开发提供了清晰的指导。