@allbluecn/web-app 0.18.1 → 0.18.3

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

@@ -0,0 +1,293 @@
+// 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.
+
+// updateTestCaseFn × §5.3 写入门卫测试（Yjs 多人协作任务 22，结构对齐
+// update-bug-guard.test / update-story-guard.test）：
+// - patch 的 Y 属主面 = 6 字段（title/precondition/type/priority/state/
+//   assigneeId）+ steps 归一化；门卫双写不互吞：forwarded → Y 属主面从直写
+//   数据剥离，version 不被 web 侧 bump（协同落库 version+1 由 collab 落库侧
+//   writeCaseColumns 维护——乐观锁对非协同客户端的语义由服务端落库时保证）
+// - expectedVersion 前置复核：版本冲突的 stale patch 在转发前短路（不得进 Y
+//   覆盖新协同态）；非协同态（pass-through）乐观锁行为零变化
+// - 非 Y 字段（folderId/storyId/automation）照旧直写
+// - pass-through（无快照）→ 原行为零变化（内容面变更 version+1 + 活动留痕）
+
+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(),
+    resolveStoryScopeProjectId: vi.fn(),
+    isUserInTeam: vi.fn(),
+    withCollabGuard: vi.fn(),
+    testCaseFindUnique: vi.fn(),
+    testCaseUpdate: vi.fn(),
+    projectActivityCreate: vi.fn(),
+    userFindUnique: vi.fn(),
+    memberFindUnique: vi.fn(),
+    folderFindUnique: vi.fn(),
+    storyFindUnique: vi.fn(),
+    sequenceCounterUpsert: vi.fn(),
+    projectFindUnique: vi.fn(),
+    collabDocumentUpdateMany: vi.fn(),
+    transaction: vi.fn(),
+  };
+  const prisma = {
+    testCase: { findUnique: fns.testCaseFindUnique, update: fns.testCaseUpdate },
+    projectActivity: { create: fns.projectActivityCreate },
+    user: { findUnique: fns.userFindUnique },
+    projectMember: { findUnique: fns.memberFindUnique },
+    testCaseFolder: { findUnique: fns.folderFindUnique },
+    story: { findUnique: fns.storyFindUnique },
+    sequenceCounter: { upsert: fns.sequenceCounterUpsert },
+    project: { findUnique: fns.projectFindUnique },
+    // R11 touch：纯非 Y 直写后同事务 touch 快照（无快照计 0）
+    collabDocument: { updateMany: fns.collabDocumentUpdateMany },
+    $transaction: fns.transaction,
+  };
+  return { fns, prisma };
+});
+const M = H.fns;
+const PRISMA = H.prisma;
+
+vi.mock("@allbluecn/database", () => ({ prisma: H.prisma, Prisma: {} }));
+vi.mock("@allbluecn/database/get-prisma", () => ({
+  getPrisma: async () => H.prisma,
+}));
+vi.mock("@/server/auth-helpers", () => ({ requireAuth: H.fns.requireAuth }));
+vi.mock("@/server/builtin-project", () => ({
+  resolveStoryScopeProjectId: H.fns.resolveStoryScopeProjectId,
+}));
+vi.mock("@/server/team-access", () => ({ isUserInTeam: H.fns.isUserInTeam }));
+vi.mock("@/server/collab/write-guard", () => ({
+  withCollabGuard: H.fns.withCollabGuard,
+  COLLAB_GUARD_TTL_MS: 3000,
+}));
+
+import { updateTestCaseFn } from "../testcase/testcase-crud";
+
+const U = "u-1";
+const P = "pr-1";
+const CASE_ID = "tc-1";
+const STEPS_JSON = {
+  steps: [
+    { order: 1, action: "步骤一", expected: "预期一" },
+    { order: 2, action: "步骤二" },
+  ],
+};
+
+const userBrief = (id: string) => ({
+  id,
+  username: `user-${id}`,
+  email: `${id}@example.com`,
+  avatarConfig: null,
+  bgShape: null,
+  bgColor: null,
+});
+
+const caseRow = (over: Record<string, unknown> = {}) => ({
+  id: CASE_ID,
+  identifier: "PRJ-TC1",
+  sequenceId: 1,
+  projectId: P,
+  folderId: null,
+  folder: null,
+  storyId: null,
+  story: null,
+  title: "旧标题",
+  precondition: null,
+  steps: STEPS_JSON,
+  type: "functional",
+  priority: "p1",
+  state: "approved",
+  version: 3,
+  automation: "none",
+  aiGenerated: false,
+  assignee: null,
+  assigneeId: null,
+  createdBy: userBrief(U),
+  archived: false,
+  archivedAt: null,
+  createdAt: new Date("2026-01-01T12:00:00Z"),
+  updatedAt: new Date("2026-01-02T12:00:00Z"),
+  ...over,
+});
+
+/** $transaction(fn) 直接以 prisma 本身作为 tx 执行 */
+const txMock = async (fn: unknown) => {
+  if (Array.isArray(fn)) return Promise.all(fn);
+  return (fn as (tx: unknown) => Promise<unknown>)(PRISMA);
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  M.requireAuth.mockResolvedValue({ user: { id: U } });
+  M.isUserInTeam.mockResolvedValue(true);
+  // 门卫属主预检与事务内重读各查一次：预检读 {projectId, version}
+  M.testCaseFindUnique.mockResolvedValue(caseRow());
+  M.testCaseUpdate.mockImplementation(async (args: { data: Record<string, unknown> }) =>
+    caseRow({
+      ...(args.data.title !== undefined && { title: args.data.title }),
+      ...(args.data.state !== undefined && { state: args.data.state }),
+      ...(args.data.version !== undefined && { version: 4 }),
+    }),
+  );
+  M.projectActivityCreate.mockResolvedValue({ id: "pa-1" });
+  M.userFindUnique.mockResolvedValue({ username: "user-u-2" });
+  M.memberFindUnique.mockResolvedValue({ status: "active" });
+  M.folderFindUnique.mockResolvedValue(null);
+  M.storyFindUnique.mockResolvedValue(null);
+  M.projectFindUnique.mockResolvedValue({ id: P, ownerId: "owner-1" });
+  M.collabDocumentUpdateMany.mockResolvedValue({ count: 1 });
+  M.transaction.mockImplementation(txMock);
+  // 缺省门卫：无快照 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("updateTestCaseFn × §5.3 写入门卫", () => {
+  it("门卫在事务之前执行（T21 教训：网络 I/O 不进事务）", async () => {
+    await updateTestCaseFn({ data: { id: CASE_ID, title: "新标题" } });
+
+    expect(M.withCollabGuard).toHaveBeenCalledTimes(1);
+    expect(M.withCollabGuard).toHaveBeenCalledWith({
+      roomName: `entity:case:${CASE_ID}`,
+      docId: CASE_ID,
+      actor: U,
+      patch: { fields: { title: "新标题" } },
+      assertWriteAllowed: expect.any(Function),
+    });
+    const order = M.withCollabGuard.mock.invocationCallOrder[0]!;
+    const existingOrder = M.testCaseFindUnique.mock.invocationCallOrder[0]!;
+    expect(order).toBeLessThan(existingOrder);
+  });
+
+  it("patch 面：6 字段 + steps 归一化转发（order 剥离）", async () => {
+    await updateTestCaseFn({
+      data: { id: CASE_ID, title: "新标题", state: "in_review", steps: STEPS_JSON },
+    });
+
+    expect(M.withCollabGuard).toHaveBeenCalledWith(
+      expect.objectContaining({
+        patch: {
+          fields: { title: "新标题", state: "in_review" },
+          steps: [
+            { action: "步骤一", expected: "预期一" },
+            { action: "步骤二" },
+          ],
+        },
+      }),
+    );
+  });
+
+  it("pass-through（无快照）→ 非协同态零行为变化：直写 + 内容面 version+1 + 活动留痕", async () => {
+    const res = await updateTestCaseFn({
+      data: { id: CASE_ID, title: "新标题", expectedVersion: 3 },
+    });
+
+    const args = M.testCaseUpdate.mock.calls[0]![0];
+    expect(args.where).toEqual({ id: CASE_ID });
+    expect(args.data).toMatchObject({ title: "新标题", version: { increment: 1 } });
+    expect(M.projectActivityCreate).toHaveBeenCalledTimes(1);
+    expect(res.version).toBe(4);
+  });
+
+  it("pass-through + expectedVersion 不符 → 乐观锁拒绝（非协同态行为零变化）", async () => {
+    M.testCaseFindUnique.mockResolvedValue(caseRow({ version: 9 }));
+    await expect(
+      updateTestCaseFn({ data: { id: CASE_ID, title: "新标题", expectedVersion: 3 } }),
+    ).rejects.toThrow("用例已被他人修改（版本冲突）");
+    expect(M.testCaseUpdate).not.toHaveBeenCalled();
+  });
+
+  it("forwarded + expectedVersion 不符 → 属主预检前置短路（stale patch 不得进 Y）", async () => {
+    guardForwardsAfterAssert();
+    // 预检读 {projectId, version}（首调），事务内重读整行（次调）
+    M.testCaseFindUnique
+      .mockResolvedValueOnce(caseRow({ version: 9 }))
+      .mockResolvedValueOnce(caseRow({ version: 9 }));
+
+    await expect(
+      updateTestCaseFn({ data: { id: CASE_ID, title: "stale 标题", expectedVersion: 3 } }),
+    ).rejects.toThrow("用例已被他人修改（版本冲突）");
+    expect(M.testCaseUpdate).not.toHaveBeenCalled();
+    // 门卫转发未发生（预检在 mock 门卫内先执行——真实门卫语义下即不触网络）
+    expect(M.withCollabGuard).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwarded + 纯 Y patch → web 侧零 mutation：不 update、version 不 bump、活动零留痕", async () => {
+    guardForwardsAfterAssert();
+    const res = await updateTestCaseFn({
+      data: { id: CASE_ID, title: "新标题", steps: STEPS_JSON },
+    });
+
+    expect(M.testCaseUpdate).not.toHaveBeenCalled();
+    expect(M.projectActivityCreate).not.toHaveBeenCalled();
+    // 响应回读 existing（version 保持服务端现值，不虚增）
+    expect(res.version).toBe(3);
+  });
+
+  it("forwarded → Y 属主面剥离；非 Y 字段（automation/folderId）照旧直写", async () => {
+    guardForwardsAfterAssert();
+    M.folderFindUnique.mockResolvedValue({ id: "f-1", projectId: P });
+    await updateTestCaseFn({
+      data: { id: CASE_ID, title: "新标题", automation: "e2e", folderId: "f-1" },
+    });
+
+    const args = M.testCaseUpdate.mock.calls[0]![0];
+    expect(args.data).toMatchObject({ automation: "e2e", folder: { connect: { id: "f-1" } } });
+    expect(args.data.title).toBeUndefined(); // Y 属主
+    expect(args.data.version).toBeUndefined(); // 内容面全被剥离，web 侧不 bump
+    expect(M.projectActivityCreate).toHaveBeenCalledTimes(1); // 非 Y 直写仍留痕
+    // R11 touch：生效直写为纯非 Y patch → 同事务 touch 快照（防误判旁路写）
+    expect(M.collabDocumentUpdateMany).toHaveBeenCalledWith({
+      where: { roomName: `entity:case:${CASE_ID}` },
+      data: { updatedAt: caseRow().updatedAt },
+    });
+  });
+
+  it("forwarded/降级直写含 Y 属主面 → 不 touch（旁路反超语义，R11）", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+    await updateTestCaseFn({ data: { id: CASE_ID, automation: "e2e", state: "in_review" } });
+
+    const args = M.testCaseUpdate.mock.calls[0]![0];
+    expect(args.data.state).toBe("in_review"); // Y 属主直写（旁路）
+    expect(M.collabDocumentUpdateMany).not.toHaveBeenCalled();
+  });
+});

