cutThink_lite/docs/PHASE5_TESTING.md

# Phase 5 - AI 分类功能测试指南

本文档提供 AI 分类功能的详细测试步骤和验证方法。

## 前置条件

### 1. 环境准备
```bash
# 确保在项目根目录
cd /home/congsh/CodeSpace/ClaudeSpace/cutThink_lite

# 安装依赖（如果尚未安装）
npm install

# 启动开发服务器
npm run tauri dev
```

### 2. API Key 准备

#### Claude API Key
1. 访问 https://console.anthropic.com/
2. 登录或注册账号
3. 进入 API Keys 页面
4. 创建新的 API Key
5. 保存 Key（格式：sk-ant-xxx）

#### OpenAI API Key
1. 访问 https://platform.openai.com/api-keys
2. 登录或注册账号
3. 点击 "Create new secret key"
4. 保存 Key（格式：sk-xxx）

## 测试步骤

### 测试 1: AI 配置功能

#### 步骤
1. 启动应用
2. 点击 "⚙️ AI 配置" 按钮
3. 选择 Claude 配置
4. 输入 Claude API Key
5. 选择模型（推荐：claude-3-5-sonnet-20241022）
6. 点击 "保存并启用 Claude"

#### 预期结果
- ✅ 保存成功提示
- ✅ "已配置" 徽章显示
- ✅ "AI 功能: 可用"

#### 测试 OpenAI
1. 切换到 OpenAI 配置
2. 输入 OpenAI API Key
3. 选择模型（推荐：gpt-4o）
4. 点击 "保存并启用 OpenAI"

#### 预期结果
- ✅ 保存成功提示
- ✅ 提供商切换成功

### 测试 2: 模板管理功能

#### 步骤
1. 点击 "📝 模板管理" 按钮
2. 查看内置模板列表
3. 应该看到 4 个内置模板：
   - 通用分类
   - 代码片段分类
   - 票据发票分类
   - 对话内容分类

#### 预期结果
- ✅ 所有内置模板正确显示
- ✅ 每个模板显示名称、描述、变量数量

### 测试 3: 模板测试功能

#### 步骤
1. 在模板管理界面
2. 双击 "通用分类" 模板
3. 在测试对话框中输入变量：
   ```
   content_type: text
   content: 这是一段关于 Python 编程的代码示例
   ```
4. 点击 "运行测试"

#### 预期结果
- ✅ 显示渲染后的 System Prompt
- ✅ 显示渲染后的 User Prompt
- ✅ User Prompt 包含输入的内容

### 测试 4: 创建自定义模板

#### 步骤
1. 点击 "+ 新建模板"
2. 填写模板信息：
   ```
   名称: 文档分类
   描述: 用于分类文档类型
   分类: documents
   系统提示词: 你是一个文档分类专家
   用户提示词模板: 请分类此文档：{{content}}
   ```
3. 点击 "保存模板"

#### 预期结果
- ✅ 模板保存成功
- ✅ 出现在自定义模板列表中
- ✅ 可以编辑、测试、导出、删除

### 测试 5: 模板导入/导出

#### 导出测试
1. 选择任意自定义模板
2. 点击 "导出" 按钮
3. 保存 JSON 文件

#### 预期结果
- ✅ 文件下载成功
- ✅ JSON 格式正确

#### 导入测试
1. 点击 "导入模板" 按钮
2. 选择刚才导出的文件
3. 检查导入结果

#### 预期结果
- ✅ 模板导入成功
- ✅ ID 自动更新避免冲突

### 测试 6: 文本分类（非流式）

#### 准备测试内容
```
def hello_world():
    print("Hello, World!")
    return True
```

#### 步骤
1. 创建或选择一条文本记录
2. 粘贴上述代码
3. 打开 AI 分类功能
4. 选择 "代码片段分类" 模板
5. 取消勾选 "流式模式"
6. 点击 "开始分类"

#### 预期结果
- ✅ 分类执行中提示
- ✅ 分类结果显示：
  - 主分类: 代码
  - 子分类: Python
  - 置信度: > 0.8
  - 标签包含: Python, 编程, 函数

### 测试 7: 文本分类（流式）

#### 步骤
1. 使用相同的测试内容
2. 勾选 "流式模式"
3. 点击 "开始分类"

#### 预期结果
- ✅ 显示 "实时预览" 区域
- ✅ 文本逐步显示
- ✅ 完成后显示完整结果

### 测试 8: OCR 内容分类

#### 准备测试图片
1. 截取包含文本的图片（如代码截图、发票等）
2. 确保 OCR 功能已配置

#### 步骤
1. 对图片执行 OCR
2. 获得 OCR 文本后
3. 点击 "AI 分类"
4. 选择合适的模板
5. 执行分类

#### 预期结果
- ✅ OCR 文本正确传递
- ✅ 分类结果准确
- ✅ 置信度合理

### 测试 9: 分类历史

#### 步骤
1. 对同一条记录执行多次分类
2. 使用不同模板
3. 查看分类历史

#### 预期结果
- ✅ 每次分类都记录在历史中
- ✅ 显示时间戳
- ✅ 显示每次的分类结果

