57 KiB

Raw Permalink Blame History

Jointo（jointo）产品需求文档

目标：定义Jointo产品的功能需求、交互逻辑和技术规范
参考设计稿：https://www.figma.com/make/xgPuMR3GZzHpYh0RZJdiYK/kaidong.ai?p=f&fullscreen=1
文档版本：v1.0 - 功能需求版
项目域名：https://www.jointo.ai

1. 产品概述

1.1 产品定位

Jointo是一个面向专业影视团队的 AI 驱动视频制作平台。提供从分镜策划、素材管理、视频剪辑到音效/字幕/配音的一体化工作流程。

1.2 核心价值

全流程覆盖：分镜 → 资源 → 视频 → 音效 → 字幕 → 配音 → 导出
AI 能力集成：大量使用 AI 生成和辅助功能，降低制作门槛
协作支持：支持多人协同编辑和项目管理
实时预览：所见即所得的预览体验

1.3 产品名称

中文：Jointo
英文/文件标识：jointo
域名：https://www.jointo.ai

2. 目标与范围

2.1 本期（MVP）目标

2.1.1 UI 还原

✅ 完整还原所有页面布局和视觉元素
✅ 还原所有按钮、图标、文本内容
✅ 还原所有颜色、字体、间距、阴影等视觉样式
✅ 还原所有交互状态（hover、active、disabled、selected）

2.1.2 功能实现

✅ 所有前端交互逻辑（点击、切换、选择、输入）
✅ 数据联动（项目切换、分镜选择、资源关联）
✅ 状态管理（当前项目、选中分镜、分镜看板位置等）
✅ AI 功能入口（统一弹窗/抽屉，mock 数据返回）

2.1.3 交互体验

✅ 流畅的页面切换和状态变化
✅ 合理的加载状态和反馈提示
✅ 新手引导流程
✅ 响应式布局适配

2.2 不在本期范围

❌ 真实的 AI 推理和生成（使用 mock 数据）
❌ 真实的视频渲染和播放（使用占位图）
❌ 真实的视频导出功能（占位按钮）
❌ 完整的账号体系和权限系统（前端 mock）
❌ 后端 API 对接（预留接口，使用 mock）

3. 用户与使用场景

3.1 用户角色

视频创作者/编辑
- 使用分镜功能规划视频结构
- 使用 AI 生成视频素材
- 在分镜看板上编排视频片段
- 添加音效、字幕、配音
运营/营销人员
- 快速制作广告片、宣传片
- 使用 AI 工具提升制作效率
- 管理多个项目
协作者
- 查看和编辑协同项目
- 参与项目讨论和备注

3.2 典型使用流程

创建/选择项目
- 点击「新建项目」或从列表选择现有项目
- 项目自动加载，显示分镜列表
编辑分镜
- 查看/编辑分镜描述文案
- 为每个分镜配置资源（人物、场景、道具）
- 插入新分镜或删除分镜
生成和管理素材
- 使用 AI 生成视频素材
- 从素材库选择已有素材
- 在分镜看板上排列素材
完善视频
- 添加音效、字幕、配音
- 在预览窗口查看效果
- 调整分镜看板上的素材位置
导出项目
- 点击「导出项目」（MVP 为占位功能）

4. 整体布局架构

4.1 页面结构（单页应用 SPA）

┌─────────────────────────────────────────────────────────────────────────┐
│  应用顶部栏（TopBar）                                                    │
│  菜单 | 超级视频工作台 | 新建项目/导出项目/AI工具箱 | 协作者/通知/备注/设置│
├─────────────────────────────────────────────────────────────────────────┤
│ ┌────────────┬──────────────────────────────────┬──────────────────────┐│
│ │ 左侧栏     │     中间区域（CenterArea）        │     右侧栏           ││
│ │            │ ┌──────────┬───────────────────┐ │                      ││
│ │ [项目]     │ │ 分镜描述 │    预览窗口       │ │ [图片提示词]         ││
│ │ [素材库]   │ │          │                   │ │ [角度变换]           ││
│ │            │ │ 分镜1    │ ┌─────────┬─────┐ │ │ [镜头调整]           ││
│ │ 我的项目   │ │ 文字描述 │ │ 主预览  │预览1│ │ │                      ││
│ │ > 项目1    │ │          │ │         ├─────┤ │ │ 角色/场景描述        ││
│ │ > 项目2    │ │ 分镜2    │ │         │预览2│ │ │                      ││
│ │            │ │ 文字描述 │ └─────────┴─────┘ │ │ AI输入区             ││
│ │ 协同项目   │ │          │                   │ │ @角色 #场景          ││
│ │            │ │ [调整]   │ 播放控制 | 时间码 │ │ [对话改图▼] [发送➤]  ││
│ │            │ └──────────┴───────────────────┘ │                      ││
│ └────────────┴──────────────────────────────────┴──────────────────────┘│
├─────────────────────────────────────────────────────────────────────────┤
│  分镜看板（TimelinePanel）                                                 │
│  分镜看板 | - 100% + | 0s ─────────────────────────────────────────── 60s │
│  轨道: 分镜 | 资源 | 视频 | 音效 | 台词 | 配音                          │
│  + 添加轨道                                                              │
│                                                                         │
│ 新手引导浮层（OnboardingOverlay）/ Cookie 提示（Consent Manager）        │
└─────────────────────────────────────────────────────────────────────────┘

4.2 React 组件层级结构

App
├── Layout
│   ├── TopBar
│   │   ├── Logo
│   │   ├── ProjectActions (新建/导出/AI工具箱)
│   │   └── RightActions (权限/协作者/通知/备注/设置)
│   ├── MainContent
│   │   ├── LeftSidebar
│   │   │   ├── Tabs (项目/素材库)
│   │   │   ├── ProjectList
│   │   │   │   ├── MyProjects
│   │   │   │   └── CollabProjects
│   │   │   └── LibraryPanel
│   │   │       ├── SearchBox (搜索项目文件)
│   │   │       ├── LibraryTabs (角色/场景/道具/实拍)
│   │   │       └── LibraryContentList (内容列表)
│   │   ├── CenterArea
│   │   │   ├── StoryboardDescPanel (分镜描述)
│   │   │   ├── PreviewPanel (预览窗口)
│   │   │   └── PlaybackControls (播放控制)
│   │   └── RightSidebar
│   │       ├── RightPanelTabs (图片提示词/角度变换/镜头调整)
│   │       ├── ImagePromptPanel (图片提示词面板)
│   │       ├── AngleTransformPanel (角度变换面板)
│   │       ├── CameraAdjustPanel (镜头调整面板)
│   │       └── AIPromptPanel (AI 输入区)
│   └── TimelinePanel (分镜看板)
│       ├── TimelineHeader (分镜看板 | 缩小 | 100% | 放大)
│       ├── TimeScale (0s-60s)
│       ├── TimelineTracks
│       │   ├── StoryboardTrack (分镜轨道)
│       │   ├── ResourceTrack (资源轨道)
│       │   ├── VideoTrack (视频轨道)
│       │   ├── SoundTrack (音效轨道)
│       │   ├── SubtitleTrack (字幕轨道)
│       │   └── VoiceoverTrack (配音轨道)
│       └── AddTrackButton (添加轨道)
└── OnboardingOverlay (新手引导浮层)

