feat(onboarding): First Dive 新手引导系统与新手期双标签导航

新增新手引导流程（onboarding feature + OnboardingOverlay），并调整
侧边栏/布局与 3D 导航实体以适配新手期双标签导航策略。

Author: Aparencia

client/src/components/layout/AppLayout.tsx

@@ -23,6 +23,7 @@ import { HelpCenter } from '@/components/onboarding/HelpCenter';
 import { useOnboardingStore } from '@/components/onboarding/useOnboardingStore';
 import { useRuntimeEnv } from '@/lib/env/useRuntimeEnv';
 import { PWAInstallPrompt } from '@/components/PWAInstallPrompt';
+import { FirstDiveGate } from '@/features/onboarding/firstDive/FirstDiveGate';
 
 export default function AppLayout() {
   const { pathname } = useLocation();
@@ -164,6 +165,7 @@ export default function AppLayout() {
       <BottomNav />
 
       {/* 全局组件 */}
+      <FirstDiveGate />
       <OnboardingOverlay />
       <ModuleTourToast moduleId={currentModule} />
       <HelpCenter />

client/src/components/layout/Sidebar.tsx

@@ -16,24 +16,26 @@ import { useAuth } from '@/lib/auth/AuthContext';
 import { useTheme } from '@/hooks/useTheme';
 import { SPRING, BEAT } from '@/lib/animation/springConfig';
 import { soundPlayer } from '@/lib/audio/SoundPlayer';
+import { useIsNewbiePhase } from '@/features/onboarding/firstDive/useFirstDiveStore';
 import FeedbackPanel from './FeedbackPanel';
 
 /* ── 导航配置 ── */
+// subtitle：新手期双标签副标题（隐喻名无法自解释，首潜完成前附直白说明）
 const navSection1 = [
   { to: '/', label: '首页', icon: Home, shortcut: '⌘ 1', exact: true },
 ];
 
 const navSection2 = [
-  { to: '/pomodoro', label: '深潜', icon: Timer, shortcut: '⌘ 2', dotColor: 'bg-brand-500' },
-  { to: '/notes', label: '结礁', icon: FileText, shortcut: '⌘ 3', dotColor: 'bg-note' },
-  { to: '/flashcards', label: '反衰减呼吸', icon: Layers, shortcut: '⌘ 4', dotColor: 'bg-flashcard' },
-  { to: '/feynman', label: '浮出水面', icon: Lightbulb, shortcut: '⌘ 5', dotColor: 'bg-feynman' },
+  { to: '/pomodoro', label: '深潜', subtitle: '专注番茄钟', icon: Timer, shortcut: '⌘ 2', dotColor: 'bg-brand-500' },
+  { to: '/notes', label: '结礁', subtitle: '学习笔记', icon: FileText, shortcut: '⌘ 3', dotColor: 'bg-note' },
+  { to: '/flashcards', label: '反衰减呼吸', subtitle: '记忆闪卡', icon: Layers, shortcut: '⌘ 4', dotColor: 'bg-flashcard' },
+  { to: '/feynman', label: '浮出水面', subtitle: '费曼讲解', icon: Lightbulb, shortcut: '⌘ 5', dotColor: 'bg-feynman' },
 ];
 
 const navSection3 = [
   { to: '/analytics', label: '数据分析', icon: BarChart3, shortcut: '⌘ 6' },
-  { to: '/inspiration', label: '萤火海沟', icon: Sparkles, shortcut: '⌘ 6' },
-  { to: '/classroom', label: '回声定位', icon: Clapperboard, shortcut: '⌘ 7', dotColor: 'bg-classroom' },
+  { to: '/inspiration', label: '萤火海沟', subtitle: '灵感收集', icon: Sparkles, shortcut: '⌘ 6' },
+  { to: '/classroom', label: '回声定位', subtitle: '课堂采集', icon: Clapperboard, shortcut: '⌘ 7', dotColor: 'bg-classroom' },
 ];
 
 /* ── 蔡格尼克效应：待继续任务提示池 ── */
@@ -73,6 +75,8 @@ export default function Sidebar() {
   const setCaptureOpen = useCaptureStore((s) => s.setOpen);
   const { user, isAuthenticated } = useAuth();
   const { theme, toggleTheme } = useTheme();
+  // 新手期显示模块副标题（首潜完成后自动隐去）
+  const isNewbie = useIsNewbiePhase();
 
   // TODO: 接入真实学习进度数据
   const _progressItems: { subject: string; progress: number }[] = [];
@@ -194,9 +198,10 @@ export default function Sidebar() {
             </motion.div>
           )}
           {collapsed && <div className="my-1 mx-1.5 border-t border-border/20" />}
-          {navSection2.map(({ to, label, icon: Icon, shortcut, dotColor }, i) => (
+          {navSection2.map(({ to, label, subtitle, icon: Icon, shortcut, dotColor }, i) => (
             <SidebarItem
               key={to} to={to} label={label} icon={Icon}
+              subtitle={isNewbie ? subtitle : undefined}
               shortcut={collapsed ? undefined : shortcut}
               dotColor={dotColor} collapsed={collapsed} index={i + 1}
             />
@@ -209,9 +214,10 @@ export default function Sidebar() {
             </div>
           )}
           {collapsed && <div className="my-1 mx-1.5 border-t border-border/20" />}
-          {navSection3.map(({ to, label, icon: Icon, shortcut, dotColor }, i) => (
+          {navSection3.map(({ to, label, subtitle, icon: Icon, shortcut, dotColor }, i) => (
             <SidebarItem
               key={to} to={to} label={label} icon={Icon}
+              subtitle={isNewbie ? subtitle : undefined}
               shortcut={collapsed ? undefined : shortcut}
               dotColor={dotColor} collapsed={collapsed} index={i + 6}
             />
@@ -316,6 +322,8 @@ export default function Sidebar() {
 interface SidebarItemProps {
   to: string;
   label: string;
+  /** 新手期双标签副标题（如"专注番茄钟"），传入即显示 */
+  subtitle?: string;
   icon: React.ComponentType<{ className?: string; strokeWidth?: string | number }>;
   shortcut?: string;
   dotColor?: string;
@@ -324,7 +332,7 @@ interface SidebarItemProps {
   index?: number;
 }
 
-function SidebarItem({ to, label, icon: Icon, shortcut, dotColor, collapsed, end, index = 0 }: SidebarItemProps) {
+function SidebarItem({ to, label, subtitle, icon: Icon, shortcut, dotColor, collapsed, end, index = 0 }: SidebarItemProps) {
   const location = useLocation();
   // 切换到不同模块时播放导航音效（点击当前已激活项不响）
   const isCurrentActive = end ? location.pathname === to : location.pathname === to || location.pathname.startsWith(to + '/');
@@ -383,6 +391,9 @@ function SidebarItem({ to, label, icon: Icon, shortcut, dotColor, collapsed, end
                 isActive ? 'opacity-100' : 'opacity-60 group-hover:opacity-100',
               )}>
                 {label}
+                {subtitle && (
+                  <span className="ml-1.5 text-[11px] text-text-tertiary/70">· {subtitle}</span>
+                )}
               </span>
             )}
             {/* 快捷键提示 — hover 显示 */}

client/src/components/onboarding/OnboardingOverlay.tsx

@@ -6,6 +6,7 @@
 import { useEffect, useCallback } from 'react';
 import { AnimatePresence } from 'framer-motion';
 import { useOnboardingStore, isGuideDone } from './useOnboardingStore';
+import { loadFirstDiveState } from '@/features/onboarding/firstDive/firstDiveStorage';
 import { Step1Welcome } from './steps/Step1Welcome';
 import { Step2Navigate } from './steps/Step2Navigate';
 import { Step3CameraFlight } from './steps/Step3CameraFlight';
@@ -19,7 +20,10 @@ export function OnboardingOverlay() {
     useOnboardingStore();
 
   // 初始化：检查 localStorage，若未完成则 1.5s 后自动启动
+  // 首潜（L0/L1）未结束时不自动启动，避免双引导叠加轰炸新用户
   useEffect(() => {
+    const diveStage = loadFirstDiveState().stage;
+    if (diveStage === 'landing' || diveStage === 'diving') return;
     if (!isGuideDone()) {
       const timer = setTimeout(() => startGuide(), 1500);
       return () => clearTimeout(timer);

client/src/features/onboarding/firstDive/FirstDiveGate.tsx

@@ -0,0 +1,37 @@
+/**
+ * 首潜编排 Gate — 按引导阶段挂载 L0/L1（AppLayout 全局挂载一次）
+ *
+ * @ai-context: bootstrap 负责旧标记迁移、老用户判定与手册种子（幂等）；
+ * stage 为 done/skipped 时本组件渲染 null，对存量用户零打扰。
+ * 最后一步的 praise 需要在 stage 变为 done 后仍短暂展示，故 diving 判断
+ * 额外放行 justCompleted 存在的瞬间。
+ */
+import { useEffect } from 'react';
+import { AnimatePresence } from 'framer-motion';
+import { LandingQuestion } from './LandingQuestion';
+import { FirstDiveGuide } from './FirstDiveGuide';
+import { useFirstDiveStore } from './useFirstDiveStore';
+
+export function FirstDiveGate() {
+  const stage = useFirstDiveStore((s) => s.stage);
+  const isReady = useFirstDiveStore((s) => s.isReady);
+  const justCompleted = useFirstDiveStore((s) => s.justCompleted);
+  const bootstrap = useFirstDiveStore((s) => s.bootstrap);
+
+  useEffect(() => {
+    bootstrap().catch(() => {});
+  }, [bootstrap]);
+
+  if (!isReady) return null;
+
+  const showLanding = stage === 'landing';
+  // done 后放行片刻，让最后一句 praise 说完
+  const showGuide = stage === 'diving' || (stage === 'done' && justCompleted !== null);
+
+  return (
+    <AnimatePresence>
+      {showLanding && <LandingQuestion key="landing" />}
+      {showGuide && <FirstDiveGuide key="guide" />}
+    </AnimatePresence>
+  );
+}

client/src/features/onboarding/firstDive/FirstDiveGuide.tsx

@@ -0,0 +1,163 @@
+/**
+ * 首潜引导条（L1）— 底部常驻微光伴航，带做完整学习循环
+ *
+ * @ai-context: 完成检测 = 轮询 checkProgress（数据基线差值），与各模块
+ * UI 零耦合；轮询仅在 diving 阶段挂载（3s 间隔 + 窗口聚焦触发）。
+ * 跳过用可见按钮而非 Esc——Esc 已被 AppLayout 用于退出模块，不抢占。
+ */
+import { useEffect, useMemo, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { AnimatePresence, motion } from 'framer-motion';
+import { ArrowRight, Play } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { usePomodoroStore } from '@/features/pomodoro/store/usePomodoroStore';
+import { DIVE_STEPS, getDiveStep, orderStepsByProfile } from './diveSteps';
+import { getCurrentStep, useFirstDiveStore } from './useFirstDiveStore';
+import { MicroLight } from './MicroLight';
+
+const PROGRESS_POLL_MS = 3000;
+const PRAISE_VISIBLE_MS = 4200;
+
+export function FirstDiveGuide() {
+  const { profile, completedSteps, justCompleted, checkProgress, skipDive, clearJustCompleted } =
+    useFirstDiveStore();
+  const startMiniDive = usePomodoroStore((s) => s.startMiniDive);
+  const pomodoroRunning = usePomodoroStore((s) => s.isRunning);
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const [showPraise, setShowPraise] = useState(false);
+
+  const currentStepId = getCurrentStep(profile, completedSteps);
+  const currentStep = currentStepId ? getDiveStep(currentStepId) : null;
+  const orderedSteps = useMemo(
+    () => (profile ? orderStepsByProfile(profile) : DIVE_STEPS),
+    [profile],
+  );
+
+  // ── 进度轮询：仅 diving 阶段挂载 ──
+  useEffect(() => {
+    const timer = setInterval(() => { checkProgress().catch(() => {}); }, PROGRESS_POLL_MS);
+    const onFocus = () => { checkProgress().catch(() => {}); };
+    window.addEventListener('focus', onFocus);
+    return () => { clearInterval(timer); window.removeEventListener('focus', onFocus); };
+  }, [checkProgress]);
+
+  // ── praise 展示：步骤刚完成时露出几秒 ──
+  useEffect(() => {
+    if (!justCompleted) return;
+    setShowPraise(true);
+    const timer = setTimeout(() => {
+      setShowPraise(false);
+      clearJustCompleted();
+    }, PRAISE_VISIBLE_MS);
+    return () => clearTimeout(timer);
+  }, [justCompleted, clearJustCompleted]);
+
+  const onPrimaryAction = () => {
+    if (!currentStep) return;
+    if (!pathname.startsWith(currentStep.route)) {
+      navigate(currentStep.route);
+      return;
+    }
+    // 已在深潜页且当前步骤是迷你潜水 → 直接替用户按下开始
+    if (currentStep.id === 'pomodoro' && !pomodoroRunning) {
+      startMiniDive();
+    }
+  };
+
+  const primaryLabel = (() => {
+    if (!currentStep) return '';
+    if (!pathname.startsWith(currentStep.route)) return '带我去';
+    if (currentStep.id === 'pomodoro') return pomodoroRunning ? '潜水中…' : '开始 3 分钟迷你深潜';
+    return '就在这页，试试吧';
+  })();
+
+  const praiseText = justCompleted ? getDiveStep(justCompleted).praise : '';
+
+  return (
+    <motion.div
+      className="fixed bottom-6 left-1/2 -translate-x-1/2 z-[70] w-[min(560px,calc(100vw-2rem))]"
+      initial={{ opacity: 0, y: 24 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: 24 }}
+      transition={{ duration: 0.5, ease: [0, 0, 0.2, 1] }}
+    >
+      <div className={cn(
+        'rounded-2xl px-5 py-4',
+        'bg-[#0A1826]/92 backdrop-blur-2xl border border-cyan-400/15',
+        'shadow-[0_8px_32px_rgba(4,10,20,0.5),0_0_24px_rgba(6,182,212,0.08)]',
+      )}>
+        <AnimatePresence mode="wait">
+          {showPraise ? (
+            /* 步骤完成的回应 */
+            <motion.div
+              key="praise"
+              className="flex items-center gap-3"
+              initial={{ opacity: 0, y: 6 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -6 }}
+            >
+              <MicroLight size={16} />
+              <p className="text-[13px] text-cyan-100/85 leading-relaxed">{praiseText}</p>
+            </motion.div>
+          ) : currentStep ? (
+            /* 当前步骤引导 */
+            <motion.div
+              key={currentStep.id}
+              initial={{ opacity: 0, y: 6 }}
+              animate={{ opacity: 1, y: 0 }}
+              exit={{ opacity: 0, y: -6 }}
+            >
+              <div className="flex items-start gap-3">
+                <MicroLight size={16} className="mt-1" />
+                <p className="flex-1 text-[13px] text-white/80 leading-relaxed">
+                  {currentStep.instruction}
+                </p>
+              </div>
+              <div className="mt-3 flex items-center gap-3">
+                {/* 潜航进度点 */}
+                <div className="flex items-center gap-1.5 mr-auto" aria-label="首潜进度">
+                  {orderedSteps.map((s) => (
+                    <span
+                      key={s.id}
+                      title={s.title}
+                      className={cn(
+                        'h-1.5 rounded-full transition-all duration-500',
+                        completedSteps.includes(s.id)
+                          ? 'w-5 bg-cyan-400/80'
+                          : s.id === currentStep.id
+                            ? 'w-3.5 bg-cyan-400/40 animate-pulse'
+                            : 'w-1.5 bg-white/15',
+                      )}
+                    />
+                  ))}
+                </div>
+                <button
+                  onClick={skipDive}
+                  className="text-[12px] text-white/30 hover:text-white/60 transition-colors px-2 py-1.5"
+                >
+                  先跳过
+                </button>
+                <button
+                  onClick={onPrimaryAction}
+                  disabled={currentStep.id === 'pomodoro' && pomodoroRunning && pathname.startsWith(currentStep.route)}
+                  className={cn(
+                    'flex items-center gap-1.5 px-4 py-1.5 rounded-full text-[12px] font-medium',
+                    'bg-cyan-500/90 text-white hover:bg-cyan-400 transition-colors',
+                    'shadow-[0_2px_12px_rgba(6,182,212,0.35)]',
+                    'disabled:opacity-50 disabled:pointer-events-none',
+                  )}
+                >
+                  {currentStep.id === 'pomodoro' && pathname.startsWith(currentStep.route)
+                    ? <Play className="w-3.5 h-3.5" strokeWidth={2} />
+                    : <ArrowRight className="w-3.5 h-3.5" strokeWidth={2} />}
+                  {primaryLabel}
+                </button>
+              </div>
+            </motion.div>
+          ) : null}
+        </AnimatePresence>
+      </div>
+    </motion.div>
+  );
+}