# 剧本和附件模块设计方案

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

---

## 1. 需求背景

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

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

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

---

## 2. 设计方案

### 2.1 核心设计思路

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

#### 阶段 1：MVP（已完成）

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

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

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

### 2.2 数据库设计

#### 2.2.1 剧本表（scripts）

```sql
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）

```sql
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）

**剧本版本历史表**：

```sql
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
);
```

**剧本角色表**：

```sql
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
);
```

**剧本场景表**：

```sql
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 类型定义

```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 数据示例

```typescript
// 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. 技术亮点

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

---

## 8. 后续优化方向

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

---

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