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
parent 1992232fda
commit 855d142fec
32 changed files with 9125 additions and 113 deletions
--- a/Phase2-测试指南.md
+++ b/Phase2-测试指南.md
@@ -0,0 +1,834 @@
+# 🧪 Phase 2 完整测试指南 - 双模式智能问答系统
+
+**创建时间**：2025-10-13  
+**测试目标**：验证全文阅读模式和逐篇精读模式的完整功能  
+**预计耗时**：60-90分钟  
+**测试人员**：____
+
+---
+
+## 📋 测试清单总览
+
+```
+☑️ 环境准备              (10分钟)
+☑️ 服务启动验证          (5分钟)
+☑️ 知识库准备            (15-20分钟)
+☑️ 全文阅读模式测试      (15分钟)
+☑️ 逐篇精读模式测试      (20分钟)
+☑️ 端到端场景测试        (15分钟)
+☑️ 问题记录与汇总        (5分钟)
+```
+
+---
+
+## 🔧 Part 1: 环境准备（10分钟）
+
+### 1.1 检查系统要求
+
+**必需服务**：
+- [ ] Docker Desktop 已启动
+- [ ] Python 3.11+ 已安装（虚拟环境）
+- [ ] Node.js 18+ 已安装
+- [ ] PostgreSQL容器运行中
+- [ ] Redis容器运行中
+
+**检查命令**：
+```bash
+docker ps
+# 应该看到：postgres、redis容器
+
+python --version
+# 应该看到：Python 3.11.x 或更高
+
+node --version
+# 应该看到：v18.x.x 或更高
+```
+
+---
+
+### 1.2 检查代码同步
+
+**Phase 2关键文件**：
+```
+✅ extraction_service/         # Python微服务
+✅ backend/src/clients/ExtractionClient.ts
+✅ backend/src/services/tokenService.ts
+✅ frontend/src/components/chat/FullTextMode.tsx
+✅ frontend/src/components/chat/DeepReadMode.tsx
+✅ frontend/src/components/chat/DocumentSelector.tsx
+```
+
+**验证方法**：
+```bash
+cd D:\MyCursor\AIclinicalresearch
+
+# 检查Python微服务
+dir extraction_service\main.py
+
+# 检查Backend文件
+dir backend\src\clients\ExtractionClient.ts
+
+# 检查Frontend组件
+dir frontend\src\components\chat\FullTextMode.tsx
+```
+
+---
+
+## 🚀 Part 2: 服务启动验证（5分钟）
+
+### 2.1 一键启动（推荐）
+
+```bash
+cd D:\MyCursor\AIclinicalresearch
+.\一键启动.bat
+```
+
+**等待时间**：约30秒
+
+**预期结果**：
+- 窗口1：Python微服务（端口8000）
+- 窗口2：Backend服务（端口3001）
+- 窗口3：Frontend服务（端口3000）
+- 自动打开浏览器：http://localhost:3000
+
+---
+
+### 2.2 手动启动（备选）
+
+**Terminal 1: Python微服务**
+```bash
+cd D:\MyCursor\AIclinicalresearch\extraction_service
+.\start.bat
+```
+✅ 看到：`Uvicorn running on http://0.0.0.0:8000`
+
+**Terminal 2: Backend**
+```bash
+cd D:\MyCursor\AIclinicalresearch\backend
+npm run dev
+```
+✅ 看到：`Server listening on http://0.0.0.0:3001`
+
+**Terminal 3: Frontend**
+```bash
+cd D:\MyCursor\AIclinicalresearch\frontend
+npm run dev
+```
+✅ 看到：`Local: http://localhost:3000/`
+
+---
+
+### 2.3 服务健康检查
+
+**Python微服务健康检查**：
+```bash
+# 浏览器访问
+http://localhost:8000/api/health
+
+# 预期返回
+{
+  "status": "healthy",
+  "nougat_available": true,
+  "pymupdf_version": "1.23.8"
+}
+```
+
+**Backend健康检查**：
+```bash
+http://localhost:3001/health
+
+# 预期返回
+{
+  "status": "ok",
+  "timestamp": "2025-10-13T..."
+}
+```
+
+**Frontend访问**：
+```bash
+http://localhost:3000
+
+# 预期：能看到登录页面或主页
+```
+
+---
+
+## 📚 Part 3: 知识库准备（15-20分钟）
+
+### 3.1 准备测试文档
+
+**推荐文档类型**：
+1. **PDF文档**（3-5个）
+   - 英文学术论文（测试Nougat）
+   - 中文学术论文（测试PyMuPDF）
+   - 混合语言文档
+
+2. **Docx文档**（1-2个）
+   - Word格式的研究报告
+
+3. **Txt文档**（1个）
+   - 纯文本文献摘要
+
+**文档大小建议**：
+- PDF：每个5-20页（1-5MB）
+- Docx：每个5-10页（<2MB）
+- Txt：每个<1MB
+
+---
+
+### 3.2 创建测试知识库
+
+**步骤**：
+
+1. **访问知识库管理**
+   ```
+   http://localhost:3000/knowledge
+   ```
+
+2. **创建新知识库**
+   - 点击"创建知识库"
+   - 名称：`Phase2测试知识库`
+   - 描述：`用于测试双模式功能`
+   - 点击"确定"
+
+3. **上传文档**
+   - 进入新知识库
+   - 点击"上传文档"
+   - 选择准备好的7-10个文档
+   - **等待处理完成**
+
+**预期处理时间**：
+| 文档类型 | 页数 | 预计时间 |
+|---------|-----|---------|
+| 中文PDF | 20页 | 30-60秒 |
+| 英文PDF | 20页 | 60-90秒 |
+| Docx | 10页 | 10-20秒 |
+| Txt | 1MB | 5-10秒 |
+
+---
+
+### 3.3 验证文档处理状态
+
+**检查清单**：
+- [ ] 所有文档显示状态：`✅ 已就绪`
+- [ ] 每个文档有Token数显示
+- [ ] 每个文档有提取方法显示（pymupdf/nougat/mammoth）
+- [ ] 没有文档显示"❌ 处理失败"
+
+**如果有失败文档**：
+```
+查看文档详情 → 查看失败原因 → 根据错误重新上传或删除
+```
+
+**验证文档信息**（点击文档查看详情）：
+```
+✅ extractedText: 有内容（不为空）
+✅ charCount: > 0
+✅ tokensCount: > 0
+✅ extractionMethod: "pymupdf" | "nougat" | "mammoth" | "direct_read"
+✅ language: "chinese" | "english"
+```
+
+---
+
+## 🌍 Part 4: 全文阅读模式测试（15分钟）
+
+### 4.1 进入全文阅读模式
+
+**步骤**：
+1. 访问：`http://localhost:3000/chat`
+2. 左侧栏选择：`⚫ 知识库模式`
+3. 选择知识库：`Phase2测试知识库`
+4. 选择工作模式：`🌍 全文阅读`
+
+**预期界面**：
+```
+┌─────────────────────────────────────────────┐
+│ 🌍 全文阅读模式                              │
+│                                             │
+│ 📊 容量使用情况                              │
+│ ┌─────────────────────────────────────┐    │
+│ │ 文件数: 7 / 50 篇                    │    │
+│ │ [████░░░░░░░░] 14%                  │    │
+│ │                                     │    │
+│ │ Token容量: 150K / 980K              │    │
+│ │ [███░░░░░░░░░] 15%                  │    │
+│ └─────────────────────────────────────┘    │
+│                                             │
+│ 已加载文档（7篇）:                           │
+│ • paper1.pdf (28K tokens)                   │
+│ • paper2.pdf (25K tokens)                   │
+│ • ...                                       │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+### 4.2 测试用例1：文献综述问题
+
+**测试目标**：验证AI能否综合所有文献回答
+
+**测试问题**：
+```
+请总结这些文献的主要研究方向和核心观点。
+```
+
+**预期结果**：
+- ✅ AI能提到多篇文献（至少3篇以上）
+- ✅ 回答包含不同文献的不同观点
+- ✅ 有明确的引用标记：`[来源1]`、`[来源2]`等
+- ✅ 点击引用标记能跳转到引用清单
+
+**评分标准**（5分制）：
+- 5分：涵盖所有文献，综述全面
+- 4分：涵盖大部分文献（70%+）
+- 3分：涵盖一半文献（50%+）
+- 2分：只涵盖少数文献（<50%）
+- 1分：基本没有综合
+
+**记录结果**：
+- 实际涵盖文献数：____/7
+- 评分：⭐⭐⭐⭐⭐
+
+---
+
+### 4.3 测试用例2：趋势分析
+
+**测试问题**：
+```
+从这些文献中，你能看出该领域的研究趋势是什么？
+```
+
+**预期结果**：
+- ✅ 能识别跨文献的共同趋势
+- ✅ 能对比不同时期的研究重点
+- ✅ 分析有深度
+
+**记录结果**：
+- 趋势识别准确度：⭐⭐⭐⭐⭐
+- 分析深度：⭐⭐⭐⭐⭐
+
+---
+
+### 4.4 测试用例3：快速查找
+
+**测试问题**：
+```
+哪些文献提到了[某个关键词]？请列出文献名称和具体内容。
+```
+
+**预期结果**：
+- ✅ 能准确找到包含关键词的文献
+- ✅ 提供文献名称
+- ✅ 引用具体内容片段
+
+**记录结果**：
+- 查找准确率：⭐⭐⭐⭐⭐
+
+---
+
+### 4.5 容量显示测试
+
+**测试目标**：验证容量指示器的准确性
+
+**检查项**：
+- [ ] 文件数显示正确（与实际上传数一致）
+- [ ] Token数显示合理（与文档大小匹配）
+- [ ] 进度条百分比正确
+- [ ] 颜色标识合理（<60%绿色，60-80%黄色，>80%红色）
+
+**记录**：
+- 显示文件数：____ / 50
+- 显示Token数：____K / 980K
+- 进度条颜色：🟢绿色 / 🟡黄色 / 🔴红色
+
+---
+
+## 🔍 Part 5: 逐篇精读模式测试（20分钟）
+
+### 5.1 进入逐篇精读模式
+
+**步骤**：
+1. 在智能问答页面
+2. 切换工作模式：`🔍 逐篇精读`
+3. **预期**：弹出文献选择器
+
+---
+
+### 5.2 测试用例4：文献选择器
+
+**功能检查**：
+
+**a) 显示所有可选文献**
+- [ ] 能看到知识库中的所有文档
+- [ ] 每个文档显示：文件名、大小、Token数
+
+**b) 多选功能**
+- [ ] 可以勾选文献
+- [ ] 最多只能选择5篇
+- [ ] 选满5篇后其他变灰不可选
+
+**c) 统计信息**
+- [ ] 底部显示：`已选X篇`
+- [ ] 底部显示：`共XXK tokens`
+- [ ] 统计实时更新
+
+**d) 确认选择**
+- [ ] "确认选择"按钮可点击
+- [ ] 点击后弹窗关闭
+- [ ] 进入精读模式
+
+**测试步骤**：
+1. 选择3篇文献（不同类型）
+   - paper1.pdf（英文，Nougat提取）
+   - paper2.pdf（中文，PyMuPDF提取）
+   - report.docx（Word文档）
+
+2. 确认选择
+
+**记录结果**：
+- 选择器UI体验：⭐⭐⭐⭐⭐
+- 功能完整性：✅ 完整 / ⚠️ 有缺陷 / ❌ 不工作
+
+---
+
+### 5.3 测试用例5：逐篇精读界面
+
+**预期界面**：
+```
+┌─────────────────────────────────────────────┐
+│ 🔍 逐篇精读模式                              │
+│                                             │
+│ 📄 文献切换器                                │
+│ ┌───────┬───────┬───────┐                  │
+│ │paper1 │paper2 │report │ (3篇)             │
+│ │ 活跃   │       │       │                   │
+│ └───────┴───────┴───────┘                  │
+│                                             │
+│ 当前文献: paper1.pdf (28K tokens)            │
+│                                             │
+│ [对话区域...]                                │
+└─────────────────────────────────────────────┘
+```
+
+**检查项**：
+- [ ] 显示所有选中的文献（3个标签）
+- [ ] 当前文献高亮显示
+- [ ] 显示当前文献的Token数
+- [ ] 输入框提示包含当前文献名
+
+---
+
+### 5.4 测试用例6：精读对话
+
+**测试目标**：验证AI专注于当前文献
+
+**测试问题1**（针对paper1.pdf）：
+```
+这篇文献的研究方法是什么？
+```
+
+**预期结果**：
+- ✅ AI回答专注于paper1.pdf
+- ✅ 回答详细（有充足对话空间）
+- ✅ 可以进行多轮追问
+
+**测试问题2**（多轮对话）：
+```
+继续问：样本量是多少？
+继续问：统计分析方法是什么？
+继续问：研究的局限性有哪些？
+```
+
+**预期结果**：
+- ✅ 每个问题都能得到详细回答
+- ✅ AI记得之前的对话上下文
+- ✅ 回答准确度高
+
+**记录结果**：
+- 回答准确度：⭐⭐⭐⭐⭐
+- 对话深度：⭐⭐⭐⭐⭐
+- 上下文记忆：✅ 正常 / ❌ 有问题
+
+---
+
+### 5.5 测试用例7：文献切换
+
+**测试目标**：验证文献切换和对话历史独立性
+
+**操作步骤**：
+
+1. **当前在paper1.pdf**
+   - 提问："这篇文献的结论是什么？"
+   - 记录AI回答
+
+2. **切换到paper2.pdf**
+   - 点击"paper2"标签
+   - **验证**：对话区域清空，显示paper2的历史（为空）
+   - 提问："这篇文献的研究对象是什么？"
+   - 记录AI回答
+
+3. **切换回paper1.pdf**
+   - 点击"paper1"标签
+   - **验证**：能看到之前的对话历史
+   - 继续提问："请继续详细说明。"
+   - **验证**：AI记得之前的上下文
+
+**检查清单**：
+- [ ] 文献切换无延迟
+- [ ] 对话历史正确保存
+- [ ] 对话历史正确加载
+- [ ] 上下文不混淆（不会把paper2的问题混入paper1）
+
+**记录结果**：
+- 切换流畅度：⭐⭐⭐⭐⭐
+- 历史保存：✅ 正常 / ❌ 有问题
+- 上下文独立性：✅ 正常 / ❌ 混淆
+
+---
+
+### 5.6 测试用例8：对话空间验证
+
+**测试目标**：验证逐篇模式有充足的对话空间
+
+**操作**：
+1. 选择1篇最大的文献（如30K tokens）
+2. 进行10轮以上的深度对话
+3. 观察AI回答质量是否下降
+
+**预期**：
+- ✅ AI回答始终详细完整
+- ✅ 不会出现"上下文太长"错误
+- ✅ 对话空间充裕（800K+ tokens）
+
+**记录结果**：
+- 对话轮数：____轮
+- 回答质量：⭐⭐⭐⭐⭐
+- 是否出错：✅ 无错误 / ❌ 出错
+
+---
+
+## 🎯 Part 6: 端到端场景测试（15分钟）
+
+### 6.1 场景1：文献综述（全文模式）
+
+**用户角色**：研究生，需要写文献综述
+
+**操作流程**：
+1. 上传10篇相关文献到知识库
+2. 选择"全文阅读模式"
+3. 提问："请总结这些文献的研究现状"
+4. 提问："有哪些研究空白？"
+5. 提问："未来研究方向是什么？"
+
+**验收标准**：
+- ✅ 3个问题都能得到综合性回答
+- ✅ 回答涵盖多篇文献
+- ✅ 分析有深度
+
+**记录**：
+- 场景完成度：✅ 完成 / ⚠️ 部分完成 / ❌ 未完成
+- 用户体验：⭐⭐⭐⭐⭐
+
+---
+
+### 6.2 场景2：核心论文精读（精读模式）
+
+**用户角色**：科研人员，需要深度分析3篇核心论文
+
+**操作流程**：
+1. 选择"逐篇精读模式"
+2. 选择3篇核心论文
+3. 对paper1进行5轮深度提问（方法、数据、结论、局限性、创新点）
+4. 切换到paper2，继续深度分析
+5. 切换到paper3，继续深度分析
+
+**验收标准**：
+- ✅ 每篇论文都能进行多轮深度对话
+- ✅ 文献切换流畅
+- ✅ 对话历史正确保存
+- ✅ AI回答准确详细
+
+**记录**：
+- 场景完成度：✅ 完成 / ⚠️ 部分完成 / ❌ 未完成
+- 用户体验：⭐⭐⭐⭐⭐
+
+---
+
+### 6.3 场景3：模式切换
+
+**测试目标**：验证两种模式可以自由切换
+
+**操作流程**：
+1. 全文模式 → 提问1个综合问题
+2. 切换到精读模式 → 选择2篇文献
+3. 精读模式 → 深度分析paper1
+4. 切换回全文模式 → 再问1个综合问题
+5. 验证历史记录是否独立
+
+**验收标准**：
+- ✅ 模式切换无错误
+- ✅ 两个模式的对话历史独立
+- ✅ 无数据丢失
+
+**记录**：
+- 切换成功率：____/4次
+- 数据一致性：✅ 正常 / ❌ 有问题
+
+---
+
+## 📝 Part 7: 问题记录与汇总（5分钟）
+
+### 7.1 功能完整性检查
+
+| 功能模块 | 状态 | 备注 |
+|---------|------|------|
+| Python微服务启动 | ✅ / ❌ | |
+| Backend服务启动 | ✅ / ❌ | |
+| Frontend页面加载 | ✅ / ❌ | |
+| 文档上传 | ✅ / ❌ | |
+| 文档处理（PDF） | ✅ / ❌ | |
+| 文档处理（Docx） | ✅ / ❌ | |
+| 文档处理（Txt） | ✅ / ❌ | |
+| Token计数 | ✅ / ❌ | |
+| 容量指示器 | ✅ / ❌ | |
+| 全文阅读模式 | ✅ / ❌ | |
+| 文献选择器 | ✅ / ❌ | |
+| 逐篇精读模式 | ✅ / ❌ | |
+| 文献切换 | ✅ / ❌ | |
+| 对话历史保存 | ✅ / ❌ | |
+
+---
+
+### 7.2 发现的问题清单
+
+**严重问题（🔴 阻断性）**：
+1. _______________________________________________
+2. _______________________________________________
+
+**中等问题（🟡 影响使用）**：
+1. _______________________________________________
+2. _______________________________________________
+
+**轻微问题（🟢 不影响主流程）**：
+1. _______________________________________________
+2. _______________________________________________
+
+---
+
+### 7.3 性能测试记录
+
+| 指标 | 预期 | 实际 | 是否达标 |
+|------|------|------|---------|
+| 页面加载时间 | <2秒 | ___秒 | ✅ / ❌ |
+| 文献选择器打开 | <1秒 | ___秒 | ✅ / ❌ |
+| 文献切换响应 | <0.5秒 | ___秒 | ✅ / ❌ |
+| AI首字响应 | <3秒 | ___秒 | ✅ / ❌ |
+| 文档上传（PDF 20页） | <60秒 | ___秒 | ✅ / ❌ |
+
+---
+
+### 7.4 用户体验评分
+
+**整体体验**：⭐⭐⭐⭐⭐
+
+**分项评分**：
+- 界面美观度：⭐⭐⭐⭐⭐
+- 操作流畅度：⭐⭐⭐⭐⭐
+- 功能易用性：⭐⭐⭐⭐⭐
+- 错误提示清晰度：⭐⭐⭐⭐⭐
+
+---
+
+### 7.5 最终结论
+
+**Phase 2验收结果**：
+
+✅ **通过验收** - 可以进入下一阶段
+- 核心功能完整
+- 性能达标
+- 无阻断性问题
+
+⚠️ **有条件通过** - 需要修复中等问题后再进入下一阶段
+- 核心功能基本完整
+- 有影响使用的问题
+- 需要优先修复
+
+❌ **未通过验收** - 需要继续完善
+- 核心功能有缺失
+- 有阻断性问题
+- 无法正常使用
+
+**测试人员签字**：________  
+**测试日期**：________  
+**建议**：________________________________________________
+
+---
+
+## 🔧 附录A：常见问题排查
+
+### A.1 Python微服务无法启动
+
+**症状**：start.bat运行后报错
+
+**排查步骤**：
+1. 检查虚拟环境
+   ```bash
+   cd extraction_service
+   dir venv
+   ```
+
+2. 重新安装依赖
+   ```bash
+   cd extraction_service
+   .\install.bat
+   ```
+
+3. 手动启动测试
+   ```bash
+   cd extraction_service
+   venv\Scripts\activate
+   python main.py
+   ```
+
+---
+
+### A.2 文档上传后一直"处理中"
+
+**症状**：文档上传后长时间不变为"已就绪"
+
+**排查步骤**：
+1. 检查Python微服务是否运行
+   ```bash
+   http://localhost:8000/api/health
+   ```
+
+2. 查看Backend日志
+   - 找到Backend的Terminal窗口
+   - 查看是否有错误日志
+
+3. 查看Python微服务日志
+   - 找到Python微服务的Terminal窗口
+   - 查看处理进度
+
+4. 手动测试提取
+   ```bash
+   http://localhost:8000/docs
+   # 使用Swagger UI测试 /api/extract 接口
+   ```
+
+---
+
+### A.3 容量显示不准确
+
+**症状**：容量指示器数字不对
+
+**排查步骤**：
+1. 刷新页面
+2. 检查Backend API
+   ```bash
+   http://localhost:3001/api/v1/knowledge-bases/{kbId}/document-selection
+   ```
+3. 检查数据库数据
+   - 使用Prisma Studio查看documents表
+   - 验证tokensCount字段
+
+---
+
+### A.4 文献选择器空白
+
+**症状**：点击"逐篇精读"后弹窗空白
+
+**排查步骤**：
+1. 打开浏览器Console（F12）
+2. 查看是否有JavaScript错误
+3. 检查Backend API
+   ```bash
+   http://localhost:3001/api/v1/knowledge-bases/{kbId}/documents
+   ```
+4. 确认知识库中有已完成的文档
+
+---
+
+### A.5 文献切换后对话历史丢失
+
+**症状**：切换文献后看不到之前的对话
+
+**排查步骤**：
+1. 打开浏览器Console
+2. 查看是否有React状态错误
+3. 检查LocalStorage/SessionStorage
+4. 尝试刷新页面重新进入
+
+---
+
+## 🔧 附录B：测试数据准备建议
+
+### B.1 推荐测试文档
+
+**英文PDF（Nougat测试）**：
+- 学术论文，包含表格和公式
+- 大小：5-20页
+- 示例：Nature、Science期刊论文
+
+**中文PDF（PyMuPDF测试）**：
+- 中文学术论文
+- 大小：10-30页
+- 示例：中文核心期刊论文
+
+**Word文档（Mammoth测试）**：
+- 研究报告或综述
+- 大小：5-10页
+- 包含段落、列表、表格
+
+**文本文件（编码测试）**：
+- 纯文本文献摘要
+- 大小：<1MB
+- 测试UTF-8、GBK编码
+
+---
+
+### B.2 测试场景示例
+
+**场景：阿尔兹海默病研究**
+- 上传7-10篇相关论文
+- 测试问题：
+  - "这些文献的主要研究方向是什么？"
+  - "有哪些治疗方法被提到？"
+  - "样本量分布是怎样的？"
+
+**场景：COVID-19研究**
+- 上传8-12篇相关论文
+- 测试问题：
+  - "这些文献发表在哪些期刊？"
+  - "研究方法有哪些？"
+  - "主要发现是什么？"
+
+---
+
+## 📞 联系与反馈
+
+**测试问题反馈**：
+- 记录在本文档的"问题清单"部分
+- 截图关键错误信息
+- 记录复现步骤
+
+**测试完成后**：
+- 保存此文档
+- 整理测试结果
+- 准备与开发团队Review
+
+---
+
+**祝测试顺利！** 🎉
+
+如有任何问题，随时记录在"问题清单"中。
+
+
+
+
+
+
+
+
+