5. 详细功能需求

5.1 应用顶部栏（TopBar）

5.3.1 左侧区域

Logo 和标题

Logo 图标：可点击的图标
标题文本："Jointo"
交互：点击 Logo 可返回项目列表或刷新当前项目（可选功能）

项目操作按钮组

新建项目按钮
- 图标 + 文本："新建项目"
- 点击行为：打开「新建项目」弹窗
  - 输入项目名称
  - 输入项目描述（可选）
  - 选择项目类型（我的项目/协同项目）
  - 确认后创建项目，自动选中新项目
- 状态：正常状态，hover 有反馈
导出项目按钮
- 图标 + 文本："导出项目"
- 点击行为：MVP 阶段显示提示「导出功能开发中」或下载项目 JSON 数据
- 后续：调用导出 API，生成视频文件
AI工具箱按钮
- 图标 + 文本："AI工具箱"
- 点击行为：打开侧边抽屉或 Modal，展示所有 AI 功能入口
  - 图片提示词
  - 角度变换
  - 镜头调整
  - AI生成分镜素材
  - AI生成资源素材
  - AI生成视频素材
  - AI生成音效素材
  - AI生成字幕素材
  - AI生成配音素材

5.3.2 右侧区域

权限管理按钮

图标按钮（无文本）
点击行为：打开权限管理弹窗
- 显示项目成员列表（mock 数据）
- 显示成员角色（所有者、编辑者、查看者）
- 添加成员功能（MVP 为占位）
- 移除成员功能（MVP 为占位）

协作者头像组按钮

显示多个用户头像
点击行为：显示协作者详情弹窗
- 显示所有协作者列表
- 显示每个协作者的角色和权限
Hover 效果：显示协作者名称提示

通知按钮

图标按钮（无文本）
点击行为：打开通知列表
- 显示未读通知数量（红点标识）
- 通知列表（mock 数据）
- 标记已读功能

项目备注按钮

图标按钮（无文本）
点击行为：打开项目备注面板
- 显示/编辑项目备注（富文本或纯文本）
- 保存备注功能
- 显示备注历史（可选）

设置按钮

图标按钮（无文本）
点击行为：打开项目设置弹窗
- 项目基本信息（名称、描述）
- 视频设置（分辨率、帧率、时长）
- 导出设置（格式、质量）
- 其他设置选项

5.2 左侧栏（LeftSidebar）

5.2.1 Tab 切换

Tab 按钮组

项目 Tab（默认选中）
素材库 Tab
样式：选中状态有视觉区分（下划线/背景色/文字颜色）
交互：点击切换显示对应内容区域

5.2.2 项目列表（项目 Tab 下）

分组结构

我的项目分组
- 分组标题："我的项目"
- 分组图标：文件夹图标
- 可折叠/展开（默认展开）
协同项目分组
- 分组标题："协同项目"
- 分组图标：协作图标
- 可折叠/展开（默认展开）

项目卡片列表

每个项目卡片包含：

缩略图：项目封面图（左侧）
项目名称：文本显示
更多操作按钮：hover 显示，点击显示菜单（编辑、删除、复制等）

交互行为：

点击项目卡片：切换当前项目
- 更新中间区域的分镜列表
- 更新右侧的资源/视频/音效/字幕/配音数据
- 更新分镜看板内容
- 项目卡片显示选中状态（高亮/边框）
Hover 项目卡片：显示预览信息或操作按钮
点击更多按钮：显示操作菜单（编辑、删除、复制、分享等）

5.2.3 素材库（素材库 Tab 下）

搜索功能：

搜索框：位于素材库顶部
- 占位文本："搜索项目文件..."
- 支持输入项目名称进行搜索
- 实时搜索，显示匹配的项目文件列表

Tab 分类：

搜索框下方显示 4 个 Tab 按钮：
- 角色 Tab
- 场景 Tab
- 道具 Tab
- 实拍 Tab
Tab 样式：选中状态有视觉区分（下划线/背景色/文字颜色）
Tab 互斥，只能选中一个

内容展示：

点击 Tab 后，显示对应类型的项目内容列表
每个内容项显示：
- 缩略图：素材预览图
- 名称：素材名称
- 来源项目：显示所属项目名称（可选）
支持滚动浏览
点击内容项：可添加到当前分镜（根据类型添加到对应资源分类）

交互行为：

搜索时：实时过滤项目文件
切换 Tab：更新显示对应类型的内容
点击内容项：添加到当前分镜的资源列表

5.3 中间区域 - 分镜列表（StoryboardPanel）

5.3.1 分镜描述区域头部

左侧标题

图标 + 文本："分镜描述"

右侧调整按钮

图标 + 文本："调整"
点击行为：打开分镜调整面板
- 批量编辑分镜
- 调整分镜顺序
- 分镜设置（时长、转场等）

5.3.2 分镜列表

分镜项结构（每个分镜包含）：

分镜缩略图：左侧显示
分镜标题："分镜1" ~ "分镜6"（Heading 5 级别）
更多按钮：右侧显示，点击显示菜单（编辑、删除、复制、插入等）
分镜描述文本：段落文本，显示详细场景描述

5.3.3 插入新分镜按钮

位置：

在每个分镜项下方
最后一个分镜项下方也有

样式：

图标 + 文本："插入新分镜"
按钮样式：次要按钮或链接样式

交互：

点击按钮：在当前分镜下方插入新分镜
- 新分镜标题："分镜X"（X 为下一个序号）
- 新分镜描述：空文本，可编辑
- 新分镜资源：空资源列表
- 自动选中新插入的分镜

5.3.4 交互行为

分镜选择：

点击分镜项：选中该分镜
- 分镜项显示选中状态（高亮/边框/背景色）
- 预览窗口更新为当前分镜的预览图
- 右侧资源面板高亮当前分镜的资源
- 分镜看板上高亮当前分镜的时间块

分镜编辑：

点击分镜标题：进入编辑模式（inline edit）
- 标题变为可编辑输入框
- 失去焦点或按 Enter 保存
- 按 Esc 取消编辑
点击分镜描述：进入编辑模式
- 描述文本变为可编辑文本域
- 支持多行编辑
- 保存/取消按钮或自动保存

分镜删除：

点击更多按钮 → 删除：显示确认对话框
- 确认后删除分镜
- 更新分镜序号
- 如果删除的是当前选中分镜，自动选中下一个分镜

分镜复制：

点击更多按钮 → 复制：复制当前分镜
- 创建新分镜，内容与原分镜相同
- 标题自动添加"（副本）"后缀
- 插入到当前分镜下方

滚动行为：

分镜列表可垂直滚动
选中分镜时，自动滚动到可视区域（如果不在视野内）

5.4 中间区域 - 预览窗口（PreviewPanel）

5.4.1 预览窗口头部

左侧标题

图标 + 文本："预览窗口"

右侧视图模式切换

适应窗口按钮
- 图标 + 文本："适应窗口"
- 选中状态：高亮显示
- 点击行为：切换预览图适应窗口大小（保持宽高比）
填充窗口按钮
- 图标 + 文本："填充窗口"
- 选中状态：高亮显示
- 点击行为：切换预览图填充整个窗口（可能裁剪）
两个按钮互斥，只能选中一个

