# RFC 120: 剧本元素变体管理系统

> **⚠️ 已废弃 (DEPRECATED)**  
> **废弃日期**：2025-01-20  
> **替代文档**：[ADR 005: 变体到标签系统重构](../../architecture/adrs/005-variant-to-tag-system-refactor.md)  
> 
> 本 RFC 已被新的标签系统架构替代。"变体"(Variant)术语已统一更新为"标签"(Tag)，并采用统一表设计。  
> 请参考最新的 [ScreenplayTagService 文档](../../requirements/backend/04-services/project/screenplay-tag-service.md)。

---

> **状态**：~~设计中~~ **已废弃**  
> **创建时间**：2025-01-27  
> **作者**：系统架构师

---

## 背景

在影视制作中，同一角色、场景或道具经常需要多个版本的素材：

### 典型需求

1. **角色多年龄段**：角色从少年到老年的一生故事，需要不同年龄段的形象
2. **场景跨时光**：同一地点在不同时代的样貌（如：1990年代的咖啡厅 vs 2020年代的咖啡厅）
3. **道具演变**：道具在剧情中的不同状态（如：古剑的完好、破损、修复状态）

### 当前问题

现有系统缺少变体管理机制：
- 无法标识同一元素的多个版本
- 素材管理混乱，难以区分不同变体
- 用户需要手动记忆和管理变体关系
- 无法利用 AI 自动识别变体需求

---

## 目标

### 核心目标

1. **结构化管理**：为角色、场景、道具提供变体管理能力
2. **AI 智能识别**：自动从剧本中识别变体需求
3. **灵活扩展**：支持预设模板和用户自定义
4. **素材关联**：素材可以关联到具体的变体

### 非目标

- 不涉及素材的自动生成（由 AI 服务负责）
- 不涉及变体之间的自动转换
- 不涉及变体的版本控制（Phase 3 考虑）

---

## 技术方案

### 1. 数据库设计

#### 1.1 变体表结构

为角色、场景、道具分别创建变体表：

```sql
-- 角色变体表
CREATE TABLE screenplay_character_variants (
    variant_id UUID PRIMARY KEY DEFAULT gen_uuid_v7(),
    character_id UUID NOT NULL REFERENCES screenplay_characters(character_id) ON DELETE CASCADE,
    variant_key TEXT NOT NULL,
    variant_label TEXT NOT NULL,
    description TEXT,
    order_index INTEGER NOT NULL DEFAULT 0,
    
    -- AI 识别信息
    ai_generated BOOLEAN NOT NULL DEFAULT false,
    ai_confidence NUMERIC(3, 2),
    ai_context TEXT,
    
    -- 元数据
    metadata JSONB NOT NULL DEFAULT '{}',
    
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    
    CONSTRAINT screenplay_character_variants_unique UNIQUE (character_id, variant_key)
);
```

**设计要点**：
- `variant_key`：变体标识（如：youth, adult, elder），用于程序逻辑
- `variant_label`：变体显示名称（如：少年、青年、老年），用于 UI 展示
- `ai_generated`：标识是否由 AI 生成，便于区分
- `ai_confidence`：AI 识别置信度（0.00-1.00）
- `ai_context`：AI 识别的剧本原文片段，便于用户验证
- `metadata`：灵活存储额外信息（年龄范围、出现场景等）

#### 1.2 剧本元素表更新

```sql
-- 添加变体标识字段
ALTER TABLE screenplay_characters ADD COLUMN has_variants BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE screenplay_scenes ADD COLUMN has_variants BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE screenplay_props ADD COLUMN has_variants BOOLEAN NOT NULL DEFAULT false;
```

**用途**：快速判断元素是否有变体，优化查询性能

#### 1.3 素材表更新

```sql
-- 添加变体关联字段
ALTER TABLE project_resources 
ADD COLUMN character_variant_id UUID REFERENCES screenplay_character_variants(variant_id) ON DELETE SET NULL,
ADD COLUMN scene_variant_id UUID REFERENCES screenplay_scene_variants(variant_id) ON DELETE SET NULL,
ADD COLUMN prop_variant_id UUID REFERENCES screenplay_prop_variants(variant_id) ON DELETE SET NULL;

-- 约束：最多只能关联一个变体
ALTER TABLE project_resources 
ADD CONSTRAINT project_resources_variant_check CHECK (
    (character_variant_id IS NOT NULL AND scene_variant_id IS NULL AND prop_variant_id IS NULL) OR
    (scene_variant_id IS NOT NULL AND character_variant_id IS NULL AND prop_variant_id IS NULL) OR
    (prop_variant_id IS NOT NULL AND character_variant_id IS NULL AND scene_variant_id IS NULL) OR
    (character_variant_id IS NULL AND scene_variant_id IS NULL AND prop_variant_id IS NULL)
);
```

### 2. 服务层设计

#### 2.1 ScreenplayVariantService

负责变体的 CRUD 操作：

```python
class ScreenplayVariantService:
    async def create_character_variant(...)  # 创建角色变体
    async def update_character_variant(...)  # 更新角色变体
    async def delete_character_variant(...)  # 删除角色变体
    async def get_character_variants(...)    # 获取角色的所有变体
    async def get_variant_templates(...)     # 获取预设模板
```

#### 2.2 ScreenplayAnalysisService

负责 AI 剧本拆解：

```python
class ScreenplayAnalysisService:
    async def analyze_screenplay(...)  # 分析剧本，提取元素和变体
    async def _call_ai_analysis(...)   # 调用 AI API
    async def _extract_characters_with_variants(...)  # 提取角色及变体
```

