jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3 Commits
1 Branch
0 Tags
2.6 MiB
 
Tree: 7e0b1b0b60
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '7e0b1b0b60'
${ noResults }
docs/v1.0/server/changelogs/2026-01-30-test-documentati...

7.7 KiB
Raw Blame History

测试文档组织优化

日期：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 中添加新章节：

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

## 特定服务测试文档

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

### 后端服务测试

- **文件存储服务测试**：[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

保留理由：

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

用途：

# 运行文件存储服务的所有测试
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

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