5.4.2 内容预览区域

主预览图

显示当前选中分镜的主预览图
尺寸标识："1920 x 1080"（显示在预览图下方）
支持点击放大查看（可选功能）

缩略图组

预览1：小缩略图
预览2：小缩略图
点击缩略图：切换为主预览图
Hover 缩略图：显示预览信息

5.4.3 缩放控制

控制按钮组

缩小按钮：图标按钮
百分比显示："100%"（文本显示）
放大按钮：图标按钮

交互行为：

点击缩小：缩放比例减小（如 100% → 75% → 50% → 25%）
点击放大：缩放比例增大（如 25% → 50% → 75% → 100%）
缩放范围：25% - 200%（可配置）
缩放步进：25%（可配置）
缩放影响：预览图大小和清晰度（前端 CSS transform）

5.4.4 状态栏

状态文本：

未选择素材时："未选择素材"
选择素材时：显示素材信息（名称、类型等）

5.5 中间区域 - 播放控制（PlaybackControls）

5.5.1 控制按钮

上一帧按钮

图标按钮
点击行为：播放位置向前移动一帧
更新时间码显示

播放按钮

图标按钮（播放/暂停图标切换）
点击行为：
- 当前为暂停状态：开始播放，图标变为暂停
- 当前为播放状态：暂停播放，图标变为播放
MVP 阶段：仅更新状态，不真实播放视频

下一帧按钮

图标按钮
点击行为：播放位置向后移动一帧
更新时间码显示

5.5.2 时间码显示

显示格式："00:00:00:00"

格式：HH:MM:SS:FF（时:分:秒:帧）
实时更新：播放时自动更新，手动操作时立即更新
可编辑：点击时间码可手动输入（可选功能）

5.5.3 状态显示

缩放信息：

文本："缩放: 100%"
与预览窗口的缩放控制联动

素材状态：

文本："未选择素材" 或显示当前选中素材信息

5.6 中间区域 - AI 输入区（AIPromptPanel）

5.6.1 AI 功能 Tab

Tab 按钮组：

图片提示词 Tab
- 图标 + 文本："图片提示词"
- 选中状态：高亮显示
角度变换 Tab
- 图标 + 文本："角度变换"
- 选中状态：高亮显示
镜头调整 Tab
- 图标 + 文本："镜头调整"
- 选中状态：高亮显示
三个 Tab 互斥，只能选中一个
切换 Tab 时，输入框和示例文本相应更新

5.6.2 提示词示例区域

示例文本（图片提示词 Tab 下）：

显示提示词示例文本
显示方式：
- 灰色文本，作为提示示例
- 可点击复制到输入框（可选功能）

5.6.3 输入框

占位文本："输入图片描述..."

输入框特性：

支持多行输入
支持特殊语法：
- @角色名：引用角色
- /道具名：引用道具
- #场景名：引用场景
实时字数统计（可选）
输入验证（可选）

5.6.4 操作按钮

对话改图按钮

文本 + 图标："对话改图"
点击行为：
- 调用 AI 对话改图 API（mock）
- 显示加载状态
- 返回结果（mock 数据）
- 显示 Toast 提示

发送按钮

图标按钮
点击行为：
- 验证输入内容
- 调用 AI 生成 API（mock）
- 显示加载状态
- 返回结果并更新预览
- 显示 Toast 提示

5.6.5 模型选择器

显示文本："当前模型: 智能选择"

交互：

点击打开下拉菜单
显示可用模型列表：
- 智能选择（默认）
- 模型1
- 模型2
- ...
选择模型后更新显示文本

5.7 分镜看板（TimelinePanel）

5.7.1 分镜看板头部

左侧标题

图标 + 文本："分镜看板"

右侧缩放控制

缩小按钮：图标按钮
百分比显示："100%"（文本显示）
放大按钮：图标按钮

交互行为：

点击缩小：分镜看板刻度放大（显示更少时间范围，更精细）
点击放大：分镜看板刻度缩小（显示更多时间范围，更粗略）
缩放范围：25% - 400%（可配置）
缩放影响：时间刻度的显示密度和轨道块的宽度

5.7.2 时间刻度

刻度范围：0s 到 60s

显示方式：

每秒一个刻度标记
每 5 秒一个主要刻度（更粗/更明显）
每 10 秒显示时间标签（0s, 10s, 20s, ...）

滚动行为：

分镜看板可水平滚动
支持鼠标滚轮水平滚动
支持拖拽滚动（可选）

5.7.3 轨道结构

分镜轨道

轨道标题："分镜"
右侧按钮："AI生成分镜素材"（图标 + 文本）
轨道内容：显示分镜块
- 每个分镜块显示：分镜名称 + 缩略图图标 + 删除按钮
- 分镜块可点击选中
- 分镜块可拖拽移动（MVP 可选实现）
- 点击删除按钮：从分镜看板移除该分镜块（不删除分镜本身）

资源轨道

轨道标题："资源"
右侧按钮："AI生成资源素材"（图标 + 文本）
轨道内容：按分镜分组显示资源块
- 每个分镜的资源块显示在对应时间位置
- 资源块显示资源类型图标和名称

视频轨道

轨道标题："视频"
右侧按钮："AI生成视频素材"（图标 + 文本）
轨道内容：显示所有视频片段
- 每个视频块显示：视频名称 + 类型标签 + 删除按钮
- 视频块显示时间范围（开始时间 - 结束时间）
- 视频块可点击选中
- 视频块可拖拽移动和调整长度（MVP 可选实现）
- 点击删除按钮：从分镜看板移除该视频块（不删除视频本身）

音效轨道

轨道标题："音效"
右侧按钮："AI生成音效素材"（图标 + 文本）
轨道内容：显示所有音效片段
- 每个音效块显示：音效名称 + 删除按钮
- 音效块显示时间范围
- 点击删除按钮：从分镜看板移除该音效块（不删除音效本身）

字幕轨道

轨道标题："字幕"
右侧按钮："AI生成字幕素材"（图标 + 文本）
轨道内容：显示所有字幕片段
- 每个字幕块显示：字幕文本 + 删除按钮
- 字幕块显示时间范围
- 点击删除按钮：从分镜看板移除该字幕块（不删除字幕本身）

配音轨道

轨道标题："配音"
右侧按钮："AI生成配音素材"（图标 + 文本）
轨道内容：显示所有配音片段
- 每个配音块显示：配音文本 + 删除按钮
- 配音块显示时间范围
- 点击删除按钮：从分镜看板移除该配音块（不删除配音本身）

5.7.4 添加轨道按钮

位置：分镜看板底部

样式：图标 + 文本："添加轨道"

交互：

点击打开「添加轨道」对话框
选择轨道类型：
- 资源
- 视频
- 音效
- 字幕
- 配音
确认后添加新轨道到分镜看板

5.7.5 分镜看板交互

点击分镜看板块：

选中对应素材/分镜
更新预览窗口
更新右侧面板选中状态
播放位置跳转到块开始时间

拖拽分镜看板块（MVP 可选）：

拖拽移动块的位置
实时更新开始/结束时间
显示时间提示

调整分镜看板块长度（MVP 可选）：

拖拽块的两端调整长度
实时更新结束时间
显示时间提示

分镜看板缩放：

