docs/v1.0/.archive/server/rfcs/120-screenplay-element-variants.md

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

⚠️ 已废弃 (DEPRECATED)
废弃日期：2025-01-20
替代文档：ADR 005: 变体到标签系统重构

本 RFC 已被新的标签系统架构替代。"变体"(Variant)术语已统一更新为"标签"(Tag)，并采用统一表设计。
请参考最新的 ScreenplayTagService 文档。

---

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

---

背景

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

典型需求

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

当前问题

现有系统缺少变体管理机制：

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

---

目标

核心目标

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

非目标

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

---

技术方案

1. 数据库设计

1.1 变体表结构

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

-- 角色变体表
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 剧本元素表更新

-- 添加变体标识字段
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 素材表更新

-- 添加变体关联字段
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 操作：

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 剧本拆解：

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. 预设模板

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

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 分析的响应时间

---

相关文档

• 剧本元素变体管理服务
• 剧本管理服务
• 项目素材管理服务

---

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