AIclinicalresearch/Phase2-测试指南.md

# 🧪 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

---

**祝测试顺利！** 🎉

如有任何问题，随时记录在"问题清单"中。