使用缩放控制按钮调整显示范围
使用鼠标滚轮缩放（Ctrl + 滚轮，可选）

5.8 右侧栏 - 资源面板（ResourcePanel）

5.8.1 面板头部

AI生成按钮

图标 + 文本："AI生成资源素材"
点击行为：打开 AI 生成资源弹窗
- 选择生成类型（人物/场景/道具/视频）
- 输入描述
- 选择分镜
- 生成资源（mock）

5.8.2 分镜资源分组

分组结构：按分镜分组

每组包含子分类：

人物分类

分类标题："人物"
资源标签列表：
- 每个资源显示为按钮标签
- 标签右侧有 "×" 删除按钮
添加人物按钮
- 图标 + 文本："添加人物"
- 点击行为：打开添加人物对话框
  - 从素材库选择
  - 或使用 AI 生成
  - 或上传图片

场景分类

分类标题："场景"
资源标签列表
添加场景按钮（如果有）

道具分类

分类标题："道具"
资源标签列表
添加道具按钮
- 图标 + 文本："添加道具"
- 点击行为：打开添加道具对话框

视频分类

分类标题："视频"
添加视频按钮
- 图标 + 文本："添加视频"
- 点击行为：打开添加视频对话框

5.8.3 交互行为

资源标签交互：

点击资源标签：选中资源，更新预览
点击 "×" 按钮：删除资源，显示确认提示（可选）

添加资源交互：

点击添加按钮：打开添加对话框
选择/生成资源后：自动添加到当前分镜的资源列表

分镜切换联动：

切换选中分镜时：资源面板自动滚动到对应分镜的资源组
高亮当前分镜的资源组

5.9 右侧栏 - 视频面板（VideoPanel）

5.9.1 面板头部

AI生成按钮

图标 + 文本："AI生成视频素材"
点击行为：打开 AI 生成视频弹窗
- 选择视频类型（图生视频/文生视频/首尾帧/融合生/实拍替换/实视频）
- 输入描述或上传图片
- 选择分镜
- 生成视频（mock）

5.9.2 视频列表

视频项结构（每个视频包含）：

视频名称：文本显示
类型标签：显示视频类型
- "图生视频"
- "文生视频"
- "首尾帧视频"
- "融合生视频"
- "实拍替换"
- "实视频"
更多按钮：右侧显示，点击显示菜单（编辑、删除、复制等）

5.9.3 交互行为

视频选择：

点击视频项：选中视频
- 视频项显示选中状态
- 更新预览窗口
- 分镜看板上高亮对应视频块
- 播放位置跳转到视频开始时间

视频编辑：

点击更多按钮 → 编辑：打开视频编辑对话框
- 修改视频名称
- 修改视频类型
- 调整视频参数（MVP 为占位）

视频删除：

点击更多按钮 → 删除：显示确认对话框
- 确认后删除视频
- 从分镜看板上移除对应视频块

5.10 右侧栏 - 音效面板（SoundEffectPanel）

5.10.1 面板头部

AI生成按钮

图标 + 文本："AI生成音效素材"
点击行为：打开 AI 生成音效弹窗
- 输入音效描述
- 选择音效类型
- 生成音效（mock）

5.10.2 音效列表

音效项结构（每个音效包含）：

音效名称：文本显示
更多按钮：右侧显示，点击显示菜单

5.10.3 交互行为

音效选择：

点击音效项：选中音效
- 音效项显示选中状态
- 分镜看板上高亮对应音效块
- 播放音效预览（MVP 为占位）

音效编辑/删除：

点击更多按钮：显示操作菜单
- 编辑：修改音效名称
- 删除：删除音效

5.11 右侧栏 - 字幕面板（SubtitlePanel）

5.11.1 面板头部

AI生成按钮

图标 + 文本："AI生成字幕素材"
点击行为：打开 AI 生成字幕弹窗
- 输入字幕文本
- 选择时间位置
- 生成字幕（mock）

5.11.2 字幕列表

字幕项结构（每个字幕包含）：

字幕文本：文本显示
更多按钮：右侧显示，点击显示菜单

5.11.3 交互行为

字幕选择：

点击字幕项：选中字幕
- 字幕项显示选中状态
- 分镜看板上高亮对应字幕块
- 预览窗口显示字幕（可选）

字幕编辑/删除：

点击更多按钮：显示操作菜单
- 编辑：修改字幕文本和时间
- 删除：删除字幕

5.12 右侧栏 - 配音面板（VoiceoverPanel）

5.12.1 面板头部

AI生成按钮

图标 + 文本："AI生成配音素材"
点击行为：打开 AI 生成配音弹窗
- 输入配音文本
- 选择语音类型
- 选择时间位置
- 生成配音（mock）

5.12.2 配音列表

配音项结构（每个配音包含）：

配音文本：文本显示
更多按钮：右侧显示，点击显示菜单

5.12.3 交互行为

配音选择：

点击配音项：选中配音
- 配音项显示选中状态
- 分镜看板上高亮对应配音块
- 播放配音预览（MVP 为占位）

配音编辑/删除：

点击更多按钮：显示操作菜单
- 编辑：修改配音文本和时间
- 删除：删除配音

5.13 右侧栏 - Tab 切换

5.13.1 Tab 按钮组

Tab 列表：

资源 Tab
视频 Tab
音效 Tab
字幕 Tab
配音 Tab

5.13.2 交互行为

Tab 切换：

点击 Tab：切换显示对应面板
选中 Tab 有视觉区分（下划线/背景色/文字颜色）
切换时保持滚动位置（可选）

Tab 状态联动：

切换 Tab 时，分镜看板上对应轨道自动滚动到可视区域（可选）

5.14 新手引导浮层（OnboardingOverlay）

5.14.1 浮层结构

跳过按钮

位置：浮层右上角
样式：图标按钮
点击行为：关闭引导，写入 localStorage，不再显示

步骤指示器

图标 + 文本："步骤 1 / 4"
显示当前步骤和总步骤数

步骤标题

Heading 3 级别

步骤描述

段落文本

步骤跳转按钮组

跳转到步骤 1/2/3/4 按钮
点击按钮：跳转到对应步骤，更新内容

导航按钮组

上一步按钮
- 图标 + 文本："上一步"
- 第一步时：disabled 状态
- 点击行为：返回上一步
跳过引导按钮
- 文本："跳过引导"
- 点击行为：关闭引导，写入 localStorage
下一步按钮
- 文本 + 图标："下一步"
- 最后一步时：显示"完成"或隐藏
- 点击行为：进入下一步

5.14.2 引导步骤内容

步骤 1：项目与素材管理

描述：项目与素材管理相关说明
高亮区域：左侧项目列表和素材库

步骤 2：分镜编辑

描述：分镜编辑相关说明
高亮区域：分镜列表

步骤 3：预览和分镜看板

描述：预览和分镜看板相关说明
高亮区域：预览窗口和分镜看板

步骤 4：AI 功能

描述：AI 功能相关说明
高亮区域：AI 输入区和 AI 生成按钮

5.14.3 交互行为

引导显示逻辑：

首次访问时自动显示
检查 localStorage，如果已跳过则不显示
可手动重新打开引导（设置中，可选功能）

步骤切换：

