Files

HaHafeng 855d142fec chore: add remaining test docs, scripts and temp files

- 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

2025-11-16 15:44:55 +08:00

11 KiB

Raw Blame History

Phase 3 批处理模式 - 最终收尾与测试指南

完成时间：2025-10-13
状态：✅ 开发100%完成，等待测试验证

✅ 已完成检查清单

开发完成度：100%

后端开发：100%
- 数据库Schema（3个表）
- 数据库迁移
- 预设模板（临床研究，8字段）
- JSON解析工具
- 批处理服务（p-queue，固定3并发）
- API控制器（5个端点）
- 路由注册
- p-queue依赖安装
前端开发：100%
- API封装（batchApi.ts）
- 状态管理（useBatchTask.ts）
- UI组件（7个组件，14个文件）
- 集成到ChatPage
- 更新ModeSelector
- xlsx依赖安装 ✅
类型定义：100%
- KnowledgeBaseMode包含'batch' ✅
- 批处理相关类型定义完整
基础测试：100%
- 后端API测试（模板API验证通过）

🧪 端到端测试指南

前提条件

确保服务已启动：

✅ Backend服务运行中（http://localhost:3001）
⏳ Frontend服务需要启动（http://localhost:3000）
✅ PostgreSQL数据库运行中
⏳ 知识库中有测试文献（至少3篇，已提取extractedText）

测试步骤

测试1：预设模板测试（推荐）

操作流程：

启动Frontend

cd D:\MyCursor\AIclinicalresearch\frontend
npm run dev

进入批处理模式
- 打开浏览器：http://localhost:3000
- 智能问答 → 知识库模式
- 选择知识库
- 点击"📦 批处理"按钮
定义任务（第1步）
- 默认选中"● 临床研究信息提取"
- 查看8个提取字段预览
- 确认字段正确
选择文献（第2步）
- 滚动查看文献列表
- 勾选3-10篇文献（测试建议5-7篇）
- 查看"已选择：X/50篇"统计
- 查看预计处理时间
开始批处理（第3步）
- 点击"🚀 开始批处理"按钮
- 等待任务开始
观察进度
- 查看进度条（百分比）
- 查看统计卡片（成功/失败/处理中/等待）
- 查看时间信息（已用时、平均速度）
- 等待任务完成（约5-10分钟）
查看结果
- 任务完成后自动切换到结果页
- 查看8列表格
- 检查每列数据是否正确
- 查看牛津评级标签颜色
导出Excel
- 点击"📥 导出Excel"按钮
- 文件自动下载
- 打开文件验证：
  - Sheet1：提取结果（8列）
  - Sheet2：任务信息

预期结果：

✅ UI流程流畅
✅ 进度实时更新
✅ 结果表格正确（8列）
✅ Excel文件格式正确
✅ 数据提取准确

测试2：自定义模板测试

操作流程：

选择自定义模板
- 点击"○ 自定义任务"单选按钮

输入自定义提示词

请总结这篇文献的研究方法、主要发现和局限性，用3-5段话描述。

选择文献
- 选择3-5篇文献（测试用较少文献）
执行任务
- 点击"🚀 开始批处理"
- 等待完成
查看结果
- 结果表格应为3列（序号、文献名、提取结果）
- 文本块显示AI的回答
- 点击"查看完整内容"链接
导出Excel
- 验证3列格式

预期结果：

✅ 文本块完整显示
✅ 格式为3列（不是8列）
✅ Excel导出正确

测试3：边界测试

场景1：文献数量不足

只选择1-2篇文献
点击"开始批处理"
预期：提示"请至少选择3篇文献"

场景2：文献数量过多

选择51篇或更多
预期：提示"最多只能选择50篇文献"

场景3：自定义模板空提示词

选择"自定义任务"
不输入提示词（留空）
选择文献后点击开始
预期：提示"请输入自定义提示词"

场景4：失败重试

如果有文档处理失败
点击"重试失败项"按钮
预期：重新处理失败的文档

🔍 检查要点

Frontend控制台

应该看到：

组件正常渲染
API调用成功
进度更新日志

不应该看到：

TypeScript类型错误
组件渲染错误
API调用失败（404/500）

Backend控制台

应该看到：

📦 [BatchController] 收到批处理请求
✅ [BatchController] 创建任务: <task-id>
📦 [BatchService] 开始执行批处理任务
✅ [BatchService] 使用已存在的任务: <task-id>
🔄 [BatchService] 处理文档 1/10: <doc-id>
✅ [BatchService] 文档处理成功: <filename> (2300ms)
...
🎉 [BatchService] 批处理任务完成

不应该看到：

数据库错误
LLM API错误（除非真的失败）
JSON解析错误（除非AI输出异常）

📋 功能验收清单

核心功能

模板选择：预设/自定义切换正常
字段预览：预设模板显示8个字段
文献选择：3-50篇限制生效
批量操作：全选/清空/反选正常
搜索过滤：文献搜索正常
开始执行：任务正常启动
进度显示：进度条和统计实时更新
结果切换：执行完成后自动显示结果
表格展示：预设8列/自定义3列正确
Excel导出：文件下载并格式正确
失败重试：重试按钮正常工作
新建任务：重置状态正常

用户体验

UI布局清晰（三栏）
操作流程直观
提示信息友好
错误处理完善
响应速度快
无明显bug

🐛 可能遇到的问题

问题1：Frontend启动报类型错误

原因：某些导入路径或类型不匹配

解决：

