# Jointo 业务流程 UML 图

> **项目名称**：Jointo（jointo）  
> **文档版本**：v1.0  
> **创建日期**：2026-01-29

---

## 📋 目录

1. [核心业务流程概览](#1-核心业务流程概览)
2. [用户认证流程](#2-用户认证流程)
3. [项目创建与管理流程](#3-项目创建与管理流程)
4. [分镜编辑流程](#4-分镜编辑流程)
5. [AI 生成流程](#5-ai-生成流程)
6. [视频导出流程](#6-视频导出流程)
7. [协作流程](#7-协作流程)
8. [系统架构流程](#8-系统架构流程)

---

## 1. 核心业务流程概览

### 1.1 整体业务流程图

```mermaid
graph TB
    %% 1. 项目层级
    subgraph Project_Hierarchy [项目层级设计]
        RootProj[父项目: 龙珠系列] -- 拥有 --> Assets[资产库: 角色/场景/道具]
        RootProj -- 派生 --> SubProj1[子项目: 第一集]
        RootProj -- 派生 --> SubProj2[子项目: 第二集]
    end

    %% 2. 资产定义 (Root Project Level)
    subgraph Asset_Definition [资产定义层 - 关联 Root ID]
        Assets --> Char[角色: 悟空]
        Assets --> Loc[场景: 武道会]
        Char --> Tag1[标签: 常服形态]
        Char --> Tag2[标签: 超级赛亚人]
        Loc --> Tag3[标签: 白天]
        Loc --> Tag4[标签: 战损]
    end

    %% 3. 剧本解析 (Sub Project Level)
    subgraph Screenplay_Process [剧本处理层 - 关联 Sub ID]
        SubProj1 --> Upload[上传剧本]
        Upload --> Parse[AI 解析]
        Parse --> SCR_Ref[screenplay_element_refs: 建立引用]
        SCR_Ref -.->|建立链接| Char
        SCR_Ref -.->|建立链接| Loc
        SCR_Ref --> Override[剧本特定覆盖: 悟空此刻受轻伤]
    end

    %% 4. 分镜创作 (Storyboard Level)
    subgraph Storyboard_Logic [分镜制作层 - 关联 Sub ID]
        SubProj1 --> SB[storyboards: 分镜 01]
        SB --> SB_Item[storyboard_items: 画面元素]
        SB_Item -->|指定变体| Tag2
        SB_Item -->|指定环境| Tag3
        SB_Item -->|关联素材| Res[project_resources: 气氛图]
    end

    %% 5. AI 执行 (Execution Level)
    subgraph AI_Generation [AI 执行层 - 多版本管理]
        SB --> Dialogue[storyboard_dialogues: 对白文本]
        Dialogue --> Voice[storyboard_voiceovers: 配音音频]
        SB_Item --> Image[storyboard_images: AI 生成图]
        Image --> Video[storyboard_videos: AI 动态视频]
    end

    %% 样式美化
    style RootProj fill:#f9f,stroke:#333,stroke-width:2px
    style SubProj1 fill:#bbf,stroke:#333
    style Assets fill:#dfd,stroke:#333
    style Tag2 fill:#fff4e1,stroke:#d4a017
    style Image fill:#fff4e1,stroke:#d4a017
    style SCR_Ref fill:#e1f0ff,stroke:#0078d4
```

```mermaid
graph TB
    Start([用户访问平台]) --> Auth{已登录?}
    Auth -->|否| Login[登录/注册]
    Auth -->|是| Dashboard[工作台]
    Login --> Dashboard
    
    Dashboard --> ProjectMgmt[项目管理]
    Dashboard --> FolderMgmt[文件夹管理]
    Dashboard --> ResourceLib[素材库]
    
    ProjectMgmt --> CreateProject[创建项目]
    ProjectMgmt --> OpenProject[打开项目]
    
    CreateProject --> ScriptUpload[剧本上传]
    ScriptUpload --> AIAnalyze[智能拆解]
    AIAnalyze --> ResourceExtract[提取资源]
    AIAnalyze --> StoryboardGen[生成分镜]
    StoryboardGen --> ApplyProject[应用到项目]
    
    OpenProject --> ScriptEdit[剧本编辑]
    OpenProject --> StoryboardEdit[分镜编辑]
    OpenProject --> TimelineEdit[时间轴编辑]
    ApplyProject --> StoryboardEdit
    
    ScriptEdit --> AIGenerate[AI 生成]
    StoryboardEdit --> AIGenerate
    TimelineEdit --> AIGenerate
    
    AIGenerate --> AIImage[AI 图片生成]
    AIGenerate --> AIVideo[AI 视频生成]
    AIGenerate --> AIAudio[AI 音效生成]
    AIGenerate --> AISubtitle[AI 字幕生成]
    AIGenerate --> AIVoice[AI 配音生成]
    
    TimelineEdit --> Preview[预览]
    Preview --> Export[导出视频]
    
    Export --> Download[下载成品]
    Download --> End([完成])
    
    style Start fill:#e1f5e1
    style End fill:#ffe1e1
    style AIGenerate fill:#fff4e1
    style Export fill:#e1f0ff
```

### 1.2 核心功能模块关系图

```mermaid
graph LR
    User[用户] --> Auth[认证系统]
    Auth --> Project[项目管理]
    Auth --> Folder[文件夹管理]
    
    Project --> Script[剧本管理]
    Project --> Storyboard[分镜管理]
    Project --> Timeline[时间轴管理]
    
    Storyboard --> Resource[资源管理]
    Timeline --> Video[视频管理]
    Timeline --> Audio[音效管理]
    Timeline --> Subtitle[字幕管理]
    Timeline --> Voice[配音管理]
    
    Resource --> AI[AI 服务]
    Video --> AI
    Audio --> AI
    Subtitle --> AI
    Voice --> AI
    
    Timeline --> Export[导出服务]
    
    Project --> Collab[协作系统]
    Collab --> Comment[评论]
    Collab --> Notify[通知]
    
    style User fill:#e1f5e1
    style AI fill:#fff4e1
    style Export fill:#e1f0ff
```

---

## 2. 用户认证流程

### 2.1 手机验证码登录流程（自动注册）

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant SMS as 短信服务
    participant R as Redis
    
    U->>F: 输入手机号
    F->>A: POST /api/v1/auth/send-code
    A->>DB: 检查手机号是否存在
    A->>SMS: 发送验证码
    A->>R: 存储验证码(5分钟过期)
    A-->>F: 返回成功
    F-->>U: 显示验证码输入框
    
    U->>F: 输入验证码
    F->>A: POST /api/v1/auth/login-with-code
    A->>R: 验证验证码
    
    alt 验证码错误
        A-->>F: 返回错误
        F-->>U: 提示验证码错误
    else 验证码正确
        A->>DB: 查询手机号是否注册
        alt 手机号已注册
            A->>DB: 查询用户信息
            A->>A: 生成 JWT Token
            A->>R: 存储 Session
            A-->>F: 返回 Token + 用户信息
            F->>F: 存储 Token 到 LocalStorage
            F-->>U: 登录成功，跳转到工作台
        else 手机号未注册（自动注册）
            A->>DB: 创建新用户记录
            A->>DB: 初始化积分(10积分)
            A->>DB: 设置默认昵称(手机号)
            A->>A: 生成 JWT Token
            A->>R: 存储 Session
            A-->>F: 返回 Token + 用户信息
            F->>F: 存储 Token 到 LocalStorage
            F-->>U: 注册并登录成功，跳转到工作台
        end
    end
```

### 2.2 微信扫码登录流程（自动注册）

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant WX as 微信服务
    participant DB as 数据库
    participant R as Redis
    
    U->>F: 点击微信登录
    F->>A: GET /api/v1/auth/wechat/qrcode
    A->>WX: 请求生成二维码
    WX-->>A: 返回二维码 URL + ticket
    A->>R: 存储 ticket(5分钟过期)
    A-->>F: 返回二维码 URL
    F-->>U: 显示二维码
    
    U->>U: 使用微信扫码
    WX->>A: 回调通知(ticket + code)
    A->>WX: 使用 code 获取 Access Token
    WX-->>A: 返回 Token + OpenID + UnionID
    A->>WX: 获取用户信息
    WX-->>A: 返回用户信息(昵称、头像)
    
    A->>DB: 查询 OpenID 是否绑定
    alt OpenID 已绑定
        A->>DB: 查询用户信息
        A->>A: 生成 JWT Token
        A->>R: 存储 Session
        A->>R: 更新扫码状态(success)
        A-->>F: WebSocket 推送登录成功
        F->>F: 存储 Token 到 LocalStorage
        F-->>U: 登录成功，跳转到工作台
    else OpenID 未绑定（自动注册）
        A->>DB: 创建新用户记录
        A->>DB: 保存微信昵称和头像
        A->>DB: 绑定 OpenID 和 UnionID
        A->>DB: 初始化积分(10积分)
        A->>A: 生成 JWT Token
        A->>R: 存储 Session
        A->>R: 更新扫码状态(success)
        A-->>F: WebSocket 推送登录成功
        F->>F: 存储 Token 到 LocalStorage
        F-->>U: 注册并登录成功，跳转到工作台
    end
    
    Note over F,A: 前端轮询扫码状态
    loop 每2秒轮询一次
        F->>A: GET /api/v1/auth/wechat/status?ticket={ticket}
        A->>R: 查询扫码状态
        alt 扫码成功
            A-->>F: 返回 Token + 用户信息
            F->>F: 停止轮询
        else 等待扫码
            A-->>F: 返回 pending 状态
        else 二维码过期
            A-->>F: 返回 expired 状态
            F-->>U: 提示二维码已过期
        end
    end
```

### 2.3 认证流程对比

| 登录方式 | 是否需要注册 | 自动注册条件 | 初始积分 | 用户信息来源 |
|---------|------------|------------|---------|------------|
| 手机验证码 | 否 | 手机号未注册时自动创建 | 10积分 | 手机号（默认昵称） |
| 微信扫码 | 否 | OpenID 未绑定时自动创建 | 10积分 | 微信昵称、头像 |

---

## 3. 项目创建与管理流程

### 3.1 项目创建流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    
    U->>F: 点击新建项目
    F->>F: 显示创建对话框
    U->>F: 输入项目信息
    F->>A: POST /api/v1/projects
    A->>A: 验证权限
    A->>DB: 检查文件夹权限
    A->>DB: 创建项目记录
    A->>DB: 添加项目成员(owner)
    DB-->>A: 返回项目 ID
    A-->>F: 返回项目信息
    F->>F: 更新项目列表
    F-->>U: 显示成功提示
    F->>F: 跳转到剧本上传页面
```

### 3.2 剧本上传与智能拆解流程

#### 3.2.1 方式一：剧本智能拆解

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant S3 as 对象存储
    participant Q as Celery 队列
    participant W as Worker
    participant AI as AI 大模型
    
    Note over U,AI: 阶段1：剧本上传
    U->>F: 上传剧本文件或粘贴文本
    alt 上传文件
        F->>S3: 上传剧本文件
        S3-->>F: 返回文件 URL
        F->>A: POST /api/v1/projects/{id}/scripts
        A->>A: 解析剧本格式(Fountain/TXT/DOC)
    else 粘贴文本
        F->>A: POST /api/v1/projects/{id}/scripts
        A->>A: 解析剧本文本
    end
    
    A->>DB: 创建剧本记录
    A->>DB: 保存原始剧本内容
    DB-->>A: 返回剧本 ID
    A-->>F: 返回解析后的剧本
    F->>F: 在原始剧本栏展示
    F-->>U: 显示剧本内容
    
    Note over U,AI: 阶段2：智能拆解剧本
    U->>F: 点击"智能拆解剧本"按钮
    F->>F: 显示拆解进度弹窗
    F->>A: POST /api/v1/projects/{id}/scripts/{scriptId}/analyze
    A->>DB: 检查积分余额
    A->>DB: 创建 AI 任务(拆解资源)
    A->>DB: 扣除积分
    A->>Q: 提交资源拆解任务
    A-->>F: 返回任务 ID
    F-->>U: 显示"正在拆解资源..."
    
    Q->>W: 分配任务
    W->>DB: 获取剧本内容
    W->>AI: 提交剧本 + 资源拆解提示词
    Note over AI: 提示词：分析剧本中的<br/>角色、场景、道具
    AI-->>W: 返回拆解结果(JSON)
    W->>DB: 存储角色列表
    W->>DB: 存储场景列表
    W->>DB: 存储道具列表
    W->>DB: 更新任务状态(资源拆解完成)
    
    Note over U,AI: 阶段3：智能拆解分镜
    W->>DB: 创建 AI 任务(拆解分镜)
    W->>Q: 提交分镜拆解任务
    
    Q->>W: 分配任务
    W->>DB: 获取剧本内容
    W->>AI: 提交剧本 + 分镜拆解提示词
    Note over AI: 提示词：将剧本拆解为<br/>多个分镜，每个分镜包含<br/>标题、描述、时间范围、<br/>涉及的角色/场景/道具
    AI-->>W: 返回分镜列表(JSON)
    
    loop 处理每个分镜
        W->>DB: 创建分镜记录
        W->>DB: 关联角色到分镜
        W->>DB: 关联场景到分镜
        W->>DB: 关联道具到分镜
    end
    
    W->>DB: 更新任务状态(分镜拆解完成)
    
    Note over U,AI: 阶段4：展示拆解结果
    loop 轮询任务状态
        F->>A: GET /api/v1/ai/jobs/{taskId}
        A->>DB: 查询任务状态
        alt 资源拆解完成
            A-->>F: 返回资源列表
            F->>F: 更新进度"资源拆解完成"
        else 分镜拆解完成
            A-->>F: 返回分镜列表
            F->>F: 更新进度"分镜拆解完成"
            F->>F: 在弹窗中展示分镜列表
            F-->>U: 显示拆解结果
        end
    end
    
    Note over U,AI: 阶段5：应用到项目
    U->>F: 预览分镜列表
    U->>F: 点击"应用到项目"按钮
    F->>A: POST /api/v1/projects/{id}/apply-storyboards
    A->>DB: 确认分镜数据
    A->>DB: 更新项目状态
    A-->>F: 返回成功
    F->>F: 关闭智能拆解弹窗
    F->>F: 跳转到项目编辑页
    F->>F: 加载分镜列表
    F-->>U: 显示项目整体编辑界面
```

#### 3.2.2 方式二：分镜模板上传

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant S3 as 对象存储
    participant Q as Celery 队列
    participant W as Worker
    participant AI as AI 大模型
    
    Note over U,AI: 阶段1：下载分镜模板
    U->>F: 点击"下载分镜模板"
    F->>A: GET /api/v1/templates/storyboard
    A-->>F: 返回模板文件(Excel/CSV)
    F-->>U: 下载模板文件
    
    Note over U,F: 用户离线编辑模板
    U->>U: 填写分镜信息
    Note over U: 模板包含：<br/>分镜标题、描述、<br/>时间范围、角色、<br/>场景、道具等
    
    Note over U,AI: 阶段2：上传分镜模板
    U->>F: 上传编辑好的分镜模板
    F->>S3: 上传模板文件
    S3-->>F: 返回文件 URL
    F->>A: POST /api/v1/projects/{id}/storyboards/import
    A->>A: 解析模板文件(Excel/CSV)
    A->>A: 验证数据格式
    
    loop 处理每个分镜
        A->>DB: 创建分镜记录
        A->>DB: 保存分镜标题和描述
        A->>DB: 保存时间范围
    end
    
    A-->>F: 返回导入成功
    F-->>U: 显示"分镜导入成功"
    
    Note over U,AI: 阶段3：自动提取资源
    A->>DB: 检查积分余额
    A->>DB: 创建 AI 任务(提取资源)
    A->>DB: 扣除积分
    A->>Q: 提交资源提取任务
    
    Q->>W: 分配任务
    W->>DB: 获取所有分镜数据
    W->>AI: 提交分镜数据 + 资源提取提示词
    Note over AI: 提示词：从所有分镜中<br/>提取并去重<br/>角色、场景、道具
    AI-->>W: 返回资源列表(JSON)
    
    W->>DB: 存储角色列表(去重)
    W->>DB: 存储场景列表(去重)
    W->>DB: 存储道具列表(去重)
    
    Note over U,AI: 阶段4：自动关联资源
    loop 处理每个分镜
        W->>DB: 读取分镜中的资源名称
        W->>DB: 匹配已入库的角色
        W->>DB: 匹配已入库的场景
        W->>DB: 匹配已入库的道具
        W->>DB: 创建分镜资源关联
    end
    
    W->>DB: 更新任务状态(完成)
    
    Note over U,AI: 阶段5：展示结果
    loop 轮询任务状态
        F->>A: GET /api/v1/ai/jobs/{taskId}
        A->>DB: 查询任务状态
        alt 任务完成
            A-->>F: 返回资源列表和分镜列表
            F->>F: 更新进度"资源提取完成"
            F->>F: 在弹窗中展示分镜列表
            F-->>U: 显示拆解结果
        end
    end
    
    Note over U,AI: 阶段6：应用到项目
    U->>F: 预览分镜列表
    U->>F: 点击"应用到项目"按钮
    F->>A: POST /api/v1/projects/{id}/apply-storyboards
    A->>DB: 确认分镜数据
    A->>DB: 更新项目状态
    A-->>F: 返回成功
    F->>F: 关闭智能拆解弹窗
    F->>F: 跳转到项目编辑页
    F->>F: 加载分镜列表
    F-->>U: 显示项目整体编辑界面
```

#### 3.2.3 两种方式对比

| 对比项 | 剧本智能拆解 | 分镜模板上传 |
|-------|------------|------------|
| **输入方式** | 上传剧本文件或粘贴文本 | 下载模板 → 编辑 → 上传 |
| **AI 处理** | 剧本 → 资源 → 分镜 | 分镜 → 资源提取 → 关联 |
| **用户控制** | AI 自动生成分镜 | 用户手动编辑分镜 |
| **适用场景** | 有完整剧本，快速生成 | 精确控制分镜内容 |
| **积分消耗** | 较多（两次 AI 调用） | 较少（一次 AI 调用） |
| **处理顺序** | 先提取资源 → 再生成分镜 | 先导入分镜 → 再提取资源 |
| **资源去重** | AI 自动去重 | AI 自动去重 |
| **关联方式** | AI 生成时自动关联 | 导入后自动匹配关联 |

### 3.3 文件夹管理流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    
    U->>F: 创建文件夹
    F->>A: POST /api/v1/folders
    A->>DB: 检查父文件夹权限
    A->>DB: 检查层级深度(<= 10)
    A->>DB: 检查同级名称唯一性
    A->>DB: 创建文件夹记录
    A->>DB: 计算并存储路径
    DB-->>A: 返回文件夹信息
    A-->>F: 返回成功
    F->>F: 更新文件夹树
    F-->>U: 显示新文件夹
    
    Note over U,DB: 移动项目到文件夹
    U->>F: 拖拽项目到文件夹
    F->>A: POST /api/v1/projects/{id}/move
    A->>DB: 检查目标文件夹权限
    A->>DB: 更新项目 folder_id
    A-->>F: 返回成功
    F->>F: 更新 UI
```

### 3.4 项目协作流程

```mermaid
sequenceDiagram
    participant O as 项目所有者
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant N as 通知服务
    participant C as 协作者
    
    O->>F: 邀请成员
    F->>A: POST /api/v1/projects/{id}/members
    A->>DB: 检查项目权限
    A->>DB: 检查用户是否存在
    A->>DB: 添加项目成员
    A->>N: 发送邀请通知
    N->>C: 推送通知
    A-->>F: 返回成功
    F-->>O: 显示成员列表
    
    C->>F: 查看通知
    C->>F: 接受邀请
    F->>A: POST /api/v1/projects/{id}/members/accept
    A->>DB: 更新成员状态
    A->>N: 通知项目所有者
    A-->>F: 返回成功
    F-->>C: 跳转到项目
```

---

## 4. 分镜编辑流程

### 4.1 分镜创建与编辑流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant Cache as Redis
    
    U->>F: 创建分镜
    F->>A: POST /api/v1/projects/{id}/storyboards
    A->>DB: 检查项目权限
    A->>DB: 计算 order_index
    A->>DB: 创建分镜记录
    DB-->>A: 返回分镜信息
    A->>Cache: 更新缓存
    A-->>F: 返回分镜数据
    F->>F: 更新分镜列表
    F-->>U: 显示新分镜
    
    Note over U,Cache: 编辑分镜描述
    U->>F: 修改分镜描述
    F->>A: PATCH /api/v1/storyboards/{id}
    A->>DB: 更新分镜记录
    A->>Cache: 更新缓存
    A-->>F: 返回成功
    F-->>U: 显示更新后内容
    
    Note over U,Cache: 调整分镜顺序
    U->>F: 拖拽分镜
    F->>A: PATCH /api/v1/storyboards/{id}
    A->>DB: 更新 order_index
    A->>DB: 调整其他分镜顺序
    A-->>F: 返回成功
    F->>F: 重新排序显示
```

### 4.2 分镜资源关联流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant S3 as 对象存储
    
    U->>F: 添加角色到分镜
    F->>A: POST /api/v1/storyboards/{id}/resources
    A->>DB: 检查资源是否存在
    A->>DB: 创建关联记录
    A->>DB: 设置 display_order
    DB-->>A: 返回关联信息
    A-->>F: 返回成功
    F->>F: 更新分镜资源列表
    F-->>U: 显示新添加的资源
    
    Note over U,S3: 上传新资源
    U->>F: 上传图片
    F->>S3: 上传文件
    S3-->>F: 返回文件 URL
    F->>A: POST /api/v1/project-resources
    A->>DB: 创建资源记录
    A->>DB: 关联到分镜
    A-->>F: 返回资源信息
    F-->>U: 显示上传成功
```

---

## 5. AI 生成流程

### 5.1 AI 图片生成流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant Q as Celery 队列
    participant W as Worker
    participant AI as AI 服务
    participant S3 as 对象存储
    
    U->>F: 输入提示词
    F->>A: POST /api/v1/ai/generate-image
    A->>DB: 检查积分余额
    alt 积分不足
        A-->>F: 返回错误
        F-->>U: 提示积分不足
    else 积分充足
        A->>DB: 创建 AI 任务
        A->>DB: 扣除积分
        A->>Q: 提交异步任务
        A-->>F: 返回任务 ID
        F-->>U: 显示生成中
        
        Q->>W: 分配任务
        W->>AI: 调用 AI API
        AI-->>W: 返回生成的图片
        W->>S3: 上传图片
        S3-->>W: 返回 URL
        W->>DB: 更新任务状态
        W->>DB: 创建资源记录
        
        loop 轮询任务状态
            F->>A: GET /api/v1/ai/jobs/{id}
            A->>DB: 查询任务状态
            DB-->>A: 返回状态
            A-->>F: 返回任务信息
            alt 任务完成
                F->>F: 显示生成结果
                F-->>U: 显示图片
            else 任务失败
                F-->>U: 显示错误信息
            end
        end
    end
```

### 5.2 AI 视频生成流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant Q as Celery 队列
    participant W as Worker
    participant AI as AI 服务
    participant S3 as 对象存储
    
    U->>F: 选择图片生成视频
    F->>A: POST /api/v1/ai/generate-video
    A->>DB: 检查积分余额
    A->>DB: 创建 AI 任务
    A->>DB: 创建视频记录(pending)
    A->>DB: 扣除积分
    A->>Q: 提交异步任务
    A-->>F: 返回任务 ID
    F-->>U: 显示生成中(进度条)
    
    Q->>W: 分配任务
    W->>AI: 调用视频生成 API
    W->>DB: 更新任务进度(0-100%)
    
    loop 轮询进度
        F->>A: GET /api/v1/ai/jobs/{id}
        A->>DB: 查询进度
        A-->>F: 返回进度
        F->>F: 更新进度条
    end
    
    AI-->>W: 返回生成的视频
    W->>S3: 上传视频
    S3-->>W: 返回 URL
    W->>DB: 更新视频记录
    W->>DB: 更新任务状态(completed)
    
    F->>A: GET /api/v1/ai/jobs/{id}
    A-->>F: 返回完成状态
    F->>F: 显示视频预览
    F-->>U: 生成完成
```

### 5.3 AI 配音生成流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant Q as Celery 队列
    participant W as Worker
    participant TTS as TTS 服务
    participant S3 as 对象存储
    
    U->>F: 输入配音文本
    F->>A: POST /api/v1/voiceovers
    A->>DB: 创建配音记录
    A->>DB: 创建 AI 任务
    A->>Q: 提交 TTS 任务
    A-->>F: 返回任务 ID
    F-->>U: 显示生成中
    
    Q->>W: 分配任务
    W->>TTS: 调用 TTS API
    TTS-->>W: 返回音频流
    W->>S3: 上传音频
    S3-->>W: 返回 URL
    W->>DB: 更新配音记录
    W->>DB: 更新任务状态
    
    F->>A: GET /api/v1/ai/jobs/{id}
    A-->>F: 返回完成状态
    F->>F: 加载音频
    F-->>U: 播放配音
```

---

## 6. 视频导出流程

### 6.1 视频导出流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant Q as Celery 队列
    participant W as Worker
    participant FF as FFmpeg
    participant S3 as 对象存储
    
    U->>F: 点击导出
    F->>F: 显示导出设置
    U->>F: 选择格式和质量
    F->>A: POST /api/v1/projects/{id}/exports
    A->>DB: 创建导出任务
    A->>DB: 查询项目所有素材
    A->>Q: 提交导出任务
    A-->>F: 返回任务 ID
    F-->>U: 显示导出中
    
    Q->>W: 分配任务
    W->>DB: 获取项目数据
    W->>S3: 下载所有素材
    W->>FF: 调用 FFmpeg 合成
    
    loop 合成进度
        FF->>W: 报告进度
        W->>DB: 更新进度
        F->>A: GET /api/v1/exports/{id}
        A->>DB: 查询进度
        A-->>F: 返回进度
        F->>F: 更新进度条
    end
    
    FF-->>W: 返回合成视频
    W->>S3: 上传最终视频
    S3-->>W: 返回 URL
    W->>DB: 更新任务状态
    W->>DB: 保存下载链接
    
    F->>A: GET /api/v1/exports/{id}
    A-->>F: 返回完成状态 + URL
    F-->>U: 显示下载按钮
    U->>F: 点击下载
    F->>S3: 下载视频
    S3-->>U: 返回视频文件
```

---

## 7. 协作流程

### 7.1 实时协作流程

```mermaid
sequenceDiagram
    participant U1 as 用户A
    participant F1 as 前端A
    participant WS as WebSocket 服务
    participant U2 as 用户B
    participant F2 as 前端B
    participant DB as 数据库
    
    U1->>F1: 打开项目
    F1->>WS: 建立 WebSocket 连接
    WS->>DB: 记录在线状态
    WS-->>F1: 返回在线用户列表
    F1-->>U1: 显示协作者在线
    
    U2->>F2: 打开同一项目
    F2->>WS: 建立 WebSocket 连接
    WS->>DB: 记录在线状态
    WS-->>F1: 推送用户上线通知
    F1-->>U1: 显示用户B上线
    
    Note over U1,DB: 用户A编辑分镜
    U1->>F1: 修改分镜描述
    F1->>WS: 发送编辑事件
    WS->>DB: 保存修改
    WS->>F2: 推送编辑事件
    F2->>F2: 更新分镜内容
    F2-->>U2: 显示最新内容
    
    Note over U1,DB: 用户B添加评论
    U2->>F2: 添加评论
    F2->>WS: 发送评论事件
    WS->>DB: 保存评论
    WS->>F1: 推送评论通知
    F1-->>U1: 显示新评论提示
```

### 7.2 评论流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 服务
    participant DB as 数据库
    participant N as 通知服务
    participant M as 被@用户
    
    U->>F: 输入评论(@用户B)
    F->>A: POST /api/v1/comments
    A->>DB: 创建评论记录
    A->>DB: 解析@提及
    A->>DB: 创建通知记录
    A->>N: 发送通知
    N->>M: 推送@提及通知
    A-->>F: 返回评论信息
    F->>F: 显示新评论
    F-->>U: 评论成功
    
    M->>F: 查看通知
    F->>A: GET /api/v1/notifications
    A->>DB: 查询通知
    A-->>F: 返回通知列表
    F-->>M: 显示@提及
    M->>F: 点击通知
    F->>F: 跳转到评论位置
```

---

## 8. 系统架构流程

### 8.1 请求处理流程

```mermaid
graph TB
    Client[客户端] -->|HTTPS| Nginx[Nginx]
    Nginx -->|负载均衡| API1[API 服务 1]
    Nginx -->|负载均衡| API2[API 服务 2]
    
    API1 --> Auth[认证中间件]
    API2 --> Auth
    
    Auth -->|验证通过| Service[业务服务层]
    Auth -->|验证失败| Error[返回 401]
    
    Service --> Cache{缓存命中?}
    Cache -->|是| ReturnCache[返回缓存数据]
    Cache -->|否| DB[数据库查询]
    
    DB --> UpdateCache[更新缓存]
    UpdateCache --> Return[返回数据]
    ReturnCache --> Return
    
    Return --> Client
    Error --> Client
    
    style Client fill:#e1f5e1
    style Error fill:#ffe1e1
    style Cache fill:#fff4e1
```

### 8.2 异步任务处理流程

```mermaid
graph TB
    API[API 服务] -->|创建任务| DB[(数据库)]
    API -->|提交任务| Queue[RabbitMQ 队列]
    
    Queue -->|分发| Worker1[Worker 1]
    Queue -->|分发| Worker2[Worker 2]
    Queue -->|分发| Worker3[Worker 3]
    
    Worker1 -->|AI 任务| AIService[AI 服务]
    Worker2 -->|导出任务| FFmpeg[FFmpeg]
    Worker3 -->|其他任务| Other[其他服务]
    
    AIService -->|上传结果| S3[对象存储]
    FFmpeg -->|上传结果| S3
    
    Worker1 -->|更新状态| DB
    Worker2 -->|更新状态| DB
    Worker3 -->|更新状态| DB
    
    DB -->|通知| Notify[通知服务]
    Notify -->|推送| Client[客户端]
    
    style Queue fill:#fff4e1
    style S3 fill:#e1f0ff
```

### 8.3 数据流转流程

```mermaid
graph LR
    User[用户操作] --> Frontend[前端应用]
    Frontend -->|HTTP/REST| API[API 网关]
    
    API --> Auth[认证服务]
    Auth --> Service[业务服务]
    
    Service --> Cache[(Redis 缓存)]
    Service --> DB[(PostgreSQL)]
    Service --> Queue[消息队列]
    
    Queue --> Worker[异步 Worker]
    Worker --> AI[AI 服务]
    Worker --> Storage[对象存储]
    
    Storage --> CDN[CDN]
    CDN --> Frontend
    
    DB --> Backup[(备份)]
    
    style User fill:#e1f5e1
    style Cache fill:#fff4e1
    style Storage fill:#e1f0ff
```

---

## 📝 流程说明

### 核心流程特点

1. **无感注册**
   - 手机验证码登录：首次登录自动注册
   - 微信扫码登录：首次扫码自动注册
   - 无需额外注册步骤，降低用户门槛
   - 自动初始化用户积分和默认设置

2. **智能剧本拆解**
   - **方式一：剧本智能拆解**
     - 支持多种剧本格式（Fountain、TXT、DOC、DOCX、PDF）
     - AI 自动提取角色、场景、道具
     - AI 自动生成分镜列表
     - 自动关联资源到分镜
   - **方式二：分镜模板上传**
     - 下载标准分镜模板（Excel/CSV）
     - 用户手动编辑分镜内容
     - 上传后自动导入分镜
     - AI 自动提取并去重资源
     - 自动匹配关联资源到分镜
   - 一键应用到项目

3. **异步优先**
   - AI 生成、视频导出等耗时操作全部异步处理
   - 使用 Celery + RabbitMQ 实现任务队列
   - 支持任务进度查询和状态通知

4. **实时协作**
   - WebSocket 实现实时状态同步
   - 多用户同时编辑同一项目
   - 实时推送编辑事件和通知

5. **权限控制**
   - 基于角色的访问控制（RBAC）
   - 文件夹级别和项目级别权限
   - 支持权限继承

6. **缓存策略**
   - Redis 缓存热点数据
   - 减少数据库查询压力
   - 提升响应速度

7. **文件管理**
   - MinIO/S3 对象存储
   - 支持大文件上传
   - CDN 加速访问

---

## 🔗 相关文档

- [功能结构大纲](./FEATURE_STRUCTURE.md)
- [功能概览](./FEATURE_OVERVIEW.md)
- [数据库设计](./requirements/database-design.md)
- [API 设计规范](./requirements/api-design-specification.md)
- [后端架构概述](./requirements/backend/01-architecture-overview.md)

---

**维护者**：开发团队  
**最后更新**：2026-01-29