refactor(pomodoro): usePomodoroStore 拆分为 timer/settings/session/preset 四 slice

Author: Aparencia

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

@@ -0,0 +1,188 @@
+/**
+ * 番茄钟状态仓库 — 类型定义与共享纯函数（slice 拆分第一文件）
+ * Pomodoro store types — shared types and pure helpers for slices
+ *
+ * @ai-context: 2026-08 拆分自 usePomodoroStore（811 行超限）。PomodoroState
+ * 为全 store 契约，timerSlice/settingsSlice/presetSlice 各实现子集；
+ * 阶段时长/下一阶段/计数迁移等纯函数集中于此，禁止在各 slice 内重复。
+ * @ai-context: Split from the 811-line monolith; PomodoroState is the full
+ * contract while slices implement subsets. Phase math stays here as pure
+ * functions shared by all slices.
+ */
+import type { StateCreator } from 'zustand';
+import type { PomodoroPreset } from '@/types/models';
+
+export type Phase = 'work' | 'short_break' | 'long_break';
+/** @deprecated 仅为兼容旧会话记录保留，新代码使用 preset */
+export type Mode = 'class' | 'self_study';
+
+/** 番茄钟动作信号类型（供 usePomodoroEffects 监听） */
+export type PomodoroAction =
+  | 'start'
+  | 'pause'
+  | 'exit_immersive'
+  | 'tick_5min_warning'
+  | 'tick_final'
+  | 'phase_complete'
+  | null;
+
+export interface PomodoroSettings {
+  workDuration: number;
+  shortBreakDuration: number;
+  longBreakDuration: number;
+  longBreakInterval: number;
+  autoStartBreak: boolean;
+  autoStartWork: boolean;
+  soundEnabled: boolean;
+  notificationEnabled: boolean;
+  classDuration: number;
+  // v0.28 扩展
+  activePresetId?: string;
+  warningMinutes?: number;
+  tickFinalEnabled?: boolean;
+  completionSoundId?: string;
+  warningSoundId?: string;
+}
+
+export interface PomodoroState {
+  // ── 计时器状态 ──
+  phase: Phase;
+  isRunning: boolean;
+  isPaused: boolean;
+  remainingSeconds: number;
+  totalSeconds: number;
+  /** 当前运行阶段的绝对截止时间戳（ms）——墙钟校准源，休眠唤醒/计时漂移后自愈 */
+  endAt: number | null;
+  completedCount: number;
+  /** @deprecated 兼容层：由 activePreset 派生，下版本移除 */
+  mode: Mode;
+  /** 当前工作会话开始时间戳（ms），用于计算 actualDuration */
+  sessionStartTime: number | null;
+  /** 暂停时刻时间戳（ms），用于排除暂停时间对 actualDuration 的影响 */
+  pausedAt: number | null;
+  /** 累计暂停时间（ms），actualDuration = (now - sessionStartTime - totalPausedMs) / 1000 */
+  totalPausedMs: number;
+  /** 当前番茄目标文字 */
+  currentGoal: string | null;
+  /** 首潜迷你会话标记：3 分钟体验潜水，会话时长按实际记录而非 settings 时长 */
+  isMiniDive: boolean;
+  /** 是否处于沉浸专注模式 */
+  isImmersive: boolean;
+  /** 退出沉浸后标记，用于 resume 时自动重入 */
+  wasImmersive: boolean;
+  /** AI 推荐的工作时长（分钟） */
+  aiRecommendedDuration?: number;
+  /** AI 推荐理由文本 */
+  aiReasoning?: string;
+  /** 动作信号（供 usePomodoroEffects 消费） */
+  lastAction: PomodoroAction;
+  lastActionCounter: number;
+  /** phase_complete 时附带的已完成阶段 */
+  lastCompletedPhase: Phase | null;
+  /** phase_complete 时是否完成整轮 */
+  isCycleComplete: boolean;
+  /** phase_complete 时实际持续秒数 */
+  lastSessionActualDuration: number | null;
+  /** v0.29: 深潜完成庆祝覆盖层可见性 */
+  showCompletionOverlay: boolean;
+  dismissCompletionOverlay: () => void;
+
+  // ── 设置与预设状态 ──
+  settings: PomodoroSettings;
+  presets: PomodoroPreset[];
+  activePreset: PomodoroPreset | null;
+
+  // ── 计时器操作 ──
+  start: () => void;
+  /** 开始首潜 3 分钟迷你体验（新手引导专用，不改动用户设置） */
+  startMiniDive: () => void;
+  /** T3: 开始 5 分钟承诺深潜（拖延重启专用，最小承诺降低启动门槛） */
+  startCommitDive: () => void;
+  pause: () => void;
+  resume: () => void;
+  reset: () => void;
+  skip: () => void;
+  tick: () => void;
+  enterImmersive: () => void;
+  exitImmersive: () => void;
+  /** @deprecated 使用 setPreset 替代 */
+  setMode: (mode: Mode) => void;
+  setPreset: (presetId: string) => void;
+  setCurrentGoal: (goal: string | null) => void;
+  updateSettings: (settings: Partial<PomodoroSettings>) => void;
+  /** 设置 AI 推荐结果 */
+  setAIRecommendation: (duration: number, reasoning: string) => void;
+  initialize: () => Promise<void>;
+
+  // ── 预设 CRUD ──
+  createPreset: (data: Omit<PomodoroPreset, 'id' | 'sortOrder' | 'createdAt' | 'builtin'>) => Promise<PomodoroPreset>;
+  updatePreset: (id: string, changes: Partial<Omit<PomodoroPreset, 'id' | 'builtin'>>) => Promise<void>;
+  deletePreset: (id: string) => Promise<void>;
+  reorderPresets: (orderedIds: string[]) => Promise<void>;
+}
+
+/** slice 创建函数类型（全 state 可见，实现自身子集） */
+export type PomodoroSlice<T> = StateCreator<PomodoroState, [], [], T>;
+
+// ── 纯函数：阶段时长与计数迁移 ─────────────────────────────
+
+/** 根据预设获取阶段时长（秒） */
+export function getPhaseDuration(phase: Phase, preset: PomodoroPreset | null, settings: PomodoroSettings): number {
+  if (!preset) {
+    // 回退到旧 settings（初始化前）
+    switch (phase) {
+      case 'work': return settings.workDuration * 60;
+      case 'short_break': return settings.shortBreakDuration * 60;
+      case 'long_break': return settings.longBreakDuration * 60;
+    }
+  }
+  switch (phase) {
+    case 'work': return preset.workDuration * 60;
+    case 'short_break': return preset.shortBreakDuration * 60;
+    case 'long_break': return preset.longBreakDuration * 60;
+  }
+}
+
+/** 首潜迷你体验时长（3 分钟），见新手引导系统 */
+export const MINI_DIVE_SECONDS = 180;
+
+/** T3 5 分钟承诺深潜时长（拖延情绪调节：不要求完美，只要求开始） */
+export const COMMIT_DIVE_SECONDS = 300;
+
+/** 获取预设的有效 longBreakInterval（0 = 无长休） */
+export function getInterval(preset: PomodoroPreset | null, settings: PomodoroSettings): number {
+  return preset ? preset.longBreakInterval : settings.longBreakInterval;
+}
+
+export function getNextPhase(
+  currentPhase: Phase,
+  completedCount: number,
+  longBreakInterval: number,
+): Phase {
+  if (currentPhase === 'work') {
+    // longBreakInterval=0 表示无长休（原上课模式），始终短休
+    if (longBreakInterval === 0) return 'short_break';
+    return (completedCount + 1) % longBreakInterval === 0
+      ? 'long_break'
+      : 'short_break';
+  }
+  return 'work';
+}
+
+/**
+ * 计算阶段结束后的完成计数：
+ * - 长休结束 → 归零（一轮完成）
+ * - 工作结束 → +1；无长休模式计数达到周期上限后回绕，避免无限累加
+ * - 其他阶段 → 不变
+ */
+export function getNextCount(
+  phase: Phase,
+  completedCount: number,
+  longBreakInterval: number,
+): number {
+  if (phase === 'long_break') return 0;
+  if (phase !== 'work') return completedCount;
+  // 无长休模式：回绕计数（用固定 4 作为显示上限）
+  if (longBreakInterval === 0) return (completedCount % 4) + 1;
+  return completedCount + 1;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * 番茄钟状态仓库 — 预设 slice（CRUD 与活动预设）
+ * Pomodoro preset slice — preset CRUD and active preset
+ *
+ * @ai-context: 拆分自 usePomodoroStore。CRUD 委托给 ../lib/presetService，
+ * 本 slice 仅同步 store 状态。删除活动预设时回退第一个并重置计时时长；
+ * reorder 保持 orderedIds 全量顺序。activePreset/mode 与 settingsSlice 的
+ * setPreset/setMode 共享同一状态槽（Zustand 组合时后者覆盖初始值）。
+ * @ai-context: Extracted from the monolith; CRUD delegates to presetService
+ * while this slice keeps store state in sync. Deleting the active preset
+ * falls back to the first and resets timer duration.
+ */
+import { getPhaseDuration, type PomodoroSlice, type PomodoroState } from './pomodoroStoreTypes';
+import {
+  createPreset as svcCreatePreset, updatePreset as svcUpdatePreset,
+  deletePreset as svcDeletePreset, reorderPresets as svcReorderPresets,
+} from '../lib/presetService';
+import type { PomodoroPreset } from '@/types/models';
+
+export const createPresetSlice: PomodoroSlice<Pick<PomodoroState, 'presets' | 'activePreset' | 'createPreset' | 'updatePreset' | 'deletePreset' | 'reorderPresets'>> = (set, get) => ({
+  presets: [],
+  activePreset: null,
+
+  createPreset: async (data) => {
+    const preset = await svcCreatePreset(data);
+    set((s) => ({ presets: [...s.presets, preset] }));
+    return preset;
+  },
+
+  updatePreset: async (id, changes) => {
+    await svcUpdatePreset(id, changes);
+    set((s) => ({
+      presets: s.presets.map(p => (p.id === id ? { ...p, ...changes } : p)),
+      activePreset: s.activePreset?.id === id
+        ? { ...s.activePreset, ...changes } as PomodoroPreset
+        : s.activePreset,
+    }));
+  },
+
+  deletePreset: async (id) => {
+    await svcDeletePreset(id);
+    const { activePreset, presets } = get();
+    const remaining = presets.filter(p => p.id !== id);
+    // 若删除的是当前活动预设，回退到第一个
+    let newActive = activePreset;
+    if (activePreset?.id === id) {
+      newActive = remaining[0] ?? null;
+      const duration = getPhaseDuration('work', newActive, get().settings);
+      set({ remainingSeconds: duration, totalSeconds: duration, phase: 'work', completedCount: 0 });
+    }
+    set({ presets: remaining, activePreset: newActive, mode: newActive?.silent ? 'class' : 'self_study' });
+  },
+
+  reorderPresets: async (orderedIds) => {
+    await svcReorderPresets(orderedIds);
+    set((s) => ({
+      presets: orderedIds
+        .map(id => s.presets.find(p => p.id === id))
+        .filter((p): p is PomodoroPreset => p != null),
+    }));
+  },
+});

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

@@ -0,0 +1,82 @@
+/**
+ * 番茄钟状态仓库 — 设置 slice（配置与预设切换）
+ * Pomodoro settings slice — config and preset switching
+ *
+ * @ai-context: 拆分自 usePomodoroStore。updateSettings 在计时器未运行时
+ * 同步刷新阶段时长；setPreset 切换=开启新周期（计数归零）；setMode 为
+ * @deprecated 兼容层映射到内置预设。saveSettings 持久化失败静默降级。
+ * @ai-context: Extracted from the monolith. updateSettings refreshes phase
+ * duration when idle; switching presets starts a fresh cycle (count resets);
+ * setMode is the deprecated compat shim mapping onto builtin presets.
+ */
+import { saveSettings } from './usePomodoroPersistence';
+import { getPhaseDuration, type Mode, type PomodoroSlice, type PomodoroState } from './pomodoroStoreTypes';
+
+export const createSettingsSlice: PomodoroSlice<Pick<PomodoroState, 'mode' | 'settings' | 'currentGoal' | 'aiRecommendedDuration' | 'aiReasoning' | 'setMode' | 'setPreset' | 'setCurrentGoal' | 'updateSettings' | 'setAIRecommendation'>> = (set, get) => ({
+  mode: 'self_study',
+  settings: {
+    workDuration: 25,
+    shortBreakDuration: 5,
+    longBreakDuration: 15,
+    longBreakInterval: 4,
+    autoStartBreak: true,
+    autoStartWork: false,
+    soundEnabled: true,
+    notificationEnabled: false,
+    classDuration: 45,
+  },
+  currentGoal: null,
+  aiRecommendedDuration: undefined,
+  aiReasoning: undefined,
+
+  /** @deprecated 兼容层：将 mode 映射到内置预设 */
+  setMode: (mode) => {
+    const { presets } = get();
+    const target = mode === 'class'
+      ? presets.find(p => p.silent)
+      : presets.find(p => !p.silent);
+    if (target) get().setPreset(target.id);
+  },
+
+  setPreset: (presetId) => {
+    const { settings, phase, isRunning, isPaused, activePreset } = get();
+    if (activePreset?.id === presetId) return;
+    const preset = get().presets.find(p => p.id === presetId) ?? null;
+    if (!preset) return;
+    // 切换预设 = 开启新周期：计数归零，避免跨预设累计
+    const mode: Mode = preset.silent ? 'class' : 'self_study';
+    set({ activePreset: preset, mode, completedCount: 0, phase: 'work' });
+    // 切换预设后，若计时器未运行，重置当前阶段时长
+    if (!isRunning && !isPaused) {
+      const duration = getPhaseDuration('work', preset, settings);
+      set({ remainingSeconds: duration, totalSeconds: duration });
+    }
+    // 持久化 activePresetId
+    saveSettings({ ...settings, activePresetId: presetId }).catch(() => {});
+  },
+
+  setCurrentGoal: (goal) => set({ currentGoal: goal }),
+
+  setAIRecommendation: (duration, reasoning) =>
+    set({ aiRecommendedDuration: duration, aiReasoning: reasoning }),
+
+  updateSettings: (newSettings) => {
+    const { settings, phase, isRunning, isPaused, activePreset } = get();
+    const merged = { ...settings, ...newSettings };
+
+    // If not running, update timer to reflect new duration
+    if (!isRunning && !isPaused) {
+      const duration = getPhaseDuration(phase, activePreset, merged);
+      set({
+        settings: merged,
+        remainingSeconds: duration,
+        totalSeconds: duration,
+      });
+    } else {
+      set({ settings: merged });
+    }
+
+    // 持久化设置
+    saveSettings(merged).catch(() => {});
+  },
+});