检查控制台错误信息
调整导入路径或类型定义
重新启动Frontend

问题2：批处理模式不显示

原因：路由或条件判断问题

检查：

是否选择了知识库
是否点击了"批处理"按钮
ChatPage.tsx中的条件判断

问题3：执行任务后无进度

原因：API调用失败或轮询问题

检查：

Backend控制台是否有错误
Frontend控制台Network标签
task_id是否正确返回

问题4：结果表格为空

原因：JSON解析失败或数据格式问题

检查：

Backend日志中的JSON解析结果
原始AI输出（raw_output字段）
是否有extractedText

问题5：Excel导出失败

原因：xlsx库未正确导入或数据格式问题

解决：

确认xlsx已安装（✅已完成）
检查浏览器控制台错误
验证results数据结构

📊 测试数据建议

理想测试场景

知识库：临床研究文献库

文献要求：

至少5-10篇临床研究文献
已上传并提取extractedText
包含完整的研究信息（目的、设计、结果等）

文献类型：

建议：RCT研究（容易提取PICO）
样本量信息明确
结果数据完整

🎯 验收标准

必须通过（核心功能）

✅ 预设模板流程：

选择临床研究信息提取模板
选择5-10篇文献
执行任务，进度正常显示
结果显示为8列表格
数据提取基本准确
Excel导出成功（双Sheet）

✅ 自定义模板流程：

选择自定义任务
输入提示词
执行任务
结果显示为3列（文本块）
Excel导出成功

建议通过（用户体验）

UI美观、响应流畅
错误提示清晰
无明显卡顿
边界测试通过

🚀 启动测试

命令

# Backend（应该已经运行中）
cd D:\MyCursor\AIclinicalresearch\backend
npm run dev

# Frontend（需要启动）
cd D:\MyCursor\AIclinicalresearch\frontend
npm run dev

访问地址

Frontend: http://localhost:3000
Backend: http://localhost:3001

📝 测试记录模板

测试执行记录

测试时间：_____________
测试人员：_____________

预设模板测试

检查项	状态	备注
模板选择	⬜ 通过 / ⬜ 失败
文献选择	⬜ 通过 / ⬜ 失败
任务执行	⬜ 通过 / ⬜ 失败
进度显示	⬜ 通过 / ⬜ 失败
结果表格	⬜ 通过 / ⬜ 失败
Excel导出	⬜ 通过 / ⬜ 失败

自定义模板测试

检查项	状态	备注
提示词输入	⬜ 通过 / ⬜ 失败
任务执行	⬜ 通过 / ⬜ 失败
文本块显示	⬜ 通过 / ⬜ 失败
Excel导出	⬜ 通过 / ⬜ 失败

边界测试

检查项	状态	备注
<3篇提示	⬜ 通过 / ⬜ 失败
>50篇提示	⬜ 通过 / ⬜ 失败
空提示词拦截	⬜ 通过 / ⬜ 失败
失败重试	⬜ 通过 / ⬜ 失败

发现的问题

（记录测试中发现的任何问题）

🎉 Phase 3 开发总结

开发成果

代码统计：

后端：~1,700行（6个新文件 + 2个修改）
前端：~2,300行（14个新文件 + 2个修改）
总计：~4,000行代码

开发时间：

设计：1小时
后端：2小时
前端：4小时
测试：待验证
总计：~8小时（1个工作日）

技术亮点

双模板系统
- 预设模板：8字段结构化
- 自定义模板：文本块灵活
并发控制
- p-queue固定3并发
- Promise.allSettled容错
容错JSON解析
- 支持多种AI输出格式
- 自动填充缺失字段
完整Excel导出
- 双Sheet设计
- 数据可追溯
三栏布局
- 流程清晰
- 步骤引导

核心价值

效率提升：

手动处理：10篇 × 10分钟 = 100分钟
批处理：10篇 × 20秒 = ~7分钟
提升约14倍 🚀

适用场景：

系统性文献综述
批量信息提取
多文献对比研究
结构化数据归档

📄 相关文档

设计与开发

docs/05-每日进度/Phase3-批处理模式-完整设计.md - 完整设计方案
docs/05-每日进度/Phase3-完成总结.md - 完成报告
Phase3-Day1-后端完成总结.md - 后端详情
Phase3-快速参考.md - 快速参考
docs/04-开发计划/开发里程碑.md - 整体进度

测试工具

backend/test-batch-api.js - 后端API测试脚本

🎯 下一步

立即执行（必需）

启动Frontend测试
```
cd frontend
npm run dev
```
端到端测试（15-30分钟）
- 预设模板测试
- 自定义模板测试
- 边界测试
问题修复（如有）
- 记录问题
- 修复bug
- 重新测试
验收决策
- 通过 → Phase 3完成 🎉
- 有问题 → 继续修复

可选优化（Phase 3.1）

WebSocket进度推送（替代HTTP轮询）
任务历史记录
更多预设模板
结果可视化
智能文献选择

✅ 完成标志

Phase 3批处理模式验收通过标准：

✅ 能进入批处理模式
✅ 能选择模板和文献
✅ 能执行任务（3-50篇）
✅ 进度显示正常
✅ 结果表格正确（预设8列/自定义3列）
✅ Excel导出成功
✅ 无阻塞性bug

如果以上全部通过 → Phase 3 正式完成！ 🎉

测试指南版本：1.0
创建时间：2025-10-13
状态：✅ 准备就绪，等待测试

祝测试顺利！ 🚀

11 KiB Raw Blame History Unescape Escape