rag/docs/测试指南.md

# 测试指南

> **文档类型**: 测试指南
> **创建日期**: 2026-04-05
> **最后更新**: 2026-04-13
> **文档总数**: 21个测试文档

---

## 一、测试文档清单

### 1.1 文档目录结构

```
documents/
├── public/          # 公开文档 - 所有人可见（包括未登录用户）
│   ├── 公司简介.txt
│   ├── 产品手册.pdf
│   ├── 产品手册.txt
│   ├── 员工手册.txt
│   ├── 组织架构.xlsx
│   ├── 组织架构说明.txt
│   └── 常见问题.txt
│
├── internal/        # 内部文档 - 登录用户可见
│   ├── 差旅管理办法.txt
│   ├── 请假制度.docx
│   ├── 信息安全管理制度.pdf
│   ├── 项目管理制度.xlsx
│   └── 会议纪要_2024Q1.txt
│
├── confidential/    # 机密文档 - 管理层及以上可见
│   ├── 财务报表_2024.pdf
│   ├── 薪酬制度.docx
│   ├── 合同台账.xlsx
│   ├── 战略规划.txt
│   └── 人员名册.txt
│
└── secret/          # 绝密文档 - 仅管理员可见
    ├── 董事会决议.pdf
    ├── 并购方案.docx
    ├── 股权结构.xlsx
    └── 核心技术机密.txt
```

### 1.2 文档格式分布

| 格式 | 数量 | 测试目的 |
|------|------|---------|
| TXT | 10个 | 测试纯文本解析、编码识别 |
| PDF | 4个 | 测试PDF解析、表格提取、中文字体 |
| DOCX | 3个 | 测试Word解析、标题样式、表格处理 |
| XLSX | 4个 | 测试Excel解析、多工作表、单元格数据 |

### 1.3 权限级别

| 目录 | 权限级别 | 可见角色 |
|------|---------|---------|
| public | public | 所有人（含未登录用户） |
| internal | internal | user, manager, admin |
| confidential | confidential | manager, admin |
| secret | secret | admin only |

---

## 二、测试环境准备

### 2.1 环境检查

```bash
# 检查 Python 版本
python --version  # 需要 Python 3.8+

# 检查依赖安装
pip list | grep -E "chromadb|sentence-transformers|neo4j|flask|jieba"

# 检查模型文件
ls models/bge-base-zh-v1.5/
```

### 2.2 启动 Neo4j（用于 Graph RAG）

```bash
# Docker 启动 Neo4j
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password123 \
  -v neo4j_data:/data \
  neo4j:latest

# 等待 Neo4j 启动（约30秒）
# 访问 http://localhost:7474 验证
```

### 2.3 配置检查

确保 `config.py` 配置正确：
```python
# API配置
DASHSCOPE_API_KEY = "your-api-key"
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
DASHSCOPE_MODEL = "qwen3.5-plus"

# Neo4j配置
NEO4J_URI = "bolt://localhost:7687"
NEO4J_USER = "neo4j"
NEO4J_PASSWORD = "password123"
USE_GRAPH_RAG = True
```

---

## 三、测试执行流程

### 3.1 第一阶段：索引构建测试

#### 测试 1.1：向量索引构建

**测试步骤**：
```bash
# 清除旧索引
rm -rf chroma_db/

# 重建向量索引
python scripts/rebuild_multi_kb.py
```

**预期结果**：
- 控制台显示文档加载进度
- 显示各格式文档解析数量
- 显示向量构建进度
- 生成 `chroma_db/` 目录

**验证方法**：
```python
import chromadb
client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_collection("knowledge_base")
print(f"向量数量: {collection.count()}")
```

#### 测试 1.2：BM25 索引构建

**测试步骤**：
```bash
# BM25索引会随向量索引一起构建
# 检查索引文件
ls -la bm25_index.pkl
```

**预期结果**：
- 生成 `bm25_index.pkl` 文件
- 文件大小约 1-5 MB

#### 测试 1.3：知识图谱构建

**测试步骤**：
```bash
# 构建知识图谱
python graph_build.py
```

**预期结果**：
- 显示实体提取进度
- 显示关系提取进度
- 显示图谱存储进度
- 无错误信息

---

### 3.2 第二阶段：权限控制测试

#### 测试 2.1：未登录用户权限

**测试步骤**：
```bash
# 不带 Token 访问
curl -X POST http://localhost:5001/rag \
  -H "Content-Type: application/json" \
  -d '{"message": "公司的产品有哪些？"}'
```

**预期结果**：
- 只返回 public 目录下的内容
- 不返回 internal、confidential、secret 内容

#### 测试 2.2：user 角色权限

**测试步骤**：
```bash
# 使用 mock token 登录
curl -X POST http://localhost:5001/rag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-token-testuser" \
  -d '{"message": "差旅费标准是多少？"}'
```

**预期结果**：
- 返回 public + internal 目录内容
- 不返回 confidential、secret 内容

