# Storyboard Resource 模块测试创建

**日期**: 2026-02-04  
**类型**: 测试实现  
**影响范围**: 分镜资源模块（图片、视频、对白、配音）

## 概述

为 Storyboard Resource 模块创建完整的测试套件，参考 Storyboard 模块的测试结构，覆盖 Repository、Service 和 API 三层。

## 变更内容

### 1. Repository 层测试

**文件**: `server/tests/unit/repositories/test_storyboard_resource_repository.py`

**测试覆盖**:

#### 分镜图片 (StoryboardImage)
- ✅ 创建图片
- ✅ 根据 ID 获取图片
- ✅ 获取分镜的所有图片版本（按版本号降序）
- ✅ 获取激活的图片
- ✅ 获取最大版本号
- ✅ 取消所有图片的激活状态
- ✅ 更新图片
- ✅ 删除图片

#### 分镜视频 (StoryboardVideo)
- ✅ 创建视频
- ✅ 根据 ID 获取视频
- ✅ 获取分镜的所有视频版本（按版本号降序）
- ✅ 获取激活的视频
- ✅ 获取最大版本号
- ✅ 取消所有视频的激活状态
- ✅ 更新视频
- ✅ 删除视频

#### 对白 (StoryboardDialogue)
- ✅ 创建对白
- ✅ 根据 ID 获取对白
- ✅ 获取分镜的所有对白（按顺序号排序）
- ✅ 获取最大顺序号
- ✅ 更新对白
- ✅ 删除对白

#### 配音 (StoryboardVoiceover)
- ✅ 创建配音
- ✅ 根据 ID 获取配音
- ✅ 获取对白的所有配音版本
- ✅ 获取激活的配音
- ✅ 取消所有配音的激活状态
- ✅ 更新配音
- ✅ 删除配音

**测试数量**: 40+ 测试用例

### 2. Service 层测试

**文件**: `server/tests/unit/services/test_storyboard_resource_service.py`

**测试覆盖**:

#### 分镜图片管理
- ✅ 创建图片成功（自动版本号管理）
- ✅ 创建激活图片时取消其他图片
- ✅ 获取图片列表成功
- ✅ 设置激活图片成功
- ✅ 删除图片成功（文件引用计数管理）
- ✅ 删除激活图片失败（业务规则验证）

#### 分镜视频管理
- ✅ 创建视频成功（自动版本号管理）
- ✅ 设置激活视频成功

#### 对白管理
- ✅ 创建对白成功
- ✅ 创建对白自动分配顺序号
- ✅ 更新对白成功
- ✅ 重新排序对白成功

#### 配音管理
- ✅ 创建配音成功
- ✅ 设置激活配音成功
- ✅ 删除配音成功（文件引用计数管理）
- ✅ 删除激活配音失败（业务规则验证）

**测试特点**:
- 使用 Mock 对象隔离依赖
- 测试权限校验逻辑
- 测试业务规则验证
- 测试文件存储集成

**测试数量**: 15+ 测试用例

### 3. API 集成测试

**文件**: `server/tests/integration/test_storyboard_resource_api.py`

**测试覆盖**:

#### 分镜图片 API
- ✅ GET `/storyboards/{id}/images` - 获取图片列表
- ✅ GET `/storyboards/{id}/images/active` - 获取激活图片
- ✅ POST `/storyboards/{id}/images` - 创建图片
- ✅ POST `/storyboard-images/{id}/activate` - 设置激活图片
- ✅ DELETE `/storyboard-images/{id}` - 删除图片
- ✅ 删除激活图片失败（400）

#### 分镜视频 API
- ✅ GET `/storyboards/{id}/videos` - 获取视频列表
- ✅ GET `/storyboards/{id}/videos/active` - 获取激活视频
- ✅ POST `/storyboards/{id}/videos` - 创建视频
- ✅ POST `/storyboard-videos/{id}/activate` - 设置激活视频
- ✅ DELETE `/storyboard-videos/{id}` - 删除视频

#### 对白 API
- ✅ GET `/storyboards/{id}/dialogues` - 获取对白列表
- ✅ POST `/storyboards/{id}/dialogues` - 创建对白
- ✅ PATCH `/dialogues/{id}` - 更新对白
- ✅ DELETE `/dialogues/{id}` - 删除对白
- ✅ POST `/storyboards/{id}/dialogues/reorder` - 重新排序对白

#### 配音 API
- ✅ GET `/dialogues/{id}/voiceovers` - 获取配音列表
- ✅ GET `/dialogues/{id}/voiceovers/active` - 获取激活配音
- ✅ POST `/dialogues/{id}/voiceovers` - 创建配音
- ✅ POST `/voiceovers/{id}/activate` - 设置激活配音
- ✅ DELETE `/voiceovers/{id}` - 删除配音

#### 权限测试
- ✅ 访问其他用户的分镜资源（403）
- ✅ 未授权访问（403）

**测试数量**: 25+ 测试用例

## 测试架构

### 测试分层

