# 测试指南

> **文档类型**: 测试指南
> **创建日期**: 2026-04-05
> **最后更新**: 2026-06-04
> **文档总数**: 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|flask|jieba"

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

### 2.2 配置检查

确保 `config.py` 配置正确：
```python
# API配置
DASHSCOPE_API_KEY = "your-api-key"
DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
DASHSCOPE_MODEL = "qwen3.6-flash"          # 主 LLM（文本生成 / RAG 对话）
INTENT_MODEL = "qwen-turbo"                 # 意图分析模型（轻量、确定性高）
```

> **注意**: Graph RAG（Neo4j）功能已废弃，相关配置（NEO4J_URI、USE_GRAPH_RAG 等）已移除。

---

## 三、测试执行流程

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

---

### 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 第四阶段：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": "技术部的组织架构和职责分工是怎样的？"}'
```

**预期结果**：
- 同时触发向量检索和 BM25 关键词检索
- 返回结果经过 Rerank 重排序并标注来源

---

### 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 测试执行摘要

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

### 4.2 测试结果统计

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

### 4.3 问题列表

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

---

## 五、快速测试命令

```bash
# 一键索引重建
python scripts/rebuild_multi_kb.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-06-04 | 3.0 | 移除 Graph RAG（Neo4j）相关内容，更新模型配置和章节编号 |
| 2026-04-13 | 2.0 | 合并测试文档清单和测试执行流程 |
| 2026-04-05 | 1.0 | 初始版本 |