点击"下一步"：进入下一步，更新内容和高亮区域
点击"上一步"：返回上一步
点击步骤跳转按钮：直接跳转到指定步骤

引导关闭：

点击"跳过引导"：关闭引导，写入 localStorage
点击右上角关闭按钮：关闭引导，写入 localStorage
完成所有步骤：自动关闭引导，写入 localStorage

5.15.1 提示内容

文本内容：

主文本和链接文本
隐私政策链接：链接到隐私政策页面
收集链接：链接到收集说明
使用链接：链接到使用说明
销售/共享链接：链接到销售/共享说明
保留链接：链接到保留说明

5.15.2 操作按钮

Opt out 按钮

文本："Opt out"
点击行为：选择退出 Cookie，写入 localStorage

关闭按钮

图标按钮
点击行为：关闭提示，写入 localStorage（同意使用 Cookie）

5.15.3 交互行为

提示显示逻辑：

首次访问时显示
检查 localStorage，如果已选择则不显示
可手动重新打开（设置中，可选功能）

链接跳转：

所有链接在新标签页打开

6. UI/UX 交互细节

6.1 视觉样式规范

6.1.1 颜色系统

主色调：根据 Figma 设计稿提取
辅助色：警告色、成功色、错误色
中性色：文本色、背景色、边框色
状态色：hover、active、selected、disabled

6.1.2 字体系统

字体家族：根据设计稿（可能包含中文字体）
字体大小：标题、正文、辅助文本
字重：正常、中等、粗体
行高：根据设计稿

6.1.3 间距系统

基础间距单位：4px 或 8px
组件间距：根据设计稿提取
内边距：按钮、输入框、卡片等
外边距：组件之间的间距

6.1.4 圆角系统

小圆角：按钮、标签
中圆角：卡片、面板
大圆角：弹窗、抽屉

6.1.5 阴影系统

小阴影：卡片、按钮 hover
中阴影：弹窗、抽屉
大阴影：模态框

6.2 交互状态

6.2.1 按钮状态

默认状态：正常显示
Hover 状态：鼠标悬停，视觉反馈（颜色变化、阴影、缩放）
Active 状态：点击时，视觉反馈
Disabled 状态：禁用，灰色，不可点击
Loading 状态：加载中，显示加载动画

6.2.2 输入框状态

默认状态：正常显示
Focus 状态：获得焦点，边框高亮
Error 状态：错误，红色边框和提示
Disabled 状态：禁用，灰色

6.2.3 选中状态

分镜选中：高亮背景、边框、或左侧指示条
资源选中：高亮背景或边框
Tab 选中：下划线、背景色、或文字颜色变化

6.3 动画与过渡

6.3.1 页面切换

淡入淡出：页面切换时
滑动：侧边栏展开/收起
缩放：弹窗打开/关闭

6.3.2 状态变化

颜色过渡：hover、active 状态变化
位置过渡：拖拽、滚动
尺寸过渡：展开/收起

6.3.3 加载动画

按钮加载：旋转图标或进度条
内容加载：骨架屏或加载指示器
AI 生成：进度条或动画效果

6.4 响应式设计

6.4.1 断点设置

桌面：> 1200px（默认布局）
平板：768px - 1200px（调整布局）
移动端：< 768px（简化布局，可选实现）

6.4.2 布局适配

侧边栏：可收起/展开
面板：可调整宽度（可选）
分镜看板：可全屏显示（可选）

6.5 可访问性（Accessibility）

6.5.1 键盘导航

Tab 键：在可交互元素间切换
Enter/Space：激活按钮
Esc：关闭弹窗/取消操作
方向键：在列表项间导航

6.5.2 屏幕阅读器

ARIA 标签：为交互元素添加标签
语义化 HTML：使用正确的 HTML 标签
焦点管理：弹窗打开时聚焦到第一个元素

6.5.3 视觉辅助

焦点指示器：清晰的焦点样式
对比度：文本与背景的对比度符合 WCAG 标准
字体大小：支持浏览器缩放

7. 数据模型

7.1 核心数据类型

// 项目类型
type Project = {
  id: string;
  name: string;
  description?: string;
  thumbnailUrl?: string;
  type: 'mine' | 'collab';
  createdAt: number;
  updatedAt: number;
  storyboards: Storyboard[];
  settings: ProjectSettings;
};

// 项目设置
type ProjectSettings = {
  resolution: {
    width: number;
    height: number;
  };
  frameRate: number;
  duration: number; // 秒
  exportFormat?: string;
  exportQuality?: string;
};

// 分镜类型
type Storyboard = {
  id: string;
  title: string; // "分镜1", "分镜2", ...
  description: string;
  thumbnailUrl?: string;
  resources: StoryboardResources;
  startTime: number; // 在分镜看板上的开始时间（秒）
  endTime: number; // 在分镜看板上的结束时间（秒）
  order: number; // 分镜顺序
};

// 分镜资源
type StoryboardResources = {
  characters: ResourceItem[]; // 人物
  scenes: ResourceItem[]; // 场景
  props: ResourceItem[]; // 道具
  videos: string[]; // 视频 ID 列表
};

// 资源项
type ResourceItem = {
  id: string;
  name: string;
  type: 'character' | 'scene' | 'prop';
  thumbnailUrl?: string;
  assetUrl?: string;
};

// 视频资产
type VideoAsset = {
  id: string;
  name: string;
  type: 'img2video' | 'text2video' | 'keyframe' | 'fusion' | 'replace' | 'real';
  thumbnailUrl?: string;
  videoUrl?: string;
  startTime: number; // 在分镜看板上的开始时间（秒）
  endTime: number; // 在分镜看板上的结束时间（秒）
  storyboardId?: string; // 关联的分镜 ID
};

// 音效资产
type SoundEffect = {
  id: string;
  name: string;
  audioUrl?: string;
  startTime: number;
  endTime: number;
  volume?: number; // 0-100
};

// 字幕资产
type Subtitle = {
  id: string;
  text: string;
  startTime: number;
  endTime: number;
  style?: SubtitleStyle;
};

type SubtitleStyle = {
  fontSize?: number;
  color?: string;
  position?: 'top' | 'center' | 'bottom';
  backgroundColor?: string;
};

// 配音资产
type Voiceover = {
  id: string;
  text: string;
  audioUrl?: string;
  startTime: number;
  endTime: number;
  voiceType?: string; // 语音类型
  volume?: number;
};

// 分镜看板轨道
type TimelineTrack = {
  id: string;
  type: 'storyboard' | 'resource' | 'video' | 'sound' | 'subtitle' | 'voice';
  name: string;
  items: TimelineItem[];
  visible: boolean;
  locked: boolean;
};

// 分镜看板项
type TimelineItem = {
  id: string;
  refId: string; // 指向 storyboard / video / sound / subtitle / voiceover 的 ID
  type: 'storyboard' | 'video' | 'sound' | 'subtitle' | 'voice';
  start: number; // 开始时间（秒）
  end: number; // 结束时间（秒）
  trackId: string; // 所属轨道 ID
};

// AI 生成请求
type AIGenerateRequest = {
  type: 'image' | 'video' | 'sound' | 'subtitle' | 'voice' | 'resource';
  prompt: string;
  model?: string;
  parameters?: Record<string, any>;
  storyboardId?: string;
};

