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

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

## 背景

根据 [ADR 04: 移除废弃的 storyboard_resources 表](../adrs/04-remove-storyboard-resources-table.md)，在完成数据库迁移后，进行最后的代码清理工作。

## 变更内容

### 1. 重命名误导性方法

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

**方法重命名**:
```python
# 旧名称（误导性）
async def _sync_storyboard_resources(...)

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

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

### 2. 更新方法文档

**旧文档**:
```python
"""为标签创建占位符项目资源记录

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

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

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

**新文档**:
```python
"""为剧本元素标签创建占位符项目资源记录

功能说明：
- 为剧本解析生成的元素标签（角色/场景/道具）创建对应的项目资源记录
- 资源为占位符状态，不包含实际文件，仅关联 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. 残留引用检查

**检查结果**: ✅ 无需清理

**检查的文件**:
1. `test_storyboard_resource_api.py` - 测试正常的 storyboard_resources API（非废弃表）
2. `.migration-backup/` - 迁移备份文件（可忽略）
3. `ai_conversation_service.py` - 注释中的说明（已更新）
4. `__init__.py` - 导入正常的 storyboard_resources 路由
5. `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()` | 创建占位符资源 | ✅ 已重命名 |

## 测试验证

### 单元测试

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

**结果**: ✅ 全部通过

### 集成测试

```bash
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 端点**（已删除，需要替代方案）:
1. `POST /api/v1/storyboards/{id}/resources/batch`
2. `DELETE /api/v1/storyboards/{id}/resources/batch`
3. `POST /api/v1/storyboards/{id}/resources/{resourceId}`
4. `DELETE /api/v1/storyboards/{id}/resources/{resourceId}`
5. `GET /api/v1/storyboards/{id}/resources`
6. `GET /api/v1/resources/{id}/storyboards`

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

## 参考

- [ADR 04: 移除废弃的 storyboard_resources 表](../adrs/04-remove-storyboard-resources-table.md)
- [Phase 1 Changelog](./2026-02-10-remove-storyboard-resources-table-phase1.md)
- [Phase 2 Changelog](./2026-02-10-remove-storyboard-resources-table-phase2.md)
- [Phase 3 Changelog](./2026-02-10-remove-storyboard-resources-table-phase3.md)