docs/v1.0/server/changelogs/2026-01-29-folder-api-test-progress.md

文件夹 API 测试进度报告

日期: 2026-01-29
类型: 测试报告
影响范围: 文件夹 API 集成测试

测试结果概览

TestFolderCRUD (9 个测试)

• ✅ 通过: 6/9 (67%)
• ❌ 失败: 3/9 (33%)

通过的测试

1. ✅ test_create_root_folder - 创建根文件夹
2. ✅ test_create_subfolder - 创建子文件夹
3. ✅ test_create_folder_without_category_fails - 创建根文件夹不指定分类应失败
4. ✅ test_get_folder_tree - 获取文件夹树
5. ✅ test_delete_empty_folder - 删除空文件夹
6. ✅ test_delete_non_empty_folder_without_cascade_fails - 删除非空文件夹（不级联）应失败

失败的测试

1. ❌ test_get_folders_list - 获取文件夹列表（返回 400）
2. ❌ test_get_folder_detail - 获取文件夹详情（返回 400）
3. ❌ test_update_folder - 更新文件夹（返回 400）

其他测试套件

• ⏸️ 待测试: 23 个测试（缺少 fixture 或 API 未实现）
  • TestFolderMove (3 个)
  • TestFolderPath (1 个)
  • TestFolderMembers (4 个)
  • TestFolderClone (2 个)
  • TestFolderShare (2 个)
  • TestFolderExport (2 个)
  • TestFolderStats (2 个)
  • TestBatchOperations (2 个)
  • TestFolderPermissions (3 个)
  • TestFolderNameUniqueness (2 个)

问题分析

1. GET /api/v1/folders 返回 400

可能原因：

• 权限检查失败（_check_folder_permission 方法）
• 响应序列化问题（UUID 未转换为字符串）
• 缺少必要字段（如 folderCategoryName）

需要修复：

• 检查 get_folders API 的响应格式
• 确保所有 UUID 字段转换为字符串
• 添加 folderCategoryName 字段

2. GET /api/v1/folders/{folder_id} 返回 400

可能原因：

• 与 get_folders 类似的响应序列化问题
• 权限检查逻辑问题

3. PUT /api/v1/folders/{folder_id} 返回 400

可能原因：

• FolderUpdate Schema 的 alias 配置问题
• 响应序列化问题

已完成的工作

1. 修复迁移脚本

• ✅ 删除重复的 20260129_1500 迁移脚本
• ✅ 修复迁移链依赖关系
• ✅ 确保 ./start_docker.sh -c 清空数据库后能正常迁移

2. 修复 Schema 驼峰命名支持

• ✅ 为 FolderCreate, FolderUpdate, FolderMove 添加 alias 配置
• ✅ 启用 populate_by_name 支持双向命名
• ✅ 修复 POST /api/v1/folders 响应序列化

3. 补充测试 Fixture

• ✅ 创建 conftest_folder.py 包含所有必要的 fixture
• ✅ 在主 conftest.py 中导入 fixture

下一步工作

优先级 1：修复失败的测试

1. 修复 get_folders API 响应

   # 需要修改 app/api/v1/folders.py
   @router.get("", response_model=ApiResponse[FolderListResponse])
   async def get_folders(...):
       # 确保响应格式与 FolderResponse 一致
       # UUID → 字符串
       # 添加 folderCategoryName
   

2. 修复 get_folder API 响应

   @router.get("/{folder_id}", response_model=ApiResponse[FolderResponse])
   async def get_folder(...):
       # 统一响应格式
   

3. 修复 update_folder API

   @router.put("/{folder_id}", response_model=ApiResponse[FolderResponse])
   async def update_folder(...):
       # 统一响应格式
   

优先级 2：实现缺失的 API 端点

1. 文件夹移动 (POST /api/v1/folders/{folder_id}/move)
2. 文件夹路径 (GET /api/v1/folders/{folder_id}/path)
3. 文件夹成员管理
   • POST /api/v1/folders/{folder_id}/members
   • GET /api/v1/folders/{folder_id}/members
   • PUT /api/v1/folders/{folder_id}/members/{user_id}
   • DELETE /api/v1/folders/{folder_id}/members/{user_id}
4. 文件夹克隆 (POST /api/v1/folders/{folder_id}/clone)
5. 文件夹分享
   • POST /api/v1/folders/{folder_id}/share
6. 文件夹导出
   • POST /api/v1/folders/{folder_id}/export
   • GET /api/v1/folders/export/{job_id}
7. 文件夹统计 (GET /api/v1/folders/{folder_id}/stats)
8. 批量操作
   • POST /api/v1/folders/batch/move
   • POST /api/v1/folders/batch/delete

优先级 3：完善测试覆盖

1. 补充权限测试的 fixture
2. 补充批量操作测试的 fixture
3. 运行完整的测试套件

技术债务

1. 响应格式统一：所有 API 端点需要统一响应格式

   • UUID → 字符串
   • 添加 folderCategoryName
   • 添加统计信息（projectCount, subfolderCount）

2. 权限检查优化：_check_folder_permission 方法需要优化

   • 缓存权限检查结果
   • 减少数据库查询

3. 日志格式问题：Loguru 日志格式化错误

   KeyError: "'type'"
   

   需要检查日志消息中的特殊字符处理

相关文档

• 文件夹迁移修复
• 文件夹 API Schema 修复
• 文件夹服务实现

测试命令

# 运行所有文件夹 CRUD 测试
docker exec jointo-server-app pytest tests/integration/test_folder_api.py::TestFolderCRUD -v

# 运行单个测试
docker exec jointo-server-app pytest tests/integration/test_folder_api.py::TestFolderCRUD::test_create_root_folder -v

# 运行所有文件夹测试
docker exec jointo-server-app pytest tests/integration/test_folder_api.py -v