# AI API 测试覆盖分析

**日期**: 2026-01-31  
**文件**: `server/app/api/v1/ai.py`  
**测试文件**: `server/tests/integration/test_ai_api_workflow.py`

## 端点列表

### 生成任务 API

| 端点 | 方法 | 测试状态 | 测试用例 |
|------|------|----------|----------|
| `/generate-image` | POST | ✅ 已测试 | `test_complete_image_generation_workflow` |
| `/generate-video` | POST | ✅ 已测试 | `test_text2video_workflow`, `test_img2video_workflow` |
| `/generate-sound` | POST | ⚠️ 部分测试 | `test_query_with_type_filter` (仅创建) |
| `/generate-voice` | POST | ❌ 未测试 | - |
| `/generate-subtitle` | POST | ❌ 未测试 | - |
| `/process-text` | POST | ❌ 未测试 | - |

### 任务管理 API

| 端点 | 方法 | 测试状态 | 测试用例 |
|------|------|----------|----------|
| `/jobs` | GET | ✅ 已测试 | `test_query_multiple_jobs`, `test_query_with_type_filter`, `test_pagination` |
| `/jobs/{job_id}` | GET | ✅ 已测试 | `test_complete_image_generation_workflow`, `test_query_nonexistent_job` |
| `/jobs/{job_id}/cancel` | POST | ✅ 已测试 | `test_complete_image_generation_workflow`, `test_cancel_nonexistent_job` |

### 统计和监控 API

| 端点 | 方法 | 测试状态 | 测试用例 |
|------|------|----------|----------|
| `/statistics` | GET | ✅ 已测试 | `test_job_statistics` |
| `/usage/stats` | GET | ✅ 已测试 | `test_usage_statistics` |
| `/queue/status` | GET | ✅ 已测试 | `test_queue_status` |

### 模型管理 API

| 端点 | 方法 | 测试状态 | 测试用例 |
|------|------|----------|----------|
| `/models` | GET | ✅ 已测试 | `test_get_all_models`, `test_get_models_by_type` |

## 测试覆盖率统计

- **总端点数**: 13
- **已测试**: 9 (69%)
- **部分测试**: 1 (8%)
- **未测试**: 3 (23%)

## 缺失的测试用例

### 1. `/generate-voice` (配音生成) ❌

**优先级**: 高

**需要测试的场景**:
- ✅ 成功创建配音任务
- ✅ 查询配音任务状态
- ✅ 不同语音类型（alloy, echo, fable, onyx, nova, shimmer）
- ✅ 不同语速（0.25 - 4.0）
- ✅ 不同语言（zh-CN, en-US）
- ✅ 积分不足
- ✅ 缺少必需字段（text）
- ✅ 无效的语音类型
- ✅ 无效的语速

**测试代码示例**:
```python
async def test_voice_generation_workflow(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试配音生成流程"""
    response = await async_client.post(
        '/api/v1/ai/generate-voice',
        json={
            'text': 'Hello, this is a test',
            'voice_type': 'alloy',
            'speed': 1.0,
            'language': 'en-US'
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data['code'] == 0
    assert 'job_id' in data['data']
```

### 2. `/generate-subtitle` (字幕生成) ❌

**优先级**: 高

**需要测试的场景**:
- ✅ 成功创建字幕任务
- ✅ 查询字幕任务状态
- ✅ 不同语言（zh, en, ja, ko）
- ✅ 积分不足
- ✅ 缺少必需字段（audio_url）
- ✅ 无效的音频 URL
- ✅ 不支持的语言代码

**测试代码示例**:
```python
async def test_subtitle_generation_workflow(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试字幕生成流程"""
    response = await async_client.post(
        '/api/v1/ai/generate-subtitle',
        json={
            'audio_url': 'https://example.com/audio.mp3',
            'language': 'zh'
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data['code'] == 0
    assert 'job_id' in data['data']
```

### 3. `/process-text` (文本处理) ❌

**优先级**: 高

**需要测试的场景**:
- ✅ 剧本解析（screenplay_parse）
- ✅ 内容分析（content_analysis）
- ✅ 风格转换（style_transform）
- ✅ 提示词生成（prompt_generation）
- ✅ 不同输出格式（json, text）
- ✅ 不同温度参数（0.0 - 2.0）
- ✅ 不同 max_tokens（100 - 8000）
- ✅ 积分不足
- ✅ 缺少必需字段（text, task_type）
- ✅ 无效的任务类型

**测试代码示例**:
```python
async def test_text_processing_workflow(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试文本处理流程"""
    response = await async_client.post(
        '/api/v1/ai/process-text',
        json={
            'task_type': 'screenplay_parse',
            'text': '场景1：室内 - 白天\n一个男人走进房间。',
            'output_format': 'json',
            'temperature': 0.7,
            'max_tokens': 2000
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 200
    data = response.json()
    assert data['code'] == 0
    assert 'job_id' in data['data']
```

### 4. `/generate-sound` (音效生成) ⚠️