### 3. AI 集成

#### 3.1 AI Prompt 设计

```
请分析以下剧本内容，提取角色、场景、道具信息，并识别它们的变体。

剧本内容：
{content}

请以 JSON 格式返回，包含：
1. characters: 角色列表
   - name: 角色名
   - variants: 变体列表
     - key: 变体标识（如 youth, adult, elder）
     - label: 变体显示名称（如 少年、青年、老年）
     - confidence: 识别置信度（0.0-1.0）
     - context: 剧本中的相关描述
```

#### 3.2 置信度评分

- **0.9-1.0**：非常确定（剧本明确描述）
- **0.7-0.9**：比较确定（有明显线索）
- **0.5-0.7**：不太确定（需要用户确认）
- **< 0.5**：不建议自动创建

### 4. 预设模板

提供常用的变体模板，降低使用门槛：

```python
class VariantTemplate:
    CHARACTER_AGE_TEMPLATES = [
        {'key': 'child', 'label': '儿童', 'description': '0-12岁'},
        {'key': 'youth', 'label': '少年', 'description': '13-17岁'},
        {'key': 'young_adult', 'label': '青年', 'description': '18-30岁'},
        {'key': 'middle_aged', 'label': '中年', 'description': '31-50岁'},
        {'key': 'elder', 'label': '老年', 'description': '51岁以上'}
    ]
```

---

## API 设计

### 1. 变体管理

```
# 获取预设模板
GET /api/v1/variant-templates?element_type=character&category=age

# 创建角色变体
POST /api/v1/characters/{character_id}/variants

# 获取角色的所有变体
GET /api/v1/characters/{character_id}/variants

# 更新变体
PATCH /api/v1/variants/{variant_id}

# 删除变体
DELETE /api/v1/variants/{variant_id}
```

### 2. AI 拆解

```
# AI 剧本拆解
POST /api/v1/screenplays/{screenplay_id}/analyze
```

### 3. 素材关联

```
# 上传素材时关联变体
POST /api/v1/projects/{project_id}/resources
FormData:
  - file: <binary>
  - character_variant_id: "019d..."

# 获取角色的所有素材（按变体分组）
GET /api/v1/characters/{character_id}/resources?group_by_variant=true
```

---

## 用户交互流程

### 流程 1：AI 剧本拆解

```
1. 用户上传剧本
2. 点击"AI 智能拆解"
3. AI 分析剧本，识别角色/场景/道具及其变体
4. 展示拆解结果（带置信度）
5. 用户确认/修正/删除变体
6. 为每个变体上传素材
```

### 流程 2：手动添加变体

```
1. 用户在角色详情页点击"添加变体"
2. 选择预设模板或自定义输入
3. 填写变体信息（标识、名称、描述）
4. 保存变体
5. 上传该变体的素材
```

### 流程 3：查看素材

```
1. 用户点击角色"张三"
2. 系统检测到 has_variants = true
3. 展示变体选项卡（少年 | 青年 | 中年 | 老年）
4. 用户切换选项卡查看不同变体的素材
```

---

## 优势

### 1. 结构化管理

- 清晰的变体层级关系
- 便于查询和统计
- 支持批量操作

### 2. AI 智能识别

- 自动识别变体需求
- 减少手动工作量
- 提供置信度参考

### 3. 灵活扩展

- 预设模板 + 自定义
- 支持任意变体类型
- 元数据字段可扩展

### 4. 用户友好

- 按变体分组展示
- 素材数量统计
- 直观的 UI 交互

---

## 风险与挑战

### 1. AI 识别准确性

**风险**：AI 可能误识别或遗漏变体

**缓解措施**：
- 提供置信度评分
- 支持用户修正
- 保留 AI 识别的上下文供用户验证

### 2. 数据一致性

**风险**：删除变体时，关联的素材如何处理

**缓解措施**：
- 使用 `ON DELETE SET NULL`，素材不会被删除
- 提供"孤儿素材"清理工具
- 删除前提示用户

### 3. 性能问题

**风险**：大量变体和素材时查询性能下降

**缓解措施**：
- 合理使用索引
- 分页查询
- 缓存常用数据

---

## 实施计划

### Phase 1：基础功能（2-3 周）

- ✅ 数据库表结构
- ✅ 变体 CRUD API
- ✅ 预设模板
- ✅ 素材关联变体
- ✅ 按变体分组查询

### Phase 2：AI 增强（2-3 周）

- ✅ AI 剧本拆解
- ✅ 变体智能识别
- ✅ 置信度评分
- ✅ 用户确认流程

### Phase 3：高级功能（3-4 周）

- 变体时间线（少年 → 青年 → 老年）
- 批量生成变体素材
- 变体模板市场
- 使用统计分析

---

## 测试策略

### 1. 单元测试

- 变体 CRUD 操作
- 数据库约束验证
- AI 识别结果解析

### 2. 集成测试

- 完整的剧本拆解流程
- 素材上传和关联
- 按变体分组查询

### 3. 性能测试

- 1000+ 变体的查询性能
- 10000+ 素材的分组性能
- AI 分析的响应时间

---

## 相关文档

- [剧本元素变体管理服务](../../requirements/backend/04-services/project/screenplay-variant-service.md)
- [剧本管理服务](../../requirements/backend/04-services/project/screenplay-service.md)
- [项目素材管理服务](../../requirements/backend/04-services/resource/project-resource-service.md)

---

**文档版本**：v1.0  
**最后更新**：2025-01-27