@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -47,10 +47,11 @@ vi.mock("@tanstack/react-start/server", () => ({
 const mocks = vi.hoisted(() => ({
   currentSession: vi.fn(),
   ensureBuiltinIndependentProject: vi.fn(),
-  resolveStoryScopeProjectId: vi.fn(),
+  resolveStoryScopeProjectIds: vi.fn(),
   isUserInTeam: vi.fn(),
   bugFindUnique: vi.fn(),
   bugFindMany: vi.fn(),
+  bugAggregate: vi.fn(),
   bugCreate: vi.fn(),
   bugUpdate: vi.fn(),
   bugDelete: vi.fn(),
@@ -62,11 +63,15 @@ const mocks = vi.hoisted(() => ({
   projectMemberFindUnique: vi.fn(),
   projectMemberFindMany: vi.fn(),
   sequenceCounterUpsert: vi.fn(),
+  sequenceCounterUpdate: vi.fn(),
   labelFindMany: vi.fn(),
   userFindUnique: vi.fn(),
   storyFindUnique: vi.fn(),
   testRunCaseFindUnique: vi.fn(),
   testRunCaseUpdateMany: vi.fn(),
+  collabDocumentFindUnique: vi.fn(),
+  collabDocumentUpdateMany: vi.fn(),
+  collabDocumentDeleteMany: vi.fn(),
 }));
 
 vi.mock("@allbluecn/database", () => {
@@ -74,6 +79,7 @@ vi.mock("@allbluecn/database", () => {
     bug: {
       findUnique: mocks.bugFindUnique,
       findMany: mocks.bugFindMany,
+      aggregate: mocks.bugAggregate,
       create: mocks.bugCreate,
       update: mocks.bugUpdate,
       delete: mocks.bugDelete,
@@ -84,12 +90,21 @@ vi.mock("@allbluecn/database", () => {
     projectActivity: { create: mocks.projectActivityCreate },
     project: { findUnique: mocks.projectFindUnique },
     projectMember: { findUnique: mocks.projectMemberFindUnique, findMany: mocks.projectMemberFindMany },
-    sequenceCounter: { upsert: mocks.sequenceCounterUpsert },
+    sequenceCounter: { upsert: mocks.sequenceCounterUpsert, update: mocks.sequenceCounterUpdate },
     label: { findMany: mocks.labelFindMany },
     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: {} };
 });
@@ -100,7 +115,7 @@ vi.mock("@/server/auth-helpers", () => ({
 
 vi.mock("@/server/builtin-project", () => ({
   ensureBuiltinIndependentProject: mocks.ensureBuiltinIndependentProject,
-  resolveStoryScopeProjectId: mocks.resolveStoryScopeProjectId,
+  resolveStoryScopeProjectIds: mocks.resolveStoryScopeProjectIds,
 }));
 
 vi.mock("@/server/team-access", () => ({
@@ -161,33 +176,51 @@ beforeEach(() => {
     user: null,
   }));
   mocks.projectActivityCreate.mockResolvedValue({});
+  // 发号自愈（对齐需求域 #447）读存量 max：默认 null → maxExisting=0，走非自愈路径
+  mocks.bugAggregate.mockResolvedValue({ _max: { sequenceId: null } });
+  // R11 touch / §5.2 删除清理：缺省给足返回形状（无快照计 0）
+  mocks.collabDocumentUpdateMany.mockResolvedValue({ count: 0 });
+  mocks.collabDocumentDeleteMany.mockResolvedValue({ count: 0 });
 });
 
 describe("listBugsFn", () => {
   it("按解析后的项目 scope 查询并返回 items/total", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugFindMany.mockResolvedValue([]);
     mocks.bugCount.mockResolvedValue(7);
     const out = await listBugsFn({ data: { projectId: "p1" } });
-    expect(mocks.resolveStoryScopeProjectId).toHaveBeenCalledWith("p1", "u1");
+    expect(mocks.resolveStoryScopeProjectIds).toHaveBeenCalledWith("p1", "u1");
     expect(mocks.bugFindMany).toHaveBeenCalledWith(
       expect.objectContaining({
-        where: { archived: false, projectId: "p1", pendingConfirm: false },
+        where: { archived: false, projectId: { in: ["p1"] }, pendingConfirm: false },
         skip: 0,
         take: 200,
       }),
     );
     expect(mocks.bugCount).toHaveBeenCalledWith({
-      where: { archived: false, projectId: "p1", pendingConfirm: false },
+      where: { archived: false, projectId: { in: ["p1"] }, pendingConfirm: false },
     });
     expect(out).toEqual({ items: [], total: 7, hasMore: true });
   });
 
+  it("「全部项目」聚合：projectId 缺省时并入成员范围内全部项目", async () => {
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1", "p2"]);
+    mocks.bugFindMany.mockResolvedValue([]);
+    mocks.bugCount.mockResolvedValue(0);
+    await listBugsFn({ data: {} });
+    expect(mocks.resolveStoryScopeProjectIds).toHaveBeenCalledWith(undefined, "u1");
+    expect(mocks.bugFindMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({ projectId: { in: ["p1", "p2"] } }),
+      }),
+    );
+  });
+
   it("__archived__ 特殊值直达 buildListWhere（归档视图），不做项目 scope 解析", async () => {
     mocks.bugFindMany.mockResolvedValue([]);
     mocks.bugCount.mockResolvedValue(0);
     await listBugsFn({ data: { projectId: "__archived__" } });
-    expect(mocks.resolveStoryScopeProjectId).not.toHaveBeenCalled();
+    expect(mocks.resolveStoryScopeProjectIds).not.toHaveBeenCalled();
     expect(mocks.bugFindMany).toHaveBeenCalledWith(
       expect.objectContaining({
         where: {
@@ -250,6 +283,67 @@ describe("createBugFn", () => {
     expect(out.firstOccurAt).toBe("2026-01-01T00:00:00.000Z");
   });
 
+  it("发号自愈：计数器落后存量（seq=1/max=5）时跳到 max+1 并回写计数器，identifier 用自愈后序号", async () => {
+    // DB 实证场景：SQL 造数绕过计数器直写 bug（存量 max=9007 形态），计数器大幅落后
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    mocks.projectFindUnique.mockResolvedValue({ id: "p1", name: "Alpha", displayId: "ABC" });
+    mocks.sequenceCounterUpsert.mockResolvedValue({ scope: "bug:p1", seq: 1 });
+    mocks.bugAggregate.mockResolvedValue({ _max: { sequenceId: 5 } });
+    mocks.bugCreate.mockResolvedValue({ ...bugRow, sequenceId: 6, identifier: "ABC-B6" });
+
+    const out = await createBugFn({ data: { title: "登录页崩溃", projectId: "p1", labelIds: [] } });
+
+    expect(mocks.bugAggregate).toHaveBeenCalledWith({
+      where: { projectId: "p1" },
+      _max: { sequenceId: true },
+    });
+    expect(mocks.sequenceCounterUpdate).toHaveBeenCalledWith({
+      where: { scope: "bug:p1" },
+      data: { seq: 6 },
+    });
+    expect(mocks.bugCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ sequenceId: 6, identifier: "ABC-B6" }),
+      }),
+    );
+    expect(out.identifier).toBe("ABC-B6");
+  });
+
+  it("发号正常领先（seq=7/max=3）时不自愈：不回写计数器，序号照用 7", async () => {
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    mocks.projectFindUnique.mockResolvedValue({ id: "p1", name: "Alpha", displayId: "ABC" });
+    mocks.sequenceCounterUpsert.mockResolvedValue({ scope: "bug:p1", seq: 7 });
+    mocks.bugAggregate.mockResolvedValue({ _max: { sequenceId: 3 } });
+    mocks.bugCreate.mockResolvedValue({ ...bugRow, sequenceId: 7, identifier: "ABC-B7" });
+
+    const out = await createBugFn({ data: { title: "崩溃", projectId: "p1", labelIds: [] } });
+
+    expect(mocks.sequenceCounterUpdate).not.toHaveBeenCalled();
+    expect(mocks.bugCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ sequenceId: 7, identifier: "ABC-B7" }),
+      }),
+    );
+    expect(out.identifier).toBe("ABC-B7");
+  });
+
+  it("空项目（存量 max=null）时不自愈：序号透传计数器值", async () => {
+    mocks.projectMemberFindUnique.mockResolvedValue({ status: "active" });
+    mocks.projectFindUnique.mockResolvedValue({ id: "p1", name: "Alpha", displayId: "ABC" });
+    mocks.sequenceCounterUpsert.mockResolvedValue({ scope: "bug:p1", seq: 1 });
+    mocks.bugCreate.mockResolvedValue(bugRow);
+
+    const out = await createBugFn({ data: { title: "崩溃", projectId: "p1", labelIds: [] } });
+
+    expect(mocks.sequenceCounterUpdate).not.toHaveBeenCalled();
+    expect(mocks.bugCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ sequenceId: 1, identifier: "ABC-B1" }),
+      }),
+    );
+    expect(out.identifier).toBe("ABC-B1");
+  });
+
   it("未传 projectId 时调 ensureBuiltinIndependentProject(userId) 兜底", async () => {
     mocks.ensureBuiltinIndependentProject.mockResolvedValue("indep-1");
     mocks.projectFindUnique.mockResolvedValue({ id: "indep-1", name: "独立需求", displayId: "INDEPENDENT" });
@@ -497,7 +591,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 +602,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 +688,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 +760,7 @@ describe("bulkArchiveBugsFn", () => {
 });
 
 describe("bulkDeleteBugsFn", () => {
-  it("项目成员批量删除并返回 deleted 计数", async () => {
+  it("项目成员批量删除并返回 deleted 计数，聚合 roomNames 一次清理快照行", async () => {
     mockBugFindManyByScope([
       { id: "a", projectId: "p1" },
       { id: "b", projectId: "p1" },
@@ -666,6 +771,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 +838,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();
+    }
+  });
+});

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

@@ -46,7 +46,7 @@ vi.mock("@tanstack/react-start/server", () => ({
 
 const mocks = vi.hoisted(() => ({
   currentSession: vi.fn(),
-  resolveStoryScopeProjectId: vi.fn(),
+  resolveStoryScopeProjectIds: vi.fn(),
   bugFindMany: vi.fn(),
   bugCount: vi.fn(),
   bugGroupBy: vi.fn(),
@@ -83,7 +83,7 @@ vi.mock("@/server/auth-helpers", () => ({
 
 vi.mock("@/server/builtin-project", () => ({
   ensureBuiltinIndependentProject: vi.fn(),
-  resolveStoryScopeProjectId: mocks.resolveStoryScopeProjectId,
+  resolveStoryScopeProjectIds: mocks.resolveStoryScopeProjectIds,
 }));
 
 vi.mock("@/server/entitlements", () => ({
@@ -150,7 +150,7 @@ beforeEach(() => {
 
 describe("listBugGroupsFn", () => {
   it("groupBy=state + showEmptyGroups 返回五组 keys（含空组，按 BUG_STATES rank 排序）并带计数", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugGroupBy.mockResolvedValue([
       { state: "open", _count: { _all: 3 } },
       { state: "fixed", _count: { _all: 1 } },
@@ -170,7 +170,7 @@ describe("listBugGroupsFn", () => {
   });
 
   it("groupBy=severity 组序按严重度 rank（critical → low），空组保留", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugGroupBy.mockResolvedValue([{ severity: "low", _count: { _all: 2 } }]);
 
     const out = await listBugGroupsFn({ data: { projectId: "p1", groupBy: "severity", showEmptyGroups: true } });
@@ -181,7 +181,7 @@ describe("listBugGroupsFn", () => {
   });
 
   it("showEmptyGroups=false 只返回非空组", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugGroupBy.mockResolvedValue([
       { state: "open", _count: { _all: 3 } },
       { state: "fixed", _count: { _all: 1 } },
@@ -196,7 +196,7 @@ describe("listBugGroupsFn", () => {
   });
 
   it("assignee 组 null 归并为 unassigned", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugGroupBy.mockResolvedValue([
       { assigneeId: null, _count: { _all: 5 } },
       { assigneeId: "u2", _count: { _all: 1 } },
@@ -215,7 +215,7 @@ describe("listBugGroupsFn", () => {
 
     await listBugGroupsFn({ data: { projectId: "__archived__", groupBy: "state", showEmptyGroups: true } });
 
-    expect(mocks.resolveStoryScopeProjectId).not.toHaveBeenCalled();
+    expect(mocks.resolveStoryScopeProjectIds).not.toHaveBeenCalled();
     expect(mocks.bugGroupBy).toHaveBeenCalledWith(
       expect.objectContaining({
         where: {
@@ -230,7 +230,7 @@ describe("listBugGroupsFn", () => {
 
 describe("listBugsInGroupFn", () => {
   it("state 组值过滤 + skip/take 分页，orderBy=created 走 DB 排序", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugFindMany.mockResolvedValue([bugRow()]);
     mocks.bugCount.mockResolvedValue(100);
 
@@ -240,7 +240,7 @@ describe("listBugsInGroupFn", () => {
 
     expect(mocks.bugFindMany).toHaveBeenCalledWith(
       expect.objectContaining({
-        where: { archived: false, projectId: "p1", pendingConfirm: false, AND: [{ state: "open" }] },
+        where: { archived: false, projectId: { in: ["p1"] }, pendingConfirm: false, AND: [{ state: "open" }] },
         orderBy: [{ createdAt: "desc" }, { id: "asc" }],
         skip: 50,
         take: 20,
@@ -254,7 +254,7 @@ describe("listBugsInGroupFn", () => {
   });
 
   it("assignee 组值 unassigned → assigneeId null 过滤", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugFindMany.mockResolvedValue([]);
     mocks.bugCount.mockResolvedValue(0);
 
@@ -264,13 +264,13 @@ describe("listBugsInGroupFn", () => {
 
     expect(mocks.bugFindMany).toHaveBeenCalledWith(
       expect.objectContaining({
-        where: { archived: false, projectId: "p1", pendingConfirm: false, AND: [{ assigneeId: null }] },
+        where: { archived: false, projectId: { in: ["p1"] }, pendingConfirm: false, AND: [{ assigneeId: null }] },
       }),
     );
   });
 
   it("orderBy=severity desc 走 rank 分层查询（首层 critical，层内 id asc）", async () => {
-    mocks.resolveStoryScopeProjectId.mockResolvedValue("p1");
+    mocks.resolveStoryScopeProjectIds.mockResolvedValue(["p1"]);
     mocks.bugFindMany
       .mockResolvedValueOnce([bugRow({ id: "b-c", severity: "critical" })])
       .mockResolvedValue([]);
@@ -348,11 +348,14 @@ describe("buildBugGroupFilter 纯函数", () => {
 });
 
 describe("compareBugsByOrderKey 纯函数", () => {
-  const row = (overrides: Partial<{ id: string; severity: string; createdAt: string; updatedAt: string }> = {}) => ({
+  const row = (
+    overrides: Partial<{ id: string; severity: string; createdAt: string; updatedAt: string; boardOrder: number }> = {},
+  ) => ({
     id: "b1",
     severity: "medium",
     createdAt: "2026-01-01T00:00:00.000Z",
     updatedAt: "2026-01-02T00:00:00.000Z",
+    boardOrder: 0,
     ...overrides,
   });
 
@@ -375,6 +378,17 @@ describe("compareBugsByOrderKey 纯函数", () => {
     expect(compareBugsByOrderKey(early, late, "updated", "asc")).toBeLessThan(0);
   });
 
+  it("manual 按 boardOrder 比较（任务 33 必带②：服务端 manual=boardOrder，客户端同步），dir 翻转符号", () => {
+    const first = row({ boardOrder: 0 });
+    const second = row({ boardOrder: 1 });
+    expect(compareBugsByOrderKey(first, second, "manual", "asc")).toBeLessThan(0);
+    expect(compareBugsByOrderKey(first, second, "manual", "desc")).toBeGreaterThan(0);
+    // 同 boardOrder 时 id 升序 tiebreaker 兜底（存量行 @default(0) 同值面）
+    const tieA = row({ id: "a" });
+    const tieB = row({ id: "b" });
+    expect(compareBugsByOrderKey(tieA, tieB, "manual", "asc")).toBeLessThan(0);
+  });
+
   it("主键相等时 id 升序 tiebreaker（与 dir 无关）", () => {
     const a = row({ id: "a", severity: "high" });
     const b = row({ id: "b", severity: "high" });
@@ -399,23 +413,27 @@ describe("getBugDisplayOptionsFn / updateBugDisplayOptionsFn", () => {
 
   it("存储的非法字段逐项回退默认值，合法字段保留", async () => {
     mocks.viewFindFirst.mockResolvedValue({
-      displayOptions: { groupBy: "hack", orderBy: 42, orderDir: "sideways", properties: ["bogus", "labels"], pageSize: "many" },
+      displayOptions: { groupBy: "hack", orderBy: 42, orderDir: "sideways", properties: ["bogus", "labels"], pageSize: "many", subGroupBy: 9, showEmptyGroups: "yes" },
     });
 
     const out = await getBugDisplayOptionsFn({ data: undefined });
 
+    // 任务 40 双层分组三键：缺失/非法逐项回落默认值
     expect(out).toEqual({
       groupBy: "state",
       orderBy: "created",
       orderDir: "desc",
       properties: ["labels"],
       pageSize: 100,
+      subGroupBy: "none",
+      showEmptyGroups: false,
+      showSubItems: false,
     });
   });
 
   it("update 无保留行时创建（filters 存空数组），返回更新后的完整对象", async () => {
     mocks.viewFindFirst.mockResolvedValue(null);
-    const options: BugDisplayOptions = { groupBy: "severity", orderBy: "severity", orderDir: "asc", properties: ["state"], pageSize: 100 };
+    const options: BugDisplayOptions = { groupBy: "severity", orderBy: "severity", orderDir: "asc", properties: ["state"], pageSize: 100, subGroupBy: "none", showEmptyGroups: false, showSubItems: false };
 
     const out = await updateBugDisplayOptionsFn({ data: options });
 
@@ -432,7 +450,7 @@ describe("getBugDisplayOptionsFn / updateBugDisplayOptionsFn", () => {
 
   it("update 已有保留行时按 id 更新", async () => {
     mocks.viewFindFirst.mockResolvedValue({ id: "v9" });
-    const options: BugDisplayOptions = { groupBy: "state", orderBy: "updated", orderDir: "asc", properties: ["state", "labels"], pageSize: 100 };
+    const options: BugDisplayOptions = { groupBy: "state", orderBy: "updated", orderDir: "asc", properties: ["state", "labels"], pageSize: 100, subGroupBy: "severity", showEmptyGroups: true, showSubItems: false };
 
     const out = await updateBugDisplayOptionsFn({ data: options });
 
@@ -454,7 +472,7 @@ describe("getBugDisplayOptionsFn / updateBugDisplayOptionsFn", () => {
     mocks.viewFindFirst.mockResolvedValue({ id: "v9" });
 
     const out = await updateBugDisplayOptionsFn({
-      data: { groupBy: "state", orderBy: "created", orderDir: "desc", properties: ["state"], pageSize: 500 },
+      data: { groupBy: "state", orderBy: "created", orderDir: "desc", properties: ["state"], pageSize: 500, subGroupBy: "none", showEmptyGroups: false, showSubItems: false },
     });
 
     expect(out.pageSize).toBe(200);
@@ -470,7 +488,7 @@ describe("getBugDisplayOptionsFn / updateBugDisplayOptionsFn", () => {
     mocks.viewFindFirst.mockResolvedValue(null);
 
     const out = await updateBugDisplayOptionsFn({
-      data: { groupBy: "state", orderBy: "created", orderDir: "desc", properties: ["state"], pageSize: 1000 },
+      data: { groupBy: "state", orderBy: "created", orderDir: "desc", properties: ["state"], pageSize: 1000, subGroupBy: "none", showEmptyGroups: false, showSubItems: false },
     });
 
     expect(mocks.requireFeature).toHaveBeenCalledWith({}, "largePageSize");