@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/serverFns/testcase/testcase-board.ts

@@ -0,0 +1,198 @@
+// 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/>.
+
+// 用例看板列查询 serverFn（UI 对齐二期 PR-7a 任务 25，照 bug-groups 条目分页
+// 模式 + story-groups 分组模式）。本文件只导出 createServerFn 产物：列过滤、
+// DTO cast 等辅助逻辑均为文件内非导出成员；排序键集与字段映射经 field-configs
+// 同源（TESTCASE_ORDER_FIELD_MAP，manual → boardOrder）。权限口径与任务 16
+// listTestCasesFn 一致：resolveStoryScopeProjectIds（缺省 = 成员关系内全部项目
+// 聚合，单项目经鉴权非成员静默回退独立项目）。归档闸门恒 false（看板只展示
+// 未归档用例，归档是「回收站」语义不进板）。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import { z } from "zod";
+import type { Prisma } from "@allbluecn/database";
+import type { AvatarConfig } from "@allbluecn/kernel";
+import { requireAuth } from "@/server/auth-helpers";
+import { resolveStoryScopeProjectIds } from "@/server/builtin-project";
+import { buildListWhere } from "@/server/testcase/list-query";
+import {
+  TESTCASE_ORDER_DIRECTIONS,
+  TESTCASE_ORDER_FIELD_MAP,
+  TESTCASE_ORDER_KEYS,
+} from "@/components/testcase/display/field-configs";
+import type { TestCaseSummary, TestCaseSteps } from "./types";
+import type { TestCaseAutomation, TestCasePriority, TestCaseState, TestCaseType } from "./constants";
+
+// ── 分组维度与列过滤（testcase-groups 的 folder/state/priority 三维同款）──
+
+/** 看板列分组维度（无 none——单列集合不是看板；folder 仅单项目 scope 有意义，
+ * 客户端任务 26 接线时与分组下拉同口径收敛） */
+const BOARD_GROUP_KEYS = ["state", "priority", "folder"] as const;
+type BoardGroupKey = (typeof BOARD_GROUP_KEYS)[number];
+
+/** 列 key → where 片段；unassigned = 未分组用例（folderId null，与
+ * testcase-groups deriveGroupKey 同款哨兵） */
+function buildColumnFilter(groupBy: BoardGroupKey, key: string): Prisma.TestCaseWhereInput {
+  switch (groupBy) {
+    case "state":
+      return { state: key };
+    case "priority":
+      return { priority: key };
+    case "folder":
+      return key === "unassigned" ? { folderId: null } : { folderId: key };
+  }
+}
+
+// ── 列条目 DTO：与列表 TestCaseSummary 同形 + boardOrder（列内当前权重，
+// 任务 26 拖拽排序决策可读；select 拷贝自 testcase-crud 的 LIST_SELECT 加此列）──
+
+const USER_BRIEF_SELECT = {
+  id: true,
+  username: true,
+  email: true,
+  avatarConfig: true,
+  bgShape: true,
+  bgColor: true,
+} as const;
+
+const TEST_CASE_BOARD_SELECT = {
+  id: true,
+  sequenceId: true,
+  identifier: true,
+  projectId: true,
+  folderId: true,
+  storyId: true,
+  title: true,
+  precondition: true,
+  steps: true,
+  type: true,
+  priority: true,
+  state: true,
+  version: true,
+  automation: true,
+  aiGenerated: true,
+  boardOrder: true,
+  assignee: { select: USER_BRIEF_SELECT },
+  createdBy: { select: USER_BRIEF_SELECT },
+  archived: true,
+  archivedAt: true,
+  createdAt: true,
+  updatedAt: true,
+} satisfies Prisma.TestCaseDefaultArgs["select"];
+
+type TestCaseBoardRow = Prisma.TestCaseGetPayload<{ select: typeof TEST_CASE_BOARD_SELECT }>;
+
+interface TestCaseBoardItem extends TestCaseSummary {
+  boardOrder: number;
+}
+
+/** DB String 域收敛为常量联合 + 日期转 ISO（跨 JSON 边界），cast 口径同 testcase-crud */
+function castBoardCase(row: TestCaseBoardRow): TestCaseBoardItem {
+  return {
+    ...row,
+    steps: row.steps as unknown as TestCaseSteps,
+    type: row.type as TestCaseType,
+    priority: row.priority as TestCasePriority,
+    state: row.state as TestCaseState,
+    automation: row.automation as TestCaseAutomation,
+    assignee: row.assignee
+      ? {
+          ...row.assignee,
+          avatarConfig: (row.assignee.avatarConfig as AvatarConfig | null) ?? null,
+        }
+      : null,
+    createdBy: {
+      ...row.createdBy,
+      avatarConfig: (row.createdBy.avatarConfig as AvatarConfig | null) ?? null,
+    },
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+// ── 批量列查询：columns 逐列独立分页（列级 cursor 翻页）──
+
+const boardSchema = z.object({
+  // 「全部项目」聚合（任务 16 同构）：缺省 → 成员关系内全部项目；传值 → 单项目经鉴权
+  projectId: z.string().optional(),
+  groupBy: z.enum(BOARD_GROUP_KEYS).default("state"),
+  // 缺省 manual：看板即手动排序面（boardOrder asc = 列内当前序）
+  orderBy: z.enum(TESTCASE_ORDER_KEYS).default("manual"),
+  orderDir: z.enum(TESTCASE_ORDER_DIRECTIONS).default("asc"),
+  // FilterCondition 三段式（任务 21 同款）：buildListWhere 翻译为 where
+  filters: z.string().optional(),
+  // 搜索词（任务 27 补：任务 25 漏收致看板搜索不生效；buildListWhere 译为
+  // title/identifier OR contains，与 listTestCasesFn 同口径）
+  searchText: z.string().optional(),
+  // 请求的列集合（键序 = 列序，由客户端分组 meta 决定；cursor = 该列上次
+  // 返回的 nextCursor，缺省取首页）
+  columns: z
+    .array(z.object({ key: z.string().min(1), cursor: z.string().optional() }))
+    .min(1)
+    .max(50),
+  take: z.number().int().min(1).max(500).default(100),
+});
+
+export const listTestCaseBoardColumnsFn = createServerFn({ method: "GET" })
+  .validator(boardSchema)
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma();
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
+    const base = buildListWhere({
+      archived: false,
+      projectIds,
+      filters: data.filters,
+      searchText: data.searchText,
+    });
+    const baseAnd = Array.isArray(base.AND) ? base.AND : base.AND ? [base.AND] : [];
+
+    const dir: "asc" | "desc" = data.orderDir === "asc" ? "asc" : "desc";
+    const field = TESTCASE_ORDER_FIELD_MAP[data.orderBy];
+    // [主键, id asc] tiebreaker：boardOrder 大量同值（@default(0)），全序确定
+    // 列内 cursor 翻页不抖动（bug/story 同构）
+    const orderBy: Prisma.TestCaseOrderByWithRelationInput[] = [{ [field]: dir }, { id: "asc" }];
+
+    // 列间相互独立（各带各的 cursor），并行取页；返回序保持请求列序
+    const columns = await Promise.all(
+      data.columns.map(async (col) => {
+        const where: Prisma.TestCaseWhereInput = {
+          ...base,
+          AND: [...baseAnd, buildColumnFilter(data.groupBy, col.key)],
+        };
+        const rows = await prisma.testCase.findMany({
+          where,
+          orderBy,
+          take: data.take,
+          ...(col.cursor ? { skip: 1, cursor: { id: col.cursor } } : {}),
+          select: TEST_CASE_BOARD_SELECT,
+        });
+        return {
+          key: col.key,
+          items: rows.map(castBoardCase),
+          nextCursor: rows.length === data.take ? rows[rows.length - 1].id : null,
+        };
+      }),
+    );
+
+    return { columns };
+  });

