@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/serverFns/__tests__/update-page-guard.test.ts

@@ -0,0 +1,276 @@
+// 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.
+
+// updateDesignPageFn × §5.3 写入门卫测试（Yjs 多人协作任务 29，结构对齐
+// update-bug-guard.test）：
+// - 门卫在 mutation 之前执行（T21 教训：网络 I/O 不进事务）
+// - patch 的 Y 属主面 = canvas（LeaferJSONPackage 原值）+ content（DocContent）；
+//   门卫双写不互吞：forwarded → Y 属主面从直写数据剥离
+// - 元数据（name/parentId/order）不归 Y：无属主面 pass-through（连查询都省）
+//   且与 Y 面组合时 forwarded 后仍直写
+// - 纯 Y patch forwarded → web 侧零 mutation（updateManyAndReturn 不调用，防
+//   误判旁路写触发重种子化）
+// - pass-through（无快照）→ 原行为零变化（全字段直写）
+// - C1 属主预检（design.userId）失败 → 短路，mutation 零发生
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@tanstack/react-start", () => {
+  const createServerFn = () => {
+    const capture: { validator?: unknown; handler?: unknown } = {};
+    const api = {
+      validator: (v: unknown) => {
+        capture.validator = v;
+        return api;
+      },
+      handler: (h: unknown) => {
+        capture.handler = h;
+        return async (args: { data: unknown }) => {
+          const v = capture.validator as { parse?: (d: unknown) => unknown } | undefined;
+          const data = v && v.parse ? v.parse(args.data) : args.data;
+          return (h as (p: { data: unknown }) => Promise<unknown>)({ data });
+        };
+      },
+    };
+    return api;
+  };
+  return { createServerFn };
+});
+vi.mock("@tanstack/react-start/server", () => ({ getRequest: () => ({}) }));
+
+const H = vi.hoisted(() => {
+  const fns = {
+    requireAuth: vi.fn(),
+    withCollabGuard: vi.fn(),
+    pageFindUnique: vi.fn(),
+    pageUpdateManyAndReturn: vi.fn(),
+    transaction: vi.fn(),
+    snapshotTouch: vi.fn(),
+  };
+  const prisma = {
+    designPage: {
+      findUnique: fns.pageFindUnique,
+      updateManyAndReturn: fns.pageUpdateManyAndReturn,
+    },
+    collabDocument: { updateMany: fns.snapshotTouch },
+    $transaction: fns.transaction,
+  };
+  return { fns, prisma };
+});
+const M = H.fns;
+const PRISMA = H.prisma;
+
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: async () => H.prisma,
+}));
+vi.mock("@allbluecn/kernel", () => ({
+  getServerSeam: () => ({ requireAuth: H.fns.requireAuth }),
+}));
+vi.mock("@/server/collab/write-guard", () => ({
+  withCollabGuard: H.fns.withCollabGuard,
+  COLLAB_GUARD_TTL_MS: 3000,
+}));
+
+import { updateDesignPageFn } from "../design/pages";
+
+const U = "u-1";
+const PAGE_ID = "pg-1";
+const CANVAS_PKG = { format: "leafer-json", version: 1, meta: {}, tree: { tag: "Group" } };
+const DOC_CONTENT = { html: "<p>文档</p>", markdown: "文档" };
+
+const pageRow = (over: Record<string, unknown> = {}) => ({
+  id: PAGE_ID,
+  designId: "dz-1",
+  parentId: null,
+  name: "页面一",
+  order: 0,
+  type: "page",
+  canvas: null,
+  content: null,
+  version: 1,
+  createdAt: new Date("2026-01-01T00:00:00Z"),
+  updatedAt: new Date("2026-01-02T00:00:00Z"),
+  ...over,
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  M.requireAuth.mockResolvedValue({ user: { id: U, username: "u1" } });
+  // verifyPageOwner 预检形态（select design.userId）缺省属主命中
+  M.pageFindUnique.mockResolvedValue({ design: { userId: U } });
+  M.pageUpdateManyAndReturn.mockResolvedValue([pageRow()]);
+  M.snapshotTouch.mockResolvedValue({ count: 1 });
+  // $transaction(fn) 直接以 prisma 本身作为 tx 执行（update-bug-guard 同款）
+  M.transaction.mockImplementation(async (fn: unknown) => {
+    if (Array.isArray(fn)) return Promise.all(fn);
+    return (fn as (tx: unknown) => Promise<unknown>)(PRISMA);
+  });
+  // 缺省门卫：无快照 pass-through（非协同态零行为变化）
+  M.withCollabGuard.mockResolvedValue({ kind: "pass-through", reason: "no-snapshot" });
+});
+
+/** 属主预检通过后返回 forwarded（忠实复刻门卫「先预检后转发」顺序） */
+function guardForwardsAfterAssert(): void {
+  M.withCollabGuard.mockImplementation(async (opts: { assertWriteAllowed?: () => Promise<void> }) => {
+    await opts.assertWriteAllowed?.();
+    return { kind: "forwarded" as const };
+  });
+}
+
+describe("updateDesignPageFn × §5.3 写入门卫", () => {
+  it("门卫在 mutation 之前执行，patch 携带 canvas/content 属主面", async () => {
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, canvas: CANVAS_PKG, content: DOC_CONTENT } });
+
+    expect(M.withCollabGuard).toHaveBeenCalledTimes(1);
+    expect(M.withCollabGuard).toHaveBeenCalledWith({
+      roomName: `canvas:design:${PAGE_ID}`,
+      docId: PAGE_ID,
+      actor: U,
+      patch: { canvas: CANVAS_PKG, content: DOC_CONTENT },
+      assertWriteAllowed: expect.any(Function),
+    });
+    const order = M.withCollabGuard.mock.invocationCallOrder[0]!;
+    const mutationOrder = M.pageUpdateManyAndReturn.mock.invocationCallOrder[0] ?? Number.MAX_SAFE_INTEGER;
+    expect(order).toBeLessThan(mutationOrder);
+  });
+
+  it("元数据-only（name）不触发门卫：无 Y 属主面连查询都省（直写原行为）", async () => {
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, name: "新页名" } });
+
+    expect(M.withCollabGuard).not.toHaveBeenCalled();
+    expect(M.pageUpdateManyAndReturn).toHaveBeenCalledWith({
+      where: { id: PAGE_ID, design: { userId: U } },
+      data: { name: "新页名" },
+    });
+  });
+
+  it("forwarded 纯 Y patch：Y 属主面剥离且零 mutation（updateManyAndReturn 不调用）", async () => {
+    guardForwardsAfterAssert();
+
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, canvas: CANVAS_PKG, content: DOC_CONTENT } });
+
+    expect(M.pageUpdateManyAndReturn).not.toHaveBeenCalled();
+    expect(M.pageFindUnique).toHaveBeenCalledWith({ where: { id: PAGE_ID } });
+  });
+
+  it("forwarded + 元数据组合：元数据照直写，Y 属主面剥离（双写不互吞）", async () => {
+    guardForwardsAfterAssert();
+
+    await updateDesignPageFn({
+      data: { pageId: PAGE_ID, name: "组合改名", order: 3, canvas: CANVAS_PKG },
+    });
+
+    expect(M.pageUpdateManyAndReturn).toHaveBeenCalledWith({
+      where: { id: PAGE_ID, design: { userId: U } },
+      data: { name: "组合改名", order: 3 },
+    });
+  });
+
+  it("pass-through（无快照）：全字段直写（非协同态零行为变化）", async () => {
+    await updateDesignPageFn({
+      data: { pageId: PAGE_ID, name: "n", canvas: CANVAS_PKG, content: DOC_CONTENT },
+    });
+
+    expect(M.pageUpdateManyAndReturn).toHaveBeenCalledWith({
+      where: { id: PAGE_ID, design: { userId: U } },
+      data: { name: "n", canvas: CANVAS_PKG, content: DOC_CONTENT },
+    });
+  });
+
+  it("C1 属主预检失败：短路抛错，mutation 零发生", async () => {
+    M.withCollabGuard.mockImplementation(async (opts: { assertWriteAllowed?: () => Promise<void> }) => {
+      await opts.assertWriteAllowed?.();
+      return { kind: "forwarded" as const };
+    });
+    // verifyPageOwner 反查：页面属主非当前用户（门卫预检即短路）
+    M.pageFindUnique.mockResolvedValue({ design: { userId: "owner-其他" } });
+
+    await expect(
+      updateDesignPageFn({ data: { pageId: PAGE_ID, canvas: CANVAS_PKG } }),
+    ).rejects.toThrow("无权限");
+    expect(M.pageUpdateManyAndReturn).not.toHaveBeenCalled();
+  });
+
+  it("degraded（collab 不可达 TTL）：照旧直写（信任重种子化兜底）", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, canvas: CANVAS_PKG } });
+
+    expect(M.pageUpdateManyAndReturn).toHaveBeenCalledWith({
+      where: { id: PAGE_ID, design: { userId: U } },
+      data: { canvas: CANVAS_PKG },
+    });
+  });
+});
+
+describe("updateDesignPageFn × R11 元数据直写同步 touch 快照", () => {
+  it("协同快照存在 + 元数据直写：同事务 touch collabDocument.updatedAt = 回读行 updatedAt", async () => {
+    const touchedAt = new Date("2026-01-03T00:00:00Z");
+    M.pageUpdateManyAndReturn.mockResolvedValue([pageRow({ updatedAt: touchedAt })]);
+
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, name: "改名" } });
+
+    // 同事务：updateManyAndReturn 与 touch 都经 $transaction 执行，且 touch 在写后
+    expect(M.transaction).toHaveBeenCalledTimes(1);
+    expect(M.pageUpdateManyAndReturn).toHaveBeenCalledWith({
+      where: { id: PAGE_ID, design: { userId: U } },
+      data: { name: "改名" },
+    });
+    expect(M.snapshotTouch).toHaveBeenCalledTimes(1);
+    expect(M.snapshotTouch).toHaveBeenCalledWith({
+      where: { roomName: `canvas:design:${PAGE_ID}` },
+      data: { updatedAt: touchedAt },
+    });
+    const writeOrder = M.pageUpdateManyAndReturn.mock.invocationCallOrder[0]!;
+    const touchOrder = M.snapshotTouch.mock.invocationCallOrder[0]!;
+    expect(touchOrder).toBeGreaterThan(writeOrder);
+  });
+
+  it("无快照时不误建：touch 走 updateMany 形态（计 0 即无行，永不 create/upsert）", async () => {
+    M.snapshotTouch.mockResolvedValue({ count: 0 });
+
+    const result = await updateDesignPageFn({ data: { pageId: PAGE_ID, order: 2 } });
+
+    // mock 不回写 patch（返回缺省行）——断言直写成功返回行本体
+    expect(result).toEqual(pageRow());
+    expect(M.snapshotTouch).toHaveBeenCalledWith({
+      where: { roomName: `canvas:design:${PAGE_ID}` },
+      data: { updatedAt: expect.any(Date) },
+    });
+  });
+
+  it("含 Y 属主面的直写（pass-through/degraded 落 canvas）不 touch：旁路写必须反超快照", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, canvas: CANVAS_PKG } });
+
+    expect(M.snapshotTouch).not.toHaveBeenCalled();
+  });
+
+  it("forwarded + 元数据组合：Y 属主面剥离后生效写入为元数据-only → 同样 touch", async () => {
+    guardForwardsAfterAssert();
+
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, name: "组合", canvas: CANVAS_PKG } });
+
+    expect(M.snapshotTouch).toHaveBeenCalledTimes(1);
+    expect(M.snapshotTouch).toHaveBeenCalledWith({
+      where: { roomName: `canvas:design:${PAGE_ID}` },
+      data: { updatedAt: expect.any(Date) },
+    });
+  });
+
+  it("forwarded 纯 Y patch：web 零 mutation 也零 touch（collab 侧 M② 负责）", async () => {
+    guardForwardsAfterAssert();
+
+    await updateDesignPageFn({ data: { pageId: PAGE_ID, canvas: CANVAS_PKG } });
+
+    expect(M.pageUpdateManyAndReturn).not.toHaveBeenCalled();
+    expect(M.snapshotTouch).not.toHaveBeenCalled();
+  });
+});