fix(pomodoro): 修复周期计数无重置路径与副作用双重执行

无重置路径的周期计数 + 跨模式状态残留 + store/hook 副作用双重执行
导致番茄钟计数统计异常。

Author: Aparencia

client/src/features/pomodoro/hooks/usePomodoroEffects.ts

@@ -1,21 +1,21 @@
 /**
  * 番茄钟副作用 hook
- * @ai-context 监听 usePomodoroStore 的 lastAction 信号，触发音效、通知、成就检测、会话记录
+ * @ai-context 监听 usePomodoroStore 的 lastAction 信号，触发视觉反馈（水墨涟漪）与通知权限请求
  *
  * 与 usePomodoroStore 配合使用：
- * - Store 仅负责纯状态变更（计时器 tick、阶段切换、设置更新）
- * - 本 hook 负责所有副作用（音效播放、浏览器通知、成就检测、会话持久化）
+ * - Store 负责状态变更及音效播放、会话持久化、浏览器通知（tick/skip/start 内联执行）
+ * - 本 hook 仅负责 store 无法执行的 DOM 级副作用（涟漪动画、权限请求）
+ *
+ * 注意：不要在此重复播放音效或记录会话——store 已执行过，
+ * 重复执行会导致会话统计翻倍（BUG：番茄会话重复记录）。
  *
  * 使用方式：在番茄钟页面顶层组件中调用一次即可
  * <code>usePomodoroEffects()</code>
  */
 
 import { useEffect, useRef } from 'react';
 import { usePomodoroActionSignal } from '../store/usePomodoroStore';
-import { recordSession, playCompletionSound, sendNotification } from '../store/usePomodoroPersistence';
-import { soundPlayer } from '@/lib/audio/SoundPlayer';
 import { triggerInkRipple } from '@/lib/animation/InkRipple';