### 测试 10: 分类统计

#### 步骤
1. 对多条记录执行分类
2. 确保至少有 5-10 条记录
3. 查看分类统计

#### 预期结果
- ✅ 显示所有分类
- ✅ 每个分类显示数量
- ✅ 按数量降序排列

### 测试 11: 错误处理

#### 无效 API Key 测试
1. 输入无效的 API Key
2. 尝试执行分类

#### 预期结果
- ✅ 显示错误提示
- ✅ 不崩溃或挂起

#### 网络错误测试
1. 断开网络连接
2. 尝试执行分类

#### 预期结果
- ✅ 显示网络错误
- ✅ 优雅处理

#### 无效模板测试
1. 创建包含无效变量的模板
2. 尝试使用该模板

#### 预期结果
- ✅ 显示模板错误
- ✅ 不执行 API 调用

### 测试 12: 性能测试

#### 大文本测试
1. 准备 5000 字以上的长文本
2. 执行分类

#### 预期结果
- ✅ 分类正常完成
- ✅ 响应时间 < 30 秒
- ✅ UI 不卡顿

#### 批量测试
1. 准备 10 条记录
2. 快速连续分类

#### 预期结果
- ✅ 所有请求都处理
- ✅ 限流正常工作
- ✅ 无请求失败

## 测试用例

### 用例 1: 代码分类
```
输入: Python 代码片段
预期: category=代码, subcategory=Python, confidence>0.9
```

### 用例 2: 对话分类
```
输入: 聊天记录
预期: category=对话, confidence>0.8
```

### 用例 3: 票据分类
```
输入: 发票 OCR 文本
预期: category=票据, 包含金额信息, confidence>0.7
```

### 用例 4: 通用文本
```
输入: 随机文章段落
预期: category=文本或文章, confidence>0.6
```

## 验证清单

### 功能验证
- [ ] Claude API 正常工作
- [ ] OpenAI API 正常工作
- [ ] 所有内置模板可加载
- [ ] 自定义模板 CRUD 正常
- [ ] 模板导入/导出正常
- [ ] 非流式分类正常
- [ ] 流式分类正常
- [ ] 分类结果保存
- [ ] 分类历史记录
- [ ] 分类统计准确

### 用户体验验证
- [ ] 界面直观易用
- [ ] 加载状态清晰
- [ ] 错误提示友好
- [ ] 响应速度快
- [ ] 结果展示清晰

### 性能验证
- [ ] 单次分类 < 10 秒
- [ ] 流式响应延迟 < 2 秒
- [ ] 内存占用合理
- [ ] CPU 占用正常

### 安全性验证
- [ ] API Key 安全存储
- [ ] 输入验证正常
- [ ] HTTPS 通信
- [ ] 错误信息不泄露敏感数据

## 常见问题

### Q: 分类结果不准确
**A:**
1. 尝试不同的模板
2. 调整 Prompt 模板
3. 使用更强的模型（如 Claude Opus）
4. 提供更多上下文信息

### Q: API 调用失败
**A:**
1. 检查 API Key 是否正确
2. 检查网络连接
3. 检查 API 配额
4. 查看错误详情

### Q: 流式响应卡住
**A:**
1. 检查网络稳定性
2. 切换到非流式模式
3. 重试请求

### Q: 分类速度慢
**A:**
1. 使用更快的模型（如 Claude Haiku）
2. 减少输入内容长度
3. 调整 max_tokens 参数

## 测试报告模板

```markdown
# AI 分类功能测试报告

**测试日期:** YYYY-MM-DD
**测试人员:** [姓名]
**环境:** [开发/生产]

## 测试结果摘要
- 总测试项: XX
- 通过: XX
- 失败: XX
- 通过率: XX%

## 详细结果

### 功能测试
| 测试项 | 状态 | 备注 |
|-------|------|------|
| AI 配置 | ✅/❌ | |
| 模板管理 | ✅/❌ | |
| 文本分类 | ✅/❌ | |
| 流式分类 | ✅/❌ | |

### 性能测试
| 指标 | 目标 | 实际 | 状态 |
|-----|------|------|------|
| 响应时间 | <10s | XXs | ✅/❌ |
| 流式延迟 | <2s | XXs | ✅/❌ |

### 问题和建议
1. [问题描述]
   - 重现步骤:
   - 预期结果:
   - 实际结果:
   - 严重程度: 低/中/高

### 总体评价
[总体评价和建议]
```

## 下一步

完成测试后：

1. **修复问题**
   - 记录所有发现的问题
   - 按优先级修复
   - 重新测试验证

2. **优化改进**
   - 根据测试结果优化
   - 改进用户体验
   - 提升性能

3. **文档更新**
   - 更新用户文档
   - 添加常见问题
   - 编写使用教程

4. **发布准备**
   - 代码审查
   - 最终测试
   - 发布说明

---

需要帮助？查看：
- [Phase 5 集成指南](./PHASE5_INTEGRATION.md)
- [Phase 5 实现总结](./PHASE5_SUMMARY.md)