# Jointo（jointo）产品需求文档 > **目标**：定义Jointo产品的功能需求、交互逻辑和技术规范 > **参考设计稿**：`https://www.figma.com/make/xgPuMR3GZzHpYh0RZJdiYK/kaidong.ai?p=f&fullscreen=1` > **文档版本**：v1.0 - 功能需求版 > **项目域名**：https://www.jointo.ai --- ## 目录 1. [产品概述](#1-产品概述) 2. [目标与范围](#2-目标与范围) 3. [用户与使用场景](#3-用户与使用场景) 4. [整体布局架构](#4-整体布局架构) 5. [详细功能需求](#5-详细功能需求) 6. [UI/UX 交互细节](#6-uiux-交互细节) 7. [数据模型](#7-数据模型) 8. [API 接口规范](#8-api-接口规范) 9. [技术方案](#9-技术方案) 10. [非功能需求](#10-非功能需求) 11. [开发迭代计划](#11-开发迭代计划) --- ## 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 用户角色 1. **视频创作者/编辑** - 使用分镜功能规划视频结构 - 使用 AI 生成视频素材 - 在分镜看板上编排视频片段 - 添加音效、字幕、配音 2. **运营/营销人员** - 快速制作广告片、宣传片 - 使用 AI 工具提升制作效率 - 管理多个项目 3. **协作者** - 查看和编辑协同项目 - 参与项目讨论和备注 ### 3.2 典型使用流程 1. **创建/选择项目** - 点击「新建项目」或从列表选择现有项目 - 项目自动加载，显示分镜列表 2. **编辑分镜** - 查看/编辑分镜描述文案 - 为每个分镜配置资源（人物、场景、道具） - 插入新分镜或删除分镜 3. **生成和管理素材** - 使用 AI 生成视频素材 - 从素材库选择已有素材 - 在分镜看板上排列素材 4. **完善视频** - 添加音效、字幕、配音 - 在预览窗口查看效果 - 调整分镜看板上的素材位置 5. **导出项目** - 点击「导出项目」（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 Cookie 提示（Consent Manager） #### 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 核心数据类型 ```typescript // 项目类型 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; storyboardId?: string; }; // AI 生成响应 type AIGenerateResponse = { success: boolean; data?: any; error?: string; jobId?: string; // 异步任务 ID }; ``` ### 7.2 状态管理数据结构 ```typescript // 应用全局状态 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 统一响应结构 ```typescript // 成功响应 type ApiSuccessResponse = { success: true; data: T; message?: string; }; // 错误响应 type ApiErrorResponse = { success: false; error: { code: string; message: string; details?: any; }; }; // 分页响应 type ApiPaginatedResponse = { success: true; data: T[]; pagination: { page: number; pageSize: number; total: number; totalPages: number; }; }; ``` #### 8.1.3 错误码规范 ```typescript 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 环境变量 ```bash # .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 切换机制 ```typescript // 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 核心依赖包 **必需依赖**： ```json { "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 预览窗口实现 - 使用 `` 标签显示预览图 - 支持缩放（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. 待补充内容 1. **新手引导步骤 2-4**：需要补充完整内容 2. **项目设置选项**：需要补充详细设置项 3. **权限管理功能**：需要补充详细权限选项 4. **导出功能**：需要补充导出选项和格式 ### C. 变更记录 - **v1.0** (2025-01-27)：功能需求版，从原文档中分离出功能需求部分 --- **文档结束** > 本文档专注于产品功能需求、交互逻辑和技术规范，不包含具体的 mock 数据内容。Mock 数据请参考《Jointo产品初始mock数据文档》。