feat(feynman): AI 反馈持久化 + 用户反馈五问题修复

- feat: AI 评估/追问/回答评估结果持久化到 Dexie（feynmanAIResults 表），返回列表后重新进入可恢复；新增重置按钮

- fix: AI 请求增加 75s 前端超时兜底（withTimeout），避免永远卡在加载态

- fix: AI 内容长度校验差异化——救援/主题类非空即可，评估类>=5，生成类保持>=10

- fix: 费曼已完成状态下隐藏卡壳了/AI评估按钮，消除状态矛盾

- fix: 闪卡创建 deckId 缺失时报错而非静默跳过，createCard 失败展示错误

- fix: 牌组卡片无描述时预留一行高度保持尺寸一致，长描述显示展开符号按钮

- chore: phase-aware 音频配置优化

Author: Aparencia

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

@@ -5,7 +5,7 @@
  * 评估的综合评分/维度进度条/优势/待改进/建议。数据来自 useAIEvaluate，
  * 评分阈值文案（≥80 出色 / ≥60 较好）为产品定义，勿随意调整。
  */
-import { X, Sparkles, CheckCircle2, Circle } from 'lucide-react';
+import { X, Sparkles, CheckCircle2, Circle, RotateCcw } from 'lucide-react';
 import { AIThinkingIndicator } from '@/components/ui/AIThinkingIndicator';
 import { cn } from '@/lib/utils';
 import type { EvaluateResult } from '@/lib/ai/types';
