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

剧本管理服务单元测试创建记录

日期: 2026-02-04
类型: 测试创建
影响范围: 剧本管理服务（Screenplay Service）

概述

为剧本管理服务创建了完整的单元测试套件，包括 Repository 层和 Service 层的所有功能测试。

测试文件

1. Repository 层测试

文件: server/tests/unit/repositories/test_screenplay_repository.py

测试覆盖:

• ✅ 基础 CRUD 操作（创建、查询、更新、删除）
• ✅ 按项目查询剧本列表（分页、筛选、排序）
• ✅ 版本管理（创建版本、查询版本历史）
• ✅ 角色/场景/道具管理
• ✅ 边界条件和错误处理

测试结果: ✅ 16/16 通过

2. Service 层测试

文件: server/tests/unit/services/test_screenplay_service.py

测试覆盖:

• ✅ 剧本列表查询（权限控制、状态筛选）
• ✅ 剧本详情获取
• ✅ 创建剧本（文本类型、权限验证、内容验证）
• ✅ 更新剧本（基本更新、版本自动创建）
• ✅ 审批剧本（权限控制）
• ✅ 版本历史查询
• ✅ 默认标签管理（角色/场景/道具）
• ✅ 角色/场景/道具创建

测试结果: ✅ 20/20 通过

修复的问题

1. UUID 类型转换问题

问题: ProjectRepository.get_by_id() 方法接收 str 类型参数，但 Service 传入 UUID 对象导致转换错误。

解决方案: 修改方法签名接受 Union[str, UUID] 类型，统一处理转换逻辑。

影响文件:

• server/app/repositories/project_repository.py

2. 权限检查失败

问题: check_user_permission() 方法比较 UUID 对象和字符串时类型不匹配。

解决方案: 统一转换为字符串进行比较。

影响文件:

• server/app/repositories/project_repository.py

3. 时区问题

问题: Screenplay.approved_at 字段使用 timezone-aware datetime，但数据库列定义为 TIMESTAMP WITHOUT TIME ZONE。

解决方案: 修改字段定义使用 TIMESTAMP(timezone=True)。

影响文件:

• server/app/models/screenplay.py

4. 测试数据问题

问题: 测试中传入 change_summary 参数，但这不是 Screenplay 模型的字段。

解决方案: 移除测试中的 change_summary 参数。

影响文件:

• server/tests/unit/services/test_screenplay_service.py

5. Repository 方法调用问题

问题: ScreenplayService._get_default_thumbnail() 调用 get_by_element_tag_id() 时传入了不存在的 limit 参数。

解决方案: 移除 limit 参数，改为在 Python 层面获取第一个元素。

影响文件:

• server/app/services/screenplay_service.py

6. 导入错误

问题: 测试中导入 app.models.screenplay_tag 应该是 app.models.screenplay_element_tag。

解决方案: 修正导入路径。

影响文件:

• server/tests/unit/services/test_screenplay_service.py

7. 测试辅助方法问题

问题: _add_project_member() 方法调用 ProjectRepository.add_member() 时参数传递错误。

解决方案: 修正方法调用，直接传递参数而不是 ProjectMember 对象。

影响文件:

• server/tests/unit/services/test_screenplay_service.py

测试执行结果

# Repository 层测试
$ docker exec jointo-server-app pytest tests/unit/repositories/test_screenplay_repository.py -v
========================= 16 passed in 0.15s =========================

# Service 层测试
$ docker exec jointo-server-app pytest tests/unit/services/test_screenplay_service.py -v
========================= 20 passed in 0.77s =========================

技术栈合规性

所有代码完全符合 jointo-tech-stack 规范：

• ✅ 使用 async/await 异步模式
• ✅ Repository 使用 flush()，Service 使用 commit()
• ✅ 日志使用 %-formatting
• ✅ 时间戳使用 TIMESTAMP(timezone=True)
• ✅ UUID 使用 generate_uuid()
• ✅ 测试使用 pytest + pytest-asyncio
• ✅ 所有测试方法使用 async/await

后续建议

1. 集成测试: 创建 API 层集成测试验证完整的请求-响应流程
2. 性能测试: 测试大量数据场景下的查询性能
3. 并发测试: 验证多用户同时操作的数据一致性
4. 边界测试: 补充更多边界条件和异常场景测试

相关文档

• 功能实现: docs/server/changelogs/2026-02-04-screenplay-service-complete-implementation.md
• 技术栈规范: .trae/skills/jointo-tech-stack/references/backend.md
• 测试指南: server/tests/README.md