# 文件夹 API 响应格式修复

**日期**: 2026-01-29  
**类型**: Bug Fix  
**影响范围**: 文件夹 API

## 问题描述

文件夹 API 的响应格式存在以下问题：

1. **UUID 字段未转换为字符串**: `get_folder` 和 `update_folder` API 返回的 UUID 字段（`id`, `ownerId`, `parentFolderId`）未转换为字符串，导致 Pydantic 验证失败
2. **缺少枚举显示名称**: 响应中缺少 `folderCategoryName` 字段
3. **面包屑路径 UUID 未转换**: `get_path` 方法返回的面包屑路径中的 `id` 字段是 UUID 对象

## 修复内容

### 1. 修复 `get_folder` API 响应格式

**文件**: `server/app/api/v1/folders.py`

```python
# 修复前
folder_data = {
    "id": folder.id,  # UUID 对象
    "ownerId": folder.owner_id,  # UUID 对象
    "parentFolderId": folder.parent_folder_id,  # UUID 对象或 None
    # 缺少 folderCategoryName
}

# 修复后
folder_data = {
    "id": str(folder.id),  # 转换为字符串
    "ownerId": str(folder.owner_id),  # 转换为字符串
    "parentFolderId": str(folder.parent_folder_id) if folder.parent_folder_id else None,
    "folderCategoryName": FolderCategory.get_display_name(folder.folder_category),  # 添加显示名称
}
```

### 2. 修复 `update_folder` API 响应格式

**文件**: `server/app/api/v1/folders.py`

```python
# 修复前
return success_response(data={
    "id": folder.id,  # UUID 对象
    "ownerId": folder.owner_id,  # UUID 对象
    "parentFolderId": folder.parent_folder_id,  # UUID 对象或 None
    # 缺少 folderCategoryName
})

# 修复后
return success_response(data={
    "id": str(folder.id),  # 转换为字符串
    "ownerId": str(folder.owner_id),  # 转换为字符串
    "parentFolderId": str(folder.parent_folder_id) if folder.parent_folder_id else None,
    "folderCategoryName": FolderCategory.get_display_name(folder.folder_category),  # 添加显示名称
})
```

### 3. 修复面包屑路径 UUID 转换

**文件**: `server/app/repositories/folder_repository.py`

```python
# 修复前
async def get_path(self, folder_id: str) -> List[Dict[str, str]]:
    path.insert(0, {
        "id": current.id,  # UUID 对象
        "name": current.name
    })

# 修复后
async def get_path(self, folder_id: str) -> List[Dict[str, str]]:
    path.insert(0, {
        "id": str(current.id),  # 转换为字符串
        "name": current.name
    })
```

## 测试结果

### TestFolderCRUD 测试套件

✅ **8/9 测试通过 (89%)**

**通过的测试**:
- ✅ test_create_root_folder - 创建根文件夹
- ✅ test_create_subfolder - 创建子文件夹
- ✅ test_create_folder_without_category_fails - 创建根文件夹时不指定分类应失败
- ✅ test_get_folder_tree - 获取文件夹树
- ✅ test_get_folder_detail - 获取文件夹详情
- ✅ test_update_folder - 更新文件夹
- ✅ test_delete_empty_folder - 删除空文件夹
- ✅ test_delete_non_empty_folder_without_cascade_fails - 删除非空文件夹（不级联）应失败

**待修复的测试**:
- ❌ test_get_folders_list - 获取文件夹列表（返回 400）

## 待解决问题

`test_get_folders_list` 测试仍然失败，返回 400 状态码。初步分析：

1. **Service 层验证通过**: 直接调用 `FolderService.get_folders()` 方法成功返回结果
2. **可能的原因**: 
   - API 层的参数验证问题
   - 权限检查逻辑问题
   - 测试 fixture 设置问题

需要进一步调试以确定根本原因。

## 影响

- ✅ 修复了 `get_folder` API 的响应格式问题
- ✅ 修复了 `update_folder` API 的响应格式问题
- ✅ 修复了面包屑路径中的 UUID 转换问题
- ✅ 提高了测试通过率从 67% 到 89%
- ⚠️ `get_folders_list` API 仍需进一步调试

## 相关文件

- `server/app/api/v1/folders.py` - API 路由层
- `server/app/repositories/folder_repository.py` - 数据访问层
- `server/tests/integration/test_folder_api.py` - 集成测试

## 后续工作

1. 调试 `test_get_folders_list` 失败的根本原因
2. 修复权限检查或参数验证问题
3. 确保所有测试通过