package/src/server/serverFns/testcase/testcase-crud.ts

@@ -17,8 +17,9 @@
 
 // 测试用例主数据 CRUD serverFn（照 bug-crud / testcase-folders 写法惯例）。本文件只准
 // 导出 createServerFn 产物，select 常量、DTO cast、成员校验等辅助逻辑用文件内非导出成员。
-// 权限口径与 BUG 模块一致：读走 resolveStoryScopeProjectId 防越权（非成员静默回退独立项目），
-// 写须项目有效成员（suspended 视同无权限）。发号：SequenceCounter(scope="testcase:{projectId}")，
+// 权限口径与 BUG 模块一致：列表读走 resolveStoryScopeProjectIds（「全部项目」缺省聚合
+// 成员关系内全部项目；单项目经鉴权，非成员静默回退独立项目），写须项目有效成员
+// （suspended 视同无权限）。发号：SequenceCounter(scope="testcase:{projectId}")，
 // identifier = "{displayId}-TC{seq}"（前缀清洗规则与 bug/story 对齐，首条 -TC1）。
 // version 口径：内容字段（title/precondition/steps/type/priority，即 caseSnapshot 锁定面）
 // 实际变更才 +1；state/automation/assignee/folder/story 等元数据变更不 bump（规格 §3：快照只锁内容）。
