# Changelog: 统一 API 响应格式

**日期**: 2026-01-26  
**类型**: 重构  
**影响**: Breaking Change

## 变更概述

实施统一的 API 响应格式，所有接口现在返回包含 `code`、`message`、`data` 的标准结构。

## 变更详情

### 新增文件

- `server/app/schemas/response.py` - 统一响应模型和辅助函数

### 修改文件

- `server/app/schemas/__init__.py` - 导出响应相关类
- `server/app/api/v1/health.py` - 2 个接口
- `server/app/api/v1/auth.py` - 2 个接口
- `server/app/api/v1/users.py` - 2 个接口
- `server/app/api/v1/folders.py` - 15 个接口
- `server/app/api/v1/projects.py` - 20 个接口（删除重复定义）
- `server/app/api/v1/ai.py` - 10 个接口

**总计**: 51+ 个接口

## Breaking Changes

### 响应格式变更

**之前**:
```json
{
  "items": [...],
  "total": 100
}
```

**现在**:
```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100
  }
}
```

### 前端迁移指南

**修改前**:
```typescript
const response = await api.getProjects()
console.log(response.items)
```

**修改后**:
```typescript
const response = await api.getProjects()
console.log(response.data.items)
```

### API 客户端更新

如果使用 TanStack Query，需要更新数据提取逻辑：

```typescript
// 修改前
const { data } = useQuery({
  queryKey: ['projects'],
  queryFn: () => api.getProjects()
})
// data.items

// 修改后
const { data } = useQuery({
  queryKey: ['projects'],
  queryFn: () => api.getProjects()
})
// data.data.items
```

## 新增功能

### 统一响应模型

```python
from app.schemas.response import ApiResponse, success_response

@router.get("", response_model=ApiResponse[ProjectListResponse])
async def get_projects(...):
    result = await service.get_projects(...)
    return success_response(data=result)
```

### 便捷函数

```python
# 成功响应
success_response(data=result, message="操作成功", code=200)

# 错误响应
error_response(message="验证失败", code=400, errors=[...])
```

## 修复问题

- 删除 `projects.py` 中重复的路由定义（delete、restore、permanent_delete）
- 统一所有接口的返回格式
- 符合 `api-design.md` 规范要求

## 测试建议

1. 验证所有接口返回格式正确
2. 检查前端 API 调用是否正常
3. 确认错误响应格式一致
4. 测试分页、列表、详情等各种场景

## 相关文档

- RFC 135: 统一 API 响应格式
- `api-design.md` - API 设计规范