HaHafeng
855d142fec
- Add Git commit preparation checklist - Add Phase testing guides and issue tracking - Add utility scripts (env setup, test data initialization) - Add temp migration SQL files (for reference) - Update startup scripts and README - Remove obsolete scripts
315 lines
8.6 KiB
Markdown
315 lines
8.6 KiB
Markdown
# Phase 3 批处理模式 - 快速参考
|
||
|
||
**完成时间**：2025-10-12
|
||
**开发用时**：6小时（开发）+ 2小时（测试修复）
|
||
**状态**：✅ 全部完成，测试通过
|
||
|
||
---
|
||
|
||
## 🎯 核心概念
|
||
|
||
**批处理模式 ≠ 对话**
|
||
**批处理模式 = 任务执行器 + 数据提取器**
|
||
|
||
### 与其他模式的区别
|
||
|
||
| 模式 | 交互方式 | 输出 | 适用场景 |
|
||
|------|---------|------|---------|
|
||
| 全文阅读 | 对话式 | 自然语言 | 文献综述 |
|
||
| 逐篇精读 | 对话式 | 自然语言 | 深度分析 |
|
||
| **批处理** | **任务式** | **结构化表格** | **批量提取** |
|
||
|
||
---
|
||
|
||
## ⚙️ 核心参数
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 文献数量 | **3-50篇** | 最少3篇，最多50篇 |
|
||
| 并发数 | **固定3** | 避免API限流 |
|
||
| 预设模板 | **1个** | 临床研究信息提取（8字段） |
|
||
| 自定义模板 | **支持** | 文本块显示（3列） |
|
||
| 失败重试 | **支持** | 单独重试失败项 |
|
||
| 导出格式 | **Excel** | 双Sheet设计 |
|
||
|
||
---
|
||
|
||
## 📋 预设模板：临床研究信息提取
|
||
|
||
### 8个提取字段
|
||
|
||
1. **研究目的** - 研究问题或假设
|
||
2. **研究设计** - RCT、队列研究等
|
||
3. **研究对象** - 纳入/排除标准
|
||
4. **样本量** - text类型，保留原文（如"干预组156人，对照组152人"）
|
||
5. **干预组** - 实验组干预措施
|
||
6. **对照组** - 对照组情况
|
||
7. **结果及数据** - 主要结局指标数据
|
||
8. **牛津评级** - 证据等级（1a/1b/2a/2b/3a/3b/4/5）
|
||
|
||
### 牛津评级标准
|
||
|
||
- **1a**：系统评价/Meta分析
|
||
- **1b**：单个RCT
|
||
- **2a**：设计良好的对照研究（无随机化）
|
||
- **2b**：准实验研究（队列、病例对照）
|
||
- **3a**：描述性研究（横断面、病例系列）
|
||
- **3b**：个案报告
|
||
- **4**：专家意见
|
||
- **5**：基础研究（动物、体外）
|
||
|
||
---
|
||
|
||
## 🗂️ 文件结构
|
||
|
||
### 后端文件（6个新建）
|
||
|
||
```
|
||
backend/src/
|
||
├── templates/
|
||
│ └── clinicalResearch.ts # 预设模板配置
|
||
├── utils/
|
||
│ └── jsonParser.ts # JSON解析工具
|
||
├── services/
|
||
│ └── batchService.ts # 批处理核心逻辑
|
||
├── controllers/
|
||
│ └── batchController.ts # API控制器
|
||
└── routes/
|
||
└── batchRoutes.ts # 路由定义
|
||
```
|
||
|
||
### 前端文件（13个新建）
|
||
|
||
```
|
||
frontend/src/
|
||
├── api/
|
||
│ └── batchApi.ts # API封装
|
||
├── hooks/
|
||
│ └── useBatchTask.ts # 状态管理
|
||
└── components/chat/
|
||
├── TaskDefinition.tsx/.css # 任务定义
|
||
├── DocumentSelection.tsx/.css # 文献选择
|
||
├── BatchProgress.tsx/.css # 执行进度
|
||
├── PresetTable.tsx # 预设表格（8列）
|
||
├── CustomTable.tsx # 自定义表格（3列）
|
||
├── BatchResults.tsx/.css # 结果展示
|
||
└── BatchMode.tsx/.css # 批处理主组件
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API端点
|
||
|
||
### 后端API
|
||
|
||
```
|
||
GET /api/v1/batch/templates # 获取模板列表
|
||
POST /api/v1/batch/execute # 执行批处理
|
||
GET /api/v1/batch/tasks/:taskId # 获取任务状态
|
||
GET /api/v1/batch/tasks/:taskId/results # 获取任务结果
|
||
POST /api/v1/batch/tasks/:taskId/retry-failed # 重试失败项
|
||
```
|
||
|
||
**测试状态**：✅ 模板API已验证通过
|
||
|
||
---
|
||
|
||
## 🎨 UI设计
|
||
|
||
### 三栏布局
|
||
|
||
```
|
||
┌────────┬───────────────┬───────────────┐
|
||
│ 模式 │ 任务定义 │ 进度/结果 │
|
||
│ 选择 │ + │ │
|
||
│ (120px)│ 文献选择 │ │
|
||
│ │ + │ │
|
||
│ ○ 全文│ 开始按钮 │ │
|
||
│ ○ 精读│ │ │
|
||
│ ● 批处理│ │ │
|
||
└────────┴───────────────┴───────────────┘
|
||
```
|
||
|
||
### 步骤流程
|
||
|
||
```
|
||
Step 1: 定义任务
|
||
↓
|
||
Step 2: 选择文献（3-50篇）
|
||
↓
|
||
Step 3: 开始批处理
|
||
↓
|
||
Step 4: 查看结果，导出Excel
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 结果展示
|
||
|
||
### 预设模板（8列表格）
|
||
|
||
```
|
||
┌──┬────────┬──────┬──────┬──────┬────┬────┬────┬──────┬────┐
|
||
│#│文献名称 │研究 │研究 │研究 │样本│干预│对照│结果 │牛津│
|
||
│ │ │目的 │设计 │对象 │量 │组 │组 │数据 │评级│
|
||
└──┴────────┴──────┴──────┴──────┴────┴────┴────┴──────┴────┘
|
||
```
|
||
|
||
### 自定义模板（3列表格）
|
||
|
||
```
|
||
┌──┬──────────┬──────────────────────┐
|
||
│#│文献名称 │提取结果（文本块） │
|
||
└──┴──────────┴──────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📥 Excel导出
|
||
|
||
### 文件结构
|
||
|
||
**Sheet 1: 提取结果**
|
||
- 预设模板：8列数据
|
||
- 自定义模板：3列数据
|
||
|
||
**Sheet 2: 任务信息**
|
||
- 任务名称、模板类型
|
||
- 执行时间、完成时间
|
||
- 文献统计（总数、成功、失败）
|
||
- 总用时
|
||
|
||
**文件名格式**：
|
||
- 预设：`批处理结果_临床研究信息提取_2025-10-13.xlsx`
|
||
- 自定义：`批处理结果_自定义任务_2025-10-13.xlsx`
|
||
|
||
---
|
||
|
||
## ⚡ 性能指标
|
||
|
||
| 指标 | 预期值 |
|
||
|------|--------|
|
||
| 单文档处理 | 15-25秒 |
|
||
| 10篇总时长 | 5-8分钟 |
|
||
| 50篇总时长 | 25-40分钟 |
|
||
| JSON解析成功率 | >90% |
|
||
|
||
**效率提升**：
|
||
- 手动：10篇 × 10分钟 = 100分钟
|
||
- 批处理：10篇 × 20秒 = ~7分钟
|
||
- **提升约14倍** 🚀
|
||
|
||
---
|
||
|
||
## ✅ 已完成的收尾工作
|
||
|
||
### 测试与修复（已完成）
|
||
|
||
1. ✅ **类型定义** - 已更新
|
||
2. ✅ **依赖安装** - xlsx已安装
|
||
3. ✅ **Frontend启动** - 正常运行
|
||
4. ✅ **端到端测试** - 全流程测试通过
|
||
5. ✅ **问题修复** - 5个问题已全部修复
|
||
|
||
### 修复的问题
|
||
1. ✅ API导入路径错误
|
||
2. ✅ 数据库用户数据缺失
|
||
3. ✅ 批处理页面空白问题
|
||
4. ✅ 结果页面布局问题（改为垂直布局）
|
||
5. ✅ 表格显示优化（列宽、换行、滚动条）
|
||
|
||
**详细修复记录**：见 `docs/05-每日进度/Phase3-最终测试-修复总结.md`
|
||
|
||
---
|
||
|
||
## ✅ 验收清单（已完成）
|
||
|
||
### 功能测试
|
||
|
||
- [x] 进入批处理模式（界面正常显示）✅
|
||
- [x] 模板选择（预设/自定义切换）✅
|
||
- [x] 文献选择（3-50篇限制生效）✅
|
||
- [x] 执行任务（进度显示正常）✅
|
||
- [x] 查看结果（表格显示正确）✅
|
||
- [x] 导出Excel（文件格式正确）✅
|
||
- [x] 重试失败项（如有失败）✅
|
||
|
||
### 边界测试
|
||
|
||
- [x] 选择<3篇文献（应提示错误）✅
|
||
- [x] 选择>50篇文献（应提示错误）✅
|
||
- [x] 自定义模板空提示词（应提示错误）✅
|
||
- [x] JSON解析失败（应标记失败，不影响其他）✅
|
||
|
||
### UI优化测试
|
||
|
||
- [x] 垂直布局显示正常 ✅
|
||
- [x] 表格列宽合理 ✅
|
||
- [x] 单元格内容换行显示 ✅
|
||
- [x] 横向滚动条可用 ✅
|
||
- [x] 牛津评级列固定右侧 ✅
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
### 设计文档
|
||
- `docs/05-每日进度/Phase3-批处理模式-完整设计.md` (设计方案)
|
||
|
||
### 完成报告
|
||
- `docs/05-每日进度/Phase3-完成总结.md` (完成总结)
|
||
- `Phase3-Day1-后端完成总结.md` (后端详情)
|
||
|
||
### 开发计划
|
||
- `docs/04-开发计划/开发里程碑.md` (整体进度)
|
||
|
||
### 测试工具
|
||
- `backend/test-batch-api.js` (API测试脚本)
|
||
|
||
---
|
||
|
||
## 💡 使用提示
|
||
|
||
### 最佳实践
|
||
|
||
**文献数量**：
|
||
- 首次测试：5-10篇
|
||
- 常规使用：10-20篇
|
||
- 大规模：30-50篇
|
||
|
||
**模板选择**：
|
||
- 标准临床研究 → 使用预设模板
|
||
- 特殊需求 → 使用自定义模板
|
||
|
||
**性能优化**：
|
||
- 避免超大文献（>200K tokens）
|
||
- 分批处理（如需处理100+篇）
|
||
- 优先使用DeepSeek-V3（快且便宜）
|
||
|
||
---
|
||
|
||
## 🎉 总结
|
||
|
||
**Phase 3 批处理模式：**
|
||
- ✅ 任务式交互（非对话）
|
||
- ✅ 双模板系统（预设8字段 + 自定义文本）
|
||
- ✅ 固定3并发（稳定可靠）
|
||
- ✅ 完整的Excel导出
|
||
- ✅ 友好的UI体验
|
||
- ✅ ~4,000行代码（6小时完成）
|
||
|
||
**核心价值**：
|
||
- 批量信息提取
|
||
- 结构化数据输出
|
||
- 效率提升14倍
|
||
- 可追溯、可归档
|
||
|
||
**已完成**：开发 + 测试 + 修复 + 优化 ✅
|
||
|
||
---
|
||
|
||
**快速参考版本**：2.0
|
||
**最后更新**：2025-10-12
|
||
**状态**：✅ 全部完成，已通过最终测试
|
||
|