289 lines
17 KiB
Markdown
289 lines
17 KiB
Markdown
# 预演台统一重构：分析、设计与执行方案
|
||
|
||
## 0. 结论先行
|
||
|
||
当前问题不是“高频工作流样式还不够精致”，而是产品结构上同时维护了两套入口：
|
||
|
||
- 高频工作流：真实高频工作流，布局清晰，用户已经反复调试到可用。
|
||
- 旧分裂工作台：功能覆盖更广，但布局、样式和交互边界长期没有同步，已经出现样式 bug、功能 bug、滚动问题和空白问题。
|
||
|
||
继续在两套页面上各自修复，会让同一份场景数据拥有两套操作语义，之后每次新增能力都要重复接线、重复测试、重复修复。
|
||
|
||
本轮方向确定为：
|
||
|
||
> 删除“高频工作流”和“旧分裂工作台”这两个产品层级，把所有能力合并到一个统一的“预演台”工作区。布局、视觉和交互以已经验证过的高频工作流方案为主；从 DirectorDesk 只吸收真正有价值的场景编排能力，尤其是轨迹绘制与轨迹播放，不复制它的表面结构。
|
||
|
||
“预演台”是产品名称。内部可以继续保留 `layout / pose / animate / camera` 作为能力状态，但它们只能是同一工作区中的上下文，不再是两套工作台。
|
||
|
||
## 1. 反复犯错的问题
|
||
|
||
### 1.1 把参考产品的表面结构当成了产品答案
|
||
|
||
错误表现：
|
||
|
||
- 看到 DirectorDesk 的左侧布景、右侧摄影机、底部时间轴，就把“多面板旧分裂工作台”整体搬过来。
|
||
- 只复制了组件形状、标题和分栏，没有先确认我们的用户真正高频的任务顺序。
|
||
- 参考产品里真正有价值的能力（轨迹、路径、基于距离的步行动画、镜头连续性）反而没有成为主线。
|
||
|
||
修复思路：
|
||
|
||
- 参考产品只提取“能力和原则”，不提取它的页面壳。
|
||
- 先问用户在当前产品里最常做什么，再决定入口、密度和默认视图。
|
||
- 对 DirectorDesk 的吸收清单只保留：自由手绘轨迹、轨迹简化、按距离分配时间、路径朝向、演员/摄影机路径可视化、同一场景多视图观察。
|
||
- 明确不复制：独立桌面应用的菜单层级、复杂资源管理、与本项目无关的深度导出和外部工程概念。
|
||
|
||
### 1.2 把“功能完整”误解成“再造一个页面
|
||
|
||
错误表现：
|
||
|
||
- 为了补齐布景、姿态、动画、摄影机，新增旧分裂工作台。
|
||
- 结果是高频工作流和旧分裂工作台分别拥有一部分能力，任何一边都不是完整事实来源。
|
||
- 同一个操作在两套页面上可能使用不同的保存、选择、视口和检查器路径。
|
||
|
||
修复思路：
|
||
|
||
- 功能完整不等于页面分裂。
|
||
- 所有场景修改都必须进入同一套 `commit / history / save coordinator` 链路。
|
||
- 所有对象、灯光、摄影机、资产、姿态、关键帧和输出都在同一个预演台布局中可达。
|
||
- 复杂功能通过同一页面里的分区、抽屉、工具栏、检查器和时间轴渐进展开，而不是增加第二个工作台。
|
||
|
||
### 1.3 先修局部样式，后补产品信息架构
|
||
|
||
错误表现：
|
||
|
||
- 不断调整圆角、颜色、间距、按钮样式。
|
||
- 但页面仍然有两套入口，用户不知道该进入哪一个。
|
||
- 旧分裂工作台中的功能不在高频工作流出现，导致“看起来有功能，实际上找不到”。
|
||
|
||
修复思路：
|
||
|
||
- 顺序固定为：信息架构 -> 任务路径 -> 状态模型 -> 组件布局 -> 视觉细节。
|
||
- 页面只有一个产品入口，先解决“在哪里做”再解决“看起来怎样”。
|
||
- 视觉规范以高频工作流当前已验证的密度、面板、颜色、对象列表和视口胶囊切换为基线。
|
||
|
||
### 1.4 通过重新实现，破坏已经修好的行为
|
||
|
||
错误表现：
|
||
|
||
- 修复 UI 时把保存、撤销、模型加载、上下文恢复、对象摆位等已稳定链路一起改动。
|
||
- 为了“统一”，把刻意放宽的产品规则重新收紧。
|
||
- 用逐个报错、逐个补洞的方式开发，最后无法确认完整流程是否可靠。
|
||
|
||
修复思路：
|
||
|
||
- 统一页面只替换产品壳，不重写已稳定的场景数据和保存底座。
|
||
- 保留 `touchPrevisScene`、`commit`、`stagedTransaction`、保存协调器、模型加载诊断和 WebGL 恢复机制。
|
||
- 每轮修改后跑完整流程：打开、加对象、选中、摆位、画轨迹、播放、保存、回写、关闭、重开。
|
||
- 不以“某一个错误消失”为完成标准，而以端到端流程通过为标准。
|
||
|
||
### 1.5 把轨迹当成动画的附属细节，而不是核心能力
|
||
|
||
错误表现：
|
||
|
||
- 目前主要依靠零散 transform 关键帧和简单折线显示。
|
||
- 用户无法像导演在场地上画走位一样直接表达动作。
|
||
- 轨迹时间可能受鼠标事件数量、停顿和绘制速度影响，导致播放速度不稳定。
|
||
|
||
修复思路：
|
||
|
||
- 轨迹是预演台的核心编辑对象，必须有明显的“画轨迹”入口。
|
||
- 轨迹采样后先做三维简化，再按路径距离分配时间，不能按 pointer event 间隔直接写时间。
|
||
- 演员沿轨迹移动时默认按路径方向转向；摄影机轨迹至少保证位置连续，并保留原镜头朝向。
|
||
- 轨迹必须能在导演视角、机位视角和时间轴播放中被验证。
|
||
|
||
## 2. 用户调教出来的产品设计原则
|
||
|
||
这些不是装饰偏好，而是预演台的产品约束：
|
||
|
||
1. 高频工作流是 99% 用户使用的真实入口，所有功能必须进入主工作流。
|
||
2. 不允许用“高级模式”作为缺功能的借口；高级能力必须在同一个预演台中自然出现。
|
||
3. UI 需要高端、专业、有质感，但不能靠装饰遮盖信息架构问题。
|
||
4. 画布节点必须有真实场景缩略图或可靠的实时预览，不用空白文字占位冒充完成。
|
||
5. 新演员必须默认拥有可区分的颜色，颜色可直接编辑。
|
||
6. 对象、摄影机、灯光、资产、环境、姿态、运镜、动画和输出必须在同一场景事实源中工作。
|
||
7. 操作必须可逆、可保存、可重开，不能出现“界面看起来成功但数据没有保存”。
|
||
8. 功能入口应该面向任务：添加角色、搭景、画轨迹、设计镜头、调整动作、输出，而不是面向内部代码模块。
|
||
9. 不用重复造同一套 UI。一个布局、一个状态模型、一个保存链路、一个测试入口。
|
||
10. 重构不得把已经明确放宽的产品规则重新收紧，例如素材删除不因为引用关系被拦截。
|
||
|
||
## 3. DirectorDesk 真正值得吸收的东西
|
||
|
||
### 吸收
|
||
|
||
- **自由手绘路径**：在地面或物体表面直接拖出演员/摄影机路线。
|
||
- **路径点清理和简化**：去掉高频采样噪声，同时保留拐角和闭环形状。
|
||
- **基于距离的时间分配**：相同路径不因鼠标快慢、帧率或事件密度而改变播放速度。
|
||
- **连续路径与途经点停留**：后续可支持停留点、分段速度和连续曲线。
|
||
- **路径方向**：演员沿路径方向朝向；摄影机可选择沿路径、看向目标或保持镜头方向。
|
||
- **路径可视化**：轨迹线、起点、终点、当前播放位置、选中状态要一眼可见。
|
||
- **位置和动作分离**：路线控制空间移动，动作片段控制走路/跑步/姿势，二者可以独立调整。
|
||
- **多视图验证**：导演视角调整空间关系，机位视角检查最终画面，时间轴检查连续性。
|
||
|
||
### 不吸收
|
||
|
||
- 不复制 DirectorDesk 的独立应用信息架构。
|
||
- 不复制与本项目无关的资源目录、导出协议和菜单层级。
|
||
- 不为了“看起来像”而保留第二个高级页面。
|
||
- 不把桌面端复杂能力一次性全部塞进首屏；复杂选项放入检查器和可展开工具。
|
||
|
||
## 4. 统一预演台设计
|
||
|
||
### 4.1 统一产品结构
|
||
|
||
名称：**预演台**。
|
||
|
||
单一全屏工作区：
|
||
|
||
- 顶部：关闭、场景标题、撤销/重做、保存状态、渲染模式、生成白膜、回写构图。
|
||
- 左侧：场景对象、摄影机、灯光、道具库、画布资产、轨迹目标入口。
|
||
- 中间：主 3D 视口；导演视角/机位视角/正交视图切换；对象和轨迹直接可见。
|
||
- 右侧：当前镜头与选中对象检查器；景别、运镜、时长、帧率、姿态、体型、颜色、变换、灯光、镜头参数和生成提示词。
|
||
- 底部：时间轴按需展开；镜头条、对象轨道、摄影机轨道、关键帧、播放和 Auto Key 都在这里。
|
||
|
||
没有“高频工作流 / 旧分裂工作台”切换按钮，也没有“进入旧分裂工作台”的隐藏入口。
|
||
|
||
### 4.2 统一页面中的上下文
|
||
|
||
内部仍可以使用 `layout / pose / animate / camera` 作为能力上下文，但它们只影响：
|
||
|
||
- 当前检查器优先展示什么。
|
||
- 是否显示时间轴和 Auto Key。
|
||
- 渲染模式有哪些。
|
||
- 当前工具栏的默认工具。
|
||
|
||
它们不能切换到另一套页面，也不能改变对象数据的来源。
|
||
|
||
### 4.3 主任务顺序
|
||
|
||
1. 选镜头或创建镜头。
|
||
2. 从左侧添加演员、道具、资产、灯光和摄影机。
|
||
3. 在中间视口拖动对象，或点击“画轨迹”直接绘制走位。
|
||
4. 在右侧调整姿态、体型、颜色和镜头参数。
|
||
5. 在底部时间轴播放、补关键帧、查看轨迹连续性。
|
||
6. 在机位视角确认画面。
|
||
7. 生成白膜或回写构图。
|
||
|
||
每一步都应在同一个页面完成，不需要跳转或换工作台。
|
||
|
||
### 4.4 轨迹交互
|
||
|
||
- 选中演员或摄影机后，工具栏出现“画轨迹”。
|
||
- 点击后进入绘制态：视口进入路径采样，OrbitControls 暂停，鼠标/触摸拖动生成地面路径。
|
||
- 绘制中显示临时路径和起点/终点。
|
||
- 松开后按当前镜头时长生成路径关键帧。
|
||
- 演员：按路径方向生成水平朝向，保留当前高度、缩放和姿态/动作。
|
||
- 摄影机：写入连续位置关键帧，默认保留当前旋转；后续再提供“沿路朝向 / 看向主体”的切换。
|
||
- 再次绘制覆盖该对象当前轨迹，撤销可以恢复旧轨迹。
|
||
- 没有选中可移动对象时，按钮给出明确提示，不进入半成品状态。
|
||
|
||
## 5. 数据与实现边界
|
||
|
||
### 保留
|
||
|
||
- `PrevisScene`、`PrevisObject`、`PrevisCamera`、`PrevisLight`。
|
||
- 现有 transform keyframe 结构，轨迹首版直接编译为关键帧，避免引入第二套持久化格式。
|
||
- `previs-animation-semantics.ts` 的动画编辑语义。
|
||
- 保存协调器、草稿恢复、页面卸载保护、诊断事件和视口 capture/record。
|
||
- 既有对象颜色、actor archetype、actorProfile、motionClips 和 boneTracks。
|
||
|
||
### 新增
|
||
|
||
- `previs-path.ts`：
|
||
- 三维点清理与 Ramer-Douglas-Peucker 简化。
|
||
- 按路径距离计算 waypoint 时间。
|
||
- 轨迹关键帧生成。
|
||
- 路径方向和 yaw 计算。
|
||
- 视口绘制态：仅在显式绘制轨迹时接管 pointer 事件。
|
||
- 轨迹预览：临时线、已保存路径、当前播放点。
|
||
- 单元测试覆盖：简化、距离计时、退化路径、方向角连续性、关键帧生成。
|
||
|
||
### 不新增
|
||
|
||
- 不再增加 第二套模式状态。
|
||
- 不再保留一套只为“旧分裂工作台”服务的 JSX 和 CSS。
|
||
- 不建立第二个场景编辑器 store。
|
||
- 不把路径采样事件直接持久化为大量 pointer 记录。
|
||
|
||
## 6. 重构阶段与验收门
|
||
|
||
### Phase 1：先写统一事实源
|
||
|
||
- 删除顶部快速/高级切换。
|
||
- 统一预演台默认显示场景对象、摄影机、灯光、资产、镜头检查器。
|
||
- 将原旧分裂工作台中仍有价值的工具接入现有 `pv-*` 布局。
|
||
- 删除重复 JSX 和对应的高级 CSS。
|
||
|
||
成功标志：项目中只剩一个预演台 UI 分支，搜索不到“高频工作流/旧分裂工作台”产品入口。
|
||
|
||
### Phase 2：轨迹基础能力
|
||
|
||
- 增加纯函数路径库和单元测试。
|
||
- 视口增加显式画轨迹态。
|
||
- 演员和摄影机轨迹编译为已有关键帧。
|
||
- 播放头和轨迹预览同步。
|
||
|
||
成功标志：能在同一页面画演员路线、播放并撤销；摄影机路线能在导演视角看到。
|
||
|
||
### Phase 3：布局与体验收敛
|
||
|
||
- 左侧补齐旧分裂工作台里的对象、灯光、模型资产和道具入口。
|
||
- 右侧补齐对象/灯光/镜头检查器和提示词输出。
|
||
- 底部时间轴按动画上下文展开，不再用页面切换表达“高级”。
|
||
- 统一按钮、焦点、触控尺寸、滚动容器和空状态。
|
||
|
||
成功标志：用户不需要记住功能属于哪一种工作台；所有高频能力在一个页面可发现。
|
||
|
||
### Phase 4：测试和清理
|
||
|
||
- 更新 Chrome E2E：不再点击旧分裂工作台；默认打开即验证统一界面。
|
||
- 保留对象添加、撤销、模型加载、上下文丢失恢复、保存失败重试等 P0 场景。
|
||
- 增加轨迹的纯函数测试和至少一条浏览器轨迹 smoke。
|
||
- 删除无引用的高级组件、样式、旧命名和测试描述。
|
||
|
||
成功标志：TypeScript、ESLint、单元测试、Vite build、Chrome E2E 全部通过；完整流程可从打开走到保存、关闭和重开。
|
||
|
||
## 7. 明确的完成标准
|
||
|
||
- 用户只看到一个产品：预演台。
|
||
- 高频工作流中已验证的布局和视觉成为全局基线。
|
||
- 布景、演员、姿态、动画、摄影机、灯光、资产、环境、提示词和输出全部可达。
|
||
- 轨迹绘制成为一等交互，不是隐藏在高级模式里的补充按钮。
|
||
- 轨迹播放速度由路径距离和镜头时长决定，不由鼠标事件或绘制速度决定。
|
||
- 新演员颜色自动区分且可编辑。
|
||
- 画布卡片、模型加载、保存恢复和输出链路没有回归。
|
||
- 没有“进入旧分裂工作台”或“切换高频工作流”的产品级文案、按钮和双份页面。
|
||
|
||
## 8. 本轮 IA 实施记录（2026-10-05）
|
||
|
||
### 已落地的左右面板职责
|
||
|
||
- 左侧只负责场景层级、对象、摄影机、灯光、道具和资源浏览；移除重复的摄影机、灯光、道具库添加入口，避免同一动作在多个面板出现。
|
||
- 中央只负责真实 WebGL 视口、对象操作、视角工具和轨迹绘制；移除旧的视图胶囊，视图状态统一由视口工具层管理。
|
||
- 右侧只负责当前选择上下文：选中对象显示对象检查器，选中灯光显示灯光检查器，选中摄影机显示摄影机检查器，无选择时才显示镜头设计上下文。
|
||
- 底部只负责时间、播放、Auto Key、镜头条、对象轨道和关键帧；不在左右面板复制时间控制。
|
||
- 移动端将右侧检查器变成滑入抽屉，通过显式打开/关闭按钮进入，不牺牲检查器能力，也不压缩主视口到不可用尺寸。
|
||
|
||
### 覆盖层与响应式纠错记录
|
||
|
||
- 下拉菜单、工具提示和检查器抽屉使用明确的层级、边界和碰撞策略；打开菜单时不遮盖错误面板，Escape 可关闭，焦点回到触发控件。
|
||
- 本轮曾将移动工具声明放在 media block 外并多写一个 `}`，导致 Vite 在 `canvas-previs-workbench.css:1415` 失败。修正方式是把移动端工具栏、轨迹按钮和时间轴声明收回同一个 `@media (max-width: 860px)`，再以生产构建验证 CSS 结构。
|
||
- 移动端保留 176-200px 左侧层级栏、单列视口和 280px 时间轴下限；右侧检查器使用不超过 92vw 的抽屉，避免面板相互覆盖。
|
||
|
||
### 当前验收状态（截至 2026-10-05）
|
||
|
||
- 已通过：TypeScript、目标 ESLint、`git diff --check`、Vite production build、轨迹纯函数测试（`npx --yes bun test test/previs-path.test.ts`，5 tests / 12 assertions）。
|
||
- 已通过：完整 Chrome P0 E2E，A-F 共 62/62 断言通过；覆盖统一工作台启动、真实 WebGL、添加/撤销、动画时间轴、模型成功加载、模型失败重试、加载中删除、WebGL context loss/restore、保存失败提示、重试入口和关闭保护。
|
||
- 已通过：桌面结构探针（1680×932）：左/右面板各 272px，中央 canvas 约 1132×879；DOM 中 `.pv-viewport-toolbar`、取景模式组和 canvas 各 1 个，旧 Dock 与视图胶囊均为 0。
|
||
- 已通过：窄屏结构探针（390×844）：左层级栏 176px，主视口约 299px，右检查器以约 359px 抽屉停在屏幕外，工具栏位于主视口内；未发现面板几何重叠。开发环境仅出现已知 Ant Design/Three 弃用提示，无运行时异常。
|
||
- 已通过：精确旧双工作台/旧产品入口扫描为 0 命中；保留的历史文档术语不构成运行时入口。
|
||
- 尚未覆盖：浏览器内真实轨迹拖拽、轨迹取消/预览/播放、轨迹撤销和演员/摄影机轨迹持久化重载；保存成功后的重开闭环；保存失败后实际点击“重试保存”并确认恢复；移动端截图级视觉验收；完整下拉碰撞与焦点回归。
|
||
- 不能宣称完成的门禁：上述浏览器轨迹与持久化闭环仍需专门 smoke；本轮已证明轨迹算法和基础 pointer 取消逻辑，但没有把它们扩大解释为完整端到端通过。
|
||
|
||
### 下一轮验收顺序
|
||
|
||
1. 在稳定的本地预演台页面完成浏览器轨迹绘制、取消、距离计时、预览、播放、撤销、镜头切换、模式切换和保存重载闭环。
|
||
2. 补保存成功重开、保存失败后重试成功，以及导出动作的浏览器断言。
|
||
3. 补移动端实际截图和打开检查器抽屉后的边界/焦点/Escape 断言。
|
||
4. 扫描源代码、测试和文档，确认不存在旧的双页面入口、路由、分支或产品级名称。
|
||
5. 最后再次运行 TypeScript、ESLint、轨迹测试、Vite build、E2E 和 `git diff --check`。
|