-import type { PomodoroAction } from '../store/usePomodoroStore';
 
 /**
  * 番茄钟副作用 hook
@@ -44,125 +44,10 @@ export function usePomodoroEffects(): void {
     if (signal.lastActionCounter === prevCounterRef.current) return;
     prevCounterRef.current = signal.lastActionCounter;
 
-    const action: PomodoroAction | null = signal.lastAction;
-    if (!action) return;
-
-    switch (action) {
-      case 'start':
-        soundPlayer.play('pomodoro_start');
-        break;
-
-      case 'pause':
-        soundPlayer.play('pomodoro_pause');
-        break;
-
-      case 'exit_immersive':
-        soundPlayer.play('pomodoro_pause');
-        break;
-
-      case 'tick_5min_warning':
-        // store 已确保 mode !== 'class' 时才发出此信号
-        soundPlayer.play('pomodoro_5min_warning');
-        break;
-
-      case 'tick_final':
-        // store 已确保 mode !== 'class' 时才发出此信号
-        soundPlayer.play('pomodoro_tick_final');
-        break;
-
-      case 'phase_complete':
-        handlePhaseComplete(signal);
-        break;
+    // 音效/会话记录/浏览器通知均由 store 内联执行，此处仅处理视觉反馈
+    if (signal.lastAction === 'phase_complete') {
+      // 水墨涟漪反馈：每次阶段完成时触发
+      triggerInkRipple(window.innerWidth / 2, window.innerHeight / 2);
     }
   }, [signal.lastActionCounter, signal.lastAction, signal]);
 }
-
-// ─────────────────────────────────────────────────────────────
-// 内部：phase_complete 副作用处理
-// ─────────────────────────────────────────────────────────────
-
-interface PhaseCompletePayload {
-  lastCompletedPhase: 'work' | 'short_break' | 'long_break' | null;
-  isCycleComplete: boolean;
-  lastSessionActualDuration: number | null;
-  mode: 'class' | 'self_study';
-  settings: {
-    soundEnabled: boolean;
-    notificationEnabled: boolean;
-    workDuration: number;
-    classDuration: number;
-  };
-  currentGoal: string | null;
-}
-
-function handlePhaseComplete(payload: PhaseCompletePayload): void {
-  const {
-    lastCompletedPhase,
-    isCycleComplete,
-    lastSessionActualDuration,
-    mode,
-    settings,
-    currentGoal,
-  } = payload;
-
-  if (!lastCompletedPhase) return;
-
-  // ── 水墨涟漪反馈：每次阶段完成时触发 ────────────────
-  triggerInkRipple(window.innerWidth / 2, window.innerHeight / 2);
-
-  // ── 记录会话（仅 work 阶段） ─────────────────────────────
-  if (lastCompletedPhase === 'work') {
-    const workMinutes = mode === 'class' ? settings.classDuration : settings.workDuration;
-    const actualDuration = lastSessionActualDuration ?? workMinutes * 60;
-
-    recordSession({
-      mode,
-      duration: workMinutes * 60,
-      actualDuration,
-      completedAt: new Date(),
-      interrupted: false,
-      goal: currentGoal ?? undefined,
-    })
-      .then(() => {
-        // 触发成就检查（动态 import 避免循环依赖）
-        import('@/lib/achievements/evaluator')
-          .then(({ checkAchievements }) => {
-            checkAchievements({ type: 'pomodoro_completed' })
-              .then((unlocked) => {
-                unlocked.forEach((a) => {
-                  window.dispatchEvent(
-                    new CustomEvent('achievement-unlocked', { detail: a }),
-                  );
-                });
-              })
-              .catch(() => {});
-          })
-          .catch(() => {});
-      })
-      .catch(() => {});
-  }
-
-  // ── 播放音效（上课模式静默） ──────────────────────────────
-  if (mode !== 'class') {
-    if (settings.soundEnabled) {
-      playCompletionSound();
-    }
-    if (lastCompletedPhase === 'work') {
-      soundPlayer.play('pomodoro_work_complete');
-    } else {
-      soundPlayer.play('pomodoro_break_end');
-      if (isCycleComplete) {
-        soundPlayer.play('pomodoro_complete');
-      }
-    }
-  }
-
-  // ── 发送浏览器通知 ────────────────────────────────────────
-  if (settings.notificationEnabled) {
-    if (lastCompletedPhase === 'work') {
-      sendNotification('又添了一段暖意', '继续深潜吧 ☕').catch(() => {});
-    } else {
-      sendNotification('休息结束！', '开始下一个番茄 🍅').catch(() => {});
-    }
-  }
-}

client/src/features/pomodoro/store/usePomodoroStore.test.ts

@@ -465,5 +465,54 @@ describe('Pomodoro Store', () => {
       usePomodoroStore.getState().setMode('class');
       expect(usePomodoroStore.getState().mode).toBe('class');
     });
+
+    it('should reset completedCount when switching mode', () => {
+      // 上课模式累计了 7 个番茄后切到自习模式，计数应归零
+      // （回归：旧计数带入新模式导致首轮长休要等到 8 个番茄）
+      usePomodoroStore.setState({ mode: 'class', completedCount: 7 });
+      usePomodoroStore.getState().setMode('self_study');
+      expect(usePomodoroStore.getState().completedCount).toBe(0);
+    });
+
+    it('should NOT reset completedCount when setting the same mode', () => {
+      usePomodoroStore.setState({ mode: 'self_study', completedCount: 2 });
+      usePomodoroStore.getState().setMode('self_study');
+      expect(usePomodoroStore.getState().completedCount).toBe(2);
+    });
+  });
+
+  // ── class mode completedCount ────────────────────────────
+
+  describe('class mode completedCount', () => {
+    const completeWorkPhase = () => {
+      usePomodoroStore.setState({ phase: 'work', remainingSeconds: 1, isRunning: true });
+      usePomodoroStore.getState().tick(); // work → short_break
+      usePomodoroStore.setState({ remainingSeconds: 1, isRunning: true });
+      usePomodoroStore.getState().tick(); // short_break → work
+    };
+
+    it('should never enter long_break in class mode', () => {
+      usePomodoroStore.setState({
+        mode: 'class', phase: 'work', completedCount: 3,
+        isRunning: true, remainingSeconds: 1,
+      });
+      usePomodoroStore.getState().tick();
+      expect(usePomodoroStore.getState().phase).toBe('short_break');
+    });
+
+    it('should wrap completedCount within longBreakInterval in class mode (no unbounded growth)', () => {
+      // 回归：上课模式无长休导致计数永不归零、一直累加（实测 9/4）
+      usePomodoroStore.setState({ mode: 'class', completedCount: 0 });
+      for (let i = 0; i < 9; i++) completeWorkPhase();
+      const count = usePomodoroStore.getState().completedCount;
+      expect(count).toBeGreaterThanOrEqual(1);
+      expect(count).toBeLessThanOrEqual(DEFAULT_SETTINGS.longBreakInterval);
+    });
+
+    it('should wrap count via skip in class mode as well', () => {
+      usePomodoroStore.setState({ mode: 'class', phase: 'work', completedCount: 4 });
+      usePomodoroStore.getState().skip();
+      expect(usePomodoroStore.getState().completedCount).toBe(1);
+    });
   });
 });

client/src/features/pomodoro/store/usePomodoroStore.ts

@@ -44,6 +44,8 @@ interface PomodoroState {
   sessionStartTime: number | null;
   /** 当前番茄目标文字 */
   currentGoal: string | null;
