# 测试文档组织优化

**日期**：2026-01-30  
**类型**：文档整理  
**影响范围**：测试文档结构

---

## 变更概述

优化测试相关文档的组织结构，将 AI API 手动测试指南移动到合适的位置，并在测试规范文档中添加特定服务测试文档的链接。

---

## 变更动机

### 问题

1. **文档位置不合理**：
   - `AI_API_TEST_GUIDE.md` 位于项目根目录
   - 不符合文档组织规范
   - 难以查找和维护

2. **文档关联性不足**：
   - 特定服务的测试文档（如 `FILE_STORAGE_TESTS.md`）缺乏统一入口
   - 开发者不知道这些文档的存在
   - 测试规范文档缺少对特定服务测试的引导

### 目标

1. 将文档移动到合理的位置
2. 建立文档之间的关联
3. 提供统一的测试文档入口

---

## 变更内容

### 1. 移动 AI API 测试指南

**原位置**：`AI_API_TEST_GUIDE.md`（项目根目录）

**新位置**：`docs/server/guides/ai-api-testing.md`

**调整内容**：
- 添加文档版本和更新日期
- 更新相关文档链接（使用相对路径）
- 明确文档适用场景（手动测试，补充自动化测试）

### 2. 更新测试规范文档

在 `.claude/skills/jointo-tech-stack/references/testing.md` 中添加新章节：

#### 新增章节：特定服务测试文档

```markdown
## 特定服务测试文档

以下是各个服务的详细测试文档，提供特定服务的测试用例、运行方法和故障排查：

### 后端服务测试

- **文件存储服务测试**：[server/tests/FILE_STORAGE_TESTS.md]
  - 文件上传和去重测试
  - 引用计数管理测试
  - Celery 清理任务测试
  - 完整的测试运行脚本

### 手动测试指南

- **AI API 手动测试**：[docs/server/guides/ai-api-testing.md]
  - Swagger UI 测试流程
  - curl 命令示例
  - 完整测试脚本
  - 常见错误处理
```

#### 扩展参考资源章节

将原有的"参考资源"章节扩展为两部分：
- **官方文档**：pytest、FastAPI、SQLModel 等
- **项目文档**：API 设计规范、后端架构、数据库设计等

---

## 文档组织结构

### 测试文档层次

```
测试文档
├── 通用测试规范
│   └── .claude/skills/jointo-tech-stack/references/testing.md
│       ├── 测试金字塔
│       ├── 常用 Fixtures 使用指南
│       ├── 集成测试认证模式
│       ├── API 响应格式处理
│       ├── 常见字段名称规范
│       ├── 测试覆盖率要求
│       └── 特定服务测试文档（链接）
│
├── 特定服务测试文档
│   ├── server/tests/FILE_STORAGE_TESTS.md
│   │   ├── 测试用例列表
│   │   ├── 运行方法
│   │   ├── 故障排查
│   │   └── 最佳实践
│   │
│   └── （未来可添加其他服务的测试文档）
│
└── 手动测试指南
    └── docs/server/guides/ai-api-testing.md
        ├── Swagger UI 测试流程
        ├── curl 命令示例
        ├── 完整测试脚本
        └── 常见错误处理
```

### 文档查找路径

1. **新开发者**：
   - 从 `testing.md` 开始，了解通用测试规范
   - 根据需要查看特定服务的测试文档

2. **编写特定服务测试**：
   - 查看 `testing.md` 了解通用规范
   - 参考 `FILE_STORAGE_TESTS.md` 了解特定服务的测试模式

3. **手动测试 API**：
   - 查看 `docs/server/guides/ai-api-testing.md`
   - 使用 Swagger UI 或 curl 进行测试

---

## 保留的文件

### 1. `server/tests/run_file_storage_tests.sh`

**保留理由**：
- 提供一键运行所有相关测试的便捷方式
- 自动检测是否在容器内
- 生成覆盖率报告
- 维护成本低，价值高

**用途**：
```bash
# 运行文件存储服务的所有测试
docker exec jointo-server-app bash tests/run_file_storage_tests.sh
```

### 2. `server/tests/FILE_STORAGE_TESTS.md`

**保留理由**：
- 提供文件存储服务的详细测试文档
- 包含完整的测试用例列表
- 提供故障排查指南
- 补充通用测试规范

