# Folder Tree API - include_projects 参数修复

**日期**: 2026-02-06  
**类型**: Bug 修复  
**接口**: `/api/v1/folders/tree`

## 问题描述

当调用 `/api/v1/folders/tree?include_projects=true` 时，返回的数据中没有 `projects` 字段。

## 根本原因

1. **类型不匹配**: `_get_folder_projects` 方法接收字符串类型的 `folder_id`，但与 `Project.folder_id`（UUID 类型）比较时没有进行类型转换
2. **ID 序列化问题**: 树节点中的 `id` 字段使用 UUID 对象，而不是字符串，可能导致序列化不一致

## 修复内容

### 1. 修复类型转换 (`folder_repository.py`)

```python
async def _get_folder_projects(self, folder_id: str) -> List[Dict[str, Any]]:
    from uuid import UUID
    
    # 转换为 UUID 类型以匹配数据库字段
    folder_uuid = UUID(folder_id) if isinstance(folder_id, str) else folder_id
    
    statement = select(Project).where(
        Project.folder_id == folder_uuid,  # 使用 UUID 类型
        Project.deleted_at.is_(None)
    ).order_by(Project.updated_at.desc())
    ...
```

### 2. 统一 ID 类型处理

```python
for folder in folders:
    folder_id_str = str(folder.id)  # 统一转换为字符串
    
    node = {
        "id": folder_id_str,  # 使用字符串类型
        ...
    }
    
    if include_projects:
        node["projects"] = await self._get_folder_projects(folder_id_str)
```

### 3. 添加调试日志

在关键位置添加日志，便于追踪问题：
- Service 层：记录 `include_projects` 参数值
- Repository 层：记录查询到的项目数量

## 测试方法

### 1. 重启服务器

```bash
cd server
# 如果使用 uvicorn
uvicorn app.main:app --reload

# 或者如果使用 docker
docker-compose restart server
```

### 2. 测试不包含项目

```bash
curl -X GET "http://localhost:8000/api/v1/folders/tree" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**预期返回**（无 `projects` 字段）：
```json
{
  "success": true,
  "data": {
    "tree": [
      {
        "id": "...",
        "name": "文件夹名称",
        "projectCount": 0,
        "children": []
      }
    ]
  }
}
```

### 3. 测试包含项目

```bash
curl -X GET "http://localhost:8000/api/v1/folders/tree?include_projects=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**预期返回**（有 `projects` 字段，即使为空数组）：
```json
{
  "success": true,
  "data": {
    "tree": [
      {
        "id": "...",
        "name": "文件夹名称",
        "projectCount": 0,
        "projects": [],
        "children": []
      }
    ]
  }
}
```

### 4. 验证日志

检查服务器日志：
```bash
tail -f server/logs/app.log
```

应该看到类似输出：
```
Getting folder tree for user xxx, include_projects=True
include_projects=True, fetching projects for folder xxx
Found 0 projects in folder xxx
Added 0 projects to folder 文件夹名称
```

## 相关文件

- `server/app/api/v1/folders.py` - API 路由层
- `server/app/services/folder_service.py` - 业务逻辑层
- `server/app/repositories/folder_repository.py` - 数据访问层

## 下一步

如果修复后仍然没有 `projects` 字段，请检查：

1. **服务器是否重启**: 代码修改后需要重启服务器
2. **参数是否正确传递**: 确认 URL 中有 `?include_projects=true`
3. **权限问题**: 确认用户有查看文件夹的权限
4. **日志输出**: 查看日志确认 `include_projects` 的值

## 数据库测试查询

手动验证项目数据：

```sql
-- 查询文件夹
SELECT id, name, owner_id FROM folders WHERE deleted_at IS NULL;

-- 查询项目
SELECT id, name, folder_id FROM projects WHERE deleted_at IS NULL;

-- 查询文件夹与项目的关联
SELECT 
    f.id as folder_id,
    f.name as folder_name,
    COUNT(p.id) as project_count
FROM folders f
LEFT JOIN projects p ON p.folder_id = f.id AND p.deleted_at IS NULL
WHERE f.deleted_at IS NULL
GROUP BY f.id, f.name;
```