诊断报告批量下载功能实现文档.md 19 KB
📋 诊断报告批量下载功能实现思路文档
🎯 功能概述
在historylist页面的ActionPanel中添加批量下载按钮，实现诊断报告的批量下载功能。支持按日期查询、多选报告、分页显示、进度提示，适配Electron、Cordova、浏览器三端。
📝 需求整理
功能详细描述
- 功能入口: historylist的右侧ActionPanel，即
src/pages/patient/components/ActionPanel.tsx中提供一个批量下载按钮 - 用户操作: 点击按钮后会打开批量下载Modal，在Modal中可以让用户选择开始时间和结束时间
- 时间选择: Modal中提供日期时间选择器，让用户手动选择下载的时间范围
- 下载功能: 调用downloadReportXlsx API下载用户选择时间范围内的所有报告为XLSX格式
- 进度提示: 下载过程中显示进度提示
- 技术要求: 可以参考诊断报告的pdf下载，适配三端，包括electron、cordova（android）、浏览器
核心功能点
- 在ActionPanel添加批量下载按钮（仅historylist页面显示）
- 创建DiagnosticReportBatchDownloadModal组件
- 实现日期时间范围选择功能
- 实现批量下载逻辑，调用downloadReportXlsx API
- 实现下载进度显示和错误处理
- 跨平台适配（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 (跨平台下载)
状态管理设计
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
新建文件
-
src/components/DiagnosticReportBatchDownloadModal.tsx- 诊断报告批量下载Modal组件 -
src/states/patient/diagnosticReportBatchDownloadSlice.ts- Redux状态管理 -
src/services/diagnosticReportBatchDownloadService.ts- 诊断报告批量下载业务逻辑 -
src/utils/dateRangeValidator.ts- 日期范围验证工具 -
src/types/diagnosticReportBatchDownload.ts- 诊断报告批量下载类型定义
修改文件
-
src/pages/patient/components/ActionPanel.tsx- 添加诊断报告批量下载按钮和Modal触发 -
src/API/report/ReportActions.ts- 确保downloadReportXlsx API导出正确 -
src/states/store.ts- 添加diagnosticReportBatchDownload reducer
国际化
- 添加诊断报告批量下载Modal相关的i18n键值对
📊 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
流程图 - 用户操作流程
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
类图 - 组件关系
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状态更新
📊 相关数据结构
诊断报告批量下载相关类型
// 日期范围
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中点击批量下载按钮
完整执行流程
- 入口触发: 用户点击ActionPanel中的批量下载按钮
- Modal打开: ActionPanel触发打开DiagnosticReportBatchDownloadModal
- 初始状态: Modal显示默认的日期时间范围（例如最近7天）
- 用户选择: 用户可以修改开始时间和结束时间
- 验证范围: 点击下载前验证日期范围的有效性
- 调用API: 使用用户选择的日期范围调用downloadReportXlsx API
- 开始下载: 使用downloadManager进行跨平台文件下载
- 进度显示: Modal中实时显示下载进度状态
- 完成处理: 下载完成后显示成功提示，自动关闭Modal
异常处理流程
- 日期范围无效: 显示错误提示，要求用户重新选择日期范围
- API调用失败: 显示错误提示，用户可以重试
- 下载失败: 显示错误信息，用户可以重新选择日期范围重试
- 网络超时: 显示超时提示，支持重试
🧪 测试方案
功能测试场景
正常下载流程
- ✅ 进入historylist页面，先选择一个或多个study
- ✅ 点击"批量下载"按钮，按钮显示loading状态
- ✅ 自动计算选中study的日期范围
- ✅ 调用downloadReportXlsx API下载报告
- ✅ 下载完成后显示成功提示
- ✅ 文件成功保存到本地
边界情况测试
- ✅ 未选中任何study时点击下载，显示错误提示
- ✅ 单个study下载功能正常
- ✅ 多个study下载功能正常
- ✅ study时间范围异常（结束时间早于开始时间）
异常情况测试
- ✅ 网络错误时的错误提示
- ✅ API调用失败的错误处理
- ✅ 下载过程中断的错误处理
- ✅ 大文件下载超时处理
跨平台测试
- ✅ 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错误: "下载失败，请稍后重试"
- 网络错误: "网络连接失败，请检查网络后重试"
🐛 潜在问题分析
边界情况
大文件下载: XLSX文件可能很大，需要考虑内存使用
- 解决: 使用流式下载，显示准确进度
网络超时: 长列表查询或大文件下载可能超时
- 解决: 设置合理的超时时间，提供重试机制
并发下载: 用户可能同时下载多个文件
- 解决: 限制同时下载数量，队列处理
权限问题: 不同平台的文件写入权限
- 解决: 平台特定的错误处理和用户提示
异常处理
API错误: 后端服务异常
- 处理: 统一的错误提示，支持重试
网络中断: 下载过程中网络断开
- 处理: 显示中断提示，支持断点续传（如可能）
磁盘空间不足: 下载目录空间不足
- 处理: 检查可用空间，提前提示
文件名冲突: 同名文件已存在
- 处理: 自动重命名或提示覆盖
用户体验优化
- 加载状态: 查询和下载过程中的加载指示
- 操作反馈: 所有操作都有明确的用户反馈
- 取消操作: 支持随时取消正在进行的操作
- 历史记录: 可选功能，记录下载历史
📝 实现计划总结
核心文件清单
- 状态管理:
src/states/patient/diagnosticReportBatchDownloadSlice.ts - 业务逻辑:
src/services/diagnosticReportBatchDownloadService.ts - 工具函数:
src/utils/dateRangeCalculator.ts - 类型定义:
src/types/diagnosticReportBatchDownload.ts - UI改动:
src/pages/patient/components/ActionPanel.tsx
关键技术点
- Redux状态管理集成
- 日期范围自动计算
- 跨平台下载适配
- 进度显示和错误处理
- Toast/Notification提示
开发优先级
- 创建Redux状态管理和类型定义
- 实现日期范围计算工具
- 实现批量下载业务逻辑服务
- 修改ActionPanel添加下载按钮
- 完善错误处理和用户体验
- 跨平台测试和优化
人工测试步骤
- 进入historylist页面
- 点击ActionPanel中的"批量下载"按钮
- 验证Modal正确打开并显示默认日期范围
- 修改开始时间和结束时间
- 点击下载按钮
- 观察Modal中的下载进度显示
- 等待下载完成，查看Modal中的完成提示
- 验证Modal自动关闭
- 验证文件是否成功下载到本地
- 测试异常情况（无效日期范围、网络错误等）
这个文档提供了完整的实现思路和详细的技术方案，为后续开发提供了清晰的指导。