package/src/server/serverFns/bug/__tests__/bug-crud.test.ts

@@ -67,6 +67,9 @@ const mocks = vi.hoisted(() => ({
   storyFindUnique: vi.fn(),
   testRunCaseFindUnique: vi.fn(),
   testRunCaseUpdateMany: vi.fn(),
+  collabDocumentFindUnique: vi.fn(),
+  collabDocumentUpdateMany: vi.fn(),
+  collabDocumentDeleteMany: vi.fn(),
 }));
 
 vi.mock("@allbluecn/database", () => {
@@ -89,7 +92,16 @@ vi.mock("@allbluecn/database", () => {
     user: { findUnique: mocks.userFindUnique },
     story: { findUnique: mocks.storyFindUnique },
     testRunCase: { findUnique: mocks.testRunCaseFindUnique, updateMany: mocks.testRunCaseUpdateMany },
-    $transaction: (cb: any) => cb(prisma),
+    // 任务 22 写入门卫快照检查：恒 null = 无快照 pass-through（非协同态零行为变化）
+    // R11 touch / §5.2 删除清理：updateMany（touch）/ deleteMany（快照清理）
+    collabDocument: {
+      findUnique: mocks.collabDocumentFindUnique,
+      updateMany: mocks.collabDocumentUpdateMany,
+      deleteMany: mocks.collabDocumentDeleteMany,
+    },
+    // $transaction 双形态：交互式（fn 回调传入同一 prisma 形状）与数组（Promise.all）
+    $transaction: (arg: any) =>
+      Array.isArray(arg) ? Promise.all(arg) : arg(prisma),
   };
   return { prisma, Prisma: {} };
 });
@@ -161,6 +173,9 @@ beforeEach(() => {
     user: null,
   }));
   mocks.projectActivityCreate.mockResolvedValue({});