**内容**：
- 测试概述和目标
- 测试结构和用例列表
- 运行方法（多种方式）
- 测试覆盖率要求
- 故障排查和调试技巧
- 最佳实践

### 3. `docs/server/guides/ai-api-testing.md`（新位置）

**保留理由**：
- 提供 AI API 的手动测试指南
- 补充自动化测试
- 对新开发者友好
- 包含完整的测试脚本

**内容**：
- Swagger UI 测试流程
- curl 命令示例
- 完整测试脚本
- 请求参数说明
- 常见错误处理
- 测试检查清单

---

## 文档维护规范

### 何时创建特定服务测试文档

✅ **应该创建**：
- 服务有复杂的测试场景
- 需要特殊的测试环境配置
- 有特定的故障排查流程
- 测试用例数量较多（> 20 个）

❌ **不需要创建**：
- 简单的 CRUD 服务
- 测试用例少（< 10 个）
- 没有特殊的测试要求

### 文档命名规范

- **服务测试文档**：`server/tests/<SERVICE>_TESTS.md`
  - 例如：`FILE_STORAGE_TESTS.md`、`AI_SERVICE_TESTS.md`

- **手动测试指南**：`docs/server/guides/<service>-<type>-testing.md`
  - 例如：`ai-api-testing.md`、`payment-api-testing.md`

- **测试脚本**：`server/tests/run_<service>_tests.sh`
  - 例如：`run_file_storage_tests.sh`、`run_ai_service_tests.sh`

### 文档更新流程

1. **创建新的服务测试文档**：
   - 在 `server/tests/` 创建 `<SERVICE>_TESTS.md`
   - 在 `testing.md` 的"特定服务测试文档"章节添加链接

2. **创建手动测试指南**：
   - 在 `docs/server/guides/` 创建测试指南
   - 在 `testing.md` 的"手动测试指南"章节添加链接

3. **更新现有文档**：
   - 保持文档版本号和更新日期
   - 在 changelog 中记录重要变更

---

## 影响范围

### 文件变更

- ✅ 移动：`AI_API_TEST_GUIDE.md` → `docs/server/guides/ai-api-testing.md`
- ✅ 更新：`.claude/skills/jointo-tech-stack/references/testing.md`
- ✅ 保留：`server/tests/run_file_storage_tests.sh`
- ✅ 保留：`server/tests/FILE_STORAGE_TESTS.md`

### 受益场景

1. **新开发者入职**：
   - 从 `testing.md` 快速了解测试规范
   - 根据链接查找特定服务的测试文档

2. **编写测试**：
   - 参考通用规范和特定服务示例
   - 使用测试脚本快速运行测试

3. **手动测试**：
   - 查看手动测试指南
   - 使用提供的脚本进行测试

4. **文档维护**：
   - 清晰的文档组织结构
   - 统一的命名和更新规范

---

## 验证方式

1. **文档可访问性**：
   - ✅ `docs/server/guides/ai-api-testing.md` 存在
   - ✅ `AI_API_TEST_GUIDE.md` 已删除
   - ✅ `testing.md` 包含特定服务测试文档链接

2. **链接有效性**：
   - ✅ 所有相对路径链接正确
   - ✅ 文档之间的引用关系清晰

3. **内容完整性**：
   - ✅ 移动后的文档内容完整
   - ✅ 相关文档链接已更新

---

## 后续优化

1. **扩展特定服务测试文档**：
   - 为其他复杂服务创建测试文档
   - 统一文档格式和结构

2. **自动化文档生成**：
   - 考虑从测试代码自动生成测试用例列表
   - 自动更新测试覆盖率统计

3. **文档索引**：
   - 创建测试文档索引页面
   - 提供搜索和导航功能

---

## 参考资源

- 测试规范文档：`.claude/skills/jointo-tech-stack/references/testing.md`
- 文件存储服务测试：`server/tests/FILE_STORAGE_TESTS.md`
- AI API 手动测试：`docs/server/guides/ai-api-testing.md`

---

**总结**：通过优化测试文档的组织结构，建立了清晰的文档层次和关联关系，提升了文档的可查找性和可维护性，为团队提供了统一的测试文档入口。