ttstd-infinite-canvas/PREVIS_REFACTOR_PLAN.md

预演台统一重构：分析、设计与执行方案

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。