# AI API 路由层实现

**日期**: 2026-02-03  
**类型**: 功能实现  
**影响范围**: 后端 API 层

## 概述

完成 AI 服务功能的 API 路由层实现，包括 AI 对话、提示词管理、模型查询和任务管理 4 个模块的完整 REST API。

## 实施内容

### 1. AI 对话 API (`ai_conversations.py`)

**路由前缀**: `/api/v1/ai/conversations`

**核心功能**:
- ✅ 对话会话管理（创建/查询/更新/删除）
- ✅ 消息管理（发送/查询）
- ✅ @ 提及功能（获取可提及资源）
- ✅ AI 生成触发（从对话触发生成任务）

**关键特性**:
- 支持多态关联（分镜/角色/场景/道具/资源/音效/配音）
- 支持标签系统（区分变体）
- 支持多维度筛选（项目/目标类型/目标对象/标签/媒体类型/状态）
- 自动解析消息中的 @ 提及标记
- 自动提取参考图并传递给 AI Service

**API 端点**:
```
POST   /api/v1/ai/conversations                          # 创建对话会话
GET    /api/v1/ai/conversations                          # 获取对话会话列表
GET    /api/v1/ai/conversations/{conversation_id}        # 获取对话会话详情
PATCH  /api/v1/ai/conversations/{conversation_id}        # 更新对话会话
DELETE /api/v1/ai/conversations/{conversation_id}        # 删除对话会话
POST   /api/v1/ai/conversations/{conversation_id}/messages              # 发送消息
GET    /api/v1/ai/conversations/{conversation_id}/messages              # 获取消息列表
GET    /api/v1/ai/conversations/{conversation_id}/mentionable-resources # 获取可提及资源
POST   /api/v1/ai/conversations/{conversation_id}/generate              # 触发 AI 生成
```

### 2. AI 提示词管理 API (`ai_prompts.py`)

**路由前缀**: `/api/v1/admin/ai-prompts`

**核心功能**:
- ✅ 提示词 CRUD（创建/查询/更新/删除）
- ✅ 默认提示词管理
- ✅ 提示词版本管理
- ✅ Skills 配置管理

**权限控制**:
- 管理接口：仅管理员可访问
- 公开接口：`GET /default/{prompt_type}` 供内部服务调用

**API 端点**:
```
POST   /api/v1/admin/ai-prompts                    # 创建提示词（管理员）
GET    /api/v1/admin/ai-prompts                    # 获取提示词列表（管理员）
GET    /api/v1/admin/ai-prompts/{prompt_id}        # 获取提示词详情（管理员）
PATCH  /api/v1/admin/ai-prompts/{prompt_id}        # 更新提示词（管理员）
DELETE /api/v1/admin/ai-prompts/{prompt_id}        # 删除提示词（管理员）
POST   /api/v1/admin/ai-prompts/{prompt_id}/set-default  # 设置默认提示词（管理员）
GET    /api/v1/admin/ai-prompts/default/{prompt_type}    # 获取默认提示词（公开）
```

### 3. AI 模型查询 API (`ai_models.py`)

**路由前缀**: `/api/v1/ai/models`

**核心功能**:
- ✅ 获取可用的 AI 模型列表
- ✅ 按模型类型筛选（文本/图片/视频/音频）
- ✅ 返回模型定价信息

**返回信息**:
- 模型名称和显示名称
- 提供商信息
- 定价信息（成本/积分）
- 模型配置
- 是否为测试版

**API 端点**:
```
GET /api/v1/ai/models  # 获取可用的 AI 模型列表
```

### 4. AI 任务管理 API (`ai_jobs.py`)

**路由前缀**: `/api/v1/ai/jobs`

**核心功能**:
- ✅ 任务状态查询
- ✅ 任务取消（退还积分）
- ✅ 批量查询用户任务
- ✅ 任务统计信息
- ✅ 使用统计

**关键特性**:
- 支持多维度筛选（任务类型/状态/时间范围）
- 支持自定义排序
- 提供详细的统计数据（总成本/总积分/成功率等）

**API 端点**:
```
GET    /api/v1/ai/jobs/{job_id}        # 查询任务状态
POST   /api/v1/ai/jobs/{job_id}/cancel # 取消任务
GET    /api/v1/ai/jobs                 # 批量查询用户任务
GET    /api/v1/ai/jobs/statistics      # 获取任务统计信息
GET    /api/v1/ai/jobs/usage/stats     # 获取使用统计
```

## 技术规范

### 符合 jointo-tech-stack 规范

✅ **异步操作**: 所有路由函数使用 `async/await`  
✅ **统一响应格式**: 使用 `success_response()` 和 `error_response()`  
✅ **完整的错误处理**: try-except + exc_info=True  
✅ **%-formatting 日志**: `logger.error("错误: %s", str(e), exc_info=True)`  
✅ **依赖注入**: 使用 `Depends(get_db)` 和 `Depends(get_current_user)`  
✅ **类型提示**: 完整的 Python 类型注解  
✅ **UUID v7**: 所有 ID 参数使用 `UUID` 类型  

### Schema 定义

