fix(3d): 相机飞行视角错位与渲染循环冻结修复

- flyTo 增加注视点参数，飞行期间朝向同步转向目标；此前只插值位置不改朝向，叠加 docked 渲染冻结导致停靠后视角错位、正对空白
- 相机飞行统一由相位迁移响应式驱动，覆盖 3D 点击/数字键/路由同步全部入口；点击入口记录行星实时坐标防公转漂移
- 新增 LoopResumer：frameloop 从 never 切回 always 时显式 invalidate 唤醒渲染循环，修复多次切换后画面永久冻结
- 停靠延迟下限 clamp 到 700ms（飞行 600ms），防静谧档飞行中途冻结相机停在半途
- exitModule 清除悬停态；isActive 结合相位判断，Esc 退出后不再残留选中视觉
- 附知识库 bug 复盘文档与索引更新

Author: Aparencia

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

@@ -11,12 +11,16 @@
  *   导致 GPU 合成风暴（内测反馈“主页流畅但切换其他页面卡顿”的根因）。
  *   暂停后画面冻结为静态背景，blur 仅计算一次即被合成器缓存，视觉设计不变。
  * - entering → docked 的停靠延迟由性能档位决定（静谧=0/从容=900ms/澎湃=1300ms），
- *   保证相机飞行到位后才暂停渲染，避免生硬冻结。
+ *   保证相机飞行到位后才暂停渲染，避免生硬冻结；下限 clamp 到 700ms（飞行时长
+ *   600ms），防止静谧档在飞行中途冻结导致相机停在半途、停靠视角错位。
  * - PerformanceMonitor 仅 overview 相位测量：entering 的飞行帧率不代表设备能力，docked 无帧率可言。
+ * - 帧循环唤醒：R3F 从 frameloop='never' 切回 'always' 时不会自动重启渲染循环
+ *   （循环停止后无帧可检查新值，且 setFrameloop 不调 invalidate），
+ *   需由 LoopResumer 在相位迁移后显式唤醒，否则多次切换后画面永久冻结。
  *
  * @ai-context: 3D 场景核心（R3F）：SceneProvider。
  */
-import { Canvas } from '@react-three/fiber';
+import { Canvas, useThree } from '@react-three/fiber';
 import { Suspense, useEffect } from 'react';
 import { Preload } from '@react-three/drei';
 import { PerformanceMonitor } from './PerformanceMonitor';
@@ -34,17 +38,41 @@ interface SceneProviderProps {
   interactive?: boolean;
 }
 
