feat(flashcards): 批量管理(选择/重学/搁置/删除)+牌组重命名+会话上限可配置

Author: Aparencia

client/src/features/flashcards/components/DeckCardList.tsx

@@ -7,7 +7,7 @@
  */
 import { motion } from 'framer-motion';
 import { Card, Tag } from '@/components/ui';
-import { BookOpen, Sparkles, Clock, CheckCircle2, Pencil, Trash2, ExternalLink } from 'lucide-react';
+import { BookOpen, Sparkles, Clock, CheckCircle2, Pencil, Trash2, ExternalLink, CheckSquare, Square } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { Tip } from '@/components/ui/Tip';
 import type { Flashcard } from '@/types/models';
@@ -70,10 +70,15 @@ export interface DeckCardListProps {
   onEdit: (card: Flashcard) => void;
   onDelete: (cardId: string | null) => void;
   onOpenSourceNote: (noteId: string) => void;
+  /** 批量模式：卡片点击切换选中，隐藏编辑/删除按钮 */
+  batchMode?: boolean;
+  selectedIds?: Set<string>;
+  onToggleSelect?: (id: string) => void;
 }
 
 export function DeckCardList({
   cards, prefersReduced, onContextMenu, onEdit, onDelete, onOpenSourceNote,
+  batchMode = false, selectedIds, onToggleSelect,
 }: DeckCardListProps) {
   return (
     <motion.div
@@ -95,9 +100,25 @@ export function DeckCardList({
           >
             <Card
               padding="sm"
-              className={cn('flex items-center gap-3', evolutionClass(card))}
-              onContextMenu={(e) => onContextMenu(e, card)}
+              className={cn(
+                'flex items-center gap-3',
+                evolutionClass(card),
+                batchMode && 'cursor-pointer',
+                batchMode && selectedIds?.has(card.id ?? '')
+                  ? 'ring-2 ring-brand-400/50 bg-brand-50/20'
+                  : undefined,
+              )}
+              onContextMenu={batchMode ? undefined : (e) => onContextMenu(e, card)}
+              onClick={batchMode ? () => onToggleSelect?.(card.id ?? '') : undefined}
             >
+              {/* 批量模式勾选指示 */}
+              {batchMode && (
+                <span className="flex-shrink-0">
+                  {selectedIds?.has(card.id ?? '')
+                    ? <CheckSquare className="w-5 h-5 text-brand-500" strokeWidth={1.5} />
+                    : <Square className="w-5 h-5 text-text-tertiary/50" strokeWidth={1.5} />}
+                </span>
+              )}
               <div className="flex-1 min-w-0">
                 <p className="text-b2 font-medium text-text-primary truncate">{card.front}</p>
                 <div className="flex items-center gap-3 mt-1 text-c1 text-text-tertiary">
@@ -109,7 +130,7 @@ export function DeckCardList({
                 </div>
               </div>
               <div className="flex items-center gap-1 flex-shrink-0">
-                {card.sourceNoteId && (
+                {card.sourceNoteId && !batchMode && (
                   <button
                     onClick={() => onOpenSourceNote(card.sourceNoteId!)}
                     className="inline-flex items-center gap-1 px-2 py-1 rounded-kb-sm text-c1 text-text-tertiary hover:text-brand-600 hover:bg-brand-50 transition-all duration-kb-fast"
@@ -121,6 +142,7 @@ export function DeckCardList({
                   </button>
                 )}
                 {/* 编辑卡片按钮，带 tooltip */}
+                {!batchMode && (
                 <Tip text="编辑卡片">
                 <button
                   onClick={() => onEdit(card)}
@@ -130,7 +152,9 @@ export function DeckCardList({
                   <Pencil className="w-4 h-4" strokeWidth={1.5} />
                 </button>
                 </Tip>
+                )}
                 {/* 删除卡片按钮，带 tooltip */}
+                {!batchMode && (
                 <Tip text="删除卡片">
                 <button
                   onClick={() => onDelete(card.id ?? null)}
@@ -140,6 +164,7 @@ export function DeckCardList({
                   <Trash2 className="w-4 h-4" strokeWidth={1.5} />
                 </button>
                 </Tip>
+                )}
               </div>
             </Card>
           </motion.div>

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

@@ -7,15 +7,18 @@
  * @ai-context: 右键菜单语义——重学=重置 SM2 状态（createNewCardState）使卡片
  * 立即可学；搁置=到期日推后一年；删除走二次确认。
  */
-import { useEffect, useCallback, useMemo } from 'react';
+import { useEffect, useCallback, useMemo, useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
-import { Button, EmptyState, Skeleton, useToast } from '@/components/ui';
+import { AnimatePresence, motion } from 'framer-motion';
+import { Button, EmptyState, Skeleton, useToast, Modal } from '@/components/ui';
 import { ContextMenu, type ContextMenuGroup } from '@/components/ui/ContextMenu';
-import { BookOpen, Plus, Pencil, Trash2, PauseCircle, RotateCcw } from 'lucide-react';
+import { BookOpen, Plus, Pencil, Trash2, PauseCircle, RotateCcw, Layers } from 'lucide-react';
+import { cn } from '@/lib/utils';
 import { useReducedMotion } from '@/hooks/useReducedMotion';
 import { useFlashcardStore } from '../store/useFlashcardStore';
 import { useShallow } from 'zustand/react/shallow';
 import { useContextMenu } from '@/lib/contextMenu/useContextMenu';
+import { useBatchSelection } from '@/hooks/useBatchSelection';
 import type { Flashcard } from '@/types/models';
 import { createNewCardState } from '@/lib/sm2';
 import { DueCardStack } from '../components/DueCardStack';
@@ -121,6 +124,46 @@ export default function DeckDetailPage() {
 
   const deleteTargetCard = cards.find((c) => c.id === dc.deleteCardId);
 
+  // 批量管理模式（对齐萤火海沟批量交互）
+  const batch = useBatchSelection<Flashcard>({ items: cards });
+  const [batchDeleteOpen, setBatchDeleteOpen] = useState(false);
+
+  // 批量删除：逐卡走 store 级联清理（复习记录 + 卡片）
+  const handleBatchDelete = useCallback(async () => {
+    const ids = Array.from(batch.selectedIds);
+    if (ids.length === 0) return;
+    await Promise.all(ids.map((id) => deleteCard(id)));
+    setBatchDeleteOpen(false);
+    batch.exit();
+  }, [batch, deleteCard]);
+
+  // 批量重学：重置 SM-2 状态，使卡片立即变为可学习状态
+  const handleBatchRelearn = useCallback(async () => {
+    const ids = Array.from(batch.selectedIds);
+    if (ids.length === 0) return;
+    const fresh = createNewCardState();
+    await Promise.all(ids.map((id) => updateCard(id, {
+      easeFactor: fresh.easeFactor,
+      interval: fresh.interval,
+      repetitions: fresh.repetitions,
+      lapses: fresh.lapses,
+      dueDate: fresh.dueDate,
+    })));
+    toast({ type: 'success', message: `已重置 ${ids.length} 张卡片` });
+    batch.exit();
+  }, [batch, updateCard, toast]);
+
+  // 批量搁置：将到期日设为 1 年后
+  const handleBatchSuspend = useCallback(async () => {
+    const ids = Array.from(batch.selectedIds);
+    if (ids.length === 0) return;
+    const farFuture = new Date();
+    farFuture.setFullYear(farFuture.getFullYear() + 1);
+    await Promise.all(ids.map((id) => updateCard(id, { dueDate: farFuture })));
+    toast({ type: 'success', message: `已搁置 ${ids.length} 张卡片` });
+    batch.exit();
+  }, [batch, updateCard, toast]);
+
   return (
     <div className="flex flex-col h-full">
       <DeckDetailHeader
@@ -136,6 +179,71 @@ export default function DeckDetailPage() {
 
       <DeckStatsRow stats={stats} />
 
+      {/* 批量管理模式（对齐萤火海沟批量交互） */}
+      <div className="flex items-center justify-between px-kb-md py-2 flex-shrink-0">
+        <button
+          onClick={() => batch.setBatchMode(v => !v)}
+          className={cn(
+            'flex items-center gap-1.5 px-3 py-1 rounded-full text-xs font-medium border transition-colors',
+            batch.batchMode
+              ? 'bg-brand-50 border-brand-300/60 text-brand-700'
+              : 'bg-bg-secondary border-border/40 text-text-tertiary hover:text-text-secondary',
+          )}
+        >
+          <Layers className="w-3.5 h-3.5" />
+          {batch.batchMode ? '退出批量' : '批量管理'}
+        </button>
+        {batch.batchMode && batch.count > 0 && (
+          <span className="text-c1 text-text-tertiary">已选中 {batch.count} 张</span>
+        )}
+      </div>
+      <AnimatePresence>
+        {batch.batchMode && (
+          <motion.div
+            initial={{ opacity: 0, height: 0 }}
+            animate={{ opacity: 1, height: 'auto' }}
+            exit={{ opacity: 0, height: 0 }}
+            className="flex items-center gap-2 flex-wrap px-kb-md pb-2 flex-shrink-0"
+          >
+            <motion.button whileTap={{ scale: 0.95 }} onClick={batch.selectAll}
+              className="px-2.5 py-1 rounded-full text-xs font-medium text-text-secondary bg-bg-secondary border border-border/40 hover:text-text-primary transition-colors">
+              全选
+            </motion.button>
+            <motion.button whileTap={{ scale: 0.95 }} onClick={batch.clear}
+              className="px-2.5 py-1 rounded-full text-xs font-medium text-text-tertiary bg-bg-secondary border border-border/40 hover:text-text-secondary transition-colors">
+              取消全选
+            </motion.button>
+            <motion.button
+              whileTap={{ scale: 0.95 }}
+              onClick={handleBatchRelearn}
+              disabled={batch.count === 0}
+              className="flex items-center gap-1 px-3 py-1 rounded-full text-xs font-medium bg-bg-secondary border border-border/40 text-text-secondary hover:text-text-primary transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
+            >
+              <RotateCcw className="w-3 h-3" strokeWidth={1.5} />
+              重学
+            </motion.button>
+            <motion.button
+              whileTap={{ scale: 0.95 }}
+              onClick={handleBatchSuspend}
+              disabled={batch.count === 0}
+              className="flex items-center gap-1 px-3 py-1 rounded-full text-xs font-medium bg-bg-secondary border border-border/40 text-text-secondary hover:text-text-primary transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
+            >
+              <PauseCircle className="w-3 h-3" strokeWidth={1.5} />
+              搁置
+            </motion.button>
+            <motion.button
+              whileTap={{ scale: 0.95 }}
+              onClick={() => setBatchDeleteOpen(true)}
+              disabled={batch.count === 0}
+              className="flex items-center gap-1 px-3 py-1 rounded-full text-xs font-medium bg-semantic-error/10 text-semantic-error border border-semantic-error/30 hover:bg-semantic-error/20 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
+            >
+              <Trash2 className="w-3 h-3" strokeWidth={1.5} />
+              删除
+            </motion.button>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
       {/* 卡片列表 */}
       <div className="flex-1 overflow-y-auto px-kb-md pb-kb-md">
         {isLoading ? (
@@ -169,6 +277,9 @@ export default function DeckDetailPage() {
               onEdit={dc.openEditModal}
               onDelete={dc.setDeleteCardId}
               onOpenSourceNote={(noteId) => navigate(`/notes/${noteId}`)}
+              batchMode={batch.batchMode}
+              selectedIds={batch.selectedIds}
+              onToggleSelect={batch.toggle}
             />
           </>
         )}
@@ -230,6 +341,22 @@ export default function DeckDetailPage() {
         onClose={() => dc.setDeleteCardId(null)}
         onConfirm={dc.handleDeleteCard}
       />
+
+      {/* 批量删除确认 */}
+      <Modal
+        open={batchDeleteOpen}
+        onClose={() => setBatchDeleteOpen(false)}
+        title="批量删除卡片"
+        description={`确定要删除选中的 ${batch.count} 张卡片吗？该操作将同时删除相关复习记录，且无法撤销。`}
+        footer={
+          <>
+            <Button variant="secondary" onClick={() => setBatchDeleteOpen(false)}>取消</Button>
+            <Button variant="danger" icon={<Trash2 className="w-4 h-4" strokeWidth={1.5} />} onClick={handleBatchDelete}>删除 {batch.count} 张</Button>
+          </>
+        }
+      >
+        <div />
+      </Modal>
     </div>
   );
 }

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

@@ -110,14 +110,18 @@ const emptyVariants = {
 
 export default function FlashcardsPage() {
   const navigate = useNavigate();
-  const { decks, isLoading, loadDecks, createDeck, deleteDeck } = useFlashcardStore(useShallow(s => s));
+  const { decks, isLoading, loadDecks, createDeck, renameDeck, deleteDeck } = useFlashcardStore(useShallow(s => s));
 
   const [allCards, setAllCards] = useState<Flashcard[]>([]);
   const [modalOpen, setModalOpen] = useState(false);
   const [newName, setNewName] = useState('');
   const [newDesc, setNewDesc] = useState('');
   const [creating, setCreating] = useState(false);
   const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
+  // 牌组重命名弹窗状态（右键「编辑牌组」）
+  const [renameTarget, setRenameTarget] = useState<FlashcardDeck | null>(null);
+  const [renameName, setRenameName] = useState('');
+  const [renaming, setRenaming] = useState(false);
   const longPressTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [importing, setImporting] = useState(false);
@@ -146,7 +150,12 @@ export default function FlashcardsPage() {
   const handleDeckSelect = useCallback(async (itemKey: string, deck: FlashcardDeck) => {
     switch (itemKey) {
       case 'study': navigate(`/flashcards/${deck.id}`); break;
-      case 'edit': navigate(`/flashcards/${deck.id}`); break;
+      case 'edit': {
+        // 编辑牌组 = 重命名（store 已有 renameDeck，补齐 UI 入口）
+        setRenameTarget(deck);
+        setRenameName(deck.name);
+        break;
+      }
       case 'share': {
         try {
           const data = await exportDeck(deck.id);
@@ -264,6 +273,20 @@ export default function FlashcardsPage() {
     setDeleteTarget(null);
   };
 
+  // 牌组重命名保存
+  const handleRename = async () => {
+    if (!renameTarget || !renameName.trim() || renameName.trim() === renameTarget.name) {
+      setRenameTarget(null);
+      return;
+    }
+    setRenaming(true);
+    try {
+      await renameDeck(renameTarget.id, renameName.trim());
+      toast({ type: 'success', message: `牌组已重命名为「${renameName.trim()}」`, silent: true });
+      setRenameTarget(null);
+    } finally { setRenaming(false); }
+  };
+
   const handlePointerDown = (id: string) => {
     longPressTimer.current = setTimeout(() => setDeleteTarget(id), LONG_PRESS_THRESHOLD_MS);
   };
@@ -559,6 +582,30 @@ export default function FlashcardsPage() {
         <div />
       </Modal>
 
+      {/* ── 编辑牌组（重命名）Modal ── */}
+      <Modal
+        open={renameTarget !== null}
+        onClose={() => setRenameTarget(null)}
+        title="编辑牌组"
+        description="修改牌组名称"
+        footer={
+          <>
+            <Button variant="secondary" onClick={() => setRenameTarget(null)}>取消</Button>
+            <Button onClick={handleRename} loading={renaming} disabled={!renameName.trim() || renameName.trim() === renameTarget?.name}>保存</Button>
+          </>
+        }
+      >
+        <div className="flex flex-col gap-kb-md">
+          <Input
+            label="牌组名称"
+            placeholder="例如：数据结构基础"
+            value={renameName}
+            onChange={(e) => setRenameName(e.target.value)}
+            autoFocus
+          />
+        </div>
+      </Modal>
+
       {/* ── 导入预览 ── */}
       <ImportPreviewModal
         open={previewOpen}

client/src/features/flashcards/store/useStudySessionStore.ts

@@ -8,7 +8,7 @@ import {
 } from '@/lib/storage';
 import { Rating } from '@/lib/sm2';
 import { getScheduler } from '@/lib/schedulingFactory';
-import { getMaxNewCardsPerDay, getMaxReviewsPerDay } from '@/lib/schedulingFactory';
+import { getMaxNewCardsPerDay, getMaxReviewsPerDay, getMaxSessionCards } from '@/lib/schedulingFactory';
 import type { Flashcard, FlashcardReview, Confidence, GoldenError } from '@/types/models';
 import { useFlashcardStore } from './useFlashcardStore';
 import { generateId } from '@/lib/utils/uuid';
@@ -21,8 +21,7 @@ import { useWorldEvents } from '@/features/retention/store/useWorldEvents';
 
 /** 到期卡片不足此数量时，补充新卡 */
 const MIN_DUE_THRESHOLD = 10;
-/** 单次会话最多卡片数 */
-const MAX_SESSION_CARDS = 20;
+/** 单次会话上限：由设置页配置（kb-max-session-cards，默认 20） */
 /** 黄金错误加速复习：下次间隔压缩上限（天） */
 const GOLDEN_ERROR_MAX_INTERVAL_DAYS = 1;
 
@@ -181,17 +180,18 @@ export const useStudySessionStore = create<StudySessionState>((set, get) => {
       };
 
       // 组装会话卡片列表（受每日限额约束）
+      const maxSessionCards = getMaxSessionCards();
       let sessionCards: Flashcard[];
       if (dueCards.length >= MIN_DUE_THRESHOLD) {
-        // 到期卡充足：只用到期卡（上限 MAX_SESSION_CARDS 和 remainingReviews）
-        const limit = Math.min(MAX_SESSION_CARDS, remainingReviews);
+        // 到期卡充足：只用到期卡（上限 maxSessionCards 和 remainingReviews）
+        const limit = Math.min(maxSessionCards, remainingReviews);
         sessionCards = dedupe(dueCards).slice(0, limit);
       } else {
-        // 到期卡不足：补充新卡，总量不超过 MAX_SESSION_CARDS 和 remainingReviews
+        // 到期卡不足：补充新卡，总量不超过 maxSessionCards 和 remainingReviews
         const dedupedDue = dedupe(dueCards);
         const dueIds = new Set(dedupedDue.map((c) => c.id!));
         const dedupedNew = dedupe(newCards, dueIds);
-        const totalLimit = Math.min(MAX_SESSION_CARDS, remainingReviews);
+        const totalLimit = Math.min(maxSessionCards, remainingReviews);
         const needNew = Math.min(
           totalLimit - dedupedDue.length,
           dedupedNew.length,