+  /** 首潜迷你会话标记：3 分钟体验潜水，会话时长按实际记录而非 settings 时长 */
+  isMiniDive: boolean;
   /** 是否处于沉浸专注模式 */
   isImmersive: boolean;
   /** 退出沉浸后标记，用于 resume 时自动重入 */
@@ -64,6 +66,8 @@ interface PomodoroState {
   lastSessionActualDuration: number | null;
 
   start: () => void;
+  /** 开始首潜 3 分钟迷你体验（新手引导专用，不改动用户设置） */
+  startMiniDive: () => void;
   pause: () => void;
   resume: () => void;
   reset: () => void;
@@ -90,6 +94,9 @@ const getPhaseDuration = (phase: Phase, settings: PomodoroSettings, mode?: Mode)
   }
 };
 
+/** 首潜迷你体验时长（3 分钟），见新手引导系统 */
+export const MINI_DIVE_SECONDS = 180;
+
 const getNextPhase = (
   currentPhase: Phase,
   completedCount: number,
@@ -106,6 +113,24 @@ const getNextPhase = (
   return 'work';
 };
 
+/**
+ * 计算阶段结束后的完成计数：
+ * - 长休结束 → 归零（一轮完成）
+ * - 工作结束 → +1；上课模式无长休，计数达到周期上限后回绕，避免无限累加
+ * - 其他阶段 → 不变
+ */
+const getNextCount = (
+  phase: Phase,
+  completedCount: number,
+  longBreakInterval: number,
+  mode?: Mode,
+): number => {
+  if (phase === 'long_break') return 0;
+  if (phase !== 'work') return completedCount;
+  if (mode === 'class') return (completedCount % longBreakInterval) + 1;
+  return completedCount + 1;
+};
+
 export const usePomodoroStore = create<PomodoroState>((set, get) => {
   const defaultSettings: PomodoroSettings = {
     workDuration: 25,
@@ -130,6 +155,7 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
     settings: defaultSettings,
     sessionStartTime: null,
     currentGoal: null,
+    isMiniDive: false,
     isImmersive: false,
     wasImmersive: false,
     aiRecommendedDuration: undefined,
@@ -168,6 +194,18 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
       soundPlayer.play('pomodoro_start');
     },
 
+    startMiniDive: () => {
+      // 3 分钟真实专注：走完整 tick 链路（记会话/触发成就），duration 按 180s 如实记录
+      set((s) => ({
+        mode: 'self_study', phase: 'work',
+        remainingSeconds: MINI_DIVE_SECONDS, totalSeconds: MINI_DIVE_SECONDS,
+        isMiniDive: true, isRunning: true, isPaused: false,
+        sessionStartTime: Date.now(), currentGoal: '首潜 · 3 分钟体验',
+        lastAction: 'start' as PomodoroAction, lastActionCounter: s.lastActionCounter + 1,
+      }));
+      soundPlayer.play('pomodoro_start');
+    },
+
     pause: () => {
       set((s) => ({
         isRunning: false, isPaused: true,
@@ -199,12 +237,13 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
         isPaused: false,
         sessionStartTime: null,
         wasImmersive: false,
+        isMiniDive: false,
       });
     },
 
     skip: () => {
       const { phase, completedCount, settings, mode } = get();
-      const newCount = phase === 'long_break' ? 0 : (phase === 'work' ? completedCount + 1 : completedCount);
+      const newCount = getNextCount(phase, completedCount, settings.longBreakInterval, mode);
       const nextPhase = getNextPhase(phase, completedCount, settings.longBreakInterval, mode);
       const duration = getPhaseDuration(nextPhase, settings, mode);
       set({
@@ -214,12 +253,15 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
         completedCount: newCount,
         isRunning: false,
         isPaused: false,
+        isMiniDive: false,
       });
     },
 
     setMode: (mode) => {
-      const { settings, phase, isRunning, isPaused } = get();
-      set({ mode });
+      const { settings, phase, isRunning, isPaused, mode: prevMode } = get();
+      if (mode === prevMode) return;
+      // 切换模式 = 开启新周期：计数归零，避免跨模式累计（自习首轮跳到 8 的根因）
+      set({ mode, completedCount: 0 });
       // 切换模式后，若计时器未运行，重置当前阶段时长
       if (!isRunning && !isPaused) {
         const duration = getPhaseDuration(phase, settings, mode);
@@ -252,7 +294,7 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
       if (remainingSeconds <= 1) {
         // Phase completed
         const wasRunning = isRunning;
-        const newCount = phase === 'long_break' ? 0 : (phase === 'work' ? completedCount + 1 : completedCount);
+        const newCount = getNextCount(phase, completedCount, settings.longBreakInterval, mode);
         const nextPhase = getNextPhase(phase, completedCount, settings.longBreakInterval, mode);
         const duration = getPhaseDuration(nextPhase, settings, mode);
         const isCycleComplete = phase === 'long_break';
@@ -272,14 +314,17 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
         // 记录完成的番茄会话
         let actualDuration: number | null = null;
         if (phase === 'work') {
-          const { sessionStartTime: sst } = get();
-          const workMinutes = mode === 'class' ? settings.classDuration : settings.workDuration;
+          const { sessionStartTime: sst, isMiniDive } = get();
+          // 迷你潜水按实际 180s 记录，避免污染效率统计（首潜决策：计入成就）
+          const plannedSeconds = isMiniDive
+            ? MINI_DIVE_SECONDS
+            : (mode === 'class' ? settings.classDuration : settings.workDuration) * 60;
           actualDuration = sst
             ? Math.round((Date.now() - sst) / 1000)
-            : workMinutes * 60;
+            : plannedSeconds;
           recordSession({
             mode: get().mode,
-            duration: workMinutes * 60,
+            duration: plannedSeconds,
             actualDuration,
             completedAt: new Date(),
             interrupted: false,
@@ -328,6 +373,8 @@ export const usePomodoroStore = create<PomodoroState>((set, get) => {
           completedCount: newCount,
           isRunning: shouldAutoStart,
           isPaused: !shouldAutoStart,
+          // 迷你潜水仅限一个工作阶段，阶段切换即恢复常规节律
+          isMiniDive: false,
           // 切换到新阶段时清空计时，下一个 start/resume 会重新设置
           sessionStartTime: null,
           // 发出 phase_complete 动作信号