@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,436 @@
+// 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/>.
+
+// updateStoryFn / transferStoryAsChildFn / deleteStoryFn × §5.3 写入门卫测试
+// （Yjs 多人协作任务 21，结构对齐任务 17 的 update-document-guard.test）：
+// - pass-through（无快照）→ 原行为零变化（非协同态回归：全字段直写 + 活动记录
+//   + updatedBy，逐字段与既有 story-crud.test 断言同口径）
+// - forwarded → Y 属主面（description + 8 字段）从直写数据与活动流剥离；
+  // 纯 Y patch 时 web 侧零 mutation（不 bump updatedAt——防误判旁路写触发重
+  // 种子化）；非 Y 字段（projectId/iterationId）照旧直写
+// - degraded → 同原行为（信任重种子化兜底）
+// - C1 属主预检（项目成员资格）失败 → 短路，mutation 零发生
+// - deleteStoryFn：实体删除与协同快照清理同事务（任务 16 知识库删除路径同构）
+// - transferStoryAsChildFn（T20 发现的父需求弹窗旁路）：forwarded 剥离
+//   parentId 直写与 parent_changed 活动
+
+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(),
+    ensureBuiltinIndependentProject: vi.fn(),
+    resolveStoryScopeProjectId: vi.fn(),
+    isUserInTeam: vi.fn(),
+    withCollabGuard: vi.fn(),
+    projectFindUnique: vi.fn(),
+    projectFindMany: vi.fn(),
+    storyFindUnique: vi.fn(),
+    storyFindMany: vi.fn(),
+    storyUpdate: vi.fn(),
+    storyDelete: vi.fn(),
+    storyActivityCreate: vi.fn(),
+    sequenceCounterUpsert: vi.fn(),
+    userFindUnique: vi.fn(),
+    iterationFindUnique: vi.fn(),
+    memberFindUnique: vi.fn(),
+    collabDocumentDeleteMany: vi.fn(),
+    collabDocumentUpdateMany: vi.fn(),
+    transaction: vi.fn(),
+  };
+  const prisma = {
+    project: { findUnique: fns.projectFindUnique, findMany: fns.projectFindMany },
+    story: {
+      findUnique: fns.storyFindUnique,
+      findMany: fns.storyFindMany,
+      update: fns.storyUpdate,
+      delete: fns.storyDelete,
+    },
+    storyActivity: { create: fns.storyActivityCreate },
+    sequenceCounter: { upsert: fns.sequenceCounterUpsert },
+    user: { findUnique: fns.userFindUnique },
+    iteration: { findUnique: fns.iterationFindUnique },
+    projectMember: { findUnique: fns.memberFindUnique },
+    collabDocument: { deleteMany: fns.collabDocumentDeleteMany, 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", () => ({
+  ensureBuiltinIndependentProject: H.fns.ensureBuiltinIndependentProject,
+  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 { deleteStoryFn, updateStoryFn } from "../story/story-crud";
+import { transferStoryAsChildFn } from "../story/story-transfer";
+import { STORY_LIST_SELECT } from "../../story/types";
+
+const U = "u-1";
+const P = "pr-1";
+const STORY_ID = "st-1";
+const DESC_JSON = JSON.stringify({ html: "<p>新描述</p>", markdown: "新描述" });
+
+const userBrief = (id: string) => ({
+  id,
+  username: `user-${id}`,
+  email: `${id}@example.com`,
+  avatarConfig: null,
+  bgShape: null,
+  bgColor: null,
+});
+
+const storyRow = (over: Record<string, unknown> = {}) => ({
+  id: STORY_ID,
+  identifier: "PRJ-1",
+  sequenceId: 1,
+  name: "需求A",
+  description: null,
+  state: "backlog",
+  priority: "none",
+  archived: false,
+  startDate: null,
+  targetDate: null,
+  boardOrder: 0,
+  projectId: P,
+  parentId: null,
+  parent: null,
+  assignee: null,
+  assigneeId: null,
+  iteration: null,
+  iterationId: null,
+  createdById: U,
+  createdBy: userBrief(U),
+  updatedBy: null,
+  labels: [],
+  createdAt: new Date("2026-01-01T12:00:00Z"),
+  updatedAt: new Date("2026-01-02T12:00:00Z"),
+  ...over,
+});
+
+/** $transaction(fn) 直接以 prisma 本身作为 tx 执行；数组形式逐项 await（delete 路径） */
+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);
+  M.storyFindUnique.mockResolvedValue(storyRow());
+  M.storyFindMany.mockResolvedValue([]); // checkDescendant：无环
+  M.storyUpdate.mockResolvedValue(storyRow({ name: "需求B" }));
+  M.storyDelete.mockResolvedValue({ id: STORY_ID });
+  M.storyActivityCreate.mockImplementation(async (args: {
+    data: { action: string; field: string | null; oldValue?: string; newValue?: string };
+  }) => ({
+    id: `act-${Math.random().toString(36).slice(2, 8)}`,
+    action: args.data.action,
+    field: args.data.field,
+    oldValue: args.data.oldValue ?? null,
+    newValue: args.data.newValue ?? null,
+    isAI: false,
+    createdAt: new Date("2026-02-01T12:00:00Z"),
+    user: userBrief(U),
+  }));
+  M.userFindUnique.mockResolvedValue({ username: "user-u-2" });
+  M.iterationFindUnique.mockResolvedValue({ name: "迭代甲" });
+  M.memberFindUnique.mockResolvedValue({ status: "active" });
+  M.projectFindUnique.mockResolvedValue({ id: P, name: "项目甲", displayId: "PRJ", ownerId: "owner-1" });
+  M.projectFindMany.mockResolvedValue([]);
+  M.collabDocumentDeleteMany.mockResolvedValue({ count: 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("updateStoryFn × §5.3 写入门卫", () => {
+  it("门卫在事务之前执行（先于 existing 读取，审查修正①：网络 I/O 不进事务）", async () => {
+    await updateStoryFn({ data: { storyId: STORY_ID, name: "需求B", description: DESC_JSON, state: "todo" } });
+
+    expect(M.withCollabGuard).toHaveBeenCalledTimes(1);
+    expect(M.withCollabGuard).toHaveBeenCalledWith({
+      roomName: `entity:story:${STORY_ID}`,
+      docId: STORY_ID,
+      actor: U,
+      patch: {
+        content: { html: "<p>新描述</p>", markdown: "新描述" },
+        fields: { name: "需求B", state: "todo" },
+      },
+      assertWriteAllowed: expect.any(Function),
+    });
+    const order = M.withCollabGuard.mock.invocationCallOrder[0]!;
+    const existingOrder = M.storyFindUnique.mock.invocationCallOrder[0]!;
+    expect(order).toBeLessThan(existingOrder);
+  });
+
+  it("pass-through（无快照）→ 非协同态零行为变化：全字段直写 + 活动记录", async () => {
+    const res = await updateStoryFn({
+      data: { storyId: STORY_ID, name: "需求B", description: DESC_JSON, state: "todo" },
+    });
+
+    const args = M.storyUpdate.mock.calls[0]![0];
+    expect(args.where).toEqual({ id: STORY_ID });
+    expect(args.select).toEqual(STORY_LIST_SELECT);
+    expect(args.data).toMatchObject({ name: "需求B", state: "todo", description: DESC_JSON });
+    expect(args.data.updatedBy).toEqual({ connect: { id: U } });
+    expect(M.storyActivityCreate).toHaveBeenCalledTimes(5); // name/state/description + 两个 content_edited 时间锚
+    expect(res.activities).toHaveLength(5);
+  });
+
+  it("forwarded + 纯 Y patch（state）→ web 侧零 mutation：不 update、不写活动、不 bump updatedAt", async () => {
+    guardForwardsAfterAssert();
+
+    const res = await updateStoryFn({ data: { storyId: STORY_ID, state: "todo" } });
+
+    expect(M.storyUpdate).not.toHaveBeenCalled();
+    expect(M.storyActivityCreate).not.toHaveBeenCalled();
+    expect(M.memberFindUnique).toHaveBeenCalled(); // assertWriteAllowed 项目成员预检
+    expect(res.activities).toEqual([]);
+    expect(res.story).toMatchObject({ id: STORY_ID, state: "backlog" });
+  });
+
+  it("forwarded + description → 直写剥离，响应回显请求值（知识库 content 回显同口径）", async () => {
+    guardForwardsAfterAssert();
+
+    const res = await updateStoryFn({ data: { storyId: STORY_ID, description: DESC_JSON } });
+
+    expect(M.storyUpdate).not.toHaveBeenCalled();
+    expect(res.story.description).toBe(DESC_JSON);
+  });
+
+  it("forwarded + 混合 patch（Y 字段 + projectId 跨项目移动）→ 仅非 Y 字段直写，Y 字段与活动剥离", async () => {
+    guardForwardsAfterAssert();
+    const targetProject = "pr-2";
+    M.storyFindUnique.mockResolvedValue(storyRow());
+
+    await updateStoryFn({
+      data: { storyId: STORY_ID, state: "todo", name: "新名", projectId: targetProject },
+    });
+
+    expect(M.storyUpdate).toHaveBeenCalledTimes(1);
+    const args = M.storyUpdate.mock.calls[0]![0];
+    expect(args.data).toEqual({
+      project: { connect: { id: targetProject } },
+      updatedBy: { connect: { id: U } },
+    });
+    expect(args.data.state).toBeUndefined();
+    expect(args.data.name).toBeUndefined();
+    // 跨项目移动的成员预检照旧（非 Y 通道的安全校验不因门卫短路）
+    expect(M.memberFindUnique).toHaveBeenCalledWith({
+      where: { projectId_userId: { projectId: targetProject, userId: U } },
+      select: { status: true },
+    });
+    // R11 touch：生效直写为纯非 Y patch（project）→ 同事务 touch 快照
+    expect(M.collabDocumentUpdateMany).toHaveBeenCalledWith({
+      where: { roomName: `entity:story:${STORY_ID}` },
+      data: { updatedAt: storyRow().updatedAt },
+    });
+  });
+
+  it("forwarded + iterationId（非 Y 字段）→ 照旧直写并保留 iteration_changed 活动", async () => {
+    guardForwardsAfterAssert();
+
+    const res = await updateStoryFn({ data: { storyId: STORY_ID, iterationId: "it-1", state: "todo" } });
+
+    expect(M.storyUpdate).toHaveBeenCalledTimes(1);
+    const args = M.storyUpdate.mock.calls[0]![0];
+    expect(args.data).toMatchObject({ iteration: { connect: { id: "it-1" } } });
+    expect(args.data.state).toBeUndefined();
+    expect(res.activities).toHaveLength(1);
+    expect(res.activities[0]).toMatchObject({ action: "iteration_changed" });
+    // R11 touch：纯非 Y 直写同步快照 updatedAt（无快照计 0 天然跳过）
+    expect(M.collabDocumentUpdateMany).toHaveBeenCalledWith({
+      where: { roomName: `entity:story:${STORY_ID}` },
+      data: { updatedAt: storyRow().updatedAt },
+    });
+  });
+
+  it("degraded（collab 不可达 TTL 降级）→ 同原行为：全字段直写", async () => {
+    M.withCollabGuard.mockResolvedValue({ kind: "degraded", reason: "unreachable" });
+
+    await updateStoryFn({ data: { storyId: STORY_ID, state: "todo" } });
+
+    const args = M.storyUpdate.mock.calls[0]![0];
+    expect(args.data).toMatchObject({ state: "todo" });
+    expect(M.storyActivityCreate).toHaveBeenCalledTimes(1);
+  });
+
+  it("C1：越权（成员预检失败）→ 短路报错，转发链路 mutation 零发生", async () => {
+    guardForwardsAfterAssert();
+    M.memberFindUnique.mockResolvedValue(null);
+
+    await expect(
+      updateStoryFn({ data: { storyId: STORY_ID, state: "todo" } }),
+    ).rejects.toThrow("无权限操作该项目的需求");
+
+    expect(M.storyUpdate).not.toHaveBeenCalled();
+    expect(M.storyActivityCreate).not.toHaveBeenCalled();
+  });
+
+  it("字段值口径：dates/labels/assignee/parentId 以 Y 写端同形转发（yyyy-MM-dd 串、id 串、id 数组、可空 id）", async () => {
+    await updateStoryFn({
+      data: {
+        storyId: STORY_ID,
+        startDate: "2026-03-01",
+        targetDate: null,
+        labelIds: ["l-1", "l-2"],
+        assigneeId: null,
+        parentId: "st-9",
+      },
+    });
+
+    expect(M.withCollabGuard).toHaveBeenCalledWith(
+      expect.objectContaining({
+        patch: {
+          content: undefined,
+          fields: {
+            startDate: "2026-03-01",
+            targetDate: null,
+            labelIds: ["l-1", "l-2"],
+            assigneeId: null,
+            parentId: "st-9",
+          },
+        },
+      }),
+    );
+  });
+});
+
+describe("deleteStoryFn × 协同快照清理（任务 16 删除路径同构）", () => {
+  it("实体删除与快照行清理同事务（deleteMany 防无快照 P2025）", async () => {
+    const res = await deleteStoryFn({ data: { storyId: STORY_ID } });
+
+    expect(res).toEqual({ success: true });
+    expect(M.storyDelete).toHaveBeenCalledWith({ where: { id: STORY_ID } });
+    expect(M.collabDocumentDeleteMany).toHaveBeenCalledWith({
+      where: { roomName: `entity:story:${STORY_ID}` },
+    });
+  });
+});
+
+describe("transferStoryAsChildFn × §5.3 写入门卫（T20 父需求弹窗旁路）", () => {
+  const PARENT = "st-parent";
+
+  function parentRow(over: Record<string, unknown> = {}) {
+    return { id: PARENT, projectId: P, identifier: "PRJ-2", name: "父需求", ...over };
+  }
+
+  beforeEach(() => {
+    // 转移链的读取：existing（子）+ parent；非独立项目 → 不触发编号重分配。
+    // 子需求行给全量形状（forwarded 时回读走 STORY_LIST_SELECT，castStoryUsers
+    // 需要 createdAt 等列）
+    M.storyFindUnique.mockImplementation(async (args: { where: { id: string } }) => {
+      if (args.where.id === STORY_ID) {
+        return storyRow({ id: STORY_ID, identifier: "PRJ-1", projectId: P, parentId: null });
+      }
+      if (args.where.id === PARENT) return parentRow();
+      return null;
+    });
+    M.storyUpdate.mockResolvedValue(storyRow({ parentId: PARENT }));
+  });
+
+  it("pass-through（无快照）→ 原行为：parentId 直写 + parent_changed 活动", async () => {
+    const res = await transferStoryAsChildFn({ data: { storyId: STORY_ID, parentStoryId: PARENT } });
+
+    const args = M.storyUpdate.mock.calls[0]![0];
+    expect(args.data).toMatchObject({ parent: { connect: { id: PARENT } } });
+    expect(res.activities.some((a: { action: string }) => a.action === "parent_changed")).toBe(true);
+  });
+
+  it("forwarded → parentId 从直写剥离、parent_changed 活动剥离；纯 parent patch 时零 mutation", async () => {
+    guardForwardsAfterAssert();
+
+    const res = await transferStoryAsChildFn({ data: { storyId: STORY_ID, parentStoryId: PARENT } });
+
+    // 无编号重分配 → 剥离 parentId 后 update 数据为空 → 跳过 update（collab 接管）
+    expect(M.storyUpdate).not.toHaveBeenCalled();
+    expect(res.activities).toEqual([]);
+    expect(M.withCollabGuard).toHaveBeenCalledWith(
+      expect.objectContaining({
+        roomName: `entity:story:${STORY_ID}`,
+        docId: STORY_ID,
+        actor: U,
+        patch: { content: undefined, fields: { parentId: PARENT } },
+      }),
+    );
+  });
+
+  it("审查修正①：门卫在标识符重试循环之外——编号冲突重试不重复走门卫网络面", async () => {
+    // 首次事务抛 P2002（identifier 唯一冲突）→ 重试第二次成功
+    const uniqueViolation = Object.assign(new Error("Unique constraint failed"), {
+      code: "P2002",
+      meta: { target: ["identifier"] },
+    });
+    let txCalls = 0;
+    M.transaction.mockImplementation(async (fn: unknown) => {
+      txCalls += 1;
+      if (txCalls === 1) throw uniqueViolation;
+      return (fn as (tx: unknown) => Promise<unknown>)(PRISMA);
+    });
+
+    await transferStoryAsChildFn({ data: { storyId: STORY_ID, parentStoryId: PARENT } });
+
+    expect(txCalls).toBe(2); // 重试确实发生
+    expect(M.withCollabGuard).toHaveBeenCalledTimes(1); // 门卫只跑一次
+  });
+});