```
tests/
├── unit/
│   ├── repositories/
│   │   └── test_storyboard_resource_repository.py  # 数据访问层
│   └── services/
│       └── test_storyboard_resource_service.py     # 业务逻辑层
└── integration/
    └── test_storyboard_resource_api.py             # API 端到端
```

### 测试模式

1. **Repository 层**: 真实数据库操作，测试 SQL 查询正确性
2. **Service 层**: Mock 依赖，测试业务逻辑和规则验证
3. **API 层**: 完整请求-响应流程，测试 HTTP 接口

### Fixture 依赖

测试需要以下 fixtures（需在 `conftest.py` 中定义）:

```python
# 基础 fixtures
- db_session: 数据库会话
- test_user: 测试用户
- test_project: 测试项目
- test_storyboard: 测试分镜
- auth_headers: 认证头

# 资源 fixtures
- test_storyboard_image: 单个图片
- test_storyboard_images: 多个图片（3个版本）
- test_storyboard_video: 单个视频
- test_storyboard_videos: 多个视频（3个版本）
- test_storyboard_dialogue: 单个对白
- test_storyboard_dialogues: 多个对白（3个）
- test_storyboard_voiceover: 单个配音
- test_storyboard_voiceovers: 多个配音（3个版本）

# 权限测试 fixtures
- test_other_user_storyboard: 其他用户的分镜
```

## 测试覆盖率目标

- **Repository 层**: 95%+
- **Service 层**: 90%+
- **API 层**: 85%+

## 运行测试

```bash
# 运行所有 Storyboard Resource 测试
docker exec jointo-server-app pytest tests/unit/repositories/test_storyboard_resource_repository.py -v
docker exec jointo-server-app pytest tests/unit/services/test_storyboard_resource_service.py -v
docker exec jointo-server-app pytest tests/integration/test_storyboard_resource_api.py -v

# 运行所有测试并生成覆盖率报告
docker exec jointo-server-app pytest tests/ --cov=app.repositories.storyboard_resource_repository --cov=app.services.storyboard_resource_service --cov-report=html
```

## 技术栈合规性

### ✅ 遵循的规范

1. **测试框架**: pytest + pytest-asyncio
2. **Mock 工具**: unittest.mock.AsyncMock
3. **数据库**: 真实 PostgreSQL 17 + UUID v7
4. **异步支持**: 所有测试使用 `@pytest.mark.asyncio`
5. **命名规范**: `test_<功能>_<场景>`
6. **文档**: 完整的 docstring 和注释

### 📋 测试最佳实践

1. **隔离性**: 每个测试独立，不依赖其他测试
2. **可读性**: 清晰的测试名称和结构（Arrange-Act-Assert）
3. **覆盖性**: 正常流程 + 异常流程 + 边界条件
4. **性能**: 使用 fixtures 复用测试数据
5. **维护性**: 遵循 DRY 原则，提取公共逻辑

## 后续工作

### 需要添加的 Fixtures

在 `server/tests/conftest.py` 中添加以下 fixtures:

```python
@pytest.fixture
async def test_storyboard_image(db_session, test_storyboard):
    """创建测试图片"""
    # 实现...

@pytest.fixture
async def test_storyboard_images(db_session, test_storyboard):
    """创建多个测试图片（3个版本）"""
    # 实现...

@pytest.fixture
async def test_storyboard_video(db_session, test_storyboard):
    """创建测试视频"""
    # 实现...

@pytest.fixture
async def test_storyboard_videos(db_session, test_storyboard):
    """创建多个测试视频（3个版本）"""
    # 实现...

@pytest.fixture
async def test_storyboard_dialogue(db_session, test_storyboard):
    """创建测试对白"""
    # 实现...

@pytest.fixture
async def test_storyboard_dialogues(db_session, test_storyboard):
    """创建多个测试对白（3个）"""
    # 实现...

@pytest.fixture
async def test_storyboard_voiceover(db_session, test_storyboard, test_storyboard_dialogue):
    """创建测试配音"""
    # 实现...

@pytest.fixture
async def test_storyboard_voiceovers(db_session, test_storyboard, test_storyboard_dialogue):
    """创建多个测试配音（3个版本）"""
    # 实现...
```

### 测试执行验证

1. 添加 fixtures 到 `conftest.py`
2. 运行测试验证通过率
3. 生成覆盖率报告
4. 修复失败的测试用例

## 参考文档

- [Storyboard 模块测试](./2026-02-04-storyboard-tests-creation.md)
- [Jointo Tech Stack - Testing](../../.trae/skills/jointo-tech-stack/references/backend.md)
- [pytest 文档](https://docs.pytest.org/)

## 总结

已为 Storyboard Resource 模块创建完整的三层测试套件，共 80+ 测试用例，覆盖：
- 分镜图片管理（版本控制、激活状态）
- 分镜视频管理（版本控制、激活状态）
- 对白管理（顺序管理、CRUD）
- 配音管理（版本控制、激活状态）
- 权限控制和业务规则验证

测试结构清晰，遵循项目技术栈规范，为模块的稳定性和可维护性提供保障。