feat(feynman): E2 录音关联持久化与跨会话回放(userData/recordings)

Author: Aparencia

client/src/features/feynman/components/FeynmanRecorder.test.tsx

@@ -0,0 +1,135 @@
+/**
+ * FeynmanRecorder 组件测试 / Tests for E2 recording persistence
+ *
+ * @ai-context: 覆盖 B5(E2) 契约——有 noteId 时停止录音持久化到
+ * {userData}/recordings（stem=feynman-{noteId}）、挂载时加载跨会话回放、
+ * 删除时清理本地文件；无 noteId 保持会话内回放（不落盘）。electronAPI
+ * 全 Mock，绝不触碰真实 IPC/麦克风。
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, cleanup, act, fireEvent } from '@testing-library/react';
+import { FeynmanRecorder } from './FeynmanRecorder';
+
+const mocks = vi.hoisted(() => {
+  const api = {
+    invoke: vi.fn(),
+    on: vi.fn(),
+    recording: {
+      save: vi.fn(),
+      load: vi.fn(),
+      delete: vi.fn(),
+    },
+  };
+  return { api };
+});
+
+beforeEach(() => {
+  // 只注入 electronAPI 属性，不替换 window 本体（保留 React 的 Node instanceof 检查）
+  Object.defineProperty(window, 'electronAPI', { value: mocks.api, configurable: true, writable: true });
+  vi.clearAllMocks();
+  // 默认 IPC 行为：ASR 可用、采集可启动
+  mocks.api.invoke.mockImplementation(async (channel: string) => {
+    switch (channel) {
+      case 'local_asr_stream_available': return { available: true };
+      case 'audio_capture_status': return { active: false };
+      case 'audio_capture_start': return { success: true };
+      case 'local_asr_stream_start': return { success: true };
+      case 'local_asr_stream_stop': return { success: true };
+      case 'audio_capture_stop': return { success: true };
+      default: return {};
+    }
+  });
+  mocks.api.on.mockReturnValue(() => {});
+  mocks.api.recording.save.mockResolvedValue({ success: true });
+  mocks.api.recording.load.mockResolvedValue({ success: false, notFound: true });
+  mocks.api.recording.delete.mockResolvedValue({ success: true });
+});
+
+afterEach(() => {
+  cleanup();
+  delete (window as { electronAPI?: unknown }).electronAPI;
+});
+
+/** 取某 channel 上注册的渲染侧回调（事件模拟入口） */
+function handlerOf(channel: string): (...args: unknown[]) => void {
+  const call = mocks.api.on.mock.calls.find((c) => c[0] === channel);
+  if (!call) throw new Error(`no handler for ${channel}`);
+  return call[1] as (...args: unknown[]) => void;
+}
+
+async function recordOnce() {
+  // 开始录音
+  fireEvent.click(screen.getByRole('button', { name: /口头讲解/ }));
+  await act(async () => { await Promise.resolve(); await Promise.resolve(); });
+  // 模拟一帧 PCM 音频块（1 秒 16kHz 单声道）
+  act(() => {
+    handlerOf('audio_capture_chunk')({ audioBuffer: new Float32Array(16000).buffer, sampleRate: 16000 });
+  });
+  // 停止录音
+  fireEvent.click(screen.getByRole('button', { name: /停止讲解/ }));
+  await act(async () => { await Promise.resolve(); await Promise.resolve(); });
+}
+
+describe('FeynmanRecorder (B5/E2 persistence)', () => {
+  it('should persist recording to {userData}/recordings when noteId given', async () => {
+    render(<FeynmanRecorder explanation="" onExplanationChange={() => {}} noteId="note-1" />);
+    await act(async () => { await Promise.resolve(); });
+    await recordOnce();
+    // 停止后触发持久化：stem = feynman-{noteId}
+    const saved = mocks.api.recording.save.mock.calls[0];
+    expect(saved?.[0]).toBe('feynman-note-1');
+    expect(typeof saved?.[1]).toBe('string');
+    expect(saved?.[1].length).toBeGreaterThan(100); // 有效 base64 WAV
+  });
+
+  it('should load persisted recording on mount for cross-session playback', async () => {
+    mocks.api.recording.load.mockResolvedValue({
+      success: true,
+      base64: 'UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAIA+AAABAAgAZGF0YQAAAAA=',
+    });
+    render(<FeynmanRecorder explanation="" onExplanationChange={() => {}} noteId="note-2" />);
+    await act(async () => { await Promise.resolve(); });
+    expect(mocks.api.recording.load).toHaveBeenCalledWith('feynman-note-2');
+    // 加载成功后显示回放条
+    expect(document.querySelector('audio')).not.toBeNull();
+  });
+
+  it('should not persist when noteId missing (session-only playback)', async () => {
+    render(<FeynmanRecorder explanation="" onExplanationChange={() => {}} />);
+    await act(async () => { await Promise.resolve(); });
+    await recordOnce();
+    expect(mocks.api.recording.save).not.toHaveBeenCalled();
+  });
+
+  it('should delete local file when playback removed', async () => {
+    mocks.api.recording.load.mockResolvedValue({
+      success: true,
+      base64: 'UklGRiQAAABXQVZFZm10IBAAAAABAAEAgD4AAIA+AAABAAgAZGF0YQAAAAA=',
+    });
+    render(<FeynmanRecorder explanation="" onExplanationChange={() => {}} noteId="note-3" />);
+    await act(async () => { await Promise.resolve(); });
+    fireEvent.click(screen.getByTitle('删除录音'));
+    await act(async () => { await Promise.resolve(); });
+    expect(mocks.api.recording.delete).toHaveBeenCalledWith('feynman-note-3');
+    expect(document.querySelector('audio')).toBeNull();
+  });
+
+  it('should wait for in-flight save before deleting local file (race guard)', async () => {
+    // save 挂起不 resolve：删除必须先等 save 完成，防止文件删而复生
+    let resolveSave: (v: unknown) => void = () => {};
+    mocks.api.recording.save.mockImplementation(
+      () => new Promise((r) => { resolveSave = r; }),
+    );
+    render(<FeynmanRecorder explanation="" onExplanationChange={() => {}} noteId="note-4" />);
+    await act(async () => { await Promise.resolve(); });
+    await recordOnce(); // save 已发起但未完成
+    fireEvent.click(screen.getByTitle('删除录音'));
+    expect(mocks.api.recording.delete).not.toHaveBeenCalled();
+    await act(async () => {
+      resolveSave({ success: true });
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(mocks.api.recording.delete).toHaveBeenCalledWith('feynman-note-4');
+  });
+});

client/src/features/feynman/components/FeynmanRecorder.tsx

@@ -2,9 +2,11 @@
  * 费曼录音讲解组件（E2 录音 + 回放自评）
  *
  * @ai-context: step1 讲解区的"口头讲解"入口：麦克风采集 + 本地流式 ASR
- * 实时转写填入 explanation；同步累积音频块，停止后编码为会话内 WAV blob
- * 供回放自评（不持久化音频，仅持久化文本）。ASR 不可用时整个入口隐藏
- * （可选增强原则）。链路复用 audio_capture_start + local_asr_stream_start。
+ * 实时转写填入 explanation；同步累积音频块，停止后编码为 WAV 并持久化
+ * 到 {userData}/recordings（以 feynman-{noteId} 为 stem，本地优先不上传），
+ * 跨会话回放可用。无 noteId 时保持会话内回放（不落盘）。ASR 不可用时
+ * 整个入口隐藏（可选增强原则）。链路复用 audio_capture_start +
+ * local_asr_stream_start + recording:save/load/delete。
  */
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { Mic, Square, Play, Trash2 } from 'lucide-react';
@@ -14,20 +16,27 @@ import { cn } from '@/lib/utils';
 interface FeynmanRecorderProps {
   explanation: string;
   onExplanationChange: (v: string) => void;
+  /** E2: 关联费曼笔记 id——录音以此持久化命名，跨会话回放 */
+  noteId?: string | null;
 }
 
 /** 单次录音时长上限：防止 PCM 累积无限增长（10 分钟 ≈ 19MB） */
 const MAX_RECORD_MS = 10 * 60 * 1000;
 
-/** base64 → Blob（会话内回放用） */
+/** 录音文件 stem：feynman-{noteId}（uuid 安全字符，符合主进程 SAFE_NAME_RE） */
+function recordingStem(noteId: string): string {
+  return `feynman-${noteId}`;
+}
+
+/** base64 → Blob（回放用） */
 function base64ToBlob(base64: string, type: string): Blob {
   const binary = atob(base64);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
   return new Blob([bytes], { type });
 }
 
-export function FeynmanRecorder({ explanation, onExplanationChange }: FeynmanRecorderProps) {
+export function FeynmanRecorder({ explanation, onExplanationChange, noteId }: FeynmanRecorderProps) {
   const [asrAvailable, setAsrAvailable] = useState(false);
   const [recording, setRecording] = useState(false);
   const [partialText, setPartialText] = useState('');
@@ -48,6 +57,11 @@ export function FeynmanRecorder({ explanation, onExplanationChange }: FeynmanRec
   const recordLimitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   // ref 同步最新 playback URL：卸载闭包只捕获初始值，必须经 ref 才能正确 revoke
   const playbackUrlRef = useRef<string | null>(null);
+  // ref 同步最新 noteId：stop 闭包与事件回调中读取，避免 useCallback 空依赖失效
+  const noteIdRef = useRef(noteId);
+  noteIdRef.current = noteId;
+  // 最近一次持久化 Promise：删除前先等待完成，防止 save 晚于 delete 写回文件（孤儿残留）
+  const savePromiseRef = useRef<Promise<unknown> | null>(null);
 
   // 可用性探测：ASR 模型未就绪则隐藏入口
   useEffect(() => {
@@ -70,6 +84,18 @@ export function FeynmanRecorder({ explanation, onExplanationChange }: FeynmanRec
     setPlaybackUrl(next);
   }, []);
 
+  // E2 跨会话回放：挂载时加载该笔记已持久化的录音（不存在静默）
+  useEffect(() => {
+    const api = window.electronAPI;
+    if (!api || !noteId) return;
+    let cancelled = false;
+    api.recording.load(recordingStem(noteId)).then((r) => {
+      if (cancelled || !r?.success || !r.base64) return;
+      updatePlaybackUrl(URL.createObjectURL(base64ToBlob(r.base64, 'audio/wav')));
+    }).catch(() => { /* 加载失败静默——仅影响回放 */ });
+    return () => { cancelled = true; };
+  }, [noteId, updatePlaybackUrl]);
+
   const stop = useCallback(async () => {
     if (!recordingRef.current) return;
     if (recordLimitTimerRef.current) {
@@ -90,7 +116,7 @@ export function FeynmanRecorder({ explanation, onExplanationChange }: FeynmanRec
     setRecording(false);
     setPartialText('');
 
-    // 会话内回放：累积的 PCM → WAV blob URL（不持久化）
+    // 回放：累积的 PCM → WAV，持久化（有笔记关联）或仅会话内 blob URL
     const chunks = samplesRef.current;
     samplesRef.current = [];
     if (chunks.length > 0) {
@@ -101,6 +127,11 @@ export function FeynmanRecorder({ explanation, onExplanationChange }: FeynmanRec
       try {
         const wavBase64 = encodeWavBase64(merged, sampleRateRef.current, 1);
         updatePlaybackUrl(URL.createObjectURL(base64ToBlob(wavBase64, 'audio/wav')));
+        // E2: 本地优先持久化（{userData}/recordings/feynman-{noteId}.wav），跨会话可回放
+        const stem = noteIdRef.current ? recordingStem(noteIdRef.current) : null;
+        if (stem) {
+          savePromiseRef.current = api?.recording.save(stem, wavBase64).catch(() => { /* 落盘失败静默——回放仍可用 */ });
+        }
       } catch { /* 编码失败不影响转写文本 */ }
     }
   }, [cleanupIpc, updatePlaybackUrl]);
@@ -221,7 +252,19 @@ export function FeynmanRecorder({ explanation, onExplanationChange }: FeynmanRec
             <Play className="w-3.5 h-3.5" strokeWidth={1.5} />
             <audio src={playbackUrl} controls className="h-7 max-w-[200px]" />
             <button
-              onClick={() => updatePlaybackUrl(null)}
+              onClick={() => {
+                // E2: 持久化录音删除本地文件，避免孤儿文件堆积。
+                // 先等待在途 save 完成再删，防止 save 晚于 delete 写回（删除失效）
+                const stem = noteIdRef.current ? recordingStem(noteIdRef.current) : null;
+                const pending = savePromiseRef.current;
+                savePromiseRef.current = null;
+                if (stem) {
+                  void Promise.resolve(pending).catch(() => {}).then(() => {
+                    window.electronAPI?.recording.delete(stem).catch(() => {});
+                  });
+                }
+                updatePlaybackUrl(null);
+              }}
               className="p-1 rounded hover:text-red-500 transition-colors"
               title="删除录音"
             >

client/src/features/feynman/components/FeynmanSteps.tsx

@@ -20,9 +20,11 @@ interface StepConceptProps {
   concept?: string;
   explanation: string;
   onExplanationChange: (v: string) => void;
+  /** E2: 费曼笔记 id，供录音持久化关联（跨会话回放） */
+  noteId?: string | null;
 }
 
-export function StepConcept({ concept, explanation, onExplanationChange }: StepConceptProps) {
+export function StepConcept({ concept, explanation, onExplanationChange, noteId }: StepConceptProps) {
   const { container, item } = useFeynmanStagger();
   return (
     <motion.div
@@ -65,8 +67,8 @@ export function StepConcept({ concept, explanation, onExplanationChange }: StepC
             )}
           />
         </div>
-        {/* E2 口头讲解入口（ASR 不可用时自动隐藏） */}
-        <FeynmanRecorder explanation={explanation} onExplanationChange={onExplanationChange} />
+        {/* E2 口头讲解入口（ASR 不可用时自动隐藏；noteId 关联录音持久化） */}
+        <FeynmanRecorder explanation={explanation} onExplanationChange={onExplanationChange} noteId={noteId} />
       </motion.div>
       <motion.div variants={item} className={cn(
         'p-kb-md rounded-kb-lg',

client/src/features/feynman/pages/FeynmanSessionPage.tsx

@@ -146,6 +146,7 @@ export default function FeynmanSessionPage() {
                   concept={note?.concept}
                   explanation={localExplanation}
                   onExplanationChange={setLocalExplanation}
+                  noteId={noteId}
                 />
               </>
             )}