#### 测试 2.3：manager 角色权限

**测试步骤**：
```bash
curl -X POST http://localhost:5001/rag \
  -H "Authorization: Bearer mock-token-manager" \
  -H "Content-Type: application/json" \
  -d '{"message": "2024年财务报表显示净利润是多少？"}'
```

**预期结果**：
- 返回 public + internal + confidential 内容
- 正确回答财务相关问题
- 不返回 secret 目录内容

#### 测试 2.4：admin 角色权限

**测试步骤**：
```bash
curl -X POST http://localhost:5001/rag \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"message": "董事会决议的并购方案是什么？"}'
```

**预期结果**：
- 返回所有目录内容
- 正确回答涉及绝密信息的问题

---

### 3.3 第三阶段：检索质量测试

#### 测试 3.1：向量语义检索

| 测试问题 | 预期命中文档 | 预期答案关键点 |
|---------|------------|--------------|
| 公司有哪些产品？ | 公司简介.txt、产品手册.pdf | 智能数据分析平台、AI知识图谱平台、RAG系统 |
| 请假需要提前几天申请？ | 请假制度.docx | 1天以内直属上级、3天内部门负责人、7天以上总经理 |
| 年假有几天？ | 请假制度.docx | 1年5天、5年7天、10年10天、20年15天 |

**测试命令**：
```bash
curl -X POST http://localhost:5001/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-token-admin" \
  -d '{"query": "公司有哪些产品？", "top_k": 5}'
```

#### 测试 3.2：BM25 关键词检索

| 测试关键词 | 预期命中文档 |
|-----------|------------|
| 差旅补助 500元 | 差旅管理办法.txt |
| 年假 15天 | 请假制度.docx |
| 薪酬 P5 35万 | 薪酬制度.docx |

#### 测试 3.3：混合检索 + Rerank

**测试步骤**：
```bash
curl -X POST http://localhost:5001/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-token-admin" \
  -d '{"query": "出差住宿标准是多少？", "top_k": 10}'
```

**预期结果**：
- 返回结果包含 rerank_score
- 结果排序比纯向量检索更准确

#### 测试 3.4：知识图谱检索

| 测试问题 | 预期实体/关系 |
|---------|-------------|
| 技术研发中心负责什么？ | 实体：技术研发中心、张明远；关系：负责 |
| 请假3天需要谁审批？ | 实体：请假、部门负责人；关系：审批 |

**测试命令**：
```bash
curl -X POST http://localhost:5001/graph/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-token-admin" \
  -d '{"query": "技术研发中心负责什么？", "depth": 2}'
```

---

### 3.4 第四阶段：Agentic RAG 测试

#### 测试 4.1：简单问题直接回答

**测试问题**：
```bash
curl -X POST http://localhost:5001/rag \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"message": "公司的请假制度是什么？"}'
```

**预期结果**：
- Agent 决策为 "answer"
- 直接返回检索结果
- 无需多轮检索

#### 测试 4.2：查询改写

**测试问题**：
```bash
curl -X POST http://localhost:5001/rag \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"message": "我想了解关于报销的事情"}'
```

**预期结果**：
- Agent 决策为 "rewrite"
- 查询被改写为更具体的表述

#### 测试 4.3：问题分解

**测试问题**：
```bash
curl -X POST http://localhost:5001/rag \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"message": "请假和报销的流程分别是什么？"}'
```

**预期结果**：
- Agent 决策为 "decompose"
- 问题被分解为多个子问题
- 分别检索后合并回答

#### 测试 4.4：多源融合

**测试问题**：
```bash
curl -X POST http://localhost:5001/rag \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"message": "技术部的组织架构和职责分工是怎样的？"}'
```

**预期结果**：
- 同时触发知识库检索和图谱检索
- 返回结果标注来源类型

---

### 3.5 第五阶段：出题系统测试

#### 测试 5.1：试卷生成

**测试步骤**：
```bash
curl -X POST http://localhost:5001/exam/generate \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"topic": "公司制度基础", "choice_count": 5, "name": "公司制度测试"}'
```

**预期结果**：
- 返回 exam_id
- 试卷状态为 "draft"
- 包含选择题、填空题、简答题

#### 测试 5.2：试卷审核

**测试步骤**：
```bash
curl -X POST http://localhost:5001/exam/<exam_id>/review \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}'
```

**预期结果**：
- 返回 success: true
- 试卷状态变为 "approved"

#### 测试 5.3：试卷批阅

**测试步骤**：
```bash
curl -X POST http://localhost:5001/exam/<exam_id>/grade \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"student_name": "测试学生", "answers": {"choice_1": "A", "choice_2": "B"}}'
```

**预期结果**：
- 返回批阅报告
- 包含每题得分和总分

---

### 3.6 第六阶段：API 接口测试

#### 测试 6.1：认证接口

```bash
# 获取用户信息
curl http://localhost:5001/auth/me \
  -H "Authorization: Bearer mock-token-admin"
```

