fix(3d): 主题切换/场景切换手动渲染修复(docked冻结)+routeToModuleId抽离

Author: Aparencia

client/src/components/layout/AppLayout.tsx

@@ -1,7 +1,7 @@
 /**
  * @ai-context: 布局组件：AppLayout。
  */
-import { useEffect, useLayoutEffect, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { motion, MotionConfig, AnimatePresence } from 'framer-motion';
 import { Home } from 'lucide-react';
@@ -17,7 +17,7 @@ import { SceneTransition } from '@/lib/3d/scenes/SceneTransition';
 import { SpatialNav } from '@/lib/3d/navigation/SpatialNav';
 import { MobileNavGrid } from '@/lib/3d/scenes/MobileNavGrid';
 import { FunctionalOverlay } from '@/components/overlay/FunctionalOverlay';
-import { useOrbitalStore, MODULE_POSITIONS } from '@/lib/3d/navigation/OrbitalStore';
+import { useOrbitalStore, routeToModuleId } from '@/lib/3d/navigation/OrbitalStore';
 import { OnboardingOverlay } from '@/components/onboarding/OnboardingOverlay';
 import { ModuleTourToast } from '@/components/onboarding/ModuleTourToast';
 import { HelpCenter } from '@/components/onboarding/HelpCenter';
@@ -28,9 +28,47 @@ import { FirstDiveGate } from '@/features/onboarding/firstDive/FirstDiveGate';
 import { usePerformanceModeStore } from '@/lib/performance/usePerformanceMode';
 import { PERFORMANCE_MODE_CONFIG } from '@/lib/performance/performanceMode';
 
+/**
+ * 路由层级映射：子路由 -> 父路由
+ * 在 ESC 处理器中用于"向上导航一级"而非直接退出模块
+ */
+function findParentRoute(pathname: string): string | null {
+  const patterns: Array<{
+    pattern: RegExp;
+    parent: string | ((match: RegExpMatchArray) => string);
+  }> = [
+    // Pomodoro 子页面
+    { pattern: /^\/pomodoro\/(stats|settings)$/, parent: '/pomodoro' },
+    // Notes 子页面
+    { pattern: /^\/notes\/graph$/, parent: '/notes' },
+    { pattern: /^\/notes\/([^/]+)$/, parent: '/notes' },
+    // Flashcards 子页面（二级子路由回到所属牌组详情）
+    { pattern: /^\/flashcards\/([^/]+)\/(study|generative-review)$/, parent: (m) => `/flashcards/${m[1]}` },
+    { pattern: /^\/flashcards\/([^/]+)$/, parent: '/flashcards' },
+    // Feynman 子页面
+    { pattern: /^\/feynman\/([^/]+)$/, parent: '/feynman' },
+    { pattern: /^\/socratic$/, parent: '/feynman' },
+    // SOP 子页面
+    { pattern: /^\/sop\/editor/, parent: '/sop' },
+    // 非模块页面（settings/analytics/settling/inbox/certificate -> 仪表盘）
+    { pattern: /^\/(settings|analytics|settling|inbox|certificate)$/, parent: '/' },
+  ];
+
+  for (const { pattern, parent } of patterns) {
+    const match = pathname.match(pattern);
+    if (match) {
+      return typeof parent === 'function' ? parent(match) : parent;
+    }
+  }
+  return null;
+}
+
 export default function AppLayout() {
   const { pathname } = useLocation();
   const navigate = useNavigate();
+  // 跟踪当前路径（ref 避免 ESC 处理器闭包读到旧值，同时避免加入 effect 依赖）
+  const pathnameRef = useRef(pathname);
+  useEffect(() => { pathnameRef.current = pathname; }, [pathname]);
   // 细粒度 selector 订阅：整 store 订阅会被 hoveredModule 等高频字段变化
   // 连带重渲染整棵布局树（含 Outlet 页面），是流畅度关键瓶颈
   const isInModule = useOrbitalStore((s) => s.isInModule);
@@ -46,6 +84,11 @@ export default function AppLayout() {
   // 性能模式：静谧(low)档全局减弱 Framer Motion 动画（transform/layout 动画直接到位）
   const perfMode = usePerformanceModeStore((s) => s.mode);
   const reduceMotion = PERFORMANCE_MODE_CONFIG[perfMode].reduceMotion;
+  // 笔记编辑/图谱路由需要满高面板：面板默认高度由内容决定（auto），
+  // 高度链 h-full → flex-1 会逐级失效，导致 React Flow 等依赖 100% 高度的
+  // 画布类组件容器高度为 0（思维导图/自由画布/图谱不渲染）。
+  // 给这些路由的面板补 !h-full 让高度链恢复（max-h 仍生效）。
+  const isFullHeightRoute = /^\/notes\/[^/]+$/.test(pathname);
 
   // 监听 session 过期事件
   useSessionExpiry();
@@ -91,10 +134,21 @@ export default function AppLayout() {
       }
 
       if (e.key === 'Escape') {
-        if (isInModule) {
+        // 层级感知：子路由 -> 父路由，根路由 -> 退出模块
+        const currentPath = pathnameRef.current;
+        const parentRoute = findParentRoute(currentPath);
+
+        if (parentRoute) {
+          // 有父路由 -> 向上导航一级（不退出模块，保持模块 docked 态）
+          e.preventDefault();
+          navigate(parentRoute);
+        } else if (isInModule) {
+          // 已是模块根路由 -> 退出模块回到 3D 概览
+          e.preventDefault();
           exitModule();
-        } else {
-          // 在 3D 场景模式下按 Esc 返回仪表盘
+        } else if (currentPath !== '/') {
+          // 3D 场景模式下按 Esc 返回仪表盘（仅非首页时）
+          e.preventDefault();
           enterModule('dashboard');
           navigate('/');
         }
@@ -110,8 +164,10 @@ export default function AppLayout() {
         if (moduleKeys[e.key]) {
           const route = moduleKeys[e.key];
           // 显式调用 enterModule：同路由 navigate 无效时仍能触发相位迁移（修复 Esc 后重复按键无响应）
-          const mod = MODULE_POSITIONS.find(m => m.route === route);
-          if (mod) enterModule(mod.id);
+          // 使用 routeToModuleId 统一映射：对非 MODULE_POSITIONS 成员（如 /settings）
+          // 也能正确调用 enterModule，避免 navigate 同路由无变化时相位无法恢复
+          const modId = routeToModuleId(route);
+          if (modId) enterModule(modId);
           navigate(route);
         }
       }
@@ -151,18 +207,21 @@ export default function AppLayout() {
           /* 萤火海沟自带全屏暗物质场：透明面板让深海背景透出，遮罩用深海底色实现整屏无缝（其他模块保持毛玻璃） */
           panelClassName={currentModule === 'inspiration'
             ? '!bg-transparent !backdrop-blur-none !shadow-none !border-white/5'
-            : undefined}
+            : isFullHeightRoute
+              ? '!h-full'
+              : undefined}
           maskClassName={currentModule === 'inspiration' ? '!bg-[var(--kb-bg-primary)] !backdrop-blur-none' : undefined}
         >
           {/* 路由级过渡：grid 叠放 + 同期交叉淡入淡出。
               历史方案 mode="wait" 要求旧页退出回调交接后才挂载新页；在
               reduced-motion / StrictMode(dev) / HMR 等条件下交接会偶发丢失，
               新页永不挂载——即内测反馈"回到主页时主页不显示"的根因。
               交叉淡入淡出下新页立即挂载、旧页淡出后卸载，退出即使延迟也不阻塞内容展示 */}
-          <div className="grid">
+          <div className="grid h-full">
             <AnimatePresence>
               <motion.div
                 key={pathname}
+                className="h-full"
                 style={{ gridArea: '1 / 1' }}
                 /* 简单的 opacity 淡入淡出，不影响 3D 场景的相机飞行和停靠时序 */
                 initial={{ opacity: 0 }}

client/src/lib/3d/core/SceneProvider.tsx

@@ -44,7 +44,7 @@ interface SceneProviderProps {
  * 确保主题切换时雾色和背景色同步更新
  */
 function ThemeAwareEnvironment() {
-  const { scene } = useThree();
+  const { gl, scene, camera } = useThree();
   const theme = useSceneTheme();
 
   useEffect(() => {
@@ -55,7 +55,13 @@ function ThemeAwareEnvironment() {
       scene.fog = new THREE.FogExp2('#e8f4f8', 0.015);
       scene.background = new THREE.Color('#e8f4f8');
     }
-  }, [theme, scene]);
+    // docked 相位 frameloop='never' 下渲染循环已冻结，invalidate() 早退不触发
+    // 重绘——主题切换后 scene 对象虽已更新但画布仍显示旧帧（背景不立即生效）。
+    // 延迟到宏任务手动渲染一帧：确保同批 theme 消费者的 Three 属性更新全部
+    // 提交后再绘制，一次性开销不破坏冻结策略（内测反馈修复）。
+    const timer = setTimeout(() => gl.render(scene, camera), 0);
+    return () => clearTimeout(timer);
+  }, [theme, scene, camera, gl]);
 
   return null;
 }

client/src/lib/3d/navigation/OrbitalStore.ts

@@ -52,6 +52,20 @@ export const MODULE_POSITIONS: ModulePosition[] = [
   { id: 'classroom', position: [-2, -3, -2], route: '/classroom', label: '回声定位' },
 ];
 
+/**
+ * 路由 → 模块ID 映射
+ * 与 syncWithRoute 中的映射逻辑一致，供外部（如数字键处理器）使用
+ */
+export function routeToModuleId(pathname: string): ModuleId | null {
+  const module = MODULE_POSITIONS.find(m => {
+    if (m.route === '/') return pathname === '/';
+    return pathname === m.route || pathname.startsWith(m.route + '/');
+  });
+  return module
+    ? module.id
+    : (pathname === '/settings' || pathname === '/analytics') ? 'dashboard' : null;
+}
+
 /** 导航洪泛防护：enterModule 最小调用间隔。
  * Chromium 对客户端导航（pushState/hash）有洪泛保护（crbug.com/1038223），
  * 超阈后导航会被限流丢弃——此时轨道状态已迁移而路由未变，
@@ -97,14 +111,7 @@ export const useOrbitalStore = create<OrbitalState>((set, get) => ({
   setHighlightAll: (v) => set({ highlightAll: v }),
   syncWithRoute: (pathname: string) => {
     const s = get();
-    // 精确匹配或前缀匹配（支持子路由如 /flashcards/:deckId/study）
-    const module = MODULE_POSITIONS.find(m => {
-      if (m.route === '/') return pathname === '/';
-      return pathname === m.route || pathname.startsWith(m.route + '/');
-    });
-    const targetId: ModuleId | null = module
-      ? module.id
-      : (pathname === '/settings' || pathname === '/analytics') ? 'dashboard' : null;
+    const targetId = routeToModuleId(pathname);
 
     if (!targetId) {
       set({ currentModule: null, phase: 'overview', overlayVisible: false, isInModule: false });

client/src/lib/3d/scenes/SceneTransition.tsx

@@ -9,7 +9,7 @@
  * @ai-context: 3D 场景：SceneTransition。
  */
 import { useRef, useState, useEffect } from 'react';
-import { useFrame } from '@react-three/fiber';
+import { useFrame, useThree } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useSceneTheme } from '../hooks/useSceneTheme';
 import { DeepSeaWorld } from './DeepSeaWorld';
@@ -22,6 +22,7 @@ export interface SceneTransitionProps {
 const TRANSITION_DURATION = 0.5;
 
 export function SceneTransition({ children }: SceneTransitionProps) {
+  const { gl, scene, camera } = useThree();
   const theme = useSceneTheme();
   const isTransitioning = useRef(false);
   const transitionProgress = useRef(0);
@@ -55,10 +56,14 @@ export function SceneTransition({ children }: SceneTransitionProps) {
       if (auroraGroupRef.current) auroraGroupRef.current.visible = !isDeepSea;
       setDeepSeaVisible(isDeepSea);
       setAuroraVisible(!isDeepSea);
+      // docked 相位 frameloop='never' 下渲染循环冻结：可见性虽已切换但无帧
+      // 绘制，canvas 仍显示旧场景（内测反馈：主题切换背景不生效）。
+      // 手动渲染一帧让场景切换立即呈现，一次性开销不破坏冻结策略。
+      gl.render(scene, camera);
     }, TRANSITION_DURATION * 1000 + 100);
 
     return () => clearTimeout(timer);
-  }, [theme]);
+  }, [theme, gl, scene, camera]);
 
   useFrame((_, delta) => {
     if (!isTransitioning.current) return;