6.6 KiB

Raw Blame History

Phase 4: 代码清理 - 重命名误导性方法

日期: 2026-02-10
类型: 代码重构
影响范围: Screenplay Service

背景

根据 ADR 04: 移除废弃的 storyboard_resources 表，在完成数据库迁移后，进行最后的代码清理工作。

变更内容

1. 重命名误导性方法

文件: server/app/services/screenplay_service.py

方法重命名:

# 旧名称（误导性）
async def _sync_storyboard_resources(...)

# 新名称（准确描述功能）
async def _create_placeholder_resources_from_tags(...)

重命名原因:

旧名称 _sync_storyboard_resources 暗示与 storyboard_resources 表相关
实际功能是为剧本元素标签创建占位符项目资源
与废弃的 storyboard_resources 表无关
新名称更准确地描述了方法的实际功能

2. 更新方法文档

旧文档:

"""为标签创建占位符项目资源记录

逻辑说明：
1. 遍历所有标签（角色/场景/道具标签）
2. 为每个标签创建一条 project_resources 记录（占位符）
3. 不创建实际文件，仅关联 element_tag_id
4. 后续由 AI 生成图片并更新 file_url

Args:
    screenplay_id: 剧本 ID
    project_id: 项目 ID
    tag_id_maps: 标签 ID 映射表

Returns:
    创建的资源数量
"""

新文档:

"""为剧本元素标签创建占位符项目资源记录

功能说明：
- 为剧本解析生成的元素标签（角色/场景/道具）创建对应的项目资源记录
- 资源为占位符状态，不包含实际文件，仅关联 element_tag_id
- 后续由 AI 生成图片并更新 file_url

实现逻辑：
1. 遍历所有标签（角色/场景/道具标签）
2. 为每个标签创建一条 project_resources 记录（占位符）
3. 设置 file_url 为 "placeholder://pending-ai-generation"
4. 记录元数据：source, screenplay_id, status 等

Args:
    screenplay_id: 剧本 ID
    project_id: 项目 ID
    tag_id_maps: 标签 ID 映射表
        格式: {
            'character_tags': {'孙悟空-青年': UUID, ...},
            'location_tags': {'花果山-白天': UUID, ...},
            'prop_tags': {'金箍棒-完整': UUID, ...}
        }

Returns:
    创建的资源数量
"""

改进点:

明确说明功能：为剧本元素标签创建资源
详细说明实现逻辑
补充参数格式说明
移除与 storyboard_resources 表的误导性关联

3. 残留引用检查

检查结果: ✅ 无需清理

检查的文件:

test_storyboard_resource_api.py - 测试正常的 storyboard_resources API（非废弃表）
.migration-backup/ - 迁移备份文件（可忽略）
ai_conversation_service.py - 注释中的说明（已更新）
__init__.py - 导入正常的 storyboard_resources 路由
storyboard_resource_repository.py - 注释中的说明（已更新）

结论: 所有引用都是合理的，不需要清理。

命名对比

废弃的概念（已删除）

名称	用途	状态
`storyboard_resources` 表	分镜与项目素材的多对多关联	❌ 已删除
`StoryboardResource` 模型	关联表的 ORM 模型	❌ 已删除
`StoryboardResourceService`	管理分镜素材关联	❌ 已删除
`_sync_storyboard_resources()` 方法	误导性命名	❌ 已重命名

正常的概念（保留）

名称	用途	状态
`storyboard_items` 表	分镜元素关联（替代方案）	✅ 正常使用
`storyboard_images` 表	分镜生成的图片	✅ 正常使用
`storyboard_videos` 表	分镜生成的视频	✅ 正常使用
`storyboard_dialogues` 表	分镜对白	✅ 正常使用
`storyboard_voiceovers` 表	分镜配音	✅ 正常使用
`StoryboardResourceRepository`	管理分镜生成的资源	✅ 正常使用
`StoryboardResourceService`	管理分镜生成的资源	✅ 正常使用
`/api/v1/storyboard-resources/*`	分镜资源管理 API	✅ 正常使用
`_create_placeholder_resources_from_tags()`	创建占位符资源	✅ 已重命名

测试验证

单元测试

docker exec jointo-server-app pytest tests/unit/services/test_screenplay_service.py -v

结果: ✅ 全部通过

集成测试

docker exec jointo-server-app pytest tests/integration/test_screenplay_api.py -v

结果: ✅ 全部通过

影响分析

无影响

✅ 方法为私有方法（_ 前缀），外部无调用
✅ 仅在 ScreenplayService 内部使用
✅ 功能逻辑未改变，仅重命名
✅ 测试全部通过

改进效果

✅ 方法名更准确地描述功能
✅ 消除与废弃表的误导性关联
✅ 文档更清晰，易于理解
✅ 代码可维护性提升

总结

Phase 1-4 完成情况

Phase	内容	状态
Phase 1	修复 AI Conversation 功能	✅ 完成
Phase 2	删除废弃代码	✅ 完成
Phase 3	数据库迁移	✅ 完成
Phase 4	代码清理	✅ 完成

后端工作总结

删除统计:

代码文件：5 个
代码行数：~1070 行
数据库表：1 个
API 端点：6 个
测试文件：2 个

重构统计:

重命名方法：1 个
更新文档：1 处
修复功能：2 个（AI Conversation）

测试覆盖:

单元测试：✅ 全部通过
集成测试：✅ 全部通过
数据库迁移：✅ 成功执行

下一步

Phase 5: 前端适配（需要前端开发配合）:

修改 API 服务层（client/src/services/api/storyboards.ts）
更新类型定义（client/src/types/storyboard.ts）
修改 UI 组件（6 个组件）
修改 Hooks（2 个 Hooks）
更新工具函数
更新 Mock 数据

前端影响的 API 端点（已删除，需要替代方案）:

POST /api/v1/storyboards/{id}/resources/batch
DELETE /api/v1/storyboards/{id}/resources/batch
POST /api/v1/storyboards/{id}/resources/{resourceId}
DELETE /api/v1/storyboards/{id}/resources/{resourceId}
GET /api/v1/storyboards/{id}/resources
GET /api/v1/resources/{id}/storyboards

替代方案: 使用 storyboard_items API（/api/v1/storyboards/{id}/items）

6.6 KiB Raw Blame History