#### 测试 6.2：会话管理

```bash
# 创建会话并对话
curl -X POST http://localhost:5001/chat \
  -H "Authorization: Bearer mock-token-admin" \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "session_id": "test-001"}'

# 获取会话列表
curl http://localhost:5001/sessions \
  -H "Authorization: Bearer mock-token-admin"

# 获取会话历史
curl http://localhost:5001/history/test-001 \
  -H "Authorization: Bearer mock-token-admin"
```

#### 测试 6.3：健康检查

```bash
curl http://localhost:5001/health
```

**预期结果**：
```json
{
  "status": "ok",
  "knowledge_base": "多向量库模式 (按集合提供服务)",
  "bm25_index": "动态按需加载",
  "mode": "Agentic RAG"
}
```

---

## 四、知识图谱测试要点

### 4.1 实体覆盖

| 实体类型 | 覆盖文档 | 示例实体 |
|---------|---------|---------|
| 部门 | 组织架构、员工手册 | 技术研发中心、人力资源部、财务部 |
| 人员 | 组织架构、人员名册 | 张志远、李明辉、王志强 |
| 制度 | 员工手册、请假制度、差旅管理办法 | 差旅管理办法、请假制度、信息安全管理制度 |
| 金额 | 差旅管理办法、财务报表、薪酬制度 | 500元/天、280万元、8-12万元 |
| 时间 | 请假制度、项目管理制度 | 3个工作日、30天、2024年1月 |
| 地点 | 公司简介、差旅管理办法 | 北京、上海、深圳 |

### 4.2 关系类型覆盖

| 关系类型 | 覆盖文档 | 示例关系 |
|---------|---------|---------|
| 负责 | 组织架构 | 技术研发中心 → 负责 → 技术总监张明远 |
| 审批 | 请假制度、差旅管理办法 | 请假3天 → 审批 → 部门负责人 |
| 限额 | 差旅管理办法 | 一线城市住宿 → 限额 → 500元/晚 |
| 时效 | 请假制度 | 离职申请 → 时效 → 提前30天 |

### 4.3 多跳推理测试点

| 测试问题 | 推理链 | 涉及文档 |
|---------|--------|---------|
| 请假5天需要谁审批？ | 5天 > 3天 → 部门负责人 + 人力资源部 + 总经理 | 请假制度.docx |
| 差旅费超过3000元怎么处理？ | >3000元 → 部门负责人 + 财务部经理审批 | 差旅管理办法.txt |
| 技术总监的薪酬范围是多少？ | 技术总监 → M4级 → 50-80万元 | 薪酬制度.docx |

---

## 五、测试报告模板

### 5.1 测试执行摘要

| 项目 | 内容 |
|------|------|
| 测试日期 | YYYY-MM-DD |
| 测试人员 | |
| 测试环境 | |
| 文档数量 | 21个 |
| 发现问题数量 | |

### 5.2 测试结果统计

| 测试类型 | 用例数 | 通过 | 失败 | 阻塞 |
|----------|--------|------|------|------|
| 索引构建测试 | 3 | | | |
| 权限控制测试 | 4 | | | |
| 检索质量测试 | 4 | | | |
| Agentic RAG测试 | 4 | | | |
| 出题系统测试 | 3 | | | |
| API接口测试 | 3 | | | |
| **总计** | **21** | | | |

### 5.3 问题列表

| 编号 | 测试用例 | 问题描述 | 严重程度 | 状态 |
|------|----------|----------|----------|------|
| BUG-001 | | | 高/中/低 | 待修复 |

---

## 六、快速测试命令

```bash
# 一键索引重建
python scripts/rebuild_multi_kb.py

# 构建知识图谱
python graph_build.py

# 启动服务
python main.py

# 快速测试
curl http://localhost:5001/health
```

---

## 七、测试文档生成

测试文档通过脚本 `generate_test_docs.py` 自动生成，支持以下格式：

- **TXT**: 直接文本写入
- **DOCX**: 使用 `python-docx` 库生成
- **XLSX**: 使用 `openpyxl` 库生成
- **PDF**: 使用 `reportlab` 库生成

运行命令：
```bash
python generate_test_docs.py
```

依赖安装：
```bash
pip install python-docx openpyxl reportlab
```

---

## 八、文本量统计

| 目录 | 文件数 | 总字符数 | 总词数(估计) |
|------|--------|---------|-------------|
| public | 7 | ~35,000 | ~15,000 |
| internal | 5 | ~25,000 | ~10,000 |
| confidential | 5 | ~20,000 | ~8,000 |
| secret | 4 | ~15,000 | ~6,000 |
| **合计** | **21** | **~95,000** | **~39,000** |

---

## 九、变更记录

| 日期 | 版本 | 变更内容 |
|------|------|---------|
| 2026-04-13 | 2.0 | 合并测试文档清单和测试执行流程 |
| 2026-04-05 | 1.0 | 初始版本 |