**优先级**: 中（已明确不支持）

**当前状态**: 返回 501 Not Implemented

**需要测试的场景**:
- ✅ 验证返回 501 状态码
- ✅ 验证错误信息清晰
- ✅ 验证不扣除积分
- ✅ 验证不创建任务

**测试代码示例**:
```python
async def test_sound_generation_not_implemented(
    async_client: AsyncClient,
    test_user_token: str,
    test_ai_pricing_configs,
    test_ai_models
):
    """测试音效生成功能不可用"""
    response = await async_client.post(
        '/api/v1/ai/generate-sound',
        json={
            'description': 'Ocean waves',
            'duration': 5
        },
        headers={'Authorization': f'Bearer {test_user_token}'}
    )
    
    assert response.status_code == 501
    data = response.json()
    assert '暂不可用' in data['message']
    assert 'TTS' in data['message']
```

## 额外需要的测试场景

### 边界条件测试

1. **图片尺寸边界**
   - 最小尺寸（256x256）
   - 最大尺寸（2048x2048）
   - 无效尺寸（负数、0、超大）

2. **视频时长边界**
   - 最小时长（1秒）
   - 最大时长（60秒）
   - 无效时长（负数、0、超大）

3. **文本长度边界**
   - 空文本
   - 超长文本（> 4096 字符）
   - 特殊字符

4. **并发限制**
   - 单用户并发任务数限制
   - 系统总并发任务数限制

### 性能测试

1. **响应时间**
   - 任务创建响应时间 < 500ms
   - 任务查询响应时间 < 200ms
   - 批量查询响应时间 < 1s

2. **吞吐量**
   - 每秒可处理的请求数
   - 并发用户数

### 安全测试

1. **SQL 注入**
   - 在 prompt、description 等字段中注入 SQL
   - 在查询参数中注入 SQL

2. **XSS 攻击**
   - 在文本字段中注入脚本

3. **权限提升**
   - 尝试访问管理员功能
   - 尝试修改其他用户的任务

4. **速率限制**
   - 短时间内大量请求
   - DDoS 防护

## 测试优先级

### P0 (必须)
1. ✅ `/generate-voice` - 配音生成（核心功能）
2. ✅ `/generate-subtitle` - 字幕生成（核心功能）
3. ✅ `/process-text` - 文本处理（核心功能）
4. ✅ `/generate-sound` - 音效生成 501 测试

### P1 (重要)
1. ✅ 边界条件测试
2. ✅ 错误处理测试
3. ✅ 并发测试

### P2 (可选)
1. ⚠️ 性能测试
2. ⚠️ 安全测试
3. ⚠️ 压力测试

## 建议的测试文件结构

```
tests/integration/
├── test_ai_api_workflow.py          # 现有：基础工作流测试
├── test_ai_voice_generation.py      # 新增：配音生成测试
├── test_ai_subtitle_generation.py   # 新增：字幕生成测试
├── test_ai_text_processing.py       # 新增：文本处理测试
├── test_ai_sound_generation.py      # 新增：音效生成 501 测试
├── test_ai_boundary_conditions.py   # 新增：边界条件测试
└── test_ai_security.py              # 新增：安全测试
```

## 测试数据准备

### Fixtures 需求

1. **测试音频文件**
   - 用于字幕生成测试
   - 格式：MP3, WAV
   - 时长：5-10秒

2. **测试图片文件**
   - 用于图生视频测试
   - 格式：JPG, PNG
   - 尺寸：1024x1024

3. **测试文本**
   - 剧本样本
   - 不同语言的文本
   - 特殊字符文本

## 下一步行动

1. **立即执行** (本周)
   - 创建 `/generate-voice` 测试
   - 创建 `/generate-subtitle` 测试
   - 创建 `/process-text` 测试
   - 创建 `/generate-sound` 501 测试

2. **短期计划** (下周)
   - 添加边界条件测试
   - 添加错误处理测试
   - 提高测试覆盖率到 90%+

3. **长期计划** (本月)
   - 添加性能测试
   - 添加安全测试
   - 集成到 CI/CD 流程

## 测试执行

### 运行所有 AI API 测试

```bash
# 在容器内执行
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py -v

# 运行特定测试类
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py::TestImageGenerationWorkflow -v

# 运行特定测试用例
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py::TestImageGenerationWorkflow::test_complete_image_generation_workflow -v

# 生成覆盖率报告
docker exec jointo-server-app pytest tests/integration/test_ai_api_workflow.py --cov=app/api/v1/ai --cov-report=html
```

### 测试覆盖率目标

- **当前覆盖率**: ~69%
- **短期目标**: 90%
- **长期目标**: 95%+

## 总结

当前 AI API 测试覆盖了大部分核心功能，但仍有 3 个重要端点缺少测试：
1. `/generate-voice` - 配音生成
2. `/generate-subtitle` - 字幕生成
3. `/process-text` - 文本处理

建议优先补充这些测试用例，以确保 API 的稳定性和可靠性。