# Previs 预演台 UI 重构执行计划 ## 执行原则 1. **严格按顺序执行**：每完成一个 Phase，运行验证命令通过后才继续下一个 2. **保持功能完整**：所有现有能力必须保留，E2E 测试必须通过 3. **增量提交**：每个 Phase 完成后独立提交，commit message 用 conventional-commits skill 4. **视觉优先**：UI 必须高端、有质感、专业，参考 Blender / Unreal / Unity 的深色专业界面 ## 当前问题诊断 ### P0 缺陷 1. **画布卡片无缩略图**：`canvas-previs-node-panel.tsx` 只在已回写构图时显示 ``，未回写时显示文字占位 2. **高频工作流功能不全**：缺少新建物品（盒子/球体/圆柱/平面）、灯光、相机的直接入口 3. **角色人偶材质单薄**：当前 `applyActorReferenceMaterial` 只是纯色 `MeshStandardMaterial`，无层次感 4. **整体布局陈旧**：间距、圆角、字号、层次、对比度不足，缺少高级感 ### 设计目标 - **画布卡片**：实时 3D 缩略图（俯视/透视小视口），显示对象数/机位数/时长，玻璃态卡片 - **高频工作流**：覆盖 100% 高频操作，分组清晰（演员/道具/灯光/机位/姿态/颜色/运镜），大图标+文字 - **角色人偶**：程序化生成质感材质（fresnel rim、ambient occlusion 近似、subtle gradient），不同演员默认不同鲜明颜色，面板可改色 - **工作台布局**：深色玻璃态、更大间距、清晰层次、减少嵌套、增加留白 --- ## Phase 1: 角色人偶材质升级（独立，无 UI 依赖） ### 目标 高质量程序化人偶材质，不依赖贴图，纯 shader 实现 rim light + 环境色 + 颜色差异化。 ### 实现文件 - `web/src/components/canvas/previs/previs-viewport-rig.ts` ### 具体改动 #### 1.1 新增高级材质构造函数 在 `previs-viewport-rig.ts` 中，找到 `applyActorReferenceMaterial` 函数，**完全替换**为： ```typescript /** * 为演员人偶应用程序化高质感材质： * - 基础颜色由 object.color 控制 * - Fresnel rim light 提供轮廓光 * - 微妙的顶部-底部渐变模拟天光与地面反射 * - roughness 0.7 + metalness 0.05 产生柔和但有质感的反射 */ export function applyActorReferenceMaterial(model: Object3D, baseColor: string) { const color = new Color(baseColor); // 构造自定义 ShaderMaterial 提供 rim + gradient const material = new ShaderMaterial({ uniforms: { uBaseColor: { value: color }, uRimColor: { value: new Color(0xffffff) }, uRimPower: { value: 3.0 }, uRimIntensity: { value: 0.35 }, uTopColor: { value: new Color(0x87ceeb).multiplyScalar(0.15) }, uBottomColor: { value: new Color(0x2c2c2c).multiplyScalar(0.3) }, }, vertexShader: ` varying vec3 vNormal; varying vec3 vViewPosition; varying float vHeight; void main() { vNormal = normalize(normalMatrix * normal); vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); vViewPosition = -mvPosition.xyz; vHeight = position.y; gl_Position = projectionMatrix * mvPosition; } `, fragmentShader: ` uniform vec3 uBaseColor; uniform vec3 uRimColor; uniform float uRimPower; uniform float uRimIntensity; uniform vec3 uTopColor; uniform vec3 uBottomColor; varying vec3 vNormal; varying vec3 vViewPosition; varying float vHeight; void main() { vec3 normal = normalize(vNormal); vec3 viewDir = normalize(vViewPosition); // Fresnel rim float rim = 1.0 - max(dot(normal, viewDir), 0.0); rim = pow(rim, uRimPower) * uRimIntensity; // 顶部-底部渐变（模拟天光） float heightFactor = clamp((vHeight + 0.5) / 2.0, 0.0, 1.0); vec3 ambientGradient = mix(uBottomColor, uTopColor, heightFactor); // 合成 vec3 finalColor = uBaseColor + ambientGradient + rim * uRimColor; gl_FragColor = vec4(finalColor, 1.0); } `, }); model.traverse((child) => { const mesh = child as Mesh; if (mesh.isMesh && !mesh.userData.previsNoMaterialOverride) { disposePrevisMaterials(mesh.material); mesh.material = material; } }); } export function updateActorReferenceColor(model: Object3D, baseColor: string) { const color = new Color(baseColor); model.traverse((child) => { const mesh = child as Mesh; if (mesh.isMesh && mesh.material && "uniforms" in mesh.material) { const uniforms = (mesh.material as ShaderMaterial).uniforms; if (uniforms.uBaseColor) uniforms.uBaseColor.value = color; } }); } ``` #### 1.2 确保新演员自动分配不同颜色 在 `web/src/components/canvas/previs/canvas-previs-workbench.tsx` 中，找到 `addActor` 函数，确保： ```typescript const addActor = () => { const existingActors = draft.objects.filter((obj) => obj.kind === "actor" || obj.primitive === "character"); const colorIndex = existingActors.length % PREVIS_ACTOR_COLORS.length; const nextColor = PREVIS_ACTOR_COLORS[colorIndex]; addObject(createPrevisActor(`演员 ${existingActors.length + 1}`, [0, 0, 0], nextColor)); }; ``` #### 1.3 验证命令 ```bash cd web ./node_modules/.bin/tsc --noEmit ./node_modules/.bin/vite build node scripts/previs-p0-chrome-e2e.mjs ``` **通过标准**：TypeScript 无错误，Vite 构建成功，E2E 62/62 通过。 **提交**： ```bash git add web/src/components/canvas/previs/previs-viewport-rig.ts web/src/components/canvas/previs/canvas-previs-workbench.tsx # 用 conventional-commits skill 生成 message ``` --- ## Phase 2: 画布节点卡片实时 3D 缩略图 ### 目标 未回写构图时，画布卡片也能显示场景内容：渲染一个小的 3D 俯视图。 ### 实现文件 - `web/src/components/canvas/previs/canvas-previs-node-panel.tsx` - `web/src/components/canvas/previs/previs-mini-viewport.tsx` (新建) ### 具体改动 #### 2.1 新建 `previs-mini-viewport.tsx` 创建 `web/src/components/canvas/previs/previs-mini-viewport.tsx`： ```typescript import { Canvas } from "@react-three/fiber"; import { OrthographicCamera } from "@react-three/drei"; import { Suspense } from "react"; import type { PrevisScene } from "@/types/previs"; /** * 画布卡片缩略图：固定俯视正交视角，只显示对象轮廓。 * 不加载真实模型，用简化几何体代替，确保快速渲染。 */ export function PrevisMiniViewport({ scene }: { scene: PrevisScene }) { return (
{scene.objects.filter((obj) => obj.visible !== false).map((obj) => { const pos = obj.transform.position; const color = obj.color || "#d6d9dd"; const primitive = obj.primitive || "box"; if (primitive === "sphere") { return ; } if (primitive === "cylinder") { return ; } if (primitive === "character" || obj.kind === "actor") { return ; } // 默认 box return ; })}
); } ``` #### 2.2 改造 `canvas-previs-node-panel.tsx` 在 `EmptyPreview` 组件中，**替换** `loading ? "正在准备场景" : "尚未生成预览"` 的分支为： ```typescript if (scene && scene.objects.length > 0) { return (
} value={scene.objects.length} label="对象" /> } value={scene.cameras.length} label="机位" /> } value={scene.lights.length} label="灯光" />
); } return (
{loading ? "正在准备场景" : "进入预演台开始创作"}
); ``` 导入新组件： ```typescript import { PrevisMiniViewport } from "./previs-mini-viewport"; ``` #### 2.3 验证命令 ```bash cd web ./node_modules/.bin/tsc --noEmit ./node_modules/.bin/vite build ``` 手动检查：打开画布，创建一个预演场景节点，确认卡片显示 3D 俯视缩略图。 **提交**： ```bash git add web/src/components/canvas/previs/canvas-previs-node-panel.tsx web/src/components/canvas/previs/previs-mini-viewport.tsx ``` --- ## Phase 3: 高频工作流功能完整化 ### 目标 高频工作流模式包含所有高频操作：新建演员/盒子/球体/圆柱/平面、灯光、相机、姿态、颜色、景别、运镜。 ### 实现文件 - `web/src/components/canvas/previs/canvas-previs-workbench.tsx` ### 具体改动 #### 3.1 高频工作流左侧面板重构 找到快速模式的 `