@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/collab/seed.ts

@@ -0,0 +1,408 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 知识库协同快照种子化 helper（Yjs 多人协作 §5.2 双轨存储与首次种子化，
+// 任务 14）：业务列 KnowledgeDocument.content（编辑器 getHTML 产物存于
+// content.html）→ Y.Doc → CollabDocument 快照落库。
+//
+// 任务 20 扩展：Story 描述种子化（seedStoryDoc）——Story.description 是
+// Text 列存 serializeStoryDescription 的 JSON 字符串（{html, markdown} 双轨），
+// 编辑器与知识库同为 NotionDocEditor（扩展集一致），故种子 schema 复用
+// 知识库同一组合；差异仅在内容提取（extractStoryDescriptionHtml）与
+// room 名（entity:story:{id}）。
+//
+// 普通服务端模块（非 serverFn 文件）：getPrisma 惰性获取连接（只写
+// CollabDocument；业务列由调用方读取后作参数传入，单次读取）+ 组装
+// collab-core 默认集与 web 自定义追加集（knowledge-additions），由 serverFn
+// （serverFns/collab-snapshot.ts）与未来 collab 回写复用。
+//
+// 三态语义（§5.2，权威口径在规格）：
+// - 无 CollabDocument 且业务列有内容 → 种子化（本模块）后返回快照
+// - 有快照且业务列较新（旁路写入发生过，KnowledgeDocument.updatedAt vs
+//   CollabDocument.updatedAt）→ 重种子化（DB 内容覆盖 Y 快照）
+// - 正常 → 直读快照
+// 判定与编排在 serverFn；本模块专注「按 docId 种子化并落库」这一步。
+//
+// DOM 纪律：seedYDocFromHtml 的 generateJSON 依赖浏览器 DOM 全局；vitest
+// jsdom 环境天然满足，生产 Node 运行时（serverFn SSR bundle）由
+// ensureServerDom 懒加载 jsdom 注入全局（jsdom 为 apps/web 运行时依赖）。
+
+import * as Y from "yjs";
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import { buildRoomName } from "@allbluecn/collab-core/rooms";
+import { seedYDocFromHtml } from "@allbluecn/collab-core/tiptap-export";
+import { hasCanvasContent, seedYTreeFromCanvas } from "@allbluecn/collab-core/canvas-package";
+import {
+  applyStepsToDoc,
+  type CollabStep,
+} from "@allbluecn/collab-core/steps";
+import { createKnowledgeExtensions } from "@allbluecn/collab-core/knowledge-schema";
+import { createKnowledgeDocAdditions } from "./knowledge-additions";
+
+/**
+ * 生产 Node 运行时的 DOM 全局注入（幂等）。generateJSON/generateHTML 走
+ * DOMParser/document 解析管线；缺失时 tiptap-export 会 fail-loud，这里
+ * 提前补齐。vitest jsdom 环境与浏览器端直接跳过。
+ */
+async function ensureServerDom(): Promise<void> {
+  if (typeof window !== "undefined") return;
+  const { JSDOM } = await import("jsdom");
+  const dom = new JSDOM("<!doctype html><html><body></body></html>");
+  const target = globalThis as unknown as Record<string, unknown>;
+  const source = dom.window as unknown as Record<string, unknown>;
+  for (const key of [
+    "window",
+    "document",
+    "DOMParser",
+    "XMLSerializer",
+    "Node",
+    "Element",
+    "HTMLElement",
+    "DocumentFragment",
+    "HTMLSpanElement",
+    "HTMLImageElement",
+  ]) {
+    if (target[key] === undefined) target[key] = source[key];
+  }
+  // jsdom window 是 opaque origin（localStorage 访问抛 SecurityError）且不实现
+  // ResizeObserver；注入后同进程的 SSR 渲染树（React 组件读这些 API）会连环
+  // ReferenceError/SecurityError。补最小可渲染面：内存 localStorage + RO stub。
+  if (target["localStorage"] === undefined) {
+    const store = new Map<string, string>();
+    target["localStorage"] = {
+      getItem: (k: string) => (store.has(k) ? store.get(k)! : null),
+      setItem: (k: string, v: string) => void store.set(k, String(v)),
+      removeItem: (k: string) => void store.delete(k),
+      clear: () => void store.clear(),
+      key: (i: number) => Array.from(store.keys())[i] ?? null,
+      get length() {
+        return store.size;
+      },
+    };
+  }
+  if (target["ResizeObserver"] === undefined) {
+    target["ResizeObserver"] = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+}
+
+/**
+ * 解析 KnowledgeDocument.content（Json 列）为可种子化的 HTML。
+ * 与 NotionDocEditor getInitialContent 读取口径同构：
+ * - { html, markdown } 双轨（编辑器 onChange/updateDocumentFn 存储形态）→ html
+ * - { text } → 包裹为单段落（同编辑器兜底）
+ * - string → 包裹为单段落（历史数据兜底）
+ * 返回 null 表示「业务列无内容」（空对象 / 空串 / 编辑器空文档产物
+ * `<p></p>`、`<p><br></p>`）——此时无需种子化，客户端直接建空 Y.Doc。
+ */
+export function extractKnowledgeDocHtml(content: unknown): string | null {
+  let html: string | null = null;
+  if (typeof content === "object" && content !== null) {
+    const record = content as Record<string, unknown>;
+    if ("html" in record && typeof record.html === "string") {
+      html = record.html;
+    } else if ("text" in record && typeof record.text === "string") {
+      html = `<p>${record.text}</p>`;
+    }
+  } else if (typeof content === "string") {
+    html = `<p>${content}</p>`;
+  }
+  if (!html) return null;
+  const trimmed = html.trim();
+  if (
+    trimmed === "" ||
+    trimmed === "<p></p>" ||
+    trimmed === "<p><br></p>"
+  ) {
+    return null;
+  }
+  return html;
+}
+
+/**
+ * 知识库文档服务端种子化（§5.2）：默认集 + web 追加集构造 schema →
+ * seedYDocFromHtml → encodeStateAsUpdate → upsert CollabDocument。
+ * content 由调用方传入（serverFn 本次请求已读的业务列值，单次读取；
+ * 独立调用方可自行直查后传入）。返回快照 update 字节（调用方自行
+ * base64 编码给客户端 applyUpdate）。
+ *
+ * ⚠️ 仅限「协作开始前首次导入」与「旁路写入后的规格授权重种子化」（§5.2）；
+ * 协作进行中调用会丢协作历史，调用方须遵守三态判定。
+ */
+export async function seedKnowledgeDoc(
+  docId: string,
+  content: unknown,
+): Promise<Uint8Array> {
+  await ensureServerDom();
+  const html = extractKnowledgeDocHtml(content);
+  if (!html) {
+    throw new Error(`知识库文档无内容，无需种子化: ${docId}`);
+  }
+  const yDoc = seedYDocFromHtml(html, [
+    ...createKnowledgeExtensions(),
+    ...createKnowledgeDocAdditions(),
+  ]);
+  // new Uint8Array 拷贝出 Uint8Array<ArrayBuffer>（Prisma Bytes 入参的
+  // 精确泛型要求；Y.encodeStateAsUpdate 返回 ArrayBufferLike 视图）
+  const state = new Uint8Array(Y.encodeStateAsUpdate(yDoc));
+  const prisma = await getPrisma();
+  await prisma.collabDocument.upsert({
+    where: { roomName: buildRoomName({ kind: "knowledge-doc", docId }) },
+    create: {
+      roomName: buildRoomName({ kind: "knowledge-doc", docId }),
+      state,
+    },
+    update: { state },
+  });
+  return state;
+}
+
+/**
+ * Story description 服务端种子化（§5.2，任务 20）：extension 组合与知识库
+ * 种子化一致（Story 描述编辑器同为 NotionDocEditor，schema 等价）；room 为
+ * entity:story:{storyId}。description 由调用方传入（serverFn 本次请求已读的
+ * Story.description Text 列值）。返回快照 update 字节。
+ *
+ * ⚠️ 仅限「协作开始前首次导入」与「旁路写入后的规格授权重种子化」（§5.2）；
+ * 协作进行中调用会丢协作历史，调用方须遵守三态判定。
+ */
+export async function seedStoryDoc(
+  storyId: string,
+  description: string | null,
+): Promise<Uint8Array> {
+  await ensureServerDom();
+  const html = extractStoryDescriptionHtml(description);
+  if (!html) {
+    throw new Error(`需求描述无内容，无需种子化: ${storyId}`);
+  }
+  const yDoc = seedYDocFromHtml(html, [
+    ...createKnowledgeExtensions(),
+    ...createKnowledgeDocAdditions(),
+  ]);
+  const state = new Uint8Array(Y.encodeStateAsUpdate(yDoc));
+  const prisma = await getPrisma();
+  await prisma.collabDocument.upsert({
+    where: { roomName: buildRoomName({ kind: "entity-story", storyId }) },
+    create: {
+      roomName: buildRoomName({ kind: "entity-story", storyId }),
+      state,
+    },
+    update: { state },
+  });
+  return state;
+}
+
+/**
+ * 解析 Story.description（Text 列）为可种子化的 HTML。
+ * 存储形态：serializeStoryDescription 的 JSON 字符串（{html, markdown}，
+ * 与 components/story/types.ts parseStoryDescription 读取口径同构——服务端
+ * 不 import 组件模块，此处镜像其解析规则）；历史裸串数据兜底为整串 html。
+ * 返回 null 表示「业务列无内容」（null / 空串 / 编辑器空文档产物
+ * `<p></p>`、`<p><br></p>`）——无需种子化，客户端直接建空 Y.Doc。
+ */
+export function extractStoryDescriptionHtml(
+  description: string | null,
+): string | null {
+  let html: string | null = null;
+  if (description) {
+    try {
+      const parsed = JSON.parse(description) as { html?: unknown };
+      if (typeof parsed.html === "string") {
+        html = parsed.html;
+      }
+    } catch {
+      html = description;
+    }
+  }
+  if (!html) return null;
+  const trimmed = html.trim();
+  if (trimmed === "" || trimmed === "<p></p>" || trimmed === "<p><br></p>") {
+    return null;
+  }
+  return html;
+}
+
+// ── entity-bug / entity-case 种子化（任务 22，§7.1 entity room 行）────────
+//
+// Bug/TestCase 的 Y 属主面 = description fragment（仅 Bug）+ fields Y.Map +
+// steps Y.Array。种子化只覆盖「有正确单源初值」的面：
+// - description（Bug）：与 Story 同一 {html} 提取（Bug.description 与
+//   Story.description 存储同构）；S12 裁决 UI 本期不接协同编辑，但 room 结构
+//   自然预留——种子化照常（门卫转发的旁路写经 internal-apply 进 Y）。
+// - steps：**服务端必种**——步骤是列表（非 per-key LWW 的字段 Map），客户端
+//   各自从 DTO 初始化会以不同 clientID 重复插入同一批步骤（并发首写重复），
+//   服务端单源种子化是唯一防重复路径（fields 沿用 Story 先例不种——单值
+//   per-key LWW 无此问题，Y 未写的 key 由 UI overlay 回退 loader 值）。
+// - 空 Y.Array steps = 「Y 无意见」（业务 schema 步骤 min(1) 空集永不合法），
+//   Bug 无描述且无步骤 → 整体无内容可种 → 抛错由调用方判定（返回快照 null）。
+
+/** 与 story/知识库种子化完全同一扩展组合（默认集 + 追加集） */
+export function entityDocExtensions() {
+  return [...createKnowledgeExtensions(), ...createKnowledgeDocAdditions()];
+}
+
+/** 把归一化步骤列表灌入 Y.Doc 的 steps Y.Array（种子化与测试共用） */
+export function fillStepsYDoc(yDoc: Y.Doc, steps: CollabStep[]): void {
+  applyStepsToDoc(yDoc, steps);
+}
+
+/**
+ * Bug 服务端种子化（§5.2，任务 22）：room 为 entity:bug:{bugId}。html 与
+ * steps 由调用方预提取（serverFn 本次请求已读的 Bug.description /
+ * reproduceSteps，单次读取）；两者皆空抛错（调用方先判定「无内容」）。
+ * 返回快照 update 字节。
+ *
+ * ⚠️ 仅限「协作开始前首次导入」与「旁路写入后的规格授权重种子化」（§5.2）；
+ * 协作进行中调用会丢协作历史，调用方须遵守三态判定。
+ */
+export async function seedBugDoc(
+  bugId: string,
+  face: {
+    /** 预提取的 description HTML（null = Bug.description 无内容） */
+    html: string | null;
+    /** 预归一化的步骤列表（null = 无步骤） */
+    steps: CollabStep[] | null;
+  },
+): Promise<Uint8Array> {
+  await ensureServerDom();
+  if (!face.html && !face.steps) {
+    throw new Error(`BUG 无内容，无需种子化: ${bugId}`);
+  }
+  const yDoc = face.html ? seedYDocFromHtml(face.html, entityDocExtensions()) : new Y.Doc();
+  if (face.steps) fillStepsYDoc(yDoc, face.steps);
+  const state = new Uint8Array(Y.encodeStateAsUpdate(yDoc));
+  const prisma = await getPrisma();
+  await prisma.collabDocument.upsert({
+    where: { roomName: buildRoomName({ kind: "entity-bug", bugId }) },
+    create: {
+      roomName: buildRoomName({ kind: "entity-bug", bugId }),
+      state,
+    },
+    update: { state },
+  });
+  return state;
+}
+
+/**
+ * TestCase 服务端种子化（§5.2，任务 22）：room 为 entity:case:{caseId}。
+ * TestCase 无 description 列——Y 属主面只有 fields（不种，Story 先例）与
+ * steps（必种，防并发首写重复）；steps 空抛错（调用方先判定「无内容」）。
+ * 返回快照 update 字节。
+ *
+ * ⚠️ 仅限「协作开始前首次导入」与「旁路写入后的规格授权重种子化」（§5.2）。
+ */
+export async function seedCaseDoc(
+  caseId: string,
+  steps: CollabStep[] | null,
+): Promise<Uint8Array> {
+  await ensureServerDom();
+  if (!steps) {
+    throw new Error(`用例无步骤，无需种子化: ${caseId}`);
+  }
+  const yDoc = new Y.Doc();
+  fillStepsYDoc(yDoc, steps);
+  const state = new Uint8Array(Y.encodeStateAsUpdate(yDoc));
+  const prisma = await getPrisma();
+  await prisma.collabDocument.upsert({
+    where: { roomName: buildRoomName({ kind: "entity-case", caseId }) },
+    create: {
+      roomName: buildRoomName({ kind: "entity-case", caseId }),
+      state,
+    },
+    update: { state },
+  });
+  return state;
+}
+
+// ── design-canvas 种子化（任务 29，§7.1 设计画布行）───────────────────────
+//
+// DesignPage 的 Y 属主面 = canvas Y 树（T26 canvas-tree 契约）+ 文档 fragment
+// （同 room 双载体）。canvas 列为双格式存量（新 LeaferJSONPackage / 旧扁平
+// SceneDocument——saveCanvasNow 优先 engine.getJSON() 回落 sceneDoc 的历史
+// 产物），seedYTreeFromCanvas 双格式兼容（旧格式 = 惰性迁移，写回经导出器
+// 自然升级为权威格式）。
+
+/**
+ * 解析 DesignPage.content（Json 列，DocContent {html, markdown} 形态）为可
+ * 种子化的 HTML。与 use-design-page-load 的读取口径同构；历史 null / 空产物
+ * （`<p></p>`、`<p><br></p>`）→ null（文档面无内容，不种）。
+ */
+export function extractDesignDocHtml(content: unknown): string | null {
+  const html =
+    typeof content === "object" && content !== null && "html" in content
+      ? (content as { html?: unknown }).html
+      : undefined;
+  if (typeof html !== "string") return null;
+  const trimmed = html.trim();
+  if (trimmed === "" || trimmed === "<p></p>" || trimmed === "<p><br></p>") {
+    return null;
+  }
+  return html;
+}
+
+/** DesignPage.canvas 有可种子化内容（新格式非空 board / 旧格式有用户节点） */
+export function hasDesignCanvasContent(canvas: unknown): boolean {
+  return hasCanvasContent(canvas);
+}
+
+/**
+ * Design 画布服务端种子化（§5.2，任务 29）：room 为 canvas:design:{pageId}。
+ * canvas Y 树 + 文档 fragment 双面可只种其一；皆无内容抛错（调用方先判定
+ * 「无内容」——canvas 经 hasDesignCanvasContent、文档经 extractDesignDocHtml）。
+ * 返回快照 update 字节。
+ *
+ * ⚠️ 仅限「协作开始前首次导入」与「旁路写入后的规格授权重种子化」（§5.2）；
+ * 协作进行中调用会丢协作历史，调用方须遵守三态判定。
+ */
+export async function seedDesignPageDoc(
+  pageId: string,
+  face: {
+    /** DesignPage.canvas 列原值（双格式；null = 无画布面） */
+    canvas: unknown;
+    /** 预提取的文档 HTML（null = 文档面无内容） */
+    html: string | null;
+  },
+): Promise<Uint8Array> {
+  await ensureServerDom();
+  const yDoc = new Y.Doc();
+  let seeded = false;
+  if (face.canvas !== null && face.canvas !== undefined) {
+    seeded = seedYTreeFromCanvas(face.canvas, yDoc) || seeded;
+  }
+  if (face.html) {
+    const docSource = seedYDocFromHtml(face.html, entityDocExtensions());
+    Y.applyUpdate(yDoc, Y.encodeStateAsUpdate(docSource));
+    seeded = true;
+  }
+  if (!seeded) {
+    throw new Error(`设计页面无内容，无需种子化: ${pageId}`);
+  }
+  const state = new Uint8Array(Y.encodeStateAsUpdate(yDoc));
+  const prisma = await getPrisma();
+  await prisma.collabDocument.upsert({
+    where: { roomName: buildRoomName({ kind: "design-canvas", pageId }) },
+    create: {
+      roomName: buildRoomName({ kind: "design-canvas", pageId }),
+      state,
+    },
+    update: { state },
+  });
+  return state;
+}

package/src/server/collab/ticket-utils.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 协同 ticket 签发的工具函数（Yjs 多人协作 §4.2，serverFn 纯净纪律的拆分件）：
+// serverFns/collab.ts 只保留 createServerFn 产物，guest sub 生成 / 昵称兜底 /
+// avatarBrief 投影 / COLLAB_SECRET 读取 / 分享密码门禁复验在此实现。
+//
+// 仅服务端：依赖 node:crypto 与 share 密码校验链（@allbluecn/database/lib/share-utils），
+// 禁止任何客户端代码 import 本模块。
+
+import { randomUUID } from "node:crypto";
+import type { CollabAvatarBrief } from "@allbluecn/collab-core/types";
+import { verifySharePassword } from "@allbluecn/database/lib/share-utils";
+import { getClientIp } from "@allbluecn/kernel";
+import {
+  isSharePasswordBlocked,
+  recordSharePasswordFailure,
+  clearSharePasswordFailures,
+} from "@/server/middlewares/auth-rate-limit";
+
+/** ticket 有效期（§4.2：now+60s 覆盖「签发→建连」窗口，重连由客户端重取） */
+export const TICKET_TTL_SECONDS = 60;
+
+/**
+ * 读取 HMAC 签名密钥。缺失/为空一律抛错（配置缺失必须显式失败，
+ * 禁止静默用空密钥签名——signTicket 同口径）。
+ */
+export function getCollabSecret(): string {
+  const secret = process.env.COLLAB_SECRET;
+  if (!secret) {
+    throw new Error("COLLAB_SECRET 未配置：无法签发协作 ticket");
+  }
+  return secret;
+}
+
+/** 访客主体 id（§4.2：sub 形如 guest:{random}，每次签发独立，不落库） */
+export function newGuestSub(): string {
+  return `guest:${randomUUID()}`;
+}
+
+/** 访客昵称兜底：trim 后为空（未填 / 纯空白）→「访客」（§4.2） */
+export function normalizeNickname(raw?: string | null): string {
+  const trimmed = raw?.trim();
+  return trimmed ? trimmed : "访客";
+}
+
+/**
+ * session user → ticket avatarBrief 投影（§4.2：取 session）。
+ * session callback 对已登录用户恒回填三字段（DB 或随机生成），此处的
+ * 空值兜底仅作类型层防御：avatarConfig→null（协议允许），shape/color→空串
+ * （CollabTicketPayload 要求字符串；渲染端按空值回退首字母头像）。
+ */
+export function avatarBriefFromSessionUser(user: {
+  avatarConfig?: Record<string, number> | null;
+  bgShape?: string | null;
+  bgColor?: string | null;
+}): CollabAvatarBrief {
+  return {
+    avatarConfig: user?.avatarConfig ?? null,
+    bgShape: user?.bgShape ?? "",
+    bgColor: user?.bgColor ?? "",
+  };
+}
+
+/** 分享密码门禁的客户端 IP（取不到归入 unknown 桶，与 verifySharePasswordFn 同口径） */
+export function shareGateClientIp(request: Request): string | null {
+  try {
+    return getClientIp(request);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 分享密码门禁复验（§4.2「密码已过」的服务端判定，与 verifySharePasswordFn
+ * 复用同一校验原语与 SEC-10 限流：blocked 短路不触达校验；失败计数、成功清零）。
+ * 密码缺失或 Share 无哈希存储一律 fail-closed 返回 false。
+ */
+export async function verifyShareGatePassword(opts: {
+  ip: string | null;
+  password?: string;
+  storedPassword: string | null;
+}): Promise<boolean> {
+  if (isSharePasswordBlocked(opts.ip)) return false;
+  if (!opts.password || !opts.storedPassword) return false;
+  const ok = await verifySharePassword(opts.password, opts.storedPassword);
+  if (ok) {
+    clearSharePasswordFailures(opts.ip);
+  } else {
+    recordSharePasswordFailure(opts.ip);
+  }
+  return ok;
+}

package/src/server/collab/touch-snapshot.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// R11 touch 不变式的共享实现（审查修复）：web 侧对业务列的直写若**不含 Y
+// 属主面**（forwarded 组合 patch 剥离后的纯元数据写、或从不归协同 room 的
+// 字段写），@updatedAt 仍会被 bump——不回同步快照则 collab-snapshot 三态
+// 判定（businessUpdatedAt <= snapshot.updatedAt → 直读）误判旁路写，下次
+// 协同打开全量重种子化、Y 协作历史重置。同事务 touch 快照 updatedAt = 回读
+// 业务行 updatedAt，保持「快照不落后于非协同写」。
+//
+// ⚠ 调用方判定：仅「生效直写不含 Y 属主面」时调用；含 Y 属主面的直写
+// （pass-through/degraded 落 content/fields/steps/canvas）**刻意不 touch**
+// ——旁路写必须让业务列反超快照，重种子化兜底才有正确输入。先例：design
+// pages.ts updateDesignPageFn（web 侧镜像 T21 锚点 M② exporter touch）。
+//
+// 工具函数文件（非 serverFn）：仅由 serverFn handler / 服务器模块引用；
+// updateMany 对不存在快照计 0 天然跳过（不误建行，无快照文档零成本）。
+
+import type { Prisma } from "@allbluecn/database";
+
+/**
+ * 同事务 touch 协同快照 updatedAt = 业务行回读 updatedAt。
+ *
+ * @param tx 业务写入所在的 Prisma 事务客户端（必须与业务写同一事务——
+ *   分离提交时 crash 窗口会留下 businessUpdatedAt > snapshot.updatedAt，
+ *   触发伪旁路写重种子化）
+ * @param roomName §3.1 注册表 room 名（buildRoomName 产物）
+ * @param businessUpdatedAt 业务行写后回读的 updatedAt（@updatedAt bump 后值）
+ * @returns updateMany 计数（无快照 = 0，天然跳过）
+ */
+export async function touchCollabSnapshot(
+  tx: Prisma.TransactionClient,
+  roomName: string,
+  businessUpdatedAt: Date,
+): Promise<number> {
+  const result = await tx.collabDocument.updateMany({
+    where: { roomName },
+    data: { updatedAt: businessUpdatedAt },
+  });
+  return result.count;
+}