Merge branch 'dev': 3D 导航修复与性能优化

合并 3D 三层根因修复（重复行星/标签可发现性/canvas 点击拦截）与性能分级优化（drei PerformanceMonitor 迁移、tier 滞回）。

Author: Aparencia

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

@@ -1,52 +1,17 @@
 /**
- * 内存管理器 — Electron窗口失焦时暂停渲染，防止内存泄漏
+ * 内存管理器 — 定期报告 GPU 内存占用
+ *
+ * 说明：窗口最小化/隐藏时浏览器会自动节流 rAF（渲染自然暂停），
+ * 无需在此手动跳帧。原“每 4 帧跳 3 帧”的实现（在 useFrame 内 return）
+ * 并不能阻止 R3F 渲染当前帧，属无效死代码，已移除。
  *
  * @ai-context: 3D 场景核心（R3F）：MemoryManager。
  */
-import { useThree, useFrame } from '@react-three/fiber';
-import { useEffect, useRef } from 'react';
+import { useThree } from '@react-three/fiber';
+import { useEffect } from 'react';
 
 export function MemoryManager() {
   const { gl } = useThree();
-  const isVisible = useRef(true);
-  const frameSkip = useRef(0);
-
-  // 监听窗口可见性
-  useEffect(() => {
-    const handleVisibility = () => {
-      isVisible.current = document.visibilityState === 'visible';
-    };
-
-    const handleBlur = () => {
-      isVisible.current = false;
-    };
-
-    const handleFocus = () => {
-      isVisible.current = true;
-    };
-
-    document.addEventListener('visibilitychange', handleVisibility);
-    window.addEventListener('blur', handleBlur);
-    window.addEventListener('focus', handleFocus);
-
-    return () => {
-      document.removeEventListener('visibilitychange', handleVisibility);
-      window.removeEventListener('blur', handleBlur);
-      window.removeEventListener('focus', handleFocus);
-    };
-  }, []);
-
-  // 窗口不可见时跳过渲染帧（每4帧渲染1帧，节省GPU）
-  useFrame(() => {
-    if (!isVisible.current) {
-      frameSkip.current++;
-      if (frameSkip.current % 4 !== 0) {
-        return; // 跳过此帧
-      }
-    } else {
-      frameSkip.current = 0;
-    }
-  });
 
   // 定期报告内存使用
   useEffect(() => {

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

@@ -1,13 +1,28 @@
 /**
- * 性能监控 — FPS追踪与动态降级
+ * 性能监控 — FPS追踪与动态降级（基于 drei 成熟方案）
+ *
+ * 重构说明（docs/standards/refactoring.md，外部行为不变）：
+ * - FPS 测量与防抖委托给 drei <PerformanceMonitor>（工业级实现）：
+ *   内置滑动均值（iterations×ms 采样）、bounds 滞回、threshold 比例持续判定
+ *   与 flip-flop 保护，替代原自研单窗口测量 + 手写滞回/持续逻辑；
+ * - tier 迁移策略抽取至纯函数模块 tierPolicy（已单测）；
+ * - 本组件仅做装配：把 drei 回调映射为 tier 逐级迁移，并在窗口隐藏时
+ *   卸载监控以重置测量基线（后台 rAF 节流期 FPS 不可信，卸载重挂即自然
+ *   清零，避免回到前台被误判降级）。
  *
  * @ai-context: 3D 场景核心（R3F）：PerformanceMonitor。
  */
-import { useFrame } from '@react-three/fiber';
-import { useRef } from 'react';
+import { useEffect, useState } from 'react';
+import { PerformanceMonitor as DreiPerformanceMonitor } from '@react-three/drei';
 import { create } from 'zustand';
+import { stepTier, type PerformanceTier } from './tierPolicy';
 
-type PerformanceTier = 'high' | 'medium' | 'low';
+/** FPS 下界：持续低于此值触发降级（滞回缓冲区下限） */
+export const FPS_LOWER_BOUND = 25;
+/** FPS 上界：持续高于此值触发升级（滞回缓冲区上限） */
+export const FPS_UPPER_BOUND = 50;
+/** 升降震荡（flip-flop）允许次数上限，超过则回落稳定档 */
+const MAX_FLIPFLOPS = 4;
 
 interface PerformanceState {
   tier: PerformanceTier;
@@ -24,27 +39,38 @@ export const usePerformanceStore = create<PerformanceState>((set) => ({
 }));
 
 export function PerformanceMonitor() {
-  const frameCount = useRef(0);
-  const lastTime = useRef(performance.now());
-  const { setTier, setFps } = usePerformanceStore();
-
-  useFrame(() => {
-    frameCount.current++;
-    const now = performance.now();
-    const elapsed = now - lastTime.current;
-
-    if (elapsed >= 2000) {
-      const fps = Math.round(frameCount.current * (1000 / elapsed));
-      setFps(fps);
-
-      if (fps < 25) setTier('low');
-      else if (fps < 45) setTier('medium');
-      else setTier('high');
+  // 窗口隐藏时卸载监控：后台期间浏览器节流 rAF，FPS 读数不可信；
+  // 返回前台重挂即自然重置采样基线，避免误判降级。
+  // 附带收益：同时重置 drei 内部 flipped/fallback 计数，防止 fallback 永久锁定。
+  const [visible, setVisible] = useState(() => document.visibilityState === 'visible');
+  useEffect(() => {
+    const onVisibility = () => setVisible(document.visibilityState === 'visible');
+    document.addEventListener('visibilitychange', onVisibility);
+    return () => document.removeEventListener('visibilitychange', onVisibility);
+  }, []);
 
-      frameCount.current = 0;
-      lastTime.current = now;
-    }
-  });
+  if (!visible) return null;
 
-  return null;
+  return (
+    <DreiPerformanceMonitor
+      bounds={() => [FPS_LOWER_BOUND, FPS_UPPER_BOUND]}
+      flipflops={MAX_FLIPFLOPS}
+      onIncline={(api) => {
+        // 持续高 FPS（75%+ 样本 ≥ 上界）→ 逐级升档
+        const { tier, setTier, setFps } = usePerformanceStore.getState();
+        setFps(Math.round(api.fps));
+        setTier(stepTier(tier, 'up'));
+      }}
+      onDecline={(api) => {
+        // 持续低 FPS（75%+ 样本 < 下界）→ 逐级降档
+        const { tier, setTier, setFps } = usePerformanceStore.getState();
+        setFps(Math.round(api.fps));
+        setTier(stepTier(tier, 'down'));
+      }}
+      onFallback={() => {
+        // 震荡超限 → 稳定在中档：保留后处理特效、适度降低 DPR
+        usePerformanceStore.getState().setTier('medium');
+      }}
+    />
+  );
 }

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

@@ -1,6 +1,8 @@
 /**
  * 3D场景全局提供器 — React Three Fiber Canvas容器
- * 作为全屏背景层，z-index: -1
+ * 作为全屏背景层：z-0 使其位于根布局 div（z-auto）之上、可接收点击，
+ * 但仍低于所有 UI 浮层（标题栏 z-50 / FunctionalOverlay z-10 / 引导 z-40+）。
+ * 注意：不能用负 z-index，否则会落到根 div 之后被其透明盒拦截点击。
  *
  * @ai-context: 3D 场景核心（R3F）：SceneProvider。
  */
@@ -21,7 +23,7 @@ interface SceneProviderProps {
 
 export function SceneProvider({ children, interactive = false }: SceneProviderProps) {
   return (
-    <div className="fixed inset-0 -z-10" style={{ pointerEvents: interactive ? 'auto' : 'none' }}>
+    <div className="fixed inset-0 z-0" style={{ pointerEvents: interactive ? 'auto' : 'none' }}>
       <Canvas
         gl={{
           antialias: true,

client/src/lib/3d/core/tierPolicy.test.ts

@@ -0,0 +1,56 @@
+/**
+ * tierPolicy 单元测试 — BDD 风格、AAA 模式
+ *
+ * @ai-context: 覆盖 stepTier 的全部迁移路径与边界保持，
+ * 是 PerformanceMonitor 重构（自研监控 → drei 成熟方案）的行为护栏。
+ */
+import { describe, it, expect } from 'vitest';
+import { stepTier } from './tierPolicy';
+
+describe('stepTier（逐级迁移策略）', () => {
+  describe('升级（up）', () => {
+    it('low 应升级为 medium', () => {
+      // Arrange & Act
+      const result = stepTier('low', 'up');
+      // Assert
+      expect(result).toBe('medium');
+    });
+
+    it('medium 应升级为 high', () => {
+      const result = stepTier('medium', 'up');
+      expect(result).toBe('high');
+    });
+
+    it('high 已达上限，应保持不变', () => {
+      const result = stepTier('high', 'up');
+      expect(result).toBe('high');
+    });
+  });
+
+  describe('降级（down）', () => {
+    it('high 应降级为 medium', () => {
+      const result = stepTier('high', 'down');
+      expect(result).toBe('medium');
+    });
+
+    it('medium 应降级为 low', () => {
+      const result = stepTier('medium', 'down');
+      expect(result).toBe('low');
+    });
+
+    it('low 已达下限，应保持不变', () => {
+      const result = stepTier('low', 'down');
+      expect(result).toBe('low');
+    });
+  });
+
+  describe('逐级性（禁止跨级跳变）', () => {
+    it('升级时 low 不得直接跳到 high', () => {
+      expect(stepTier('low', 'up')).not.toBe('high');
+    });
+
+    it('降级时 high 不得直接跳到 low', () => {
+      expect(stepTier('high', 'down')).not.toBe('low');
+    });
+  });
+});

client/src/lib/3d/core/tierPolicy.ts

@@ -0,0 +1,34 @@
+/**
+ * tierPolicy — 性能分级（tier）逐级迁移策略（纯函数）
+ *
+ * 从 PerformanceMonitor 中抽取：将"tier 如何迁移"（纯逻辑）与"如何测量 FPS"
+ * （R3F 副作用）物理分离，遵循 AI 编程规范 §1（副作用隔离）与 §6（自底向上：
+ * 先原子纯函数层并附单测，再由系统层装配）。
+ *
+ * @ai-context: 纯函数模块，无副作用，可独立单测与安全重构。
+ * @ai-context: tier 三级抽象（high/medium/low）被 AuroraDomeWorld / DeepSeaWorld /
+ * ParticleSystem / QualityController 四处消费，改变其语义影响面大，需同步评估。
+ */
+
+/** 性能分级：high=全画质，medium=降分辨率，low=关闭后处理特效 */
+export type PerformanceTier = 'high' | 'medium' | 'low';
+
+/** tier 调整方向：up=升级，down=降级 */
+export type TierTrend = 'up' | 'down';
+
+/**
+ * 逐级调整 tier（一次只迁移一级，不跨级跳变）。
+ *
+ * 为什么逐级：悬崖式变更（high→low）会立即卸载后处理与云层，
+ * 造成"动画特效突然消失"的强烈视觉波动；逐级迁移使画质降级/恢复平滑。
+ *
+ * @param current - 当前 tier
+ * @param trend - 调整方向
+ * @returns 调整后的 tier；已处于边界时保持不变（low 不再降、high 不再升）
+ */
+export function stepTier(current: PerformanceTier, trend: TierTrend): PerformanceTier {
+  if (trend === 'up') {
+    return current === 'low' ? 'medium' : 'high';
+  }
+  return current === 'high' ? 'medium' : 'low';
+}

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

@@ -115,7 +115,7 @@ export function SpatialNav() {
               emissiveColor={config.emissiveColor}
               isHovered={hoveredModule === module.id || highlightAll}
               isActive={currentModule === module.id}
-              showLabel={highlightAll}
+              showLabel={highlightAll || !isInModule}
               onClick={() => handleModuleClick(module.id)}
               onPointerOver={() => handleHover(module.id)}
               onPointerOut={() => handleHover(null)}
@@ -143,7 +143,7 @@ export function SpatialNav() {
             orbitSpeed={config.orbitSpeed}
             initialAngle={config.initialAngle}
             isActive={currentModule === module.id}
-            showLabel={highlightAll}
+            showLabel={highlightAll || !isInModule}
             onClick={handleModuleClick}
             onHover={handleHover}
           />

client/src/lib/3d/objects/AuroraModuleEntity.tsx

@@ -9,7 +9,6 @@ import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
 import { Float, Html } from '@react-three/drei';
 import type { ModuleId } from '../navigation/OrbitalStore';
-import { useIsNewbiePhase } from '@/features/onboarding/firstDive/useFirstDiveStore';
 import { getModuleSubtitle } from '@/features/onboarding/firstDive/moduleSubtitles';
 
 export interface AuroraModuleEntityProps {
@@ -55,8 +54,7 @@ export function AuroraModuleEntity({
   const ringRef = useRef<THREE.Mesh>(null);
   const [hovered, setHovered] = useState(false);
   const angleRef = useRef(initialAngle);
-  // 新手期双标签（首潜完成后自动隐去）
-  const isNewbie = useIsNewbiePhase();
+  // 功能副标题：隐喻名（深潜/结礁…）无法自解释，常驻直白功能名确保用户能把行星对应到功能
   const subtitle = getModuleSubtitle(id);
 
   const config = PLANET_CONFIGS[id];
@@ -173,8 +171,8 @@ export function AuroraModuleEntity({
             >
               <div className="rounded-lg bg-slate-900/80 px-3 py-1.5 text-sm font-medium text-white backdrop-blur-sm whitespace-nowrap border border-indigo-500/30">
                 {config.label}
-                {/* 新手期双标签：隐喻名旁附直白副标题 */}
-                {isNewbie && subtitle && (
+                {/* 常驻功能副标题：隐喻名旁附直白功能名 */}
+                {subtitle && (
                   <span className="ml-1.5 text-xs text-white/50">· {subtitle}</span>
                 )}
               </div>

client/src/lib/3d/objects/ModuleEntity.tsx

@@ -8,7 +8,6 @@ import { useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
 import { Float, Html } from '@react-three/drei';
-import { useIsNewbiePhase } from '@/features/onboarding/firstDive/useFirstDiveStore';
 import { getModuleSubtitle } from '@/features/onboarding/firstDive/moduleSubtitles';
 
 type GeometryType = 'dodecahedron' | 'torus' | 'box' | 'sphere' | 'octahedron' | 'icosahedron';
@@ -82,8 +81,7 @@ export function ModuleEntity({
 }: ModuleEntityProps) {
   const meshRef = useRef<THREE.Mesh>(null);
   const materialRef = useRef<THREE.MeshStandardMaterial>(null);
-  // 新手期双标签（首潜完成后自动隐去）
-  const isNewbie = useIsNewbiePhase();
+  // 功能副标题：隐喻名（深潜/结礁…）无法自解释，常驻直白功能名确保用户能把几何体对应到功能
   const subtitle = getModuleSubtitle(id);
 
   // Each entity has a unique rotation axis and speed
@@ -160,8 +158,8 @@ export function ModuleEntity({
           >
             <div className="rounded-lg bg-slate-900/80 px-3 py-1.5 text-sm font-medium text-white backdrop-blur-sm whitespace-nowrap border border-indigo-500/30">
               {label}
-              {/* 新手期双标签：隐喻名旁附直白副标题 */}
-              {isNewbie && subtitle && (
+              {/* 常驻功能副标题：隐喻名旁附直白功能名 */}
+              {subtitle && (
                 <span className="ml-1.5 text-xs text-white/50">· {subtitle}</span>
               )}
             </div>