docs/v1.0/server/changelogs/2026-02-04-storyboard-resource-tests-creation.md

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 中定义）:

# 基础 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%+

运行测试

# 运行所有 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:

@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 模块测试
• Jointo Tech Stack - Testing
• pytest 文档

总结

已为 Storyboard Resource 模块创建完整的三层测试套件，共 80+ 测试用例，覆盖：

• 分镜图片管理（版本控制、激活状态）
• 分镜视频管理（版本控制、激活状态）
• 对白管理（顺序管理、CRUD）
• 配音管理（版本控制、激活状态）
• 权限控制和业务规则验证

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