+  // R11 touch / §5.2 删除清理：缺省给足返回形状（无快照计 0）
+  mocks.collabDocumentUpdateMany.mockResolvedValue({ count: 0 });
+  mocks.collabDocumentDeleteMany.mockResolvedValue({ count: 0 });
 });
 
 describe("listBugsFn", () => {
@@ -497,7 +512,7 @@ describe("updateBugFn", () => {
 });
 
 describe("deleteBugFn", () => {
-  it("项目成员可删除", async () => {
+  it("项目成员可删除，且同事务清理协同快照行（§5.2 幽灵 room 防务）", async () => {
     mocks.bugFindUnique.mockResolvedValue({ id: "b1", projectId: "p1" });
     mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
     mocks.bugDelete.mockResolvedValue(bugRow);
@@ -508,6 +523,10 @@ describe("deleteBugFn", () => {
       select: { status: true },
     });
     expect(mocks.bugDelete).toHaveBeenCalledWith({ where: { id: "b1" } });
+    // Important 3：实体删后快照行必删（room 命名与 collab-core 注册表一致）
+    expect(mocks.collabDocumentDeleteMany).toHaveBeenCalledWith({
+      where: { roomName: "entity:bug:b1" },
+    });
   });
 
   it("非项目成员拒绝删除且不触删除", async () => {
@@ -590,11 +609,18 @@ describe("archiveBugFn / unarchiveBugFn", () => {
   });
 });
 
-// assertBugsInMemberProjects 与事务内查询共用 bugFindMany mock，按 select 形状分流：
-// 成员圈定查询 select {projectId: true} → 只回 projectId；其余（事务内行查询）回原 rows
+// assertBugsInMemberProjects 与事务外行查询共用 bugFindMany mock，按 select 形状分流：
+// 成员圈定查询 select 仅 {projectId: true} 单键 → 只回 projectId；其余（bulk 行
+// 查询/bulkArchive 行查询）回原 rows
 function mockBugFindManyByScope(rows: unknown[]) {
-  mocks.bugFindMany.mockImplementation(async (args: { select?: { projectId?: boolean } }) => {
-    if (args?.select?.projectId) return rows.map((r) => ({ projectId: (r as { projectId: string }).projectId }));
+  mocks.bugFindMany.mockImplementation(async (args: { select?: Record<string, unknown> }) => {
+    if (
+      args?.select &&
+      Object.keys(args.select).length === 1 &&
+      "projectId" in args.select
+    ) {
+      return rows.map((r) => ({ projectId: (r as { projectId: string }).projectId }));
+    }
     return rows;
   });
 }
@@ -655,7 +681,7 @@ describe("bulkArchiveBugsFn", () => {
 });
 
 describe("bulkDeleteBugsFn", () => {
-  it("项目成员批量删除并返回 deleted 计数", async () => {
+  it("项目成员批量删除并返回 deleted 计数，聚合 roomNames 一次清理快照行", async () => {
     mockBugFindManyByScope([
       { id: "a", projectId: "p1" },
       { id: "b", projectId: "p1" },
@@ -666,6 +692,10 @@ describe("bulkDeleteBugsFn", () => {
     const out = await bulkDeleteBugsFn({ data: { bugIds: ["a", "b", "c"] } });
     expect(out).toEqual({ deleted: 3 });
     expect(mocks.bugDeleteMany).toHaveBeenCalledWith({ where: { id: { in: ["a", "b", "c"] } } });
+    // Important 3：聚合 in 查询一次清理（deleteMany 不误建不报错）
+    expect(mocks.collabDocumentDeleteMany).toHaveBeenCalledWith({
+      where: { roomName: { in: ["entity:bug:a", "entity:bug:b", "entity:bug:c"] } },
+    });
   });
 
   it("非项目成员批量删除被拒且不触删除", async () => {
@@ -729,3 +759,194 @@ describe("bulkUpdateBugsFn", () => {
     ).rejects.toThrow();
   });
 });
+
+// ── R11 touch 不变式（审查 Important 1）：生效直写不含 Y 属主面时同事务
+// touch 快照；含 Y 属主面的直写保持旁路语义不 touch ──────────────────────
+
+describe("updateBugFn × R11 touch 不变式", () => {
+  it("纯非 Y patch（url）→ 同事务 touch 快照（updatedAt = 回读行值）", async () => {
+    mocks.bugFindUnique.mockResolvedValue(bugRow);
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    const TOUCH_AT = new Date("2026-02-02T00:00:00Z");
+    mocks.bugUpdate.mockResolvedValue({ ...bugRow, url: "https://x.example.com", updatedAt: TOUCH_AT });
+    mocks.collabDocumentUpdateMany.mockResolvedValue({ count: 1 });
+
+    await updateBugFn({ data: { bugId: "b1", url: "https://x.example.com" } });
+
+    expect(mocks.collabDocumentUpdateMany).toHaveBeenCalledWith({
+      where: { roomName: "entity:bug:b1" },
+      data: { updatedAt: TOUCH_AT },
+    });
+  });
+
+  it("含 Y 属主面的直写（state，无快照 pass-through）→ 不 touch（旁路反超语义）", async () => {
+    mocks.bugFindUnique.mockResolvedValue(bugRow);
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    mocks.bugUpdate.mockResolvedValue({ ...bugRow, state: "fixed" });
+
+    await updateBugFn({ data: { bugId: "b1", state: "fixed" } });
+
+    expect(mocks.bugUpdate).toHaveBeenCalled();
+    expect(mocks.collabDocumentUpdateMany).not.toHaveBeenCalled();
+  });
+
+  it("forwarded 组合 patch（快照存在 + collab 可达）：Y 面剥离、纯非 Y 直写后 touch", async () => {
+    vi.stubEnv("COLLAB_INTERNAL_URL", "http://collab.test:3030");
+    vi.stubEnv("COLLAB_SECRET", "test-secret");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("{}", { status: 202 })));
+    mocks.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    mocks.bugFindUnique.mockResolvedValue(bugRow);
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    const TOUCH_AT = new Date("2026-03-03T00:00:00Z");
+    mocks.bugUpdate.mockResolvedValue({ ...bugRow, url: "https://x.example.com", updatedAt: TOUCH_AT });
+    mocks.collabDocumentUpdateMany.mockResolvedValue({ count: 1 });
+
+    try {
+      // description 是 Y 属主面（content）→ 转发；url 非 Y → 照旧直写
+      await updateBugFn({ data: { bugId: "b1", description: "<p>x</p>", url: "https://x.example.com" } });
+
+      // 直写数据剥离 Y 属主面（description 不落库）
+      const updateCall = mocks.bugUpdate.mock.calls[0][0] as { data: Record<string, unknown> };
+      expect(updateCall.data.description).toBeUndefined();
+      expect(updateCall.data.url).toBe("https://x.example.com");
+      // 生效直写为纯非 Y patch → touch（R11）
+      expect(mocks.collabDocumentUpdateMany).toHaveBeenCalledWith({
+        where: { roomName: "entity:bug:b1" },
+        data: { updatedAt: TOUCH_AT },
+      });
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+      warn.mockRestore();
+    }
+  });
+
+  it("forwarded 纯 Y patch（剥离后零直写）→ 零 mutation 零 touch（不 bump updatedAt）", async () => {
+    vi.stubEnv("COLLAB_INTERNAL_URL", "http://collab.test:3030");
+    vi.stubEnv("COLLAB_SECRET", "test-secret");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("{}", { status: 202 })));
+    mocks.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    mocks.bugFindUnique.mockResolvedValue(bugRow);
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+
+    try {
+      await updateBugFn({ data: { bugId: "b1", state: "fixed" } });
+
+      expect(mocks.bugUpdate).not.toHaveBeenCalled();
+      expect(mocks.collabDocumentUpdateMany).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+      warn.mockRestore();
+    }
+  });
+});
+
+// ── bulkUpdateBugsFn × 协同门卫（审查 Important 2）：批量 patch 全为 Y 属主
+// 字段——快照存在一律转发（防活跃协同期互吞本体）；降级/无快照照旧直写 ────
+
+describe("bulkUpdateBugsFn × 协同门卫三态", () => {
+  const bulkRows = () => [
+    { id: "a", projectId: "p1", state: "open", severity: "medium", assignee: null, labels: [] },
+    { id: "b", projectId: "p1", state: "fixed", severity: "medium", assignee: null, labels: [] },
+  ];
+
+  beforeEach(() => {
+    mocks.projectMemberFindMany.mockResolvedValue([{ projectId: "p1" }]);
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    mocks.bugUpdate.mockResolvedValue({});
+  });
+
+  it("forwarded：快照存在 + collab 可达 → Y 属主面剥离（零直写零活动），计入 updated", async () => {
+    vi.stubEnv("COLLAB_INTERNAL_URL", "http://collab.test:3030");
+    vi.stubEnv("COLLAB_SECRET", "test-secret");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const fetchMock = vi.fn().mockResolvedValue(new Response("{}", { status: 202 }));
+    vi.stubGlobal("fetch", fetchMock);
+    mockBugFindManyByScope(bulkRows());
+
+    try {
+      const out = await bulkUpdateBugsFn({ data: { bugIds: ["a", "b"], patch: { state: "in_progress" } } });
+
+      expect(out).toEqual({ updated: 2 });
+      // 直写与活动剥离（collab 落库侧产出）——互吞防务本体
+      expect(mocks.bugUpdate).not.toHaveBeenCalled();
+      expect(mocks.bugActivityCreate).not.toHaveBeenCalled();
+      // per-bug 信封 fields 面齐备（仅变化字段，updateBugFn 口径）
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      const body = JSON.parse(String(fetchMock.mock.calls[0]![1]!.body)) as {
+        patch: { fields: Record<string, unknown> };
+      };
+      expect(body.patch).toEqual({ fields: { state: "in_progress" } });
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+      warn.mockRestore();
+    }
+  });
+
+  it("degraded：快照存在但 COLLAB_INTERNAL_URL 未配置 → 降级直写（既有语义）", async () => {
+    vi.stubEnv("COLLAB_INTERNAL_URL", "");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubGlobal("fetch", vi.fn());
+    mocks.collabDocumentFindUnique.mockResolvedValue({ id: "snap-1" });
+    mockBugFindManyByScope(bulkRows());
+
+    try {
+      const out = await bulkUpdateBugsFn({ data: { bugIds: ["a", "b"], patch: { state: "in_progress" } } });
+
+      expect(out).toEqual({ updated: 2 });
+      expect(mocks.bugUpdate).toHaveBeenCalledTimes(2);
+      expect(mocks.bugActivityCreate).toHaveBeenCalledTimes(2);
+      expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+      // 直写全为 Y 属主面 → 不 touch（R11 旁路反超语义）
+      expect(mocks.collabDocumentUpdateMany).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+      warn.mockRestore();
+    }
+  });
+
+  it("pass-through：无快照 → 照旧直写（非协同态零行为变化，不触网络）", async () => {
+    vi.stubGlobal("fetch", vi.fn());
+    mockBugFindManyByScope(bulkRows());
+
+    try {
+      const out = await bulkUpdateBugsFn({ data: { bugIds: ["a", "b"], patch: { state: "in_progress" } } });
+
+      expect(out).toEqual({ updated: 2 });
+      expect(mocks.bugUpdate).toHaveBeenCalledTimes(2);
+      expect(mocks.bugActivityCreate).toHaveBeenCalledTimes(2);
+      expect(vi.mocked(globalThis.fetch)).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("同值 bug 零变化 → 不进门卫（零快照查询）不直写", async () => {
+    vi.stubEnv("COLLAB_INTERNAL_URL", "http://collab.test:3030");
+    vi.stubEnv("COLLAB_SECRET", "test-secret");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    mockBugFindManyByScope([
+      { id: "a", projectId: "p1", state: "in_progress", severity: "medium", assignee: null, labels: [] },
+    ]);
+
+    try {
+      const out = await bulkUpdateBugsFn({ data: { bugIds: ["a"], patch: { state: "in_progress" } } });
+
+      expect(out).toEqual({ updated: 0 });
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(mocks.collabDocumentFindUnique).not.toHaveBeenCalled();
+      expect(mocks.bugUpdate).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+      warn.mockRestore();
+    }
+  });
+});