feat: 岗位会商命令幂等与圆桌后台作业租约调度

岗位会商写操作引入 command_id 幂等与版本锁,前端支持同键重试;圆桌后台作业改为 DB 租约 dispatcher、去重与草稿 outbox 补偿,并持久化 intent turns。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-14 11:08:12 +08:00
1 parent 4f536d9b39
commit 75963c9ad9
51 files changed
+4449 -670

No files matched your search

@@ -24,10 +24,12 @@ import {
deleteDraft,
deriveDraftName,
getDraft,
isDraftVersionConflictError,
listDrafts,
updateDraft,
type DraftCreatePayload,
type DraftRecord,
type DraftStep2RunSnapshot,
type DraftStep2Snapshot,
type DraftStep3Snapshot,
type DraftUpdatePayload,
@@ -42,6 +44,34 @@ import {
} from "@/roundtable-planning/api/task-drafts";
import type { JobStatus } from "@/roundtable-planning/lib/job-types";
/**
* 409 冲突后的 step2 合并:以**服务端**为基准,把本地 runs 按 id upsert 回去。
*
* 这样既保住并发写手(后台作业 / 另一个标签页)新增的 runs,又保留本标签页刚产出的
* run 内容。activeRunId 若本地显式有值则以本地为准(本标签页正在看的 run),否则保留
* 服务端值。其余 step2 顶层字段以本地为准(本地是最新交互态)。一致性来自 DB 版本号,
* 合并只是把双方都不丢地拼回来。
*/
function mergeStep2OnConflict(
local: DraftStep2Snapshot,
server: DraftStep2Snapshot | null,
): DraftStep2Snapshot {
if (!server) return local;
const byId = new Map<string, DraftStep2RunSnapshot>();
for (const run of server.runs ?? []) {
if (run?.id) byId.set(run.id, run);
}
for (const run of local.runs ?? []) {
if (run?.id) byId.set(run.id, run); // 本地覆盖同 id 的服务端 run
}
return {
...server,
...local,
runs: Array.from(byId.values()),
activeRunId: local.activeRunId ?? server.activeRunId,
};
}
/** 历史下拉渲染用的轻量列表项(`name` 映射自后端 `title`)。 */
export interface DraftListItem {
id: string;
@@ -198,6 +228,10 @@ export function useDraftPersistence(
// 同步镜像,供保存队列在 render 之前读到最新 id(修复重复建草稿竞态)。
const currentDraftIdRef = useRef<string | null>(null);
// 当前草稿的乐观锁版本号(本地副本基于的 server version)。update 时经 expectedVersion
// 回传;冲突(409)后重拉最新草稿、合并本地改动、用新版本号重试。load/create/update 成功
// 后同步刷新,保证下一次写基于最新版本。
const draftVersionRef = useRef<number | null>(null);
// 串行化所有写操作,避免并发 create。
const saveQueueRef = useRef<Promise<unknown>>(Promise.resolve());
// 当前步骤镜像 —— 自动保存(不带 furthestStep)落到 create 分支时,用它兜底建档步骤。
@@ -207,10 +241,12 @@ export function useDraftPersistence(
}, [currentStep]);
// 包一层 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;
if (next !== currentDraftIdRef.current) draftVersionRef.current = null;
currentDraftIdRef.current = next;
return next;
});
@@ -273,14 +309,40 @@ export function useDraftPersistence(
const id = currentDraftIdRef.current;
if (id) {
const updated = await apiUpdate(id, {
...(furthestStep !== undefined ? { furthestStep } : {}),
step1,
step2,
...(step3 ? { step3 } : {}),
});
if (updated) return updated.id;
// 服务端已不存在(被删/换账号)→ 落回新建。
try {
const updated = await apiUpdate(id, {
...(furthestStep !== undefined ? { furthestStep } : {}),
step1,
step2,
...(step3 ? { step3 } : {}),
...(draftVersionRef.current !== null ? { expectedVersion: draftVersionRef.current } : {}),
});
if (updated) {
draftVersionRef.current = updated.version;
return updated.id;
}
// 服务端已不存在(被删/换账号)→ 落回新建。
} catch (err) {
if (!isDraftVersionConflictError(err)) throw err;
// 乐观锁冲突:另一写手(后台作业 / 另一标签页 / 重命名)已推进版本。
// 重拉最新草稿,把本地 step2.runs 合并回去,用新版本号重试一次——双方都不丢。
const latest = await apiGet(id);
if (latest) {
const mergedStep2 = mergeStep2OnConflict(step2, latest.step2);
const retried = await apiUpdate(id, {
...(furthestStep !== undefined ? { furthestStep } : {}),
step1,
step2: mergedStep2,
...(step3 ? { step3 } : {}),
expectedVersion: latest.version,
});
if (retried) {
draftVersionRef.current = retried.version;
return retried.id;
}
}
// latest 为 null(被删)或重试仍 404 → 落回新建。
}
}
const created = await apiCreate({
...(taskIdRef.current ? { taskId: taskIdRef.current } : {}),
@@ -294,6 +356,7 @@ export function useDraftPersistence(
...(step3 ? { step3 } : {}),
});
currentDraftIdRef.current = created.id;
draftVersionRef.current = created.version;
setCurrentDraftId(created.id);
return created.id;
};
@@ -301,7 +364,7 @@ export function useDraftPersistence(
saveQueueRef.current = next.catch(() => undefined);
return next as Promise<string | null>;
},
[apiCreate, apiUpdate, getStep1Snapshot, getStep2Snapshot, getStep3Snapshot, hasSavableContent, setCurrentDraftId],
[apiCreate, apiGet, apiUpdate, getStep1Snapshot, getStep2Snapshot, getStep3Snapshot, hasSavableContent, setCurrentDraftId],
);
const ensureDraft = useCallback(
@@ -340,12 +403,35 @@ export function useDraftPersistence(
const run = async (): Promise<string | null> => {
const id = currentDraftIdRef.current;
if (id) {
const updated = await apiUpdate(id, { furthestStep, step2 });
if (updated) {
currentDraftIdRef.current = updated.id;
return updated.id;
try {
const updated = await apiUpdate(id, {
furthestStep,
step2,
...(draftVersionRef.current !== null ? { expectedVersion: draftVersionRef.current } : {}),
});
if (updated) {
currentDraftIdRef.current = updated.id;
draftVersionRef.current = updated.version;
return updated.id;
}
// 服务端已不存在 → 落回新建。
} catch (err) {
if (!isDraftVersionConflictError(err)) throw err;
// 冲突 → 重拉合并 runs 后用新版本号重试一次(与 enqueueSave 同策略)。
const latest = await apiGet(id);
if (latest) {
const retried = await apiUpdate(id, {
furthestStep,
step2: mergeStep2OnConflict(step2, latest.step2),
expectedVersion: latest.version,
});
if (retried) {
currentDraftIdRef.current = retried.id;
draftVersionRef.current = retried.version;
return retried.id;
}
}
}
// 服务端已不存在 → 落回新建。
}
const step1 = getStep1Snapshot();
if (!hasSavableContent(step1, step2)) return null;
@@ -360,6 +446,7 @@ export function useDraftPersistence(
step2,
});
currentDraftIdRef.current = created.id;
draftVersionRef.current = created.version;
setCurrentDraftId(created.id);
return created.id;
};
@@ -367,7 +454,7 @@ export function useDraftPersistence(
saveQueueRef.current = next.catch(() => undefined);
return next as Promise<string | null>;
},
[apiCreate, apiUpdate, getStep1Snapshot, hasSavableContent, setCurrentDraftId],
[apiCreate, apiGet, apiUpdate, getStep1Snapshot, hasSavableContent, setCurrentDraftId],
);
const handleManualSave = useCallback(() => {
@@ -463,6 +550,8 @@ export function useDraftPersistence(
setStep2InitGate(draft.furthestStep >= 2);
setCurrentDraftId(draft.id);
// 必须在 setCurrentDraftId 之后:切换草稿会先把版本复位,这里再打上加载到的版本。
draftVersionRef.current = draft.version;
setIsHistoryOpen(false);
prevStepRef.current = draft.furthestStep;
setCurrentStep(draft.furthestStep);
@@ -563,8 +652,12 @@ export function useDraftPersistence(
void (async () => {
try {
// 只发 title —— 与自动保存的「不带 title」互补,重命名是唯一改标题的入口。
// 不带 expectedVersion:部分更新不触碰内容字段,与自动保存并发时双方各写各的
// 字段;自动保存侧撞 409 会重拉合并重试(标题被保留),一致性由 DB 版本保证。
const updated = await apiUpdate(id, { title: trimmed });
if (updated) {
// 重命名的正是当前草稿 → 同步版本号,省掉下一次自动保存的一次 409 往返。
if (id === currentDraftIdRef.current) draftVersionRef.current = updated.version;
await refreshList();
triggerToast("已重命名");
}