/** * 圆桌规划草稿持久化 hook(后端版)。 * * 2026-06 改造:草稿从浏览器 localStorage 迁移到后端 MySQL(`/api/roundtable-drafts`), * 按登录用户隔离、跨设备/会话保留。本 hook 仍只负责编排「什么时机存 / 加载到哪里」, * Step 1 / Step 2 的状态由各自的 hook 提供快照函数与 hydrate。 * * 对外返回的接口(`drafts` 列表项含 `name` 等字段、各 handler 签名)与旧版保持一致, * 主页面无需改动。 * * 同时修复了旧 localStorage 版的几个存储 bug: * 1. **自动保存会覆盖手动重命名** —— 现在 create 时写一次派生标题,之后所有 update * 一律不带 title;标题只由显式「重命名」改写。 * 2. **快速连续前进(1→2→3)产生重复草稿** —— 所有保存经一条串行队列,create 完成 * 即写入 `currentDraftIdRef`,后续保存读到 id 走 update 而非再 create。 * 3. **加载读到 state 里的旧列表快照** —— load 走 `getDraft(id)` 实时拉服务端最新全量。 * 4. localStorage 配额导致的静默写失败 / 数据丢失 —— 改后端后不复存在。 */ import { useCallback, useEffect, useRef, useState } from "react"; import type { Step1Snapshot } from "@/roundtable-planning/hooks/useStep1Intent"; import type { Step2Snapshot } from "@/roundtable-planning/hooks/useStep2Orchestration"; import { createDraft, deleteDraft, deriveDraftName, getDraft, listDrafts, updateDraft, } from "@/roundtable-planning/api/drafts"; /** 历史下拉渲染用的轻量列表项(`name` 映射自后端 `title`)。 */ export interface DraftListItem { id: string; name: string; furthestStep: 1 | 2 | 3; createdAt: string; updatedAt: string; } export interface UseDraftPersistenceOptions { currentStep: number; setCurrentStep: React.Dispatch>; triggerToast: (msg: string) => void; /** 读 Step 1 当前快照(由 useStep1Intent 提供的 getter)。 */ getStep1Snapshot: () => Step1Snapshot; /** 读 Step 2 当前快照(由 useStep2Orchestration 提供的 getter)。 */ getStep2Snapshot: () => Step2Snapshot; /** 加载草稿时把 Step 1 状态打回去。 */ hydrateStep1: (snapshot: Step1Snapshot) => void; /** 加载草稿时把 Step 2 状态打回去。 */ hydrateStep2: (snapshot: Step2Snapshot) => void; /** 加载草稿前先中断所有 Step 1 / Step 2 in-flight。 */ cancelAllStreams: () => void; /** * Step 2 的 init 闸门控制 —— 仅当 furthestStep>=2 时把闸门置上,跳过自动 SSE; * 否则保持原 false 让进入 Step 2 时正常初始化。 */ setStep2InitGate: (initialized: boolean) => void; /** * Step 1 是否正在等待任务理解回复。由 true→false 视为「本轮模型回答完」, * 触发一次自动保存(详见 autoSave 的两个 effect)。 */ intentSending: boolean; /** * Step 2 已收尾(streaming===false)的对话气泡数量。每次递增意味着总控/某个 * 子智能体刚交付完一轮,触发一次自动保存。流式增量不改变该计数,因此不会刷屏式保存。 */ step2FinalizedCount: number; } export interface UseDraftPersistenceReturn { drafts: DraftListItem[]; currentDraftId: string | null; isHistoryOpen: boolean; renamingDraftId: string | null; renameDraftValue: string; historyDropdownRef: React.MutableRefObject; loadedFromDraftRef: React.MutableRefObject; setIsHistoryOpen: React.Dispatch>; setRenameDraftValue: React.Dispatch>; setCurrentDraftId: React.Dispatch>; handleManualSave: () => void; handleLoadDraft: (id: string) => void; handleDeleteDraft: (id: string) => void; handleStartRename: (draft: DraftListItem) => void; handleCommitRename: (id: string) => void; handleCancelRename: () => void; /** * 幂等地保证后端存在一条对应当前会话的草稿,返回其 id(无可保存内容时返回 null)。 * 推荐弹窗打开前调用,确保推荐历史有 draft_id 可归属。 */ ensureDraft: (furthestStep?: 1 | 2 | 3) => Promise; } export function useDraftPersistence( options: UseDraftPersistenceOptions, ): UseDraftPersistenceReturn { const { currentStep, setCurrentStep, triggerToast, getStep1Snapshot, getStep2Snapshot, hydrateStep1, hydrateStep2, cancelAllStreams, setStep2InitGate, intentSending, step2FinalizedCount, } = options; const [drafts, setDrafts] = useState([]); const [currentDraftId, setCurrentDraftIdState] = useState(null); const [isHistoryOpen, setIsHistoryOpen] = useState(false); const [renamingDraftId, setRenamingDraftId] = useState(null); const [renameDraftValue, setRenameDraftValue] = useState(""); const loadedFromDraftRef = useRef(false); const prevStepRef = useRef(currentStep); const historyDropdownRef = useRef(null); // 同步镜像,供保存队列在 render 之前读到最新 id(修复重复建草稿竞态)。 const currentDraftIdRef = useRef(null); // 串行化所有写操作,避免并发 create。 const saveQueueRef = useRef>(Promise.resolve()); // 当前步骤镜像 —— 自动保存(不带 furthestStep)落到 create 分支时,用它兜底建档步骤。 const currentStepRef = useRef(currentStep); useEffect(() => { currentStepRef.current = currentStep; }, [currentStep]); // 包一层 setter:同时更新 state 与同步 ref。主页面通过它 setCurrentDraftId(null)。 const setCurrentDraftId = useCallback>>( (action) => { setCurrentDraftIdState((prev) => { const next = typeof action === "function" ? (action as (p: string | null) => string | null)(prev) : action; currentDraftIdRef.current = next; return next; }); }, [], ); const refreshList = useCallback(async () => { try { const metas = await listDrafts(); setDrafts( metas.map((m) => ({ id: m.id, name: m.title, furthestStep: m.furthestStep, createdAt: m.createdAt, updatedAt: m.updatedAt, })), ); } catch (err) { console.warn("[drafts] 刷新草稿列表失败:", err); } }, []); // 首次挂载拉一次草稿列表。 useEffect(() => { void refreshList(); }, [refreshList]); /** 当前会话是否有值得保存的内容。 */ const hasSavableContent = useCallback((step1: Step1Snapshot, step2: Step2Snapshot): boolean => { const hasUserMessage = step1.interactiveMessages.some((m) => m.sender === "user"); return hasUserMessage || step2.step2RoundtableDialogues.length > 0; }, []); /** * 串行执行一次保存:有 id 走 update(不带 title,保护重命名);无 id 走 create * (写一次派生标题)。create/update 成功后同步 currentDraftIdRef。 * 返回 draft id(无可保存内容返回 null)。 * * `furthestStep` 可选: * - 传值(前进切换 / 手动保存 / ensureDraft)→ update 时一并推进 furthest_step; * - 省略(每轮模型回答完的自动保存)→ update **不带** furthest_step,只回写 * step1/step2 内容,避免把「回到上一步继续研讨」误判成 furthest 回退。create * 分支用 currentStepRef 兜底建档步骤。 */ const enqueueSave = useCallback( (furthestStep?: 1 | 2 | 3): Promise => { const run = async (): Promise => { const step1 = getStep1Snapshot(); const step2 = getStep2Snapshot(); if (!hasSavableContent(step1, step2)) return null; const id = currentDraftIdRef.current; if (id) { const updated = await updateDraft(id, { ...(furthestStep !== undefined ? { furthestStep } : {}), step1, step2, }); if (updated) return updated.id; // 服务端已不存在(被删/换账号)→ 落回新建。 } const created = await createDraft({ title: deriveDraftName({ intentReady: step1.intentReady, interactiveMessages: step1.interactiveMessages, }), furthestStep: furthestStep ?? ((currentStepRef.current as 1 | 2 | 3) || 1), step1, step2, }); currentDraftIdRef.current = created.id; setCurrentDraftId(created.id); return created.id; }; const next = saveQueueRef.current.then(run, run); saveQueueRef.current = next.catch(() => undefined); return next as Promise; }, [getStep1Snapshot, getStep2Snapshot, hasSavableContent, setCurrentDraftId], ); const ensureDraft = useCallback( async (furthestStep: 1 | 2 | 3 = (currentStep as 1 | 2 | 3) || 1): Promise => { if (currentDraftIdRef.current) return currentDraftIdRef.current; const id = await enqueueSave(furthestStep); if (id) await refreshList(); return id; }, [currentStep, enqueueSave, refreshList], ); const handleManualSave = useCallback(() => { const furthest = (currentStep as 1 | 2 | 3) || 1; void (async () => { const id = await enqueueSave(furthest); if (id) { await refreshList(); triggerToast("💾 已保存为草稿"); } else { triggerToast("当前会话还没有可保存的内容"); } })(); }, [currentStep, enqueueSave, refreshList, triggerToast]); // 前进切换时自动保存;后退不保存以避免覆盖 furthestStep。 useEffect(() => { const prev = prevStepRef.current; prevStepRef.current = currentStep; if (currentStep > prev) { void (async () => { const id = await enqueueSave(currentStep as 1 | 2 | 3); if (id) await refreshList(); })(); } // eslint-disable-next-line react-hooks/exhaustive-deps }, [currentStep]); /** * 每轮模型回答完成后落一次草稿。不带 furthestStep(见 enqueueSave),只回写内容。 * 仅当本次保存是「新建」时才刷新列表 —— 普通增量回写无需让下拉重排/多发一个 GET。 */ const autoSave = useCallback(async (): Promise => { const hadId = currentDraftIdRef.current; const id = await enqueueSave(); if (id && !hadId) await refreshList(); }, [enqueueSave, refreshList]); // ── 触发器 1:Step 1 任务理解一轮回复结束(isIntentSending true→false)。 ── const prevIntentSendingRef = useRef(intentSending); useEffect(() => { const was = prevIntentSendingRef.current; prevIntentSendingRef.current = intentSending; // 此刻 React 已 flush 完终态 setState(气泡内容/INTENT_READY), // 快照 getter 读到的是收尾后的最新状态,不会丢最后一段。 if (was && !intentSending) void autoSave(); }, [intentSending, autoSave]); // ── 触发器 2:Step 2 某个气泡刚收尾(已收尾计数递增)。 ── // 加载草稿会把历史对话整批 hydrate 进来,计数从 0 跳到 N —— 那不是一次真实交付, // 用 suppress latch 跳过这一跳变(handleLoadDraft 在 hydrate 前置位)。 const prevFinalizedCountRef = useRef(step2FinalizedCount); const suppressStep2AutoSaveRef = useRef(false); useEffect(() => { const prev = prevFinalizedCountRef.current; prevFinalizedCountRef.current = step2FinalizedCount; if (suppressStep2AutoSaveRef.current) { suppressStep2AutoSaveRef.current = false; return; } if (step2FinalizedCount > prev) void autoSave(); }, [step2FinalizedCount, autoSave]); const handleLoadDraft = useCallback( (id: string) => { void (async () => { let draft; try { draft = await getDraft(id); } catch (err) { console.warn("[drafts] 加载草稿失败:", err); triggerToast("⚠️ 加载草稿失败,请重试"); return; } if (!draft) { triggerToast("⚠️ 该草稿已不存在"); await refreshList(); return; } cancelAllStreams(); // 先置 latch,再 setCurrentStep —— 顺序反过来会让 step1/step2 init effect // 把 loadedFromDraftRef.current 当成 false 处理,导致角色面板卡在「正在上线」。 loadedFromDraftRef.current = true; // hydrate 会让 step2 已收尾计数从 0 跳到 N,抑制由此触发的「假交付」自动保存, // 避免刚加载就把同样内容原样回写一遍、并把该草稿顶到列表最前。 suppressStep2AutoSaveRef.current = true; if (draft.step1) hydrateStep1(draft.step1 as Step1Snapshot); if (draft.step2) hydrateStep2(draft.step2 as Step2Snapshot); setStep2InitGate(draft.furthestStep >= 2); setCurrentDraftId(draft.id); setIsHistoryOpen(false); prevStepRef.current = draft.furthestStep; setCurrentStep(draft.furthestStep); triggerToast(`📂 已加载草稿:${draft.title}`); })(); }, [ cancelAllStreams, hydrateStep1, hydrateStep2, refreshList, setCurrentDraftId, setCurrentStep, setStep2InitGate, triggerToast, ], ); const handleDeleteDraft = useCallback( (id: string) => { if (typeof window !== "undefined" && !window.confirm("确定要删除这条历史记录吗?此操作不可恢复。")) { return; } void (async () => { try { await deleteDraft(id); } catch (err) { console.warn("[drafts] 删除草稿失败:", err); triggerToast("⚠️ 删除失败,请重试"); return; } await refreshList(); if (currentDraftIdRef.current === id) setCurrentDraftId(null); if (renamingDraftId === id) setRenamingDraftId(null); triggerToast("🗑 已删除历史记录"); })(); }, [refreshList, renamingDraftId, setCurrentDraftId, triggerToast], ); const handleStartRename = useCallback((draft: DraftListItem) => { setRenamingDraftId(draft.id); setRenameDraftValue(draft.name); }, []); const handleCommitRename = useCallback( (id: string) => { const trimmed = renameDraftValue.trim(); if (!trimmed) { setRenamingDraftId(null); setRenameDraftValue(""); return; } void (async () => { try { // 只发 title —— 与自动保存的「不带 title」互补,重命名是唯一改标题的入口。 const updated = await updateDraft(id, { title: trimmed }); if (updated) { await refreshList(); triggerToast("✏️ 已重命名"); } } catch (err) { console.warn("[drafts] 重命名失败:", err); triggerToast("⚠️ 重命名失败,请重试"); } finally { setRenamingDraftId(null); setRenameDraftValue(""); } })(); }, [refreshList, renameDraftValue, triggerToast], ); const handleCancelRename = useCallback(() => { setRenamingDraftId(null); setRenameDraftValue(""); }, []); // 点击外部收起下拉。只在打开时挂监听,关闭时立刻摘掉。 useEffect(() => { if (!isHistoryOpen) return; const handler = (e: MouseEvent) => { if (!historyDropdownRef.current) return; if (e.target instanceof Node && !historyDropdownRef.current.contains(e.target)) { setIsHistoryOpen(false); } }; document.addEventListener("mousedown", handler); return () => document.removeEventListener("mousedown", handler); }, [isHistoryOpen]); return { drafts, currentDraftId, isHistoryOpen, renamingDraftId, renameDraftValue, historyDropdownRef, loadedFromDraftRef, setIsHistoryOpen, setRenameDraftValue, setCurrentDraftId, handleManualSave, handleLoadDraft, handleDeleteDraft, handleStartRename, handleCommitRename, handleCancelRename, ensureDraft, }; }