9.8 KiB

Raw Permalink Blame History

剧本和附件模块设计方案

创建日期：2025-01-27
设计者：系统架构师
状态：已完成

1. 需求背景

项目需要支持剧本管理功能，用户在创建项目时可以：

直接输入剧本文本：在线编辑剧本内容
上传剧本文档：支持 PDF、Word、TXT、Markdown 等格式

同时需要一个通用的附件管理系统，支持多种文件类型的上传、存储和管理。

2. 设计方案

2.1 核心设计思路

采用渐进式设计，分为两个阶段：

阶段 1：MVP（已完成）

scripts 表：剧本核心表，支持文本和附件两种类型
attachments 表：通用附件表，可复用于多种场景

阶段 2：增强功能（可选）

script_versions 表：剧本版本历史
script_characters 表：剧本角色管理
script_scenes 表：剧本场景管理

2.2 数据库设计

2.2.1 剧本表（scripts）

CREATE TYPE script_type AS ENUM ('text', 'attachment');
CREATE TYPE script_status AS ENUM ('draft', 'review', 'approved', 'archived');

CREATE TABLE scripts (
    script_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    project_id BIGINT NOT NULL REFERENCES projects(project_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    type script_type NOT NULL,
    content TEXT,                    -- 文本剧本内容
    attachment_id BIGINT,            -- 附件剧本ID
    version INTEGER NOT NULL DEFAULT 1,
    word_count INTEGER DEFAULT 0,
    scene_count INTEGER DEFAULT 0,
    character_count INTEGER DEFAULT 0,
    ai_job_id BIGINT,               -- AI生成关联
    ai_prompt TEXT,
    status script_status NOT NULL DEFAULT 'draft',
    created_by BIGINT NOT NULL,
    updated_by BIGINT,
    approved_by BIGINT,
    approved_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ,
    CONSTRAINT scripts_content_check CHECK (
        (type = 'text' AND content IS NOT NULL AND attachment_id IS NULL) OR
        (type = 'attachment' AND attachment_id IS NOT NULL AND content IS NULL)
    )
);

关键特性：

✅ 使用 ENUM 定义剧本类型和状态
✅ CHECK 约束确保 content 和 attachment_id 二选一
✅ 支持版本号、字数统计等元数据
✅ 支持 AI 生成剧本的关联
✅ 支持审批流程（draft -> review -> approved）

2.2.2 附件表（attachments）

CREATE TYPE attachment_category AS ENUM ('script', 'document', 'contract', 'reference', 'other');

CREATE TABLE attachments (
    attachment_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name TEXT NOT NULL,
    original_name TEXT NOT NULL,
    file_url TEXT NOT NULL,
    file_size BIGINT NOT NULL,
    mime_type TEXT NOT NULL,
    category attachment_category NOT NULL DEFAULT 'other',
    extension TEXT,
    checksum TEXT,                   -- 文件校验和（防重复）
    project_id BIGINT,
    user_id BIGINT,
    is_public BOOLEAN NOT NULL DEFAULT false,
    access_count INTEGER NOT NULL DEFAULT 0,
    download_count INTEGER NOT NULL DEFAULT 0,
    storage_provider TEXT,
    storage_path TEXT,
    uploaded_by BIGINT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ,
    expires_at TIMESTAMPTZ
);

关键特性：

✅ 通用附件表，支持多种文件类型
✅ 使用校验和防止重复上传
✅ 支持多态关联（项目、用户等）
✅ 记录访问和下载次数
✅ 支持临时文件（expires_at）

2.2.3 扩展表（阶段2）

剧本版本历史表：

CREATE TABLE script_versions (
    version_id BIGINT PRIMARY KEY,
    script_id BIGINT NOT NULL,
    version_number INTEGER NOT NULL,
    content_snapshot TEXT,
    change_summary TEXT,
    created_by BIGINT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL
);

剧本角色表：

CREATE TABLE script_characters (
    character_id BIGINT PRIMARY KEY,
    script_id BIGINT NOT NULL,
    name TEXT NOT NULL,
    description TEXT,
    role_type ENUM ('main', 'supporting', 'extra'),
    line_count INTEGER DEFAULT 0
);

剧本场景表：

CREATE TABLE script_scenes (
    scene_id BIGINT PRIMARY KEY,
    script_id BIGINT NOT NULL,
    scene_number INTEGER NOT NULL,
    title TEXT NOT NULL,
    location TEXT,
    time_of_day ENUM ('dawn', 'morning', 'noon', 'afternoon', 'dusk', 'night'),
    duration_estimate NUMERIC(10, 3)
);

3. 后端服务设计

3.1 剧本管理服务（ScriptService）

核心功能：

get_scripts() - 获取剧本列表（支持分页、状态筛选）
create_script() - 创建剧本（文本或附件）
update_script() - 更新剧本（自动创建版本）
approve_script() - 审批剧本
get_script_versions() - 获取版本历史
add_character() - 添加角色
add_scene() - 添加场景

权限控制：

查看：viewer 及以上
编辑：editor 及以上
审批：owner

3.2 附件管理服务（AttachmentService）

核心功能：

upload_attachment() - 上传附件（支持去重）
get_attachment() - 获取附件详情
get_download_url() - 获取下载链接（预签名URL）
delete_attachment() - 删除附件

文件类型限制：

剧本文件：PDF、Word、TXT、Markdown
最大文件大小：50MB（可配置）

安全特性：

✅ 文件类型白名单验证
✅ 文件大小限制
✅ SHA256 校验和防重复
✅ 预签名 URL 临时访问
✅ 访问权限控制

4. API 设计

4.1 剧本相关 API

GET    /api/v1/scripts                    # 获取剧本列表
POST   /api/v1/scripts                    # 创建剧本
GET    /api/v1/scripts/{id}               # 获取剧本详情
PUT    /api/v1/scripts/{id}               # 更新剧本
POST   /api/v1/scripts/{id}/approve       # 审批剧本
GET    /api/v1/scripts/{id}/versions      # 获取版本历史
POST   /api/v1/scripts/{id}/characters    # 添加角色
POST   /api/v1/scripts/{id}/scenes        # 添加场景

4.2 附件相关 API

POST   /api/v1/attachments                # 上传附件
GET    /api/v1/attachments/{id}           # 获取附件详情
GET    /api/v1/attachments/{id}/download  # 获取下载链接
DELETE /api/v1/attachments/{id}           # 删除附件

5. 前端集成

5.1 TypeScript 类型定义

// Script 类型
export type ScriptType = "text" | "attachment";
export type ScriptStatus = "draft" | "review" | "approved" | "archived";

export interface Script {
  script_id: number;
  project_id: number;
  name: string;
  type: ScriptType;
  content?: string;
  attachment_id?: number;
  version: number;
  word_count: number;
  scene_count: number;
  character_count: number;
  status: ScriptStatus;
  created_by: number;
  created_at: string;
  updated_at: string;
}

// Attachment 类型
export type AttachmentCategory =
  | "script"
  | "document"
  | "contract"
  | "reference"
  | "other";

export interface Attachment {
  attachment_id: number;
  name: string;
  original_name: string;
  file_url: string;
  file_size: number;
  mime_type: string;
  category: AttachmentCategory;
  extension: string;
  uploaded_by: number;
  created_at: string;
}

5.2 Mock 数据示例

// client/src/mocks/scripts.ts
export const mockScripts: Script[] = [
  {
    script_id: 1,
    project_id: 1,
    name: "西游记之大圣归来 - 完整剧本",
    type: "text",
    content: "第一幕：花果山...",
    version: 3,
    word_count: 15000,
    scene_count: 45,
    character_count: 12,
    status: "approved",
    created_by: 1,
    created_at: "2025-01-20T10:00:00Z",
    updated_at: "2025-01-25T15:30:00Z",
  },
  {
    script_id: 2,
    project_id: 2,
    name: "琅琊榜 - 第一集剧本",
    type: "attachment",
    attachment_id: 101,
    version: 1,
    word_count: 0,
    scene_count: 0,
    character_count: 0,
    status: "draft",
    created_by: 1,
    created_at: "2025-01-27T09:00:00Z",
    updated_at: "2025-01-27T09:00:00Z",
  },
];

6. 实施计划

阶段 1：数据库迁移（1天）

创建 scripts 表
创建 attachments 表
创建索引和约束
编写迁移脚本

阶段 2：后端服务（2-3天）

实现 ScriptService
实现 AttachmentService
实现 API 路由
编写单元测试

阶段 3：前端集成（2-3天）

创建 TypeScript 类型定义
实现剧本管理 UI
实现附件上传组件
集成 API 调用

阶段 4：测试和优化（1-2天）

端到端测试
性能优化
文档完善

7. 技术亮点

灵活的剧本类型：支持文本和附件两种形式，满足不同输入方式
完整的版本管理：剧本版本历史表支持版本追溯和回滚
结构化剧本数据：角色表和场景表支持剧本的结构化管理
通用附件系统：附件表可复用于多种场景（剧本、合同、参考文档等）
AI 生成支持：剧本表关联 AI 任务，支持 AI 辅助创作
审批流程：剧本状态管理支持草稿、审核、批准流程
全文搜索：剧本内容、角色名、场景信息均支持全文搜索
文件安全：附件表支持校验和、访问控制、过期时间

8. 后续优化方向

剧本协作编辑：支持多人实时编辑剧本（WebSocket）
剧本模板：提供常见剧本模板（广告、短视频、电影等）
AI 剧本生成：基于提示词自动生成剧本大纲
剧本导出：支持导出为 PDF、Word、Final Draft 格式
剧本分析：统计角色台词、场景分布、时长预估等

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

9.8 KiB Raw Permalink Blame History