@@ -29,8 +30,14 @@ import { z } from "zod";
 import type { Prisma } from "@allbluecn/database";
 import type { AvatarConfig } from "@allbluecn/kernel";
 import { requireAuth } from "@/server/auth-helpers";
-import { resolveStoryScopeProjectId } from "@/server/builtin-project";
+import { resolveStoryScopeProjectIds } from "@/server/builtin-project";
+import { buildListWhere } from "@/server/testcase/list-query";
 import { isUserInTeam } from "@/server/team-access";
+import {
+  TESTCASE_ORDER_DIRECTIONS,
+  TESTCASE_ORDER_FIELD_MAP,
+  TESTCASE_ORDER_KEYS,
+} from "@/components/testcase/display/field-configs";
 import { CreateTestCaseInputSchema, UpdateTestCaseInputSchema } from "./schemas";
 import {
   TEST_CASE_AUTOMATION_VALUES,
@@ -44,6 +51,10 @@ import {
   type TestCaseType,
 } from "./constants";
 import type { TestCaseDetail, TestCaseSteps, TestCaseSummary } from "./types";
+import { buildRoomName } from "@allbluecn/collab-core/rooms";
+import { normalizeCollabSteps } from "@allbluecn/collab-core/steps";
+import { withCollabGuard } from "@/server/collab/write-guard";
+import { touchCollabSnapshot } from "@/server/collab/touch-snapshot";
 
 /** 项目有效成员校验（口径同 testcase-folders / deleteBugFn：suspended 视同无权限） */
 async function assertProjectMembership(projectId: string, userId: string) {
@@ -153,10 +164,13 @@ function castTestCase(row: TestCaseRow): TestCaseSummary {
   };
 }
 
-// ── 列表：多筛选 + 游标分页（cursor 用例 id，orderBy sequenceId 项目内稳定唯一）──
+// ── 列表：多筛选 + 游标分页（cursor 用例 id；排序入参任务 25 起开放，缺省
+//    sequenceId asc 保持既有首屏行为）──
 
 const listSchema = z.object({
-  projectId: z.string().min(1),
+  // 「全部项目」聚合（二期 TC-A）：缺省 → 成员关系内全部项目（同 story/bug 域
+  // resolveStoryScopeProjectIds）；传值 → 单项目经鉴权
+  projectId: z.string().optional(),
   folderId: z.string().nullable().optional(),
   storyId: z.string().nullable().optional(),
   state: z.enum(TEST_CASE_STATE_VALUES).optional(),
@@ -164,12 +178,20 @@ const listSchema = z.object({
   priority: z.enum(TEST_CASE_PRIORITY_VALUES).optional(),
   automation: z.enum(TEST_CASE_AUTOMATION_VALUES).optional(),
   assigneeId: z.string().nullable().optional(),
+  // FilterCondition 三段式（任务 21）：客户端 serializeFilters 产物（JSON 串），
+  // 经 server/testcase/list-query.ts buildListWhere 翻译为 where（story/bug
+  // filters 传参形态同构）；与上方扁平参数并存（其他消费方仍走扁平键）
+  filters: z.string().optional(),
   // 归档筛选：缺省/false 仅未归档（默认列表不出现归档用例，与 delete 被 RunCase
   // 引用挡住时的「请改用归档」提示配套）；true 仅归档。不做 all 选项（YAGNI）。
   archived: z.boolean().optional(),
   searchText: z.string().optional(),
   cursor: z.string().optional(),
   take: z.number().int().min(1).max(200).default(50),
+  // 排序入参（任务 25，复审 P1-3 收口）：键集与字段映射同源 field-configs，
+  // manual → boardOrder（看板手动排序权重）。缺省保持既有行为 sequenceId asc。
+  orderBy: z.enum(TESTCASE_ORDER_KEYS).default("sequenceId"),
+  orderDir: z.enum(TESTCASE_ORDER_DIRECTIONS).default("asc"),
 });
 
 export const listTestCasesFn = createServerFn({ method: "GET" })
@@ -180,32 +202,34 @@ export const listTestCasesFn = createServerFn({ method: "GET" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
-    // scope 解析：未传/无效/非成员 → 静默回退独立项目，防越权查询（同 listFoldersFn）
-    const projectId = await resolveStoryScopeProjectId(data.projectId, userId);
+    // scope 解析（同 story/story-groups 与 bug 域）：未传 → 成员关系全部项目聚合；
+    // 单项目经鉴权（无效/非成员 → 静默回退独立项目），防越权查询
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
 
-    const where: Prisma.TestCaseWhereInput = {
-      projectId,
+    const where = buildListWhere({
       // 归档闸门：缺省/false 仅未归档，true 仅归档（无 all——归档是「回收站」语义）
       archived: data.archived ?? false,
-      // folderId === null 是有意义筛选（未分组用例），与 undefined（不筛）区分
-      ...(data.folderId !== undefined && { folderId: data.folderId }),
-      ...(data.storyId !== undefined && { storyId: data.storyId }),
-      ...(data.state && { state: data.state }),
-      ...(data.type && { type: data.type }),
-      ...(data.priority && { priority: data.priority }),
-      ...(data.automation && { automation: data.automation }),
-      ...(data.assigneeId !== undefined && { assigneeId: data.assigneeId }),
-      ...(data.searchText && {
-        OR: [
-          { title: { contains: data.searchText, mode: "insensitive" } },
-          { identifier: { contains: data.searchText, mode: "insensitive" } },
-        ],
-      }),
-    };
+      projectIds,
+      folderId: data.folderId,
+      storyId: data.storyId,
+      state: data.state,
+      type: data.type,
+      priority: data.priority,
+      automation: data.automation,
+      assigneeId: data.assigneeId,
+      searchText: data.searchText,
+      filters: data.filters,
+    });
+
+    // 排序：键 → 字段映射经 TESTCASE_ORDER_FIELD_MAP（manual → boardOrder）。
+    // id tiebreaker：boardOrder（@default(0)）/sequenceId 大量同值时全序确定，
+    // cursor 跨批次翻页不抖动（bug/story 同构）
+    const orderField = TESTCASE_ORDER_FIELD_MAP[data.orderBy];
+    const dir: "asc" | "desc" = data.orderDir === "asc" ? "asc" : "desc";
 
     const items = await prisma.testCase.findMany({
       where,
-      orderBy: [{ sequenceId: "asc" }],
+      orderBy: [{ [orderField]: dir }, { id: "asc" }],
       take: data.take,
       ...(data.cursor ? { skip: 1, cursor: { id: data.cursor } } : {}),
       select: TEST_CASE_LIST_SELECT,
@@ -305,6 +329,37 @@ export const createTestCaseFn = createServerFn({ method: "POST" })
 
 // ── 编辑：部分更新；内容字段实际变更才 version+1；expectedVersion 乐观锁可选 ──
 
+/**
+ * entity room 的 Y 属主字段清单（Yjs 多人协作 §7.1，任务 22）——与客户端写端
+ * components/testcase/detail/case-detail-body.tsx 的 CASE_COLLAB_FIELDS 镜像，
+ * 两侧必须同步维护（漏字段 = 旁路写互吞/协同态丢写）。folderId/storyId/
+ * automation 不入 Y（非协同 serverFn 直写面，DB 单一事实源无互吞面）。
+ */
+const CASE_Y_OWNED_FIELDS = [
+  "title",
+  "precondition",
+  "type",
+  "priority",
+  "state",
+  "assigneeId",
+] as const;
+
+/**
+ * Prisma.TestCaseUpdateInput 键视角的 Y 属主面（R11 touch 判定用）——
+ * assigneeId→assignee；steps 在此处属 Y 直写面（steps 列表入 Y，任务 22）。
+ * version 只随内容 Y 面（title/precondition/steps/type/priority）递增，
+ * 键集合判定已覆盖。
+ */
+const CASE_Y_UPDATE_KEYS = new Set([
+  "title",
+  "precondition",
+  "steps",
+  "type",
+  "priority",
+  "state",
+  "assignee",
+]);
+
 export const updateTestCaseFn = createServerFn({ method: "POST" })
   .validator(UpdateTestCaseInputSchema)
   .handler(async ({ data }) => {
@@ -313,6 +368,43 @@ export const updateTestCaseFn = createServerFn({ method: "POST" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
+    // ── Yjs 多人协作 §5.3 写入门卫（任务 22；T21 教训：提至 $transaction
+    // 之前——门卫转发含网络 I/O（TTL 内重试最坏 ≈4s），事务内等待会击穿
+    // Prisma 默认 5s 事务超时（P2028）让 degraded 兜底失效）。patch 的 Y
+    // 属主面 = 6 字段 + steps；快照存在 → 一律转发 collab 内部通道（在线应用
+    // Y 并广播 / 离线 collab 直落业务列含 version+1——协同落库维护乐观锁对
+    // 非协同客户端的语义）；无快照 pass-through、不可达 TTL 降级 → 照旧直写
+    // （非协同态零行为变化）。expectedVersion 在 assertWriteAllowed 前置复核
+    // （转发发生前）——版本冲突的 stale patch 不得进 Y 覆盖新协同态；事务内
+    // 仍保留原校验（precheck 与事务间的窗口由重查兜底）。
+    const yFields: Record<string, unknown> = {};
+    for (const key of CASE_Y_OWNED_FIELDS) {
+      const value = (data as Record<string, unknown>)[key];
+      if (value !== undefined) yFields[key] = value;
+    }
+    const guardSteps = data.steps !== undefined ? normalizeCollabSteps(data.steps) : null;
+    const guard = await withCollabGuard({
+      roomName: buildRoomName({ kind: "entity-case", caseId: data.id }),
+      docId: data.id,
+      actor: userId,
+      patch: {
+        ...(Object.keys(yFields).length > 0 && { fields: yFields }),
+        ...(guardSteps && guardSteps.length > 0 && { steps: guardSteps }),
+      },
+      assertWriteAllowed: async () => {
+        const row = await prisma.testCase.findUnique({
+          where: { id: data.id },
+          select: { projectId: true, version: true },
+        });
+        if (!row) throw new Error("用例不存在");
+        await assertProjectMembership(row.projectId, userId);
+        if (data.expectedVersion !== undefined && data.expectedVersion !== row.version) {
+          throw new Error("用例已被他人修改（版本冲突），请刷新后重试");
+        }
+      },
+    });
+    const forwarded = guard.kind === "forwarded";
+
     // 读 + expectedVersion 校验 + diff 全部在事务内（fast-follow：check-then-act 的
     // 版本塌缩竞态会波及 automation 产物的 stale 锚；事务内重读对账，task 20 adopt 先例）
     const updated = await prisma.$transaction(async (tx) => {
@@ -332,8 +424,13 @@ export const updateTestCaseFn = createServerFn({ method: "POST" })
     await validateAssignee(existing.projectId, data.assigneeId);
 
     const updates: Prisma.TestCaseUpdateInput = {};
-    // 内容面（caseSnapshot 锁定的五个字段）实际变更才 version+1
+    // 内容面（caseSnapshot 锁定的五个字段）实际变更才 version+1。
+    // Y 属主面（6 字段 + steps）：forwarded 时从直写数据剥离——写入由 collab
+    // 接管（web 侧再写即双写互吞；version+1/活动由 collab 落库侧
+    // writeCaseColumns 产出，web 再写即双 bump/重复流水）。forwarded 且剥离后
+    // 无剩余写入 → 下方既有的「无变化早退」自然生效（不 update 不留痕）。
     let contentChanged = false;
+    if (!forwarded) {
     if (data.title !== undefined && data.title !== existing.title) {
       updates.title = data.title;
       contentChanged = true;
@@ -356,15 +453,17 @@ export const updateTestCaseFn = createServerFn({ method: "POST" })
     }
     // 元数据面：不 bump version
     if (data.state !== undefined && data.state !== existing.state) updates.state = data.state;
-    if (data.automation !== undefined && data.automation !== existing.automation) {
-      updates.automation = data.automation;
-    }
     if (data.assigneeId !== undefined) {
       const next = data.assigneeId;
       if (next !== (existing.assignee?.id ?? null)) {
         updates.assignee = next ? { connect: { id: next } } : { disconnect: true };
       }
     }
+    } // ── end if (!forwarded)：Y 属主面剥离完毕 ──
+    // 非 Y 字段照旧直写（无论门卫裁决——Y 从不拥有它们，无互吞面）
+    if (data.automation !== undefined && data.automation !== existing.automation) {
+      updates.automation = data.automation;
+    }
     if (data.folderId !== undefined && data.folderId !== existing.folderId) {
       updates.folder = data.folderId ? { connect: { id: data.folderId } } : { disconnect: true };
     }
@@ -376,6 +475,12 @@ export const updateTestCaseFn = createServerFn({ method: "POST" })
     // 无变化早退返回原始行，DTO 转换统一由事务外的 castTestCase(updated) 一次完成
     if (Object.keys(updates).length === 0) return existing;
 
+    // R11 touch 不变式判定：生效直写是否含 Y 属主面。forwarded 时 Y 字段已
+    // 剥离（updates 只剩 automation/folder/story 等非 Y 面）；pass-through/
+    // degraded 直写 Y 字段 → 旁路语义，业务列必须反超快照让重种子化兜底，
+    // 刻意不 touch。
+    const writesYFace = Object.keys(updates).some((key) => CASE_Y_UPDATE_KEYS.has(key));
+
     // update + 活动留痕同事务（规格 §5.2：create/update 均为关键事件；字段惯例照
     // createTestCaseFn / testcase-folders：action/targetType/targetId 五字段无 metadata）
     const row = await tx.testCase.update({
@@ -383,6 +488,15 @@ export const updateTestCaseFn = createServerFn({ method: "POST" })
       data: updates,
       select: TEST_CASE_LIST_SELECT,
     });
+    // R11 touch：生效直写为纯非 Y patch（automation/folderId/storyId）时
+    // 同步快照 updatedAt = 回读行 updatedAt（无快照计 0 天然跳过）
+    if (!writesYFace) {
+      await touchCollabSnapshot(
+        tx,
+        buildRoomName({ kind: "entity-case", caseId: data.id }),
+        row.updatedAt,
+      );
+    }
     await tx.projectActivity.create({
       data: {
         projectId: existing.projectId,
@@ -447,10 +561,21 @@ export const archiveTestCaseFn = createServerFn({ method: "POST" })
     if (!existing) throw new Error("用例不存在");
     await assertProjectMembership(existing.projectId, userId);
 
-    const updated = await prisma.testCase.update({
-      where: { id: existing.id },
-      data: { archived: true, archivedAt: new Date() },
-      select: TEST_CASE_LIST_SELECT,
+    const updated = await prisma.$transaction(async (tx) => {
+      const row = await tx.testCase.update({
+        where: { id: existing.id },
+        data: { archived: true, archivedAt: new Date() },
+        select: TEST_CASE_LIST_SELECT,
+      });
+
+      // R11 touch：archive bump updatedAt 但不含 Y 属主面（同 story/bug archive）
+      await touchCollabSnapshot(
+        tx,
+        buildRoomName({ kind: "entity-case", caseId: existing.id }),
+        row.updatedAt,
+      );
+
+      return row;
     });
     return castTestCase(updated);
   });
@@ -476,8 +601,15 @@ export const deleteTestCaseFn = createServerFn({ method: "POST" })
       throw new Error(`该用例已被 ${runCaseCount} 条执行记录引用，无法删除，请改用归档`);
     }
 
+    // 删除实体 + 协同快照同事务清理（Yjs 多人协作 §5.2 删除路径，story/
+    // knowledge/bug 删除同构）：实体删后快照行必删，防 collab 服务后续装载
+    // 幽灵 room；用 deleteMany 而非 delete——room 未协同打开过时无行，delete
+    // 会 P2025 竞态炸。room 命名与 collab-core 注册表一致（entity:case:<id>）。
     await prisma.$transaction(async (tx) => {
       await tx.testCase.delete({ where: { id: existing.id } });
+      await tx.collabDocument.deleteMany({
+        where: { roomName: buildRoomName({ kind: "entity-case", caseId: existing.id }) },
+      });
       await tx.projectActivity.create({
         data: {
           projectId: existing.projectId,