// AI 生成响应
type AIGenerateResponse = {
  success: boolean;
  data?: any;
  error?: string;
  jobId?: string; // 异步任务 ID
};

7.2 状态管理数据结构

// 应用全局状态
type AppState = {
  // 当前项目
  currentProject: Project | null;
  
  // 当前选中的分镜
  selectedStoryboard: Storyboard | null;
  
  // 当前选中的资源/视频/音效/字幕/配音
  selectedItem: {
    type: 'resource' | 'video' | 'sound' | 'subtitle' | 'voice' | null;
    id: string | null;
  };
  
  // 预览窗口状态
  preview: {
    mode: 'fit' | 'fill'; // 适应窗口 / 填充窗口
    zoom: number; // 缩放比例，如 100 表示 100%
    currentImageUrl?: string;
  };
  
  // 播放控制状态
  playback: {
    isPlaying: boolean;
    currentTime: number; // 当前播放时间（秒）
    timecode: string; // 时间码 "00:00:00:00"
  };
  
  // 分镜看板状态
  timeline: {
    zoom: number; // 分镜看板缩放比例
    scrollPosition: number; // 滚动位置
    selectedTrackId: string | null;
  };
  
  // 右侧面板状态
  rightPanel: {
    activeTab: 'resource' | 'video' | 'sound' | 'subtitle' | 'voice';
    scrollPosition: number;
  };
  
  // AI 输入区状态
  aiPrompt: {
    activeTab: 'image' | 'angle' | 'lens';
    inputText: string;
    selectedModel: string;
  };
  
  // 新手引导状态
  onboarding: {
    isVisible: boolean;
    currentStep: number;
    totalSteps: number;
    skipped: boolean; // 是否已跳过
  };
  
  // UI 状态
  ui: {
    isLeftSidebarCollapsed: boolean;
    isRightSidebarCollapsed: boolean;
    modals: {
      [key: string]: boolean; // 各种弹窗的显示状态
    };
  };
};

8. API 接口规范

8.1 API 设计原则

8.1.1 基础规范

协议：HTTPS
数据格式：JSON
请求方法：RESTful（GET、POST、PUT、DELETE、PATCH）
认证方式：Bearer Token（JWT）
响应格式：统一响应结构

8.1.2 统一响应结构

// 成功响应
type ApiSuccessResponse<T> = {
  success: true;
  data: T;
  message?: string;
};

// 错误响应
type ApiErrorResponse = {
  success: false;
  error: {
    code: string;
    message: string;
    details?: any;
  };
};

// 分页响应
type ApiPaginatedResponse<T> = {
  success: true;
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    total: number;
    totalPages: number;
  };
};

8.1.3 错误码规范

enum ApiErrorCode {
  // 通用错误
  UNAUTHORIZED = 'UNAUTHORIZED',           // 401 未授权
  FORBIDDEN = 'FORBIDDEN',                 // 403 禁止访问
  NOT_FOUND = 'NOT_FOUND',                 // 404 资源不存在
  VALIDATION_ERROR = 'VALIDATION_ERROR',   // 400 参数验证失败
  INTERNAL_ERROR = 'INTERNAL_ERROR',       // 500 服务器错误
  
  // 业务错误
  PROJECT_NOT_FOUND = 'PROJECT_NOT_FOUND',
  STORYBOARD_NOT_FOUND = 'STORYBOARD_NOT_FOUND',
  AI_GENERATION_FAILED = 'AI_GENERATION_FAILED',
  AI_GENERATION_TIMEOUT = 'AI_GENERATION_TIMEOUT',
  EXPORT_FAILED = 'EXPORT_FAILED',
}

8.2 Mock 数据与真实 API 区分

8.2.1 前端纯状态管理（无需 API）

以下功能仅在前端状态管理，无需调用后端 API：

✅ UI 状态：Tab 切换、面板展开/收起、弹窗显示/隐藏
✅ 选中状态：分镜选中、资源选中、分镜看板选中
✅ 预览窗口状态：缩放比例、视图模式（适应/填充）
✅ 分镜看板状态：分镜看板缩放、滚动位置
✅ 播放控制状态：播放/暂停、当前时间（前端模拟）
✅ 新手引导状态：当前步骤、是否跳过（localStorage）

8.2.2 需要 Mock 数据的 API（MVP 阶段）

以下功能在 MVP 阶段使用 Mock 数据，但需要按照真实 API 格式实现：

🔶 项目 CRUD：创建、读取、更新、删除项目
🔶 分镜 CRUD：创建、读取、更新、删除分镜
🔶 资源管理：添加、删除资源（人物、场景、道具）
🔶 视频管理：添加、删除、更新视频
🔶 音效管理：添加、删除、更新音效
🔶 字幕管理：添加、删除、更新字幕
🔶 配音管理：添加、删除、更新配音
🔶 分镜看板操作：保存分镜看板配置
🔶 AI 生成功能：所有 AI 生成请求
🔶 项目导出：导出项目配置或视频

8.2.3 真实后端 API（后续对接）

所有标记为 🔶 的功能，在后续阶段需要对接真实后端 API。

8.3 API 接口详细定义

（详细 API 接口定义请参考原文档第 8.3 节，此处省略具体接口定义，仅保留接口规范说明）

8.4 API 调用封装

8.4.1 API Client 实现

（API Client 实现代码请参考原文档第 8.4 节）

8.4.2 Mock API 实现

（Mock API 实现代码请参考原文档第 8.4 节）

8.4.3 API Hooks 封装

（API Hooks 封装代码请参考原文档第 8.4 节）

8.5 环境配置

8.5.1 环境变量

# .env.development
VITE_API_BASE_URL=http://localhost:3000/api/v1
VITE_USE_MOCK=true

# .env.production
VITE_API_BASE_URL=https://api.jointo.ai/api/v1
VITE_USE_MOCK=false

8.5.2 API 切换机制

// src/services/api/index.ts
const isMock = import.meta.env.VITE_USE_MOCK === 'true';

export const api = isMock ? mockApiClient : apiClient;

// 使用示例
import { api } from '@/services/api';

// 自动根据环境使用 Mock 或真实 API
const projects = await api.getProjects();

9. 技术方案

9.1 技术栈选择

9.1.1 核心框架

React 19：使用最新版本的 React
TypeScript：类型安全，提升开发效率
Vite：快速构建工具，开发体验好

9.1.2 状态管理

Zustand 或 Jotai：轻量级状态管理
或 React Context + useReducer：如果状态不复杂

9.1.3 UI 组件库

shadcn/ui：基于 Radix UI 和 Tailwind CSS 的组件库
- 提供高质量、可访问的组件基础
- 组件可复制到项目中，完全可定制
- 支持按需引入，不增加 bundle 体积
- 使用方式：npx shadcn-ui@latest add [component-name]
图标库：lucide-react
- 与设计稿中使用的图标库一致
- 提供丰富的图标集合
- 使用方式：import { IconName } from 'lucide-react'
工具库：
- clsx 或 classnames：条件类名
- react-dnd：拖拽功能（分镜看板拖拽，可选）

9.1.4 样式方案

Tailwind CSS：必需，shadcn/ui 基于 Tailwind CSS
- 快速开发，易于维护
- 与 shadcn/ui 完美集成
- 支持自定义主题和设计系统