创建了 `server/app/schemas/ai_conversation.py`，包含：
- `ConversationCreateRequest`: 创建对话会话请求
- `ConversationUpdateRequest`: 更新对话会话请求
- `MessageCreateRequest`: 发送消息请求
- `GenerateRequest`: 触发 AI 生成请求

## 路由注册

已在 `server/app/api/v1/__init__.py` 中注册所有新路由：

```python
from app.api.v1 import (
    # ... 其他路由
    ai_conversations,
    ai_prompts,
    ai_models,
    ai_jobs,
)

api_router.include_router(ai_conversations.router)
api_router.include_router(ai_prompts.router)
api_router.include_router(ai_models.router)
api_router.include_router(ai_jobs.router)
```

## 依赖关系

### Service 层依赖
- `AIConversationService`: 对话会话和消息管理
- `AIPromptSystemService`: 提示词管理
- `AIService`: AI 生成、模型查询、任务管理

### Repository 层依赖
- `AIConversationRepository`: 对话数据访问
- `AIPromptSystemRepository`: 提示词数据访问
- `AIRepository`: AI 任务数据访问

### 核心依赖
- `get_db`: 数据库会话
- `get_current_user`: 当前用户认证
- `require_admin`: 管理员权限验证

## 后续工作

### 阶段 2: Celery 异步任务实现
- [ ] 创建 `app/tasks/ai_tasks.py`
- [ ] 实现异步生成任务
- [ ] 实现任务状态回调
- [ ] 实现任务失败重试

### 阶段 3: AI Provider 集成
- [ ] 集成 `ai_providers` 目录中的 AI 服务
- [ ] 实现统一的 Provider 接口
- [ ] 实现 Provider 路由和负载均衡
- [ ] 实现 Provider 错误处理和降级

### 阶段 4: 测试和优化
- [ ] 编写单元测试
- [ ] 编写集成测试
- [ ] 性能优化
- [ ] 文档完善

## 测试建议

### 1. 对话会话测试
```bash
# 创建对话会话
curl -X POST http://localhost:8000/api/v1/ai/conversations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": 1,
    "target_id": "uuid",
    "media_type": 1,
    "project_id": "uuid",
    "title": "测试对话"
  }'

# 发送消息（带 @ 提及）
curl -X POST http://localhost:8000/api/v1/ai/conversations/{conversation_id}/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "请生成一个角色形象，参考 @resource:uuid"
  }'
```

### 2. 提示词管理测试
```bash
# 创建提示词（管理员）
curl -X POST http://localhost:8000/api/v1/admin/ai-prompts \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "角色生成提示词",
    "prompt_type": 1,
    "prompt_content": "生成一个角色形象...",
    "skills_data": {},
    "version": "1.0.0"
  }'

# 获取默认提示词
curl http://localhost:8000/api/v1/admin/ai-prompts/default/1
```

### 3. 模型查询测试
```bash
# 获取所有可用模型
curl http://localhost:8000/api/v1/ai/models \
  -H "Authorization: Bearer <token>"

# 按类型筛选
curl "http://localhost:8000/api/v1/ai/models?model_type=2" \
  -H "Authorization: Bearer <token>"
```

### 4. 任务管理测试
```bash
# 查询任务状态
curl http://localhost:8000/api/v1/ai/jobs/{job_id} \
  -H "Authorization: Bearer <token>"

# 取消任务
curl -X POST http://localhost:8000/api/v1/ai/jobs/{job_id}/cancel \
  -H "Authorization: Bearer <token>"

# 获取使用统计
curl http://localhost:8000/api/v1/ai/jobs/usage/stats \
  -H "Authorization: Bearer <token>"
```

## 相关文档

- 需求文档: `docs/requirements/backend/04-services/ai/`
- 架构文档: `docs/architecture/changelogs/2026-02-03-ai-conversation-system-implementation.md`
- Service 实现: `server/app/services/ai_*.py`
- Repository 实现: `server/app/repositories/ai_*.py`

## 影响范围

### 新增文件
- `server/app/api/v1/ai_conversations.py`
- `server/app/api/v1/ai_prompts.py`
- `server/app/api/v1/ai_models.py`
- `server/app/api/v1/ai_jobs.py`
- `server/app/schemas/ai_conversation.py`

### 修改文件
- `server/app/api/v1/__init__.py` - 注册新路由

### 无影响
- 现有 API 路由
- 数据库结构
- 前端代码

## 注意事项

1. **权限控制**: AI 提示词管理接口需要管理员权限
2. **积分扣除**: 触发 AI 生成时会扣除用户积分，需确保积分充足
3. **任务取消**: 只能取消 pending 或 processing 状态的任务
4. **@ 提及**: 消息中的 @ 提及会自动解析和验证
5. **参考图**: 参考图会自动从消息 metadata 中提取并传递给 AI Service

## 验证清单

- [x] 所有路由函数使用 async/await
- [x] 所有路由使用统一响应格式
- [x] 所有路由有完整的错误处理
- [x] 所有路由有日志记录
- [x] 所有路由有类型提示
- [x] 所有路由已注册到主路由器
- [x] 代码通过 getDiagnostics 检查
- [x] 符合 jointo-tech-stack 规范