+/**
+ * 渲染循环唤醒器 — 修复“多次切换功能后页面无渲染”
+ *
+ * R3F 的循环在 frameloop='never' 下会 cancelAnimationFrame 彻底停止；
+ * 切回 'always' 时 setFrameloop 只改 store 值，不会重启循环，
+ * 而期间所有 invalidate() 又因 frameloop 尚为 'never' 被早退丢弃。
+ * 因此在相位/档位迁移后（此时 frameloop prop 已应用）显式 invalidate：
+ * 'always' 下 render 每帧返回 1，一次唤醒即可让循环永续运行；
+ * docked（'never'）时 invalidate 自动早退，无副作用。
+ */
+function LoopResumer() {
+  const invalidate = useThree((s) => s.invalidate);
+  const phase = useOrbitalStore((s) => s.phase);
+  const mode = usePerformanceModeStore((s) => s.mode);
+
+  useEffect(() => {
+    invalidate();
+  }, [phase, mode, invalidate]);
+
+  return null;
+}
+
 export function SceneProvider({ children, interactive = false }: SceneProviderProps) {
   const phase = useOrbitalStore((s) => s.phase);
   const currentModule = useOrbitalStore((s) => s.currentModule);
   const mode = usePerformanceModeStore((s) => s.mode);
 
-  // entering → docked 停靠计时器：相机飞行过渡结束后才暂停渲染（相位/模块/档位变化时重置）
+  // entering → docked 停靠计时器：相机飞行过渡结束后才暂停渲染（相位/模块/档位变化时重置）。
+  // 下限 clamp 到 700ms（相机飞行固定 600ms）：静谧档 dockDelayMs=0 会在飞行中途
+  // 冻结渲染（frameloop='never'），相机停在半途且朝向插值未完成，停靠后视角错位
   useEffect(() => {
     if (phase !== 'entering') return;
     const timer = setTimeout(
       () => useOrbitalStore.getState().dock(),
-      PERFORMANCE_MODE_CONFIG[mode].dockDelayMs,
+      Math.max(PERFORMANCE_MODE_CONFIG[mode].dockDelayMs, 700),
     );
     return () => clearTimeout(timer);
   }, [phase, currentModule, mode]);
@@ -82,6 +110,7 @@ export function SceneProvider({ children, interactive = false }: SceneProviderPr
       >
         {/* FPS 自动降档仅在概览态测量（entering 飞行帧率不代表设备能力，docked 无帧率可言） */}
         {phase === 'overview' && <PerformanceMonitor />}
+        <LoopResumer />
         <QualityController />
         <MemoryManager />
         <ContextRecovery />

client/src/lib/3d/hooks/useCameraFlight.test.ts

@@ -0,0 +1,99 @@
+/**
+ * useCameraFlight 单元测试
+ *
+ * 重点覆盖"飞行结束时相机朝向正对注视目标"——此前 flyTo 只插值 position
+ * 不改朝向，用户用 OrbitControls 旋转过视角后点击模块，相机抵达后仍保持
+ * 旧朝向，叠加 docked 渲染冻结导致停靠视角错位（正对空白处）。
+ *
+ * @ai-context: useCameraFlight hook tests: verifies position flight and
+ * quaternion slerp orientation toward lookTarget on arrival.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import * as THREE from 'three';
+
+// 通过 hoisted 持有可变相机实例，供 vi.mock 工厂（被提升）引用
+const { cameraHolder } = vi.hoisted(() => ({
+  cameraHolder: { camera: null as unknown as THREE.PerspectiveCamera },
+}));
+
+vi.mock('@react-three/fiber', () => ({
+  useThree: () => ({ camera: cameraHolder.camera }),
+}));
+
+import { useCameraFlight } from './useCameraFlight';
+
+beforeEach(() => {
+  const cam = new THREE.PerspectiveCamera();
+  cam.position.set(0, 0, 10);
+  cam.lookAt(0, 0, 0);
+  cam.updateMatrixWorld();
+  cameraHolder.camera = cam;
+});
+
+/** 相机世界前向（-Z 轴经四元数旋转） */
+function cameraForward(cam: THREE.PerspectiveCamera): THREE.Vector3 {
+  return new THREE.Vector3(0, 0, -1).applyQuaternion(cam.quaternion);
+}
+
+describe('useCameraFlight', () => {
+  it('指定注视点时，飞行结束时位置到位且朝向正对目标', () => {
+    const cam = cameraHolder.camera;
+    // 模拟用户已用 OrbitControls 旋转视角：朝向偏离 -Z（旧实现会带着该朝向抵达）
+    cam.rotateY(Math.PI / 2);
+
+    const { result } = renderHook(() => useCameraFlight());
+    // 模块 [4,2,-2] + CAMERA_OFFSET [0,0,4] = [4,2,2]，注视模块本体
+    act(() => { result.current.flyTo([4, 2, 2], [4, 2, -2]); });
+    act(() => { for (let i = 0; i < 10; i++) result.current.update(0.1); });
+
+    expect(cam.position.x).toBeCloseTo(4, 3);
+    expect(cam.position.y).toBeCloseTo(2, 3);
+    expect(cam.position.z).toBeCloseTo(2, 3);
+
+    const fwd = cameraForward(cam);
+    const toTarget = new THREE.Vector3(4, 2, -2).sub(cam.position).normalize();
+    expect(fwd.dot(toTarget)).toBeGreaterThan(0.999);
+  });
+
+  it('飞行中途朝向持续转向目标（非抵达瞬间突变）', () => {
+    const cam = cameraHolder.camera;
+    cam.rotateY(Math.PI / 2);
+
+    const { result } = renderHook(() => useCameraFlight());
+    act(() => { result.current.flyTo([4, 2, 2], [4, 2, -2]); });
+    // 推进约一半时长（0.3s）
+    act(() => { for (let i = 0; i < 3; i++) result.current.update(0.1); });
+
+    const fwd = cameraForward(cam);
+    const toTarget = new THREE.Vector3(4, 2, -2).sub(cam.position).normalize();
+    const dot = fwd.dot(toTarget);
+    // 中途应已明显转向（起点朝向与目标接近垂直，dot≈0）；ease-out cubic
+    // 前半程进度较快，不锁死上界，仅要求未完全到位
+    expect(dot).toBeGreaterThan(0.5);
+    expect(dot).toBeLessThan(0.9999);
+  });
+
+  it('未指定注视点时保持原行为：只动位置不改朝向', () => {
+    const cam = cameraHolder.camera;
+    cam.rotateY(Math.PI / 2);
+    const before = cam.quaternion.clone();
+
+    const { result } = renderHook(() => useCameraFlight());
+    act(() => { result.current.flyTo([0, 0, 10]); });
+    act(() => { for (let i = 0; i < 10; i++) result.current.update(0.1); });
+
+    expect(cam.quaternion.equals(before)).toBe(true);
+  });
+
+  it('自定义时长生效（duration 参数不再被忽略）', () => {
+    const cam = cameraHolder.camera;
+    const { result } = renderHook(() => useCameraFlight());
+    act(() => { result.current.flyTo([0, 0, 5], undefined, 1.0); });
+    // 推进 0.6s：若旧实现硬编码 0.6 则已抵达 z=5，新实现（时长 1.0）应仍在半途
+    // （ease-out cubic 在 t=0.6 时进度约 93.6%，z≈5.32，仍严格大于 5）
+    act(() => { for (let i = 0; i < 6; i++) result.current.update(0.1); });
+    expect(cam.position.z).toBeGreaterThan(5.05);
+    expect(cam.position.z).toBeLessThan(10);
+  });
+});

client/src/lib/3d/hooks/useCameraFlight.ts

@@ -1,6 +1,12 @@
 /**
  * 相机飞行动画hook — 用于模块间导航
  *
+ * 位置与朝向同步插值：flyTo 可指定注视点 lookTarget，飞行期间相机朝向
+ * 从起始四元数 slerp 到"终点位置注视 lookTarget"的四元数。此前只动 position
+ * 不动朝向，相机抵达后仍保持概览态旧朝向（尤其用户用 OrbitControls 旋转过
+ * 视角时），叠加 docked 相位 frameloop='never' 无法由 CameraController 纠正，
+ * 导致停靠后视角错位、正对空白处。
+ *
  * @ai-context: 3D 相机飞行动画 Hook，模块间导航的视觉过渡。
  */
 import { useThree } from '@react-three/fiber';
@@ -12,19 +18,47 @@ export function useCameraFlight() {
   const isFlying = useRef(false);
   const startPos = useRef(new THREE.Vector3());
   const endPos = useRef(new THREE.Vector3());
+  const startQuat = useRef(new THREE.Quaternion());
+  const endQuat = useRef(new THREE.Quaternion());
+  const hasLook = useRef(false);
+  const duration = useRef(0.6);
   const progress = useRef(0);
+  // 复用的临时对象，避免每帧/每次飞行分配
+  const lookMat = useRef(new THREE.Matrix4());
+  const lookVec = useRef(new THREE.Vector3());
 
-  const flyTo = useCallback((target: [number, number, number], duration = 0.6) => {
+  /**
+   * 启动一次相机飞行
+   * @param target - 终点位置
+   * @param lookTarget - 可选注视点：飞行期间朝向平滑转向该点；省略则保持原行为（不改朝向）
+   * @param flightDuration - 飞行时长（秒），默认 0.6
+   */
+  const flyTo = useCallback((
+    target: [number, number, number],
+    lookTarget?: [number, number, number],
+    flightDuration = 0.6,
+  ) => {
     startPos.current.copy(camera.position);
     endPos.current.set(...target);
+    duration.current = flightDuration;
     progress.current = 0;
     isFlying.current = true;
+    if (lookTarget) {
+      startQuat.current.copy(camera.quaternion);
+      lookVec.current.set(...lookTarget);
+      // 与 Camera.lookAt 同一算法（Matrix4.lookAt(eye, target, up)）计算终点朝向
+      lookMat.current.lookAt(endPos.current, lookVec.current, camera.up);
+      endQuat.current.setFromRotationMatrix(lookMat.current);
+      hasLook.current = true;
+    } else {
+      hasLook.current = false;
+    }
   }, [camera]);
 
   const update = useCallback((delta: number) => {
     if (!isFlying.current) return;
 
-    progress.current += delta / 0.6;
+    progress.current += delta / duration.current;
     if (progress.current >= 1) {
       progress.current = 1;
       isFlying.current = false;
@@ -33,6 +67,10 @@ export function useCameraFlight() {
     // Ease out cubic
     const t = 1 - Math.pow(1 - progress.current, 3);
     camera.position.lerpVectors(startPos.current, endPos.current, t);
+    // 朝向与位置按同一缓动同步插值，确保抵达时正对目标
+    if (hasLook.current) {
+      camera.quaternion.slerpQuaternions(startQuat.current, endQuat.current, t);
+    }
   }, [camera]);
 
   return { flyTo, update, isFlying: isFlying.current };

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

@@ -73,8 +73,9 @@ export const useOrbitalStore = create<OrbitalState>((set, get) => ({
     });
   },
   exitModule: () => {
-    // 保留 currentModule：覆盖层保持挂载（不可见），页面状态存活，重入时不重播动画
-    set({ phase: 'overview', overlayVisible: false, isInModule: false });
+    // 保留 currentModule：覆盖层保持挂载（不可见），页面状态存活，重入时不重播动画；
+    // 清除悬停态：退出后实体不应残留悬停视觉（覆盖层显示期间指针事件已关闭，hovered 可能滞留）
+    set({ phase: 'overview', overlayVisible: false, isInModule: false, hoveredModule: null });
   },
   dock: () => {
     if (get().phase === 'entering') {

client/src/lib/3d/navigation/SpatialNav.tsx

@@ -7,9 +7,12 @@
  * - entering 模式：useCameraFlight 独占相机，CameraController 暂停
  * - docked 模式：CameraController 接管（渲染已暂停，实际不执行 lerp）
  *
+ * 相机飞行统一由相位迁移响应式驱动（覆盖 3D 点击/数字键/路由同步等全部入口）；
+ * 点击入口额外记录行星实时坐标供飞行使用（行星在公转，固定坐标会飞向错误位置）。
+ *
  * @ai-context: 3D 空间导航组件——键盘/手势驱动的模块间轨道跳转，与 OrbitalStore 状态联动；渲染于 R3F Canvas 内，禁止使用 DOM API。
  */
-import { useCallback } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useFrame } from '@react-three/fiber';
 import { OrbitControls } from '@react-three/drei';
@@ -60,6 +63,9 @@ const AURORA_ORBIT_CONFIG: Record<ModuleId, {
 /** 相机飞入模块时的偏移（从模块位置向相机方向偏移） */
 const CAMERA_OFFSET: [number, number, number] = [0, 0, 4];
 
+/** 概览态相机全景位（退出模块时相机飞回此位置） */
+const OVERVIEW_CAMERA_POS: [number, number, number] = [0, 0, 10];
+
 function addVectors(a: [number, number, number], b: [number, number, number]): [number, number, number] {
   return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
 }
@@ -71,46 +77,76 @@ export function SpatialNav() {
   const { flyTo, update } = useCameraFlight();
   const { shouldDegrade3D } = useRuntimeEnv();
 
+  // 点击入口记录的行星实时世界坐标（飞行 effect 优先消费），点击后才有效
+  const clickFlightPosRef = useRef<Partial<Record<ModuleId, [number, number, number]>>>({});
+  // 上一次已处理的飞行键（entering:模块 / overview / docked），防止重复飞行
+  const flightKeyRef = useRef<string | null>(null);
+
   // 每帧更新相机飞行
   useFrame((_, delta) => {
     // 防止浏览器节流导致的帧时间尖峰
     const safeDelta = Math.min(delta, 0.1);
     update(safeDelta);
   });
 
-  // 点击模块实体（深海模式使用固定坐标）
+  // 响应式相机飞行：统一覆盖全部入口（3D 点击/数字键/返回首页/路由同步）。
+  // 此前 flyTo 仅在点击回调中命令式调用，数字键等入口进入时无镜头移动；
+  // 退出（Esc）时相机也需从模块停靠位飞回全景位。
+  useEffect(() => {
+    const flightKey = phase === 'entering' ? `entering:${currentModule}` : phase;
+    if (flightKeyRef.current === flightKey) return;
+    const prevKey = flightKeyRef.current;
+    flightKeyRef.current = flightKey;
+
+    if (phase === 'entering' && currentModule) {
+      const module = MODULE_POSITIONS.find((m) => m.id === currentModule);
+      if (!module) return;
+      // 优先使用点击时记录的实时坐标，fallback 到固定坐标
+      const basePos = clickFlightPosRef.current[currentModule] ?? module.position;
+      delete clickFlightPosRef.current[currentModule];
+      // 注视点传入模块实时坐标：飞行期间朝向同步转向模块，
+      // 否则相机抵达后仍保持概览态旧朝向，叠加 docked 渲染冻结导致视角错位
+      flyTo(addVectors(basePos, CAMERA_OFFSET), basePos);
+    } else if (phase === 'overview' && prevKey && prevKey !== 'overview') {
+      // 退出模块：返回全景位并转向场景中心（初始挂载即 overview 时 prevKey 为 null，不飞行）
+      flyTo(OVERVIEW_CAMERA_POS, [0, 0, 0]);
+    }
+  }, [phase, currentModule, flyTo]);
+
+  // 点击模块实体：飞行由相位迁移 effect 统一触发（深海模式使用固定坐标）
   const handleModuleClick = useCallback((id: ModuleId) => {
     const module = MODULE_POSITIONS.find(m => m.id === id);
     if (!module) return;
 
     soundPlayer.play('ui_module_enter');
     enterModule(id);
-    // 相机飞向模块位置（加偏移）
-    flyTo(addVectors(module.position, CAMERA_OFFSET));
     navigate(module.route);
-  }, [enterModule, flyTo, navigate]);
+  }, [enterModule, navigate]);
 
-  // 点击 Aurora 模式行星：使用行星实时世界坐标作为 flyTo 目标，而非 MODULE_POSITIONS 固定坐标
+  // 点击 Aurora 模式行星：记录实时世界坐标供飞行 effect 消费，而非使用 MODULE_POSITIONS 固定坐标
   // 因为行星在轨道上持续公转，固定坐标会导致相机飞向错误位置（漂移根因之一）
   const handleAuroraClick = useCallback((id: ModuleId, currentPosition?: [number, number, number]) => {
     const module = MODULE_POSITIONS.find(m => m.id === id);
     if (!module) return;
 
     soundPlayer.play('ui_module_enter');
+    // enterModule 在"同模块已停靠且覆盖层可见"时为无操作（不产生飞行），此时不记录，避免陈旧坐标被后续进入误用
+    const s = useOrbitalStore.getState();
+    const willNoop = s.currentModule === id && s.phase === 'docked' && s.overlayVisible;
+    if (!willNoop && currentPosition) {
+      clickFlightPosRef.current[id] = currentPosition;
+    }
     enterModule(id);
-    // 优先使用行星当前实时世界坐标，fallback 到固定坐标
-    const basePos = currentPosition ?? module.position;
-    flyTo(addVectors(basePos, CAMERA_OFFSET));
     navigate(module.route);
-  }, [enterModule, flyTo, navigate]);
+  }, [enterModule, navigate]);
 
   // 悬停音效（移动端降级时不播放，仅在指针事件回调中触发）
   const handleHover = useCallback((id: ModuleId | null) => {
     if (id && !shouldDegrade3D) soundPlayer.play('ui_hover_3d', { throttleMs: 200 });
     setHovered(id);
   }, [setHovered, shouldDegrade3D]);
 
-  // 计算相机目标位置与注视点：非概览相位（entering/docked）时飞向并注视当前模块，否则全景位/场景中心
+  // 计算相机目标位置与注视点：非概览相位（entering/docked）时注视当前模块，否则全景位/场景中心
   const inModuleView = phase !== 'overview' && currentModule;
   const activeModulePos = inModuleView
     ? MODULE_POSITIONS.find(m => m.id === currentModule)?.position
@@ -165,7 +201,8 @@ export function SpatialNav() {
               color={config.color}
               emissiveColor={config.emissiveColor}
               isHovered={hoveredModule === module.id || highlightAll}
-              isActive={currentModule === module.id}
+              // 选中态需结合相位：Esc 退出后 currentModule 保留（页面状态存活），但视觉选中必须解除
+              isActive={phase !== 'overview' && currentModule === module.id}
               showLabel={highlightAll || !overlayVisible}
               onClick={() => handleModuleClick(module.id)}
               onPointerOver={() => handleHover(module.id)}
@@ -211,7 +248,9 @@ export function SpatialNav() {
             orbitRadius={config.orbitRadius}
             orbitSpeed={config.orbitSpeed}
             initialAngle={config.initialAngle}
-            isActive={currentModule === module.id}
+            // 选中态需结合相位：Esc 退出后 currentModule 保留（页面状态存活），
+            // 若不解除，行星将持续保持放大/光环/停止公转的"选中"表现
+            isActive={phase !== 'overview' && currentModule === module.id}
             showLabel={highlightAll || !overlayVisible}
             onClick={handleAuroraClick}
             onHover={handleHover}