9.1.5 工具库

日期时间：dayjs 或 date-fns
HTTP 请求：axios 或 fetch
表单处理：react-hook-form（如果需要复杂表单）
动画：framer-motion 或 CSS transitions

9.1.6 核心依赖包

必需依赖：

{
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "typescript": "^5.7.0",
    "tailwindcss": "^3.4.0",
    "lucide-react": "^0.400.0",
    "@radix-ui/react-*": "^1.0.0",  // shadcn/ui 依赖的 Radix UI 组件
    "class-variance-authority": "^0.7.0",  // shadcn/ui 工具
    "clsx": "^2.0.0",  // 条件类名工具
    "tailwind-merge": "^2.0.0"  // Tailwind 类名合并工具
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.0.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0"
  }
}

shadcn/ui 安装：

shadcn/ui 不是 npm 包，而是通过 CLI 工具将组件代码复制到项目中
安装方式：npx shadcn-ui@latest init
组件添加：npx shadcn-ui@latest add [component-name]

9.2 项目结构

jointo/
├── public/                 # 静态资源
│   ├── images/            # 图片资源
│   └── mock-data/         # Mock 数据文件
├── src/
│   ├── components/        # 组件
│   │   ├── ui/            # shadcn/ui 组件（自动生成）
│   │   │   ├── button.tsx
│   │   │   ├── input.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── tabs.tsx
│   │   │   └── ...        # 其他 shadcn/ui 组件
│   │   ├── layout/        # 布局组件
│   │   ├── storyboard/    # 分镜相关组件
│   │   ├── preview/       # 预览相关组件
│   │   ├── timeline/      # 分镜看板相关组件
│   │   ├── resource/      # 资源相关组件
│   │   ├── video/         # 视频相关组件
│   │   ├── common/        # 通用组件
│   │   └── onboarding/   # 新手引导
│   ├── hooks/             # 自定义 Hooks
│   ├── store/             # 状态管理
│   ├── services/          # 服务层
│   │   ├── api/           # API 调用
│   │   └── storage/       # 本地存储
│   ├── types/             # TypeScript 类型
│   ├── utils/             # 工具函数
│   │   └── cn.ts          # shadcn/ui 工具函数（clsx 封装）
│   ├── styles/            # 全局样式
│   │   └── globals.css    # Tailwind CSS 入口
│   ├── App.tsx            # 根组件
│   └── main.tsx           # 入口文件
├── .env                   # 环境变量
├── .gitignore
├── components.json        # shadcn/ui 配置文件
├── package.json
├── tsconfig.json
├── tailwind.config.js     # Tailwind CSS 配置
└── vite.config.ts         # Vite 配置

9.3 关键实现细节

9.3.1 分镜看板实现

使用 Canvas 或 SVG 绘制时间刻度（性能更好）
或使用 CSS + 虚拟滚动（实现简单）
支持水平滚动和缩放
支持拖拽和调整时间块（可选）

9.3.2 预览窗口实现

使用 <img> 标签显示预览图
支持缩放（CSS transform）
支持适应/填充模式切换
支持点击放大查看（可选）

9.3.3 AI 功能实现

统一封装 AI 请求函数
使用 Promise 模拟异步请求
返回 mock 数据
显示加载状态和结果反馈

9.3.4 状态同步

项目切换时，同步更新所有相关状态
分镜选择时，同步更新预览、资源、分镜看板
分镜看板操作时，同步更新播放位置

9.3.5 shadcn/ui 和 lucide-react 使用规范

shadcn/ui 组件使用：

初始化：运行 npx shadcn-ui@latest init 初始化项目
添加组件：使用 npx shadcn-ui@latest add [component-name] 添加所需组件
常用组件：
- Button：按钮组件
- Input：输入框组件
- Dialog：对话框/弹窗
- Tabs：标签页组件
- Card：卡片组件
- Select：下拉选择
- DropdownMenu：下拉菜单
- Toast：提示消息
- Sheet：侧边抽屉
- Popover：弹出框
组件定制：所有组件代码在 src/components/ui/ 目录下，可直接修改
主题定制：通过 tailwind.config.js 和 CSS 变量自定义主题

lucide-react 图标使用：

导入方式：import { IconName } from 'lucide-react'
常用图标：
- Plus：添加/新建
- Search：搜索
- Settings：设置
- User：用户
- File：文件
- Folder：文件夹
- Play：播放
- Pause：暂停
- Edit：编辑
- Trash：删除
- Copy：复制
- Download：下载
- Upload：上传
- ChevronLeft/Right/Up/Down：方向箭头
- X：关闭
- Check：确认
图标属性：支持 size、color、strokeWidth 等属性自定义
与 shadcn/ui 集成：图标可直接在 shadcn/ui 组件中使用

开发规范：

优先使用 shadcn/ui 提供的组件，减少自定义组件开发
图标统一使用 lucide-react，保持视觉一致性
组件样式通过 Tailwind CSS 类名控制
复杂交互可基于 shadcn/ui 组件进行扩展

9.4 性能优化

9.4.1 组件优化

使用 React.memo 避免不必要的重渲染
使用 useMemo 和 useCallback 优化计算和函数
虚拟滚动处理长列表

9.4.2 资源优化

图片懒加载
代码分割（路由级别或组件级别）
压缩静态资源

9.4.3 状态优化

按需加载数据
缓存常用数据
防抖和节流处理频繁操作

10. 非功能需求

10.1 性能要求

首屏加载时间：< 3 秒（不含真实 AI 请求）
交互响应时间：< 100ms（点击、切换等操作）
页面滚动帧率：≥ 60 FPS
内存使用：合理控制，避免内存泄漏

10.2 兼容性要求

浏览器：Chrome、Edge、Safari 最新版本
屏幕分辨率：1920x1080 及以上（主要适配）
操作系统：Windows、macOS、Linux

10.3 多语言支持（i18n）

默认语言：简体中文（zh-CN）
支持语言：
- 简体中文（zh-CN）- 默认
- 英文（en-US）
- 繁体中文（zh-TW）
- 后续可扩展其他语言包
切换方式：用户可在设置中手动切换语言
语言持久化：用户选择的语言保存到 localStorage
实现要求：
- 使用 react-i18next 或类似方案
- 所有 UI 文本必须通过 i18n 函数获取，禁止硬编码
- 支持动态加载语言包，减少初始包体积
- 日期、数字等需根据语言环境格式化

10.4 主题支持

主题模式：
- 深色主题（Dark）- 默认
- 亮色主题（Light）
- 跟随系统（System）- 自动检测系统偏好
切换方式：用户可在设置或顶栏快速切换
主题持久化：用户选择的主题保存到 localStorage
实现要求：
- 使用 CSS 变量实现主题切换
- 支持 prefers-color-scheme 媒体查询
- 切换时无闪烁（避免 FOUC）
- 所有组件必须适配两种主题

10.5 可用性要求

中英文混排：界面不破版，文字正确显示
响应式布局：适配不同屏幕尺寸（可选）
错误处理：友好的错误提示和处理
加载状态：清晰的加载指示

10.6 可维护性要求

代码规范：遵循 ESLint、Prettier 规范
类型安全：完整的 TypeScript 类型定义
组件文档：关键组件添加注释
测试覆盖：关键功能添加单元测试（可选）