@@ -17,10 +17,12 @@ interface AIEvaluationResultProps {
   data: EvaluateResult | null;
   onClose: () => void;
   onGoSettings: () => void;
+  /** v0.30: 重置 AI 反馈（用户建议） */
+  onReset?: () => void;
 }
 
 export function AIEvaluationResult({
-  loading, error, needsConfig, data, onClose, onGoSettings,
+  loading, error, needsConfig, data, onClose, onGoSettings, onReset,
 }: AIEvaluationResultProps) {
   return (
     <div className={cn(
@@ -32,12 +34,24 @@ export function AIEvaluationResult({
           <Sparkles className="w-icon-sm h-icon-sm text-brand-500" strokeWidth={1.5} />
           AI 评估结果
         </h3>
-        <button
-          onClick={onClose}
-          className="p-1 rounded-kb-full text-text-tertiary hover:text-text-primary hover:bg-bg-tertiary transition-all duration-kb-fast"
-        >
-          <X className="w-4 h-4" strokeWidth={1.5} />
-        </button>
+        <div className="flex items-center gap-1">
+          {onReset && data && !loading && (
+            <button
+              onClick={onReset}
+              className="inline-flex items-center gap-1 px-2 py-1 rounded-kb-md text-c1 text-text-tertiary hover:text-text-primary hover:bg-bg-tertiary transition-all duration-kb-fast"
+              title="清除评估结果，可重新评估"
+            >
+              <RotateCcw className="w-3.5 h-3.5" strokeWidth={1.5} />
+              重置
+            </button>
+          )}
+          <button
+            onClick={onClose}
+            className="p-1 rounded-kb-full text-text-tertiary hover:text-text-primary hover:bg-bg-tertiary transition-all duration-kb-fast"
+          >
+            <X className="w-4 h-4" strokeWidth={1.5} />
+          </button>
+        </div>
       </div>
 
       {loading && (

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

@@ -68,7 +68,8 @@ export function FeynmanTopBar({
       <h1 className="text-b1 font-semibold text-text-primary flex-1 truncate">
         {concept || '浮出水面'}
       </h1>
-      {hasExplanation && (
+      {/* v0.30: 已完成状态下隐藏卡壳救援与 AI 评估入口，避免状态矛盾 */}
+      {hasExplanation && !isCompleted && (
         <button
           onClick={onRescue}
           className={cn(
@@ -83,7 +84,7 @@ export function FeynmanTopBar({
           卡壳了
         </button>
       )}
-      {hasExplanation && (
+      {hasExplanation && !isCompleted && (
         <AIButton
           size="sm"
           loading={aiEvalLoading}

client/src/features/feynman/hooks/useFeynmanAI.tsx

@@ -6,6 +6,8 @@
  * （Ctrl+Shift+H 快捷键 + 停滞计时）及讲解文本右键 AI 操作菜单。
  * @ai-context: 接收 note 作为参数（由 useFeynmanSession 提供）；反问/评估
  * 均要求 concept+explanation 已填写，否则 toast 提示。
+ * @ai-context: v0.30 — AI 结果持久化：评估/追问/回答评估成功后写入
+ * feynmanAIResults 表，重新进入会话时自动恢复；“重置 AI 反馈”删除记录。
  */
 import { useEffect, useState, useCallback, useMemo } from 'react';
 import { MessageCircle, Lightbulb, SearchCheck } from 'lucide-react';
@@ -14,7 +16,9 @@ import { useContextMenu } from '@/lib/contextMenu';
 import { useAIEvaluate, useAIFeynmanQuestion, useAIFeynmanEvaluateAnswers } from '@/lib/ai/useAI';
 import { useAIErrorHandler } from '@/lib/ai/hooks/useAIErrorHandler';
 import { useStuckTimer } from '@/hooks/useStuckTimer';
-import type { FeynmanNote } from '@/types/models';
+import { feynmanAIResultStore } from '@/lib/storage';
+import { createWithLog, updateWithLog } from '@/lib/storage/writeWithLog';
+import type { FeynmanNote, FeynmanAIResult } from '@/types/models';
 
 export function useFeynmanAI(note: FeynmanNote | null) {
   const { toast } = useToast();
@@ -26,6 +30,7 @@ export function useFeynmanAI(note: FeynmanNote | null) {
     error: aiEvalError,
     needsConfig: aiEvalNeedsConfig,
     evaluate: aiEvaluate,
+    clear: clearEval,
   } = useAIEvaluate();
 
   // AI 反问
@@ -35,6 +40,7 @@ export function useFeynmanAI(note: FeynmanNote | null) {
     error: aiQuestionError,
     needsConfig: aiQuestionNeedsConfig,
     generateQuestions,
+    clear: clearQuestion,
   } = useAIFeynmanQuestion();
 
   // AI 回答评估
@@ -44,6 +50,7 @@ export function useFeynmanAI(note: FeynmanNote | null) {
     error: aiAnswerEvalError,
     needsConfig: aiAnswerEvalNeedsConfig,
     evaluateAnswers: aiEvaluateAnswers,
+    clear: clearAnswerEval,
   } = useAIFeynmanEvaluateAnswers();
 
   const handleQuestionError = useAIErrorHandler('AI 追问生成失败');
@@ -54,6 +61,66 @@ export function useFeynmanAI(note: FeynmanNote | null) {
   const [showQuestionPanel, setShowQuestionPanel] = useState(false);
   const [localAnswers, setLocalAnswers] = useState<string[]>([]);
 
+  // ── v0.30: AI 结果持久化 ────────────────────────────────
+  const [persisted, setPersisted] = useState<FeynmanAIResult | null>(null);
+
+  /** 会话加载时恢复持久化的 AI 结果 */
+  useEffect(() => {
+    if (!note?.id) { setPersisted(null); return; }
+    let cancelled = false;
+    feynmanAIResultStore.where('noteId', note.id).then((records) => {
+      if (cancelled) return;
+      const record = records[0] ?? null;
+      setPersisted(record);
+      if (record) {
+        if (record.evalResult) setShowAIEval(true);
+        if (record.questionData) setShowQuestionPanel(true);
+        if (record.answers?.length) setLocalAnswers(record.answers);
+      }
+    }).catch(() => { /* 恢复失败不阻塞主流程 */ });
+    return () => { cancelled = true; };
+  }, [note?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  /** 将 AI 结果增量写入持久层（upsert by noteId） */
+  const persistAIResult = useCallback(async (patch: Partial<FeynmanAIResult>) => {
+    if (!note?.id) return;
+    const noteId = note.id;
+    try {
+      const existing = (await feynmanAIResultStore.where('noteId', noteId))[0];
+      if (existing) {
+        const updated = { ...existing, ...patch, updatedAt: new Date() };
+        await updateWithLog(feynmanAIResultStore, 'feynmanAIResults', existing.id, updated);
+        setPersisted(updated);
+      } else {
+        const now = new Date();
+        const data = { noteId, ...patch, createdAt: now, updatedAt: now };
+        const id = await createWithLog(feynmanAIResultStore, 'feynmanAIResults', data);
+        setPersisted({ id, ...data } as FeynmanAIResult);
+      }
+    } catch { /* 持久化失败不阻塞主流程 */ }
+  }, [note?.id]);
+
+  /** 重置 AI 反馈：删除持久化记录 + 清空内存状态 */
+  const resetAIResults = useCallback(async () => {
+    if (!note?.id) return;
+    try {
+      const records = await feynmanAIResultStore.where('noteId', note.id);
+      for (const r of records) await feynmanAIResultStore.delete(r.id);
+    } catch { /* 忽略 */ }
+    setPersisted(null);
+    setShowAIEval(false);
+    setShowQuestionPanel(false);
+    setLocalAnswers([]);
+    clearEval();
+    clearQuestion();
+    clearAnswerEval();
+    toast({ type: 'success', message: 'AI 反馈已重置' });
+  }, [note?.id, clearEval, clearQuestion, clearAnswerEval, toast]);
+
+  /** 是否存在 AI 结果（内存或持久层）——用于展示重置按钮 */
+  const hasAIResults = !!(aiEvalData || aiQuestionData || aiAnswerEvalData
+    || persisted?.evalResult || persisted?.questionData || persisted?.answerEvalData);
+
   // 卡壳救援
   const [rescueOpen, setRescueOpen] = useState(false);
   const stuckTimer = useStuckTimer({
@@ -81,8 +148,10 @@ export function useFeynmanAI(note: FeynmanNote | null) {
       return;
     }
     setShowAIEval(true);
-    aiEvaluate(note.concept, note.explanation).catch(handleEvalError);
-  }, [note, toast, aiEvaluate, handleEvalError]);
+    aiEvaluate(note.concept, note.explanation)
+      .then((result) => { persistAIResult({ evalResult: result }); })
+      .catch(handleEvalError);
+  }, [note, toast, aiEvaluate, handleEvalError, persistAIResult]);
 
   const handleGenerateQuestions = useCallback(() => {
     if (!note?.concept || !note?.explanation) {
@@ -91,8 +160,10 @@ export function useFeynmanAI(note: FeynmanNote | null) {
     }
     setShowQuestionPanel(true);
     setLocalAnswers([]);
-    generateQuestions(note.concept, note.explanation).catch(handleQuestionError);
-  }, [note, toast, generateQuestions, handleQuestionError]);
+    generateQuestions(note.concept, note.explanation)
+      .then((result) => { persistAIResult({ questionData: result, answers: undefined, answerEvalData: undefined }); })
+      .catch(handleQuestionError);
+  }, [note, toast, generateQuestions, handleQuestionError, persistAIResult]);
 
   const handleSubmitAnswers = useCallback(async () => {
     if (!note?.concept || !aiQuestionData) return;
@@ -102,8 +173,11 @@ export function useFeynmanAI(note: FeynmanNote | null) {
       toast({ type: 'warning', message: '请至少回答一个追问' });
       return;
     }
-    await aiEvaluateAnswers(note.concept, questions, answers).catch(handleEvalError);
-  }, [note, aiQuestionData, localAnswers, toast, aiEvaluateAnswers, handleEvalError]);
+    const evalResult = await aiEvaluateAnswers(note.concept, questions, answers).catch(handleEvalError);
+    if (evalResult) {
+      persistAIResult({ answers, answerEvalData: evalResult });
+    }
+  }, [note, aiQuestionData, localAnswers, toast, aiEvaluateAnswers, handleEvalError, persistAIResult]);
 
   // ── 右键 AI 操作菜单 ──
 
@@ -171,13 +245,21 @@ export function useFeynmanAI(note: FeynmanNote | null) {
   return {
     rescueOpen, setRescueOpen, stuckTimer,
     showAIEval, setShowAIEval,
-    aiEvalLoading, aiEvalData, aiEvalError, aiEvalNeedsConfig, handleAIEval,
+    aiEvalLoading,
+    // v0.30: 内存数据优先，回退持久化记录（返回列表后重新进入可恢复）
+    aiEvalData: aiEvalData ?? persisted?.evalResult ?? null,
+    aiEvalError, aiEvalNeedsConfig, handleAIEval,
     showQuestionPanel, setShowQuestionPanel,
     localAnswers, setLocalAnswers,
-    aiQuestionLoading, aiQuestionData, aiQuestionError, aiQuestionNeedsConfig,
+    aiQuestionLoading,
+    aiQuestionData: aiQuestionData ?? persisted?.questionData ?? null,
+    aiQuestionError, aiQuestionNeedsConfig,
     handleGenerateQuestions,
-    aiAnswerEvalLoading, aiAnswerEvalData, aiAnswerEvalError, aiAnswerEvalNeedsConfig,
+    aiAnswerEvalLoading,
+    aiAnswerEvalData: aiAnswerEvalData ?? persisted?.answerEvalData ?? null,
+    aiAnswerEvalError, aiAnswerEvalNeedsConfig,
     handleSubmitAnswers,
+    resetAIResults, hasAIResults,
     menuOpen, menuPosition, menuContext, closeMenu,
     aiMenuGroups, handleMenuSelect, handleNoteContextMenu,
   };

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

@@ -56,6 +56,7 @@ export default function FeynmanSessionPage() {
     handleGenerateQuestions,
     aiAnswerEvalLoading, aiAnswerEvalData, aiAnswerEvalError, aiAnswerEvalNeedsConfig,
     handleSubmitAnswers,
+    resetAIResults,
     menuOpen, menuPosition, menuContext, closeMenu,
     aiMenuGroups, handleMenuSelect, handleNoteContextMenu,
   } = useFeynmanAI(note);
@@ -198,6 +199,7 @@ export default function FeynmanSessionPage() {
                     data={aiEvalData}
                     onClose={() => setShowAIEval(false)}
                     onGoSettings={() => navigate('/settings')}
+                    onReset={resetAIResults}
                   />
                 )}
 

client/src/features/flashcards/hooks/useDeckCards.ts

@@ -66,13 +66,18 @@ export function useDeckCards({
 
   const handleSaveCard = useCallback(async () => {
     if (!cardFront.trim() || !cardBack.trim()) return;
+    // v0.30: deckId 缺失时明确报错，禁止静默跳过（用户反馈“有时看不见创建的闪卡”）
+    if (editingCardId === null && !deckId) {
+      toast({ type: 'error', message: '牌组信息异常，无法创建卡片，请返回重试' });
+      return;
+    }
     setSaving(true);
     try {
       if (editingCardId !== null) {
         await updateCard(editingCardId, { front: cardFront.trim(), back: cardBack.trim() });
-      } else if (deckId) {
+      } else {
         await createCard({
-          deckId,
+          deckId: deckId!,
           front: cardFront.trim(),
           back: cardBack.trim(),
           type: 'basic',
@@ -81,10 +86,12 @@ export function useDeckCards({
       setCardModalOpen(false);
       setCardFront('');
       setCardBack('');
+    } catch {
+      toast({ type: 'error', message: '保存卡片失败，请重试' });
     } finally {
       setSaving(false);
     }
-  }, [cardFront, cardBack, editingCardId, deckId, createCard, updateCard]);
+  }, [cardFront, cardBack, editingCardId, deckId, createCard, updateCard, toast]);
 
   const handleDeleteCard = useCallback(async () => {
     if (deleteCardId === null) return;

client/src/features/flashcards/pages/FlashcardsPage.tsx

@@ -1,9 +1,9 @@
 /**
  * @ai-context: flashcards 功能模块页面：FlashcardsPage。
  */
-import { useEffect, useState, useCallback, useRef } from 'react';
+import { useEffect, useState, useCallback, useRef, useLayoutEffect } from 'react';
 import { motion, AnimatePresence } from 'framer-motion';
-import { Card, Button, Tag, Modal, Input, EmptyState, Skeleton, useToast } from '@/components/ui';
+import { Button, Tag, Modal, Input, EmptyState, Skeleton, useToast } from '@/components/ui';
 import { ContextMenu, type ContextMenuGroup } from '@/components/ui/ContextMenu';
 import { Plus, Layers, Clock, Trash2, Layers3, Upload, BookOpen, Pencil, Share2 } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
@@ -20,6 +20,60 @@ import { soundPlayer } from '@/lib/audio/SoundPlayer';
 
 const LONG_PRESS_THRESHOLD_MS = 600;
 
+/**
+ * 牌组描述行（v0.30）
+ *
+ * 无描述时始终预留一行高度，保证卡片尺寸一致；
+ * 描述超过一行时截断并展示“⋯”符号按钮，点击展开完整内容。
+ */
+function DeckCardDescription({ description }: { description?: string }) {
+  const [expanded, setExpanded] = useState(false);
+  const [overflows, setOverflows] = useState(false);
+  const textRef = useRef<HTMLParagraphElement>(null);
+
+  // 收起状态下测量是否溢出一行（垂直换行或水平不可断行溢出均算）
+  useLayoutEffect(() => {
+    if (expanded) return;
+    const el = textRef.current;
+    if (el) {
+      setOverflows(
+        el.scrollHeight > el.clientHeight + 1 || el.scrollWidth > el.clientWidth + 1,
+      );
+    }
+  }, [description, expanded]);
+
+  if (!description) {
+    // 无描述：占位一行高度（12px × 1.5 行高），确保卡片尺寸一致
+    return <div className="mt-0.5 min-h-[1.125rem]" aria-hidden="true" />;
+  }
+
+  return (
+    <div className="flex items-start gap-1 mt-0.5">
+      <p
+        ref={textRef}
+        className={cn(
+          // break-words：无空格长串（如 URL/连续字符）也能正常断行，
+          // 收起时配合 line-clamp-1 转为垂直溢出以便检测，展开时不撑出卡片
+          'text-b3 text-text-tertiary flex-1 min-w-0 min-h-[1.125rem] break-words',
+          !expanded && 'line-clamp-1',
+        )}
+      >
+        {description}
+      </p>
+      {overflows && (
+        <button
+          onClick={(e) => { e.stopPropagation(); setExpanded(v => !v); }}
+          className="flex-shrink-0 text-b3 leading-[1.125rem] text-text-tertiary hover:text-text-primary transition-colors"
+          title={expanded ? '收起描述' : '查看完整描述'}
+          aria-label={expanded ? '收起描述' : '查看完整描述'}
+        >
+          {expanded ? '▴' : '⋯'}
+        </button>
+      )}
+    </div>
+  );
+}
+
 interface DeckLocalStats {
   total: number;
   due: number;
@@ -380,9 +434,7 @@ export default function FlashcardsPage() {
                             )}
                             <h3 className="text-b1 font-semibold text-text-primary truncate">{deck.name}</h3>
                           </div>
-                          {deck.description && (
-                            <p className="text-b3 text-text-tertiary mt-0.5 line-clamp-2">{deck.description}</p>
-                          )}
+                          <DeckCardDescription description={deck.description} />
                         </div>
                         <Tag color="flashcard">{stats.total} 卡</Tag>
                       </div>