feat(assistant): F3 睡前复习气泡拉起 5 卡迷你复习 + T4 孵化呼吸引导

Author: Aparencia

client/src/features/assistant/AssistantRoot.tsx

@@ -5,6 +5,7 @@
  * 偏好 enabled=false 时整体不渲染（零开销）。
  * 设计原则：可逆 > 不可逆——用户可随时关闭助手。
  */
+import { useState } from 'react';
 import { AnimatePresence } from 'framer-motion';
 import { useAssistantStore } from './store/useAssistantStore';
 import { useChat } from './hooks/useChat';
@@ -13,6 +14,8 @@ import { useAssistantAudio } from './hooks/useAssistantAudio';
 import { useBehaviorSignals } from './hooks/useBehaviorSignals';
 import { useBedtimeReminder } from './hooks/useBedtimeReminder';
 import { useIntentionCoach } from './hooks/useIntentionCoach';
+import { findTopDueDeck } from './lib/bedtimeReview';
+import { IncubationBreathing } from './components/IncubationBreathing';
 import { CreatureAvatar } from './components/CreatureAvatar';
 import { ConversationPanel } from './components/ConversationPanel';
 
@@ -21,6 +24,8 @@ export function AssistantRoot() {
   const panelState = useAssistantStore(s => s.panelState);
   const setPanelState = useAssistantStore(s => s.setPanelState);
   const setCreatureState = useAssistantStore(s => s.setCreatureState);
+  // T4 孵化呼吸引导浮层可见性（stuck-incubation 气泡点击触发）
+  const [incubationOpen, setIncubationOpen] = useState(false);
 
   const { sendMessage, retryLastMessage, dismissError } = useChat();
   const { playSound } = useAssistantAudio();
@@ -43,6 +48,26 @@ export function AssistantRoot() {
   const handleBubbleClick = () => {
     reportBubbleResponded();
     playSound('ack');
+    // T4 孵化休息引导：卡壳救援气泡点击 → 打开 3 分钟呼吸引导浮层
+    if (useAssistantStore.getState().bubbleTriggerId === 'stuck-incubation') {
+      useAssistantStore.getState().hideBubble();
+      setIncubationOpen(true);
+      return;
+    }
+    // F3 闭环：睡前复习气泡点击直接拉起 5 卡迷你复习会话
+    // （到期卡最多的牌组，?mini=5 限制卡数；hash 路由在 Router 外导航）
+    if (useAssistantStore.getState().bubbleTriggerId === 'bedtime-review') {
+      void findTopDueDeck().then((deckId) => {
+        if (deckId) {
+          useAssistantStore.getState().hideBubble();
+          window.location.hash = `#/flashcards/${deckId}/study?mini=5`;
+          return;
+        }
+        setPanelState('expanded');
+        setCreatureState('listening');
+      });
+      return;
+    }
     setPanelState('expanded');
     setCreatureState('listening');
   };
@@ -64,6 +89,8 @@ export function AssistantRoot() {
         onBubbleClick={handleBubbleClick}
         onBubbleDismiss={handleBubbleDismiss}
       />
+      {/* T4 孵化呼吸引导（卡壳救援气泡的落地动作） */}
+      <IncubationBreathing open={incubationOpen} onClose={() => setIncubationOpen(false)} />
       <AnimatePresence>
         {panelState === 'expanded' && (
           <ConversationPanel onSend={sendMessage} onClose={handleClosePanel} onRetry={retryLastMessage} onDismiss={dismissError} />

client/src/features/assistant/components/IncubationBreathing.test.tsx

@@ -0,0 +1,76 @@
+/**
+ * IncubationBreathing 组件测试 / Tests for the T4 incubation overlay
+ *
+ * @ai-context: 覆盖 T4 孵化休息契约——3 分钟倒计时、提前关闭、完成态提示；
+ * 复用呼吸组件的降级模式（reduced-motion）渲染，jsdom 内 stub matchMedia
+ * 与 RAF，避免真实动画循环。
+ * @ai-context: Covers the 3-minute countdown, early close and finished state;
+ * uses the degraded breathing mode to stay deterministic in jsdom.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, cleanup, act } from '@testing-library/react';
+import { IncubationBreathing } from './IncubationBreathing';
+
+function stubMatchMedia(reduced: boolean) {
+  vi.stubGlobal('matchMedia', (query: string) => ({
+    matches: reduced && query.includes('reduced-motion'),
+    media: query,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+    onchange: null,
+  }));
+}
+
+beforeEach(() => {
+  vi.stubGlobal('requestAnimationFrame', () => 1);
+  vi.stubGlobal('cancelAnimationFrame', () => {});
+  stubMatchMedia(true); // 降级模式：静态圆环 + 1Hz 倒计时，测试确定性
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe('IncubationBreathing (T4)', () => {
+  it('should render nothing when closed', () => {
+    render(<IncubationBreathing open={false} onClose={() => {}} />);
+    expect(screen.queryByText(/孵化时刻/)).not.toBeInTheDocument();
+  });
+
+  it('should show 3-minute countdown when opened', () => {
+    render(<IncubationBreathing open onClose={() => {}} />);
+    expect(screen.getByText(/孵化时刻/)).toBeInTheDocument();
+    expect(screen.getByText(/3:00/)).toBeInTheDocument();
+    expect(screen.getByText(/随时可提前回到任务/)).toBeInTheDocument();
+  });
+
+  it('should count down every second and finish after 3 minutes', () => {
+    render(<IncubationBreathing open onClose={() => {}} />);
+    // React 渲染与 fake timers 互锁：逐秒推进 + act flush，链式重注册
+    for (let i = 0; i < 60; i++) {
+      act(() => { vi.advanceTimersByTime(1000); });
+    }
+    expect(screen.getByText(/2:00/)).toBeInTheDocument();
+
+    for (let i = 0; i < 120; i++) {
+      act(() => { vi.advanceTimersByTime(1000); });
+    }
+    expect(screen.getByText(/放松完成/)).toBeInTheDocument();
+    expect(screen.queryByText(/2:00/)).not.toBeInTheDocument();
+  });
+
+  it('should call onClose when early-close button clicked', () => {
+    const onClose = vi.fn();
+    render(<IncubationBreathing open onClose={onClose} />);
+    act(() => {
+      screen.getByRole('button', { name: /回到任务/ }).click();
+    });
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});

client/src/features/assistant/components/IncubationBreathing.tsx

@@ -0,0 +1,103 @@
+/**
+ * T4 孵化呼吸引导浮层 — 卡壳后的 3 分钟轻体力放松
+ * Incubation breathing overlay — 3-minute micro-break after getting stuck
+ *
+ * @ai-context: 复用仪式呼吸组件（BreathingProvider + RitualStepBreathing），
+ * 不重造 RAF 循环。3 分钟自动倒计时（可提前关闭，可逆原则）；完成时
+ * 静默提示"随时回到任务"。降级模式（reduced-motion/低帧）由 Provider
+ * 内部处理为 1Hz 倒计时圆环。
+ * @ai-context: Reuses the ritual breathing stack (single RAF source); a
+ * 3-minute countdown with early-close keeps the break reversible.
+ */
+import { useEffect, useState } from 'react';
+import { Wind, X, Check } from 'lucide-react';
+import { BreathingProvider } from '@/features/dashboard/components/ritual/BreathingProvider';
+import { RitualStepBreathing } from '@/features/dashboard/components/ritual/RitualStepBreathing';
+import { Button } from '@/components/ui';
+
+/** 孵化休息时长（秒）：3 分钟轻体力引导 */
+const INCUBATION_SECONDS = 180;
+
+interface Props {
+  open: boolean;
+  onClose: () => void;
+}
+
+export function IncubationBreathing({ open, onClose }: Props) {
+  const [secondsLeft, setSecondsLeft] = useState(INCUBATION_SECONDS);
+  const [finished, setFinished] = useState(false);
+
+  // 打开时重置倒计时
+  useEffect(() => {
+    if (open) {
+      setSecondsLeft(INCUBATION_SECONDS);
+      setFinished(false);
+    }
+  }, [open]);
+
+  // 3 分钟倒计时（挂起/后台时自然减速，不强求精确）
+  useEffect(() => {
+    if (!open || finished) return;
+    const timer = setTimeout(() => {
+      setSecondsLeft((s) => {
+        if (s <= 1) {
+          setFinished(true);
+          return 0;
+        }
+        return s - 1;
+      });
+    }, 1000);
+    return () => clearTimeout(timer);
+  }, [open, finished, secondsLeft]);
+
+  if (!open) return null;
+
+  const minutes = Math.floor(secondsLeft / 60);
+  const seconds = secondsLeft % 60;
+
+  return (
+    <div className="bg-bg-primary/95 fixed inset-0 z-[90] flex flex-col items-center justify-center gap-6 p-6 backdrop-blur-2xl">
+      <div className="flex flex-col items-center gap-4">
+        <div className="flex items-center gap-2 text-focus">
+          <Wind className="w-5 h-5" strokeWidth={1.5} />
+          <span className="text-b1 font-semibold text-text-primary">孵化时刻</span>
+        </div>
+        <p className="max-w-xs text-center text-c1 text-text-secondary">
+          卡壳不是停滞，是潜意识在孵化。用 3 分钟呼吸放松，让思路自己浮上来。
+        </p>
+      </div>
+
+      <BreathingProvider>
+        <RitualStepBreathing onFirstCycleComplete={() => { /* 首圈完成仅点亮视觉，无需额外动作 */ }} />
+      </BreathingProvider>
+
+      {!finished ? (
+        <div className="flex flex-col items-center gap-3">
+          {/* 倒计时条 */}
+          <div className="h-1 w-64 overflow-hidden rounded-full bg-bg-tertiary">
+            <div
+              className="h-full rounded-full bg-gradient-to-r from-accent-500 to-brand-500 transition-all duration-1000"
+              style={{ width: `${(secondsLeft / INCUBATION_SECONDS) * 100}%` }}
+            />
+          </div>
+          <span className="text-c1 text-text-tertiary tabular-nums">
+            {minutes}:{String(seconds).padStart(2, '0')} · 随时可提前回到任务
+          </span>
+          <Button variant="ghost" size="sm" icon={<X className="w-3.5 h-3.5" />} onClick={onClose}>
+            回到任务
+          </Button>
+        </div>
+      ) : (
+        <div className="flex flex-col items-center gap-3">
+          <div className="flex items-center gap-2 text-emerald-400">
+            <Check className="w-4 h-4" />
+            <span className="text-b2 font-medium">放松完成——现在回到任务，思路会更清晰</span>
+          </div>
+          <Button variant="primary" size="md" onClick={onClose}>
+            回到任务
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

client/src/features/assistant/hooks/useBedtimeReminder.ts

@@ -6,8 +6,9 @@
  * 可选增强设计：任何检测异常静默跳过，绝不打扰用户。
  */
 import { useEffect } from 'react';
-import { flashcardStore, flashcardReviewStore } from '@/lib/storage';
+import { flashcardReviewStore } from '@/lib/storage';
 import { assistantEventBus } from '../lib/eventBus';
+import { findDueCards, findTopDueDeck } from '../lib/bedtimeReview';
 
 /** 睡前推荐窗口起点（21:30，以分钟计） */
 const BEDTIME_START_MIN = 21 * 60 + 30;
@@ -33,15 +34,16 @@ export function useBedtimeReminder(): void {
         if (reviewsToday > 0) return;
 
         // 到期卡计数（dueDate 索引范围查询，避免全表加载）
-        const dueCount = await flashcardStore.getTable()
-          .where('dueDate').belowOrEqual(now)
-          .and((c) => c.repetitions > 0)
-          .count();
-        if (dueCount < MIN_DUE_CARDS) return;
+        const dueCards = await findDueCards(now);
+        if (dueCards.length < MIN_DUE_CARDS) return;
+
+        // F3 闭环：到期卡最多的牌组作为迷你复习目标（无牌组则纯提醒）
+        const topDeckId = await findTopDueDeck(now);
 
         assistantEventBus.emit('review:bedtime', {
           currentHour: now.getHours(),
-          dueCardCount: dueCount,
+          dueCardCount: dueCards.length,
+          topDeckId,
         });
       } catch {
         // 可选增强：检测失败静默跳过

client/src/features/assistant/lib/bedtimeReview.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Bedtime review shared logic tests
+ * B2 (F3): due-card stats + mini-review target selection
+ * @ai-context 睡前复习共享查询测试：到期卡过滤、牌组目标选择、失败静默降级；
+ * 存储层全 Mock，绝不触碰真实 IndexedDB。
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  flashcardStore: { getTable: vi.fn() },
+  flashcardDeckStore: { getTable: vi.fn() },
+}));
+
+vi.mock('@/lib/storage', () => ({
+  flashcardStore: mocks.flashcardStore,
+  flashcardDeckStore: mocks.flashcardDeckStore,
+}));
+
+import { findDueCards, findTopDueDeck } from './bedtimeReview';
+
+interface FakeCard {
+  id: string;
+  deckId: string;
+  dueDate: Date;
+  repetitions: number;
+}
+
+/** 保留 Dexie where/and/toArray 语义的极简内存表 mock */
+function makeCardTable(rows: FakeCard[]) {
+  return {
+    where: (field: string) => ({
+      belowOrEqual: (bound: Date) => ({
+        and: (pred: (r: FakeCard) => boolean) => ({
+          toArray: async () =>
+            rows.filter((r) => field !== 'dueDate' || new Date(r.dueDate) <= bound).filter(pred),
+        }),
+      }),
+    }),
+    toArray: async () => rows,
+  };
+}
+
+const DUE_SOON = new Date('2026-08-03T10:00:00Z');
+const DUE_LATER = new Date('2026-08-10T10:00:00Z');
+const NOW = new Date('2026-08-03T12:00:00Z');
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.flashcardStore.getTable.mockReset();
+  mocks.flashcardDeckStore.getTable.mockReset();
+});
+
+describe('findDueCards', () => {
+  it('should return due cards (dueDate <= now, repetitions > 0)', async () => {
+    const cards: FakeCard[] = [
+      { id: 'c1', deckId: 'd1', dueDate: DUE_SOON, repetitions: 2 },
+      { id: 'c2', deckId: 'd1', dueDate: DUE_LATER, repetitions: 3 }, // 未到期
+      { id: 'c3', deckId: 'd2', dueDate: DUE_SOON, repetitions: 0 },  // 新卡
+    ];
+    mocks.flashcardStore.getTable.mockReturnValue(makeCardTable(cards));
+
+    const result = await findDueCards(NOW);
+    expect(result.map((c) => c.id)).toEqual(['c1']);
+  });
+
+  it('should return empty array when no due cards', async () => {
+    mocks.flashcardStore.getTable.mockReturnValue(makeCardTable([{ id: 'c2', deckId: 'd1', dueDate: DUE_LATER, repetitions: 3 }]));
+    expect(await findDueCards(NOW)).toEqual([]);
+  });
+});
+
+describe('findTopDueDeck', () => {
+  it('should return the deck with most due cards', async () => {
+    const cards: FakeCard[] = [
+      { id: 'c1', deckId: 'd1', dueDate: DUE_SOON, repetitions: 1 },
+      { id: 'c2', deckId: 'd1', dueDate: DUE_SOON, repetitions: 1 },
+      { id: 'c3', deckId: 'd2', dueDate: DUE_SOON, repetitions: 1 },
+      { id: 'c4', deckId: 'd3', dueDate: DUE_LATER, repetitions: 1 },
+    ];
+    mocks.flashcardStore.getTable.mockReturnValue(makeCardTable(cards));
+    mocks.flashcardDeckStore.getTable.mockReturnValue(makeCardTable([
+      { id: 'd1', deckId: 'd1', dueDate: DUE_LATER, repetitions: 0 },
+      { id: 'd2', deckId: 'd2', dueDate: DUE_LATER, repetitions: 0 },
+    ]));
+
+    expect(await findTopDueDeck(NOW)).toBe('d1');
+  });
+
+  it('should return undefined when no decks exist', async () => {
+    mocks.flashcardStore.getTable.mockReturnValue(makeCardTable([
+      { id: 'c1', deckId: 'd1', dueDate: DUE_SOON, repetitions: 1 },
+    ]));
+    mocks.flashcardDeckStore.getTable.mockReturnValue(makeCardTable([]));
+    expect(await findTopDueDeck(NOW)).toBeUndefined();
+  });
+
+  it('should return undefined when no due cards at all', async () => {
+    mocks.flashcardStore.getTable.mockReturnValue(makeCardTable([
+      { id: 'c4', deckId: 'd3', dueDate: DUE_LATER, repetitions: 1 },
+    ]));
+    mocks.flashcardDeckStore.getTable.mockReturnValue(makeCardTable([
+      { id: 'd3', deckId: 'd3', dueDate: DUE_LATER, repetitions: 0 },
+    ]));
+    expect(await findTopDueDeck(NOW)).toBeUndefined();
+  });
+
+  it('should silently return undefined when storage query throws', async () => {
+    // deck 表保持正常，确保 Promise.all 正常成立，卡片表拒绝被统一捕获
+    mocks.flashcardDeckStore.getTable.mockReturnValue(makeCardTable([]));
+    mocks.flashcardStore.getTable.mockImplementation(() => {
+      throw new Error('storage unavailable');
+    });
+    expect(await findTopDueDeck(NOW)).toBeUndefined();
+  });
+});