10.7 可扩展性要求

API 接口：预留后端 API 接口，易于切换
插件化：AI 功能模块化，易于扩展
配置化：关键参数可配置

11. 开发迭代计划

11.1 第一阶段：基础架构搭建（1-2 天）

目标：搭建项目基础结构和核心布局

任务清单：

初始化 React + TypeScript + Vite 项目
配置 Tailwind CSS
初始化 shadcn/ui：运行 npx shadcn-ui@latest init
安装 lucide-react：npm install lucide-react
添加必要的 shadcn/ui 组件（Button、Input、Dialog、Tabs 等）
配置 ESLint、Prettier
创建基础目录结构
实现 Layout 组件（TopBar、LeftSidebar、RightSidebar、CenterArea）
实现基础样式和变量
配置路由（如果需要）

验收标准：

项目可以正常运行
基础布局结构完整
样式系统配置完成

11.2 第二阶段：静态数据展示（2-3 天）

目标：填充所有静态数据和 UI 元素

任务清单：

创建 Mock 数据文件
实现项目列表组件
实现分镜列表组件
实现预览窗口组件
实现分镜看板组件（静态显示）
实现资源面板组件
实现视频/音效/字幕/配音面板组件
实现 AI 输入区组件
实现所有按钮、图标、文本内容

验收标准：

所有 UI 元素完整显示
所有文本内容正确
所有数据正确展示

11.3 第三阶段：交互逻辑实现（3-4 天）

目标：实现所有交互逻辑和状态管理

任务清单：

实现状态管理（Zustand 或 Context）
实现项目切换逻辑
实现分镜选择逻辑
实现 Tab 切换逻辑
实现预览窗口交互（缩放、模式切换）
实现播放控制逻辑
实现分镜看板交互（选中、滚动、缩放）
实现资源添加/删除逻辑
实现分镜编辑逻辑（标题、描述）
实现插入新分镜逻辑

验收标准：

所有交互功能正常工作
状态同步正确
用户体验流畅

11.4 第四阶段：AI 功能和弹窗（2-3 天）

目标：实现所有 AI 功能入口和弹窗

任务清单：

实现 AI 生成弹窗组件
封装 AI API 调用（mock）
实现图片提示词功能
实现角度变换功能
实现镜头调整功能
实现所有 AI 生成按钮（分镜、资源、视频、音效、字幕、配音）
实现模型选择器
实现 Toast 提示组件
实现加载状态显示

验收标准：

所有 AI 功能入口可点击
弹窗显示和交互正常
Mock 数据返回正确

11.5 第五阶段：新手引导和全局功能（1-2 天）

目标：实现新手引导和其他全局功能

任务清单：

实现新手引导浮层组件
实现引导步骤切换逻辑
实现引导跳过和持久化
实现 Cookie 提示
实现权限管理弹窗（mock）
实现项目备注功能
实现设置弹窗（mock）
实现通知功能（mock）

验收标准：

新手引导流程完整
全局功能正常工作
持久化功能正常

11.6 第六阶段：优化和打磨（2-3 天）

目标：优化性能、修复问题、完善细节

任务清单：

性能优化（组件 memo、虚拟滚动等）
交互细节优化（动画、过渡效果）
响应式适配（可选）
错误处理和边界情况
代码重构和优化
添加注释和文档
测试和修复 bug

验收标准：

性能指标达标
无明显 bug
代码质量良好
用户体验流畅

11.7 总计时间估算

第一阶段：1-2 天
第二阶段：2-3 天
第三阶段：3-4 天
第四阶段：2-3 天
第五阶段：1-2 天
第六阶段：2-3 天

总计：11-17 个工作日（约 2.5-3.5 周）

附录

A. 设计稿参考

Figma 文件：https://www.figma.com/make/xgPuMR3GZzHpYh0RZJdiYK/kaidong.ai?p=f&fullscreen=1
密码：0592

B. 待补充内容

新手引导步骤 2-4：需要补充完整内容
项目设置选项：需要补充详细设置项
权限管理功能：需要补充详细权限选项
导出功能：需要补充导出选项和格式

C. 变更记录

v1.0 (2025-01-27)：功能需求版，从原文档中分离出功能需求部分

文档结束

本文档专注于产品功能需求、交互逻辑和技术规范，不包含具体的 mock 数据内容。Mock 数据请参考《Jointo产品初始mock数据文档》。

57 KiB Raw Permalink Blame History

Jointo（jointo）产品需求文档

目录

1. 产品概述

1.1 产品定位

1.2 核心价值

1.3 产品名称

2. 目标与范围

2.1 本期（MVP）目标

2.1.1 UI 还原

2.1.2 功能实现

2.1.3 交互体验

2.2 不在本期范围

3. 用户与使用场景

3.1 用户角色

3.2 典型使用流程

4. 整体布局架构

4.1 页面结构（单页应用 SPA）

4.2 React 组件层级结构

5. 详细功能需求

5.1 应用顶部栏（TopBar）

5.3.1 左侧区域

5.3.2 右侧区域

5.2 左侧栏（LeftSidebar）

5.2.1 Tab 切换

5.2.2 项目列表（项目 Tab 下）

5.2.3 素材库（素材库 Tab 下）

5.3 中间区域 - 分镜列表（StoryboardPanel）

5.3.1 分镜描述区域头部

5.3.2 分镜列表

5.3.3 插入新分镜按钮

5.3.4 交互行为

5.4 中间区域 - 预览窗口（PreviewPanel）

5.4.1 预览窗口头部

5.4.2 内容预览区域

5.4.3 缩放控制

5.4.4 状态栏

5.5 中间区域 - 播放控制（PlaybackControls）

5.5.1 控制按钮

5.5.2 时间码显示

5.5.3 状态显示

5.6 中间区域 - AI 输入区（AIPromptPanel）

5.6.1 AI 功能 Tab

5.6.2 提示词示例区域

5.6.3 输入框

5.6.4 操作按钮

5.6.5 模型选择器

5.7 分镜看板（TimelinePanel）

5.7.1 分镜看板头部

5.7.2 时间刻度

5.7.3 轨道结构

5.7.4 添加轨道按钮

5.7.5 分镜看板交互

5.8 右侧栏 - 资源面板（ResourcePanel）

5.8.1 面板头部

5.8.2 分镜资源分组

5.8.3 交互行为

5.9 右侧栏 - 视频面板（VideoPanel）

5.9.1 面板头部

5.9.2 视频列表

5.9.3 交互行为

5.10 右侧栏 - 音效面板（SoundEffectPanel）

5.10.1 面板头部

5.10.2 音效列表

5.10.3 交互行为

5.11 右侧栏 - 字幕面板（SubtitlePanel）

5.11.1 面板头部

5.11.2 字幕列表

5.11.3 交互行为

5.12 右侧栏 - 配音面板（VoiceoverPanel）

5.12.1 面板头部

5.12.2 配音列表

5.12.3 交互行为

5.13 右侧栏 - Tab 切换

5.13.1 Tab 按钮组

5.13.2 交互行为

5.14 新手引导浮层（OnboardingOverlay）

5.14.1 浮层结构

5.14.2 引导步骤内容

5.14.3 交互行为

57 KiB

Raw Permalink Blame History