新增 /api/roundtable-drafts 草稿 CRUD 与会话级推荐历史;前端 useDraftPersistence 改走 api/drafts,删除本地 drafts.ts。 Co-authored-by: Cursor <cursoragent@cursor.com>
368 lines
13 KiB
TypeScript
368 lines
13 KiB
TypeScript
/**
|
||
* 圆桌规划草稿持久化 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<React.SetStateAction<number>>;
|
||
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;
|
||
}
|
||
|
||
export interface UseDraftPersistenceReturn {
|
||
drafts: DraftListItem[];
|
||
currentDraftId: string | null;
|
||
isHistoryOpen: boolean;
|
||
renamingDraftId: string | null;
|
||
renameDraftValue: string;
|
||
historyDropdownRef: React.MutableRefObject<HTMLDivElement | null>;
|
||
loadedFromDraftRef: React.MutableRefObject<boolean>;
|
||
setIsHistoryOpen: React.Dispatch<React.SetStateAction<boolean>>;
|
||
setRenameDraftValue: React.Dispatch<React.SetStateAction<string>>;
|
||
setCurrentDraftId: React.Dispatch<React.SetStateAction<string | null>>;
|
||
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<string | null>;
|
||
}
|
||
|
||
export function useDraftPersistence(
|
||
options: UseDraftPersistenceOptions,
|
||
): UseDraftPersistenceReturn {
|
||
const {
|
||
currentStep,
|
||
setCurrentStep,
|
||
triggerToast,
|
||
getStep1Snapshot,
|
||
getStep2Snapshot,
|
||
hydrateStep1,
|
||
hydrateStep2,
|
||
cancelAllStreams,
|
||
setStep2InitGate,
|
||
} = options;
|
||
|
||
const [drafts, setDrafts] = useState<DraftListItem[]>([]);
|
||
const [currentDraftId, setCurrentDraftIdState] = useState<string | null>(null);
|
||
const [isHistoryOpen, setIsHistoryOpen] = useState<boolean>(false);
|
||
const [renamingDraftId, setRenamingDraftId] = useState<string | null>(null);
|
||
const [renameDraftValue, setRenameDraftValue] = useState<string>("");
|
||
|
||
const loadedFromDraftRef = useRef<boolean>(false);
|
||
const prevStepRef = useRef<number>(currentStep);
|
||
const historyDropdownRef = useRef<HTMLDivElement | null>(null);
|
||
|
||
// 同步镜像,供保存队列在 render 之前读到最新 id(修复重复建草稿竞态)。
|
||
const currentDraftIdRef = useRef<string | null>(null);
|
||
// 串行化所有写操作,避免并发 create。
|
||
const saveQueueRef = useRef<Promise<unknown>>(Promise.resolve());
|
||
|
||
// 包一层 setter:同时更新 state 与同步 ref。主页面通过它 setCurrentDraftId(null)。
|
||
const setCurrentDraftId = useCallback<React.Dispatch<React.SetStateAction<string | null>>>(
|
||
(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)。
|
||
*/
|
||
const enqueueSave = useCallback(
|
||
(furthestStep: 1 | 2 | 3): Promise<string | null> => {
|
||
const run = async (): Promise<string | null> => {
|
||
const step1 = getStep1Snapshot();
|
||
const step2 = getStep2Snapshot();
|
||
if (!hasSavableContent(step1, step2)) return null;
|
||
|
||
const id = currentDraftIdRef.current;
|
||
if (id) {
|
||
const updated = await updateDraft(id, { furthestStep, step1, step2 });
|
||
if (updated) return updated.id;
|
||
// 服务端已不存在(被删/换账号)→ 落回新建。
|
||
}
|
||
const created = await createDraft({
|
||
title: deriveDraftName({
|
||
intentReady: step1.intentReady,
|
||
interactiveMessages: step1.interactiveMessages,
|
||
}),
|
||
furthestStep,
|
||
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<string | null>;
|
||
},
|
||
[getStep1Snapshot, getStep2Snapshot, hasSavableContent, setCurrentDraftId],
|
||
);
|
||
|
||
const ensureDraft = useCallback(
|
||
async (furthestStep: 1 | 2 | 3 = (currentStep as 1 | 2 | 3) || 1): Promise<string | null> => {
|
||
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]);
|
||
|
||
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;
|
||
|
||
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,
|
||
};
|
||
}
|