# AI Jobs API 响应格式标准化

**日期**: 2026-02-11  
**类型**: 重构  
**影响范围**: AI Jobs API (`/api/v1/ai/jobs`)

## 变更概述

统一 AI Jobs API 的响应格式，符合项目 API 响应标准规范。

## 变更详情

### 1. 导入标准响应类型

```python
# 新增导入
from app.schemas.common import SuccessResponse, PaginatedResponse
from app.core.exceptions import NotFoundError, ValidationError
```

### 2. 分页接口标准化

**接口**: `GET /api/v1/ai/jobs`

**变更前**:
```python
response_model=SuccessResponse[dict]

# 返回自定义字典结构
response_data = {
    "items": serialized_items,
    "total": result['total'],
    "page": result['page'],
    "pageSize": result['page_size'],
    "totalPages": result['total_pages']
}
```

**变更后**:
```python
response_model=SuccessResponse[PaginatedResponse[AIJobListItemResponse]]

# 使用标准 PaginatedResponse
paginated_data = PaginatedResponse(
    items=serialized_items,
    total=result['total'],
    page=result['page'],
    page_size=result['page_size'],
    total_pages=result['total_pages']
)
```

### 3. 异常处理准备

导入自定义异常类，为后续统一异常处理做准备：
- `NotFoundError` - 资源不存在（404）
- `ValidationError` - 数据验证失败（400）

## 技术细节

### 响应格式对比

**变更前**:
```json
{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  },
  "timestamp": "2026-02-11T10:00:00Z"
}
```

**变更后**:
```json
{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  },
  "timestamp": "2026-02-11T10:00:00Z"
}
```

**注**: 响应结构保持一致，但使用标准 Pydantic 模型确保类型安全和字段验证。

## 影响评估

### 前端兼容性
- ✅ **完全兼容** - 响应 JSON 结构未变化
- ✅ 字段名保持 camelCase（通过 Pydantic `alias` 配置）
- ✅ 所有现有查询参数保持不变

### 后端改进
- ✅ 类型安全增强（使用泛型 `PaginatedResponse`）
- ✅ 代码一致性提升（与其他 API 保持统一）
- ✅ 为统一异常处理做准备

## 测试建议

### 1. 分页查询测试
```bash
# 基础查询
curl -X GET "http://localhost:8000/api/v1/ai/jobs?page=1&pageSize=20"

# 带筛选条件
curl -X GET "http://localhost:8000/api/v1/ai/jobs?jobType=1&status=2&page=1&pageSize=10"

# 时间范围筛选
curl -X GET "http://localhost:8000/api/v1/ai/jobs?startDate=2026-02-01T00:00:00Z&endDate=2026-02-11T23:59:59Z"

# 自定义排序
curl -X GET "http://localhost:8000/api/v1/ai/jobs?orderBy=created_at&orderDesc=false"
```

### 2. 验证响应格式
- 确认 `data` 字段包含 `items`, `total`, `page`, `pageSize`, `totalPages`
- 确认 `items` 数组中每个元素符合 `AIJobListItemResponse` Schema
- 确认所有字段名为 camelCase

### 3. 其他接口验证
- `GET /api/v1/ai/jobs/statistics` - 统计信息
- `GET /api/v1/ai/jobs/usage/stats` - 使用统计
- `GET /api/v1/ai/jobs/{job_id}` - 任务详情
- `POST /api/v1/ai/jobs/{job_id}/cancel` - 取消任务

## 相关文档

- [ADR-001: API 响应格式标准化](../../architecture/adrs/001-api-response-format-standardization.md)
- Schema 定义: `app/schemas/common.py` - `PaginatedResponse`
- 异常定义: `app/core/exceptions.py`

## 后续优化

1. **统一异常处理**: 将 Service 层可能抛出的异常统一转换为自定义异常类
2. **参数验证增强**: 考虑添加更多查询参数验证（如日期范围合法性）
3. **性能优化**: 对高频查询接口添加缓存机制

## 检查清单

- [x] 导入 `PaginatedResponse` 和自定义异常类
- [x] 修改 `list_user_jobs` 使用标准分页响应
- [x] 保持查询参数 camelCase 支持（`alias`）
- [x] 保持其他接口使用 `SuccessResponse` 标准格式
- [x] 创建 Changelog 文档
- [ ] 前端验证响应格式兼容性
- [ ] 添加集成测试用例

## 提交信息

```
refactor(ai-jobs): 统一 API 响应格式标准

- 使用 PaginatedResponse 标准分页格式
- 导入自定义异常类为后续统一异常处理做准备
- 保持前端完全兼容（响应结构未变化）
- 符合 ADR-001 API 响应格式标准化规范
```