@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/story/detail/__tests__/story-collab.test.tsx

@@ -0,0 +1,897 @@
+// 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/>.
+
+// StoryDetailBody 协同态改造测试（Yjs 多人协作任务 20，规格 §7.1 Story 行 /
+// §10.1 字段型 pill）。测试结构对齐任务 15 的 knowledge-doc-editor-collab：
+//
+//   ① 协同态 description 编辑不触发旧 8s flush（Y 唯一写手，审查重点 #3），
+//      blur/卸载 flush 通道同样短路；远端 Y 写入也不触发 DB 保存。
+//   ② state/priority/assignee 改动写 fields Y.Map（广播=provider doc 增量）
+//      且不触发 updateStoryFn；远端字段变化实时回写本地 UI。
+//   ③ key={story.id} 重建时 room 正确切换销毁（旧 handle destroy、新 room 建连）。
+//   ④ 字段 pill 数据源来自 awareness（editing:* 标记 → pill 显示；移除 →
+//      3s 余晖后消失）。
+//   ⑤ collab=false 回归：8s 防抖 / meta 字段改动走既有 DB 通道，零协同开销。
+//   ⑥ 降级模式（offline → DB 通道恢复 + 提示条；synced → 再短路）。
+
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { render, fireEvent, act, screen } from "@testing-library/react";
+import { Suspense } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import * as Y from "yjs";
+
+// 整编辑器挂载重（TipTap 全扩展 + 协同插件），全量并行负载下默认 5s 会超时
+vi.setConfig({ testTimeout: 60_000 });
+
+// ---------------------------------------------------------------------------
+// mock（vi.mock 提升：真实 serverFn / provider / session 均不参与）
+// ---------------------------------------------------------------------------
+
+const mocks = vi.hoisted(() => ({
+  updateStoryFn: vi.fn(),
+  listStoryReactionsFn: vi.fn(),
+  toggleStoryReactionFn: vi.fn(),
+  createLabelFn: vi.fn(),
+  listLabelsFn: vi.fn().mockResolvedValue([]),
+  suggestStoryLabelsFn: vi.fn(),
+  listProjectStoriesFn: vi.fn(),
+  transferStoryAsChildFn: vi.fn(),
+  getOrCreateProvider: vi.fn(),
+  useSession: vi.fn(),
+  aiUseSession: vi.fn(),
+  listEnabledModelsFn: vi.fn(),
+}));
+
+vi.mock("@/server/serverFns/story", () => ({
+  updateStoryFn: mocks.updateStoryFn,
+  listStoryReactionsFn: mocks.listStoryReactionsFn,
+  toggleStoryReactionFn: mocks.toggleStoryReactionFn,
+  // LabelsEditor / StorySelectDialog 的依赖（通道短路测试触达 StoryProperties）
+  createLabelFn: mocks.createLabelFn,
+  suggestStoryLabelsFn: mocks.suggestStoryLabelsFn,
+  listLabelsFn: mocks.listLabelsFn,
+  listProjectStoriesFn: mocks.listProjectStoriesFn,
+  transferStoryAsChildFn: mocks.transferStoryAsChildFn,
+}));
+
+// 可外部驱动状态的假 provider handle（getOrCreateProvider 返回值，按 room 隔离）。
+// ⚠ 类型派生自真实 CollabProviderHandle 契约（同 T15 C1 修复）：真实 buildHandle
+// 新增成员时本文件 tsc 编译即失败，杜绝「替身偏离契约」的假绿。
+const rooms = new Map<string, FakeProviderHandle>();
+type FakeProviderHandle = CollabProviderHandle & {
+  __setStatus: (s: CollabConnectionStatus) => void;
+};
+
+/** 编辑标记可注入的 awareness 替身（API 面 = y-protocols Awareness 消费子集） */
+function buildFakeAwareness() {
+  const listeners = new Set<(u: unknown) => void>();
+  const remotes = new Map<number, Record<string, unknown>>();
+  return {
+    clientID: 999,
+    localState: null as Record<string, unknown> | null,
+    states: new Map(),
+    setLocalState: vi.fn((next: Record<string, unknown> | null) => {
+      (fakeAwareness as { localState: unknown }).localState = next;
+    }),
+    setLocalStateField: vi.fn((field: string, value: unknown) => {
+      const awareness = fakeAwareness;
+      awareness.localState = { ...(awareness.localState ?? {}), [field]: value };
+    }),
+    getLocalState: () => fakeAwareness.localState,
+    getStates: () => {
+      const all = new Map(remotes);
+      if (fakeAwareness.localState) all.set(fakeAwareness.clientID, fakeAwareness.localState);
+      return all;
+    },
+    on: (_e: string, handler: (u: unknown) => void) => {
+      listeners.add(handler);
+    },
+    off: (_e: string, handler: (u: unknown) => void) => {
+      listeners.delete(handler);
+    },
+    /** 测试注入远端 editing 标记（等价远端 awareness update 到达） */
+    __addRemote(clientId: number, state: Record<string, unknown>) {
+      remotes.set(clientId, state);
+      for (const handler of [...listeners]) handler({});
+    },
+    __removeRemote(clientId: number) {
+      remotes.delete(clientId);
+      for (const handler of [...listeners]) handler({});
+    },
+  };
+}
+let fakeAwareness: ReturnType<typeof buildFakeAwareness>;
+
+function buildFakeProvider(roomName: string, init: CollabConnectionStatus = "connecting"): FakeProviderHandle {
+  let status: CollabConnectionStatus = init;
+  const listeners = new Set<(s: CollabConnectionStatus) => void>();
+  const handle: FakeProviderHandle = {
+    roomName,
+    doc: new Y.Doc(),
+    awareness: fakeAwareness as unknown as CollabAwareness,
+    getStatus: () => status,
+    onStatusChange: (listener) => {
+      listeners.add(listener);
+      listener(status);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    on: vi.fn(() => () => {}),
+    off: vi.fn(),
+    destroy: vi.fn(),
+    __setStatus: (next) => {
+      status = next;
+      for (const listener of [...listeners]) listener(next);
+    },
+  };
+  return handle;
+}
+
+vi.mock("@/lib/collab/provider", () => ({
+  // 惰性转发（工厂执行早于模块体，直接引用会 TDZ）
+  getOrCreateProvider: (roomName: string) => mocks.getOrCreateProvider(roomName),
+}));
+
+vi.mock("@/components/shared-kit/auth/auth-client", () => ({
+  useSession: mocks.useSession,
+}));
+
+vi.mock("@/lib/auth/auth-client", () => ({
+  useSession: mocks.aiUseSession,
+}));
+
+vi.mock("@/server/serverFns/design/ai/providers", () => ({
+  listEnabledModelsFn: mocks.listEnabledModelsFn,
+}));
+
+// AI 工具栏替身：暴露 stub 按钮驱动 onApply（handleAiApply 通道的可控触发点）
+vi.mock("@/components/story/ai/story-ai-toolbar", () => ({
+  StoryAiToolbar: ({ onApply }: { onApply?: (markdown: string) => void }) => (
+    <button
+      type="button"
+      data-testid="story-ai-apply-stub"
+      onClick={() => onApply?.("AI 改写后的内容")}
+    >
+      ai-apply
+    </button>
+  ),
+}));
+// 重型子组件替身（非本任务被测面）
+vi.mock("@/components/story/detail/activity-tabs", () => ({
+  ActivityTabs: () => null,
+}));
+vi.mock("@/components/shared-kit/comments/emoji-picker", () => ({
+  EmojiPicker: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}));
+vi.mock("@/components/shared-kit", () => ({
+  UserAvatar: ({ name }: { name: string }) => <span data-testid="avatar">{name}</span>,
+}));
+vi.mock(
+  "@/components/shared-kit/icons/lucide-icon-picker/lucide-icon-by-name",
+  () => ({
+    LucideIconByName: () => null,
+  }),
+);
+
+// 预热 lazy 的 NotionDocEditor 动态 import（模块图大，渲染前先解析完）
+const notionLikeReady = import("@/components/tiptap/notion-like");
+
+// 被测组件（mock 声明之后 import，保证 mock 生效）
+import { StoryDetailBody } from "../story-detail-body";
+import type { StoryDetail, UserBrief } from "../../types";
+// 真实契约类型（vi.mock 只替换运行时，类型仍取自真实模块 → 替身受契约约束）
+import type {
+  CollabAwareness,
+  CollabConnectionStatus,
+  CollabProviderHandle,
+} from "@/lib/collab/provider";
+
+// ---------------------------------------------------------------------------
+// 夹具
+// ---------------------------------------------------------------------------
+
+const alice: UserBrief = {
+  id: "user-1",
+  username: "alice",
+  email: "alice@x",
+  avatarConfig: null,
+  bgShape: null,
+  bgColor: null,
+};
+const bob: UserBrief = {
+  id: "user-2",
+  username: "bob",
+  email: "bob@x",
+  avatarConfig: null,
+  bgShape: null,
+  bgColor: null,
+};
+
+/** 标签/项目清单（labels/parent 通道测试触达 StoryProperties 渲染分支） */
+const LABELS = [
+  { id: "label-1", name: "缺陷", color: "#ef4444" },
+  { id: "label-2", name: "特性", color: "#3b82f6" },
+];
+const PROJECTS = [{ id: "proj-1", name: "项目A", displayId: "ALL", icon: "rocket" }];
+/** 父需求候选（StorySelectDialog 列表项，listProjectStoriesFn mock 返回） */
+const PARENT_CANDIDATE = {
+  id: "story-9",
+  identifier: "ALL-9",
+  name: "父需求候选",
+  state: "done",
+  priority: "high",
+  projectId: "proj-1",
+};
+
+function mkStory(overrides: Partial<StoryDetail> = {}): StoryDetail {
+  return {
+    id: "story-1",
+    identifier: "ALL-1",
+    sequenceId: 1,
+    projectId: "proj-1",
+    name: "登录页改版",
+    description: JSON.stringify({ html: "<p>初始描述</p>", markdown: "初始描述" }),
+    state: "backlog",
+    priority: "medium",
+    archived: false,
+    boardOrder: 0,
+    startDate: null,
+    targetDate: null,
+    assignee: alice,
+    createdBy: alice,
+    updatedBy: null,
+    parentId: null,
+    parent: null,
+    labels: [],
+    createdAt: "2026-10-01T00:00:00.000Z",
+    updatedAt: "2026-10-01T00:00:00.000Z",
+    ...overrides,
+  } as StoryDetail;
+}
+
+const STORY = mkStory();
+
+function base64Encode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** 造一份带内容的协同快照（XmlFragment 'default'，与 COLLAB_XML_FRAGMENT 一致） */
+function buildSnapshotBase64(text: string): string {
+  const source = new Y.Doc();
+  const fragment = source.getXmlFragment("default");
+  const paragraph = new Y.XmlElement("paragraph");
+  const xmlText = new Y.XmlText();
+  xmlText.insert(0, text);
+  paragraph.insert(0, [xmlText]);
+  fragment.insert(0, [paragraph]);
+  return base64Encode(Y.encodeStateAsUpdate(source));
+}
+
+function renderBody(options: {
+  collab?: boolean;
+  collabSnapshot?: string | null;
+  story?: StoryDetail;
+  labels?: { id: string; name: string; color: string }[];
+  projects?: { id: string; name: string; icon: string; displayId?: string | null }[];
+  onEditorReady?: (editor: unknown) => void;
+  onStoryPatch?: (storyId: string, patch: Record<string, unknown>) => void;
+}) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <Suspense fallback={null}>
+        <StoryDetailBody
+          key={options.story?.id ?? STORY.id}
+          story={options.story ?? STORY}
+          users={[alice, bob]}
+          comments={[]}
+          activities={[]}
+          currentUserId={alice.id}
+          identifier="ALL-1"
+          labels={options.labels}
+          projects={options.projects}
+          collab={options.collab}
+          collabSnapshot={options.collabSnapshot}
+          onEditorReady={options.onEditorReady as never}
+          onStoryPatch={options.onStoryPatch as never}
+        />
+      </Suspense>
+    </QueryClientProvider>,
+  );
+}
+
+/** 等 lazy 的 NotionDocEditor 装载并返回编辑器实例（轮询至就绪，抗全量并行负载） */
+async function renderUntilEditorReady(options: Parameters<typeof renderBody>[0]) {
+  await notionLikeReady;
+  const editorRef: { current: unknown } = { current: null };
+  const view = renderBody({
+    ...options,
+    onEditorReady: (editor: unknown) => {
+      editorRef.current = editor;
+    },
+  });
+  await act(async () => {
+    for (let i = 0; i < 60 && !editorRef.current; i++) {
+      await Promise.resolve();
+      await vi.advanceTimersByTimeAsync(50);
+    }
+  });
+  const editor = editorRef.current as {
+    commands: { insertContent: (x: string) => void; setContent: (x: string) => void }
+    getHTML: () => string;
+    getJSON: () => unknown;
+    storage: Record<string, { manager?: { serialize?: (json: unknown) => string } }>;
+    extensionManager: { extensions: { name: string; options: Record<string, unknown> }[] };
+    isDestroyed: boolean;
+  } | null;
+  return { view, editor };
+}
+
+async function insertText(
+  editor: NonNullable<Awaited<ReturnType<typeof renderUntilEditorReady>>["editor"]>,
+  text: string,
+) {
+  await act(async () => {
+    editor.commands.insertContent(text);
+    await Promise.resolve();
+  });
+}
+
+async function openEditorAndPick(triggerLabel: string, optionLabel: string) {
+  await act(async () => {
+    fireEvent.click(screen.getByText(triggerLabel));
+  });
+  await act(async () => {
+    fireEvent.click(screen.getByText(optionLabel));
+  });
+}
+
+beforeEach(() => {
+  // jsdom 无 matchMedia（编辑器 use-is-breakpoint hook 需要）
+  if (typeof window.matchMedia !== "function") {
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: (query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      }),
+    });
+  }
+  // jsdom 的 Range 无 getClientRects（prosemirror-view 布局量测路径需要）
+  if (typeof Range !== "undefined" && typeof Range.prototype.getClientRects !== "function") {
+    const emptyRectList = () => {
+      const list = { length: 0, item: () => null, [Symbol.iterator]: [][Symbol.iterator] };
+      return list as unknown as DOMRectList;
+    };
+    Range.prototype.getClientRects = emptyRectList as unknown as typeof Range.prototype.getClientRects;
+    (Range.prototype as unknown as { getBoundingClientRect: () => DOMRect }).getBoundingClientRect = (() => ({
+      x: 0, y: 0, top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0,
+      toJSON: () => ({}),
+    })) as unknown as () => DOMRect;
+  }
+  vi.useFakeTimers();
+  rooms.clear();
+  fakeAwareness = buildFakeAwareness();
+  mocks.getOrCreateProvider.mockImplementation((roomName: string) => {
+    const existing = rooms.get(roomName);
+    if (existing) return existing;
+    const handle = buildFakeProvider(roomName);
+    rooms.set(roomName, handle);
+    return handle;
+  });
+  mocks.updateStoryFn.mockResolvedValue({ story: {}, activities: [] });
+  mocks.listStoryReactionsFn.mockResolvedValue([]);
+  mocks.toggleStoryReactionFn.mockResolvedValue([]);
+  mocks.createLabelFn.mockResolvedValue({ id: "label-new" });
+  mocks.suggestStoryLabelsFn.mockResolvedValue({ existingLabels: [], newNames: [] });
+  mocks.listProjectStoriesFn.mockResolvedValue({
+    items: [PARENT_CANDIDATE],
+    hasMore: false,
+    nextCursor: null,
+  });
+  mocks.transferStoryAsChildFn.mockResolvedValue({ activities: [] });
+  mocks.listEnabledModelsFn.mockResolvedValue([]);
+  mocks.useSession.mockReturnValue({
+    data: { user: { id: "user-1", name: "alice" } },
+    isPending: false,
+  });
+  mocks.aiUseSession.mockReturnValue({
+    data: { user: { id: "user-1", name: "alice" } },
+    isPending: false,
+  });
+});
+
+afterEach(() => {
+  rooms.clear();
+  vi.useRealTimers();
+  vi.clearAllMocks();
+});
+
+/** 取当前渲染树中的提示条文案（无则 null） */
+function bannerText(testId: string): string | null {
+  const node = document.body.querySelector(`[data-testid="${testId}"]`);
+  return node?.textContent ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// ① 协同态 description：Y 唯一写手（8s 防抖让位，审查重点 #3）
+// ---------------------------------------------------------------------------
+
+describe("协同态 description：旧 8s flush 通道短路", () => {
+  it("协同编辑内容 8s 兜底防抖窗口后不触发 updateStoryFn（Y 唯一写手）", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    expect(editor).not.toBeNull();
+
+    await insertText(editor!, "协同编辑内容");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600); // NotionDocEditor 500ms change 防抖
+      await vi.advanceTimersByTimeAsync(8_000 + 1_000); // 8s 兜底防抖窗口 + 余量
+    });
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("失焦 flush / 卸载 flush 通道同样短路（协同期）", async () => {
+    const { editor, view } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    expect(editor).not.toBeNull();
+
+    await insertText(editor!, "失焦前编辑");
+    // 失焦：pointerdown 落在编辑器容器外 → isEditorFocused=false → flush 通道
+    await act(async () => {
+      fireEvent.pointerDown(document.body);
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+
+    // 卸载 flush 通道（切换需求 / 关页面）
+    view.unmount();
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("远端 Y 写入（协作者编辑）同样不触发 DB 保存", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(handle).toBeTruthy();
+    expect(editor).not.toBeNull();
+
+    await act(async () => {
+      const fragment = handle!.doc.getXmlFragment("default");
+      const paragraph = new Y.XmlElement("paragraph");
+      const xmlText = new Y.XmlText();
+      xmlText.insert(0, "远端写入");
+      paragraph.insert(0, [xmlText]);
+      fragment.insert(fragment.length, [paragraph]);
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600 + 8_000 + 1_000);
+    });
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+    expect(editor!.getHTML()).toContain("远端写入");
+  });
+
+  it("SSR 快照预水合：snapshot 进 provider doc，编辑器内容来自 Y；collab 扩展挂 Collaboration+Caret", async () => {
+    const snapshot = buildSnapshotBase64("协同快照内容");
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: snapshot });
+    const handle = rooms.get("entity:story:story-1")!;
+
+    expect(handle.doc.getXmlFragment("default").toString()).toContain("协同快照内容");
+    await act(async () => {});
+    expect(editor!.getHTML()).toContain("协同快照内容");
+    expect(editor!.getHTML()).not.toContain("初始描述");
+
+    const names = editor!.extensionManager.extensions.map((e) => e.name);
+    expect(names).toContain("collaboration");
+    expect(names).toContain("collaborationCaret");
+    const caret = editor!.extensionManager.extensions.find((e) => e.name === "collaborationCaret");
+    expect(caret!.options.user).toEqual({ name: "alice", color: expect.any(String) });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ② 字段级协同：写 Y 并广播；远端变化实时回写 UI
+// ---------------------------------------------------------------------------
+
+/** 点击唯一含目标文本的 Button（mock UserAvatar 会渲染名字文本，选项按钮文本为「名字x2」；创建人行非 button 不参与匹配） */
+function clickUniqueButtonContaining(text: string) {
+  const buttons = [...document.body.querySelectorAll("button")].filter((b) =>
+    (b.textContent ?? "").includes(text),
+  );
+  if (buttons.length !== 1) {
+    throw new Error(`unique button ambiguous/missing: ${text} (${buttons.length})`);
+  }
+  fireEvent.click(buttons[0]!);
+}
+
+describe("协同态字段：改动写 fields Y.Map（广播），不触发 DB", () => {
+  it("state / priority / assignee 改动写入 Y.Map 且 updateStoryFn 零调用", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+
+    // state：待规划 → 待办
+    await openEditorAndPick("待规划", "待办");
+    // priority：中 → 高
+    await openEditorAndPick("中", "高");
+    // assignee：alice → bob
+    await act(async () => {
+      clickUniqueButtonContaining("alice");
+    });
+    await act(async () => {
+      clickUniqueButtonContaining("bob");
+    });
+
+    const fields = handle.doc.getMap<unknown>("fields");
+    expect(fields.get("state")).toBe("todo");
+    expect(fields.get("priority")).toBe("high");
+    expect(fields.get("assigneeId")).toBe("user-2");
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("远端字段变化实时回写本地 UI（不再手动刷新）", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+    expect(handle).toBeTruthy();
+
+    // 远端协作者直接写 Y（等价远端 update 应用）
+    await act(async () => {
+      handle!.doc.getMap<unknown>("fields").set("state", "in_progress");
+    });
+    // StateEditor 触发按钮显示远端值
+    expect(screen.getByText("进行中")).toBeTruthy();
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+});
+
+/** 按内含 lucide 图标类定位按钮（variant=button 的空值触发器无文本，仅图标） */
+function findButtonWithIcon(iconClass: string): HTMLButtonElement {
+  const button = [...document.body.querySelectorAll("button")].find((b) =>
+    b.querySelector(`svg.${iconClass}`),
+  );
+  if (!button) throw new Error(`button with icon not found: ${iconClass}`);
+  return button;
+}
+
+// ---------------------------------------------------------------------------
+// ②' 协同态通道全覆盖：labels / parent / AI apply / name / dates（8 字段补全）
+// ---------------------------------------------------------------------------
+
+describe("协同态通道全覆盖：labels/parent/AI/name/dates 写 Y 零 DB", () => {
+  it("labels 通道：StoryProperties 勾选标签写 Y labelIds，updateStoryFn 零调用", async () => {
+    const { editor } = await renderUntilEditorReady({
+      collab: true,
+      collabSnapshot: null,
+      labels: LABELS,
+    });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+
+    // LabelsEditor 触发按钮（初始无标签 → 图标-only 按钮）
+    await act(async () => {
+      fireEvent.click(findButtonWithIcon("lucide-tag"));
+    });
+    // multi 模式：点击标签行立即 onChange（不关弹窗）
+    await act(async () => {
+      fireEvent.click(screen.getByText("缺陷"));
+    });
+
+    expect(handle.doc.getMap<unknown>("fields").get("labelIds")).toEqual(["label-1"]);
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("parent 通道：StoryProperties 选择父需求写 Y parentId，updateStoryFn 零调用", async () => {
+    const { editor } = await renderUntilEditorReady({
+      collab: true,
+      collabSnapshot: null,
+      projects: PROJECTS,
+    });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+
+    // 打开父需求选择弹窗（「添加父需求」触发按钮）
+    await act(async () => {
+      fireEvent.click(screen.getByText("添加父需求"));
+    });
+    // 等待弹窗列表加载（listProjectStoriesFn 已 mock resolve）
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50);
+    });
+    // 选中候选需求行 → 确认
+    await act(async () => {
+      fireEvent.click(screen.getByText("父需求候选"));
+    });
+    await act(async () => {
+      fireEvent.click(screen.getByText("确认选择"));
+    });
+
+    expect(handle.doc.getMap<unknown>("fields").get("parentId")).toBe("story-9");
+    // 本组件的 parent DB 通道（updateStoryFn）短路；弹窗内部 transferStoryAsChildFn
+    // 是弹窗自带的 DB 操作（非本组件保存通道，旁路写入语义由 §5.3 门卫承接）
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("AI apply 通道：AI 改写经 Collaboration 写进 Y（description fragment），updateStoryFn 零调用", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("story-ai-apply-stub"));
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600 + 8_000 + 1_000);
+    });
+
+    expect(editor!.getHTML()).toContain("AI 改写后的内容");
+    expect(handle.doc.getXmlFragment("default").toString()).toContain("AI 改写后的内容");
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("name 通道：标题聚焦写 editing 标记、失焦写 Y name，updateStoryFn 零调用", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+
+    const input = screen.getByDisplayValue("登录页改版") as HTMLInputElement;
+    await act(async () => {
+      fireEvent.focus(input);
+    });
+    // editing:name 标记写入 awareness（远端见 name pill 数据源）
+    expect(fakeAwareness.localState?.["editing:name"]).toBeTruthy();
+
+    await act(async () => {
+      fireEvent.change(input, { target: { value: "新标题" } });
+      fireEvent.blur(input);
+    });
+
+    expect(handle.doc.getMap<unknown>("fields").get("name")).toBe("新标题");
+    // blur 摘除 editing 标记
+    expect(fakeAwareness.localState?.["editing:name"]).toBeUndefined();
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+
+  it("dates 通道：起始日期选日写 Y startDate，updateStoryFn 零调用", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+
+    // DateEditor(startDate) 触发按钮（空值 → 图标-only，CalendarPlus2 图标定位）
+    await act(async () => {
+      fireEvent.click(findButtonWithIcon("lucide-calendar-plus-2"));
+    });
+    // 点选日历 15 日（showOutsideDays 下同号可能重复，任一命中即断言日匹配）
+    await act(async () => {
+      const dayButtons = [...document.body.querySelectorAll("button")].filter(
+        (b) => (b.textContent ?? "").trim() === "15",
+      );
+      expect(dayButtons.length).toBeGreaterThan(0);
+      fireEvent.click(dayButtons[0]!);
+    });
+
+    expect(handle.doc.getMap<unknown>("fields").get("startDate")).toMatch(/-\d{2}-15$/);
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ③ key={story.id} 重建：room 正确切换销毁
+// ---------------------------------------------------------------------------
+
+describe("key 重建：room 切换销毁", () => {
+  it("切换需求：旧 room handle destroy、新 room 建连（entity:story:{新id}）", async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const view = render(
+      <QueryClientProvider client={queryClient}>
+        <Suspense fallback={null}>
+          <StoryDetailBody
+            key="story-1"
+            story={STORY}
+            users={[alice, bob]}
+            comments={[]}
+            activities={[]}
+            currentUserId={alice.id}
+            identifier="ALL-1"
+            collab
+            collabSnapshot={null}
+          />
+        </Suspense>
+      </QueryClientProvider>,
+    );
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50);
+    });
+    const oldRoom = rooms.get("entity:story:story-1")!;
+    expect(oldRoom).toBeTruthy();
+
+    const story2 = mkStory({ id: "story-2", identifier: "ALL-2", name: "需求二" });
+    await act(async () => {
+      view.rerender(
+        <QueryClientProvider client={queryClient}>
+          <Suspense fallback={null}>
+            <StoryDetailBody
+              key="story-2"
+              story={story2}
+              users={[alice, bob]}
+              comments={[]}
+              activities={[]}
+              currentUserId={alice.id}
+              identifier="ALL-2"
+              collab
+              collabSnapshot={null}
+            />
+          </Suspense>
+        </QueryClientProvider>,
+      );
+    });
+
+    expect(oldRoom.destroy).toHaveBeenCalled();
+    expect(rooms.has("entity:story:story-2")).toBe(true);
+    expect(mocks.getOrCreateProvider).toHaveBeenCalledWith("entity:story:story-2");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ④ 字段 pill：数据源来自 awareness（editing:*），3s 余晖
+// ---------------------------------------------------------------------------
+
+describe("字段编辑 pill：awareness 数据源 + 3s 余晖", () => {
+  it("远端 editing:state 标记到达 → state 字段旁显示「bob 正在编辑」；移除 → 3s 后消失", async () => {
+    await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+
+    await act(async () => {
+      fakeAwareness.__addRemote(1001, {
+        "editing:state": { userId: "user-2", name: "bob", ts: Date.now() },
+      });
+    });
+    const pill = document.body.querySelector('[data-testid="collab-field-pill-state"]');
+    expect(pill).toBeTruthy();
+    expect(pill!.textContent).toContain("bob");
+    expect(pill!.textContent).toContain("正在编辑");
+
+    // 远端 blur（标记摘除）→ 3s 余晖内仍在，3s 后消失
+    await act(async () => {
+      fakeAwareness.__removeRemote(1001);
+    });
+    expect(document.body.querySelector('[data-testid="collab-field-pill-state"]')).toBeTruthy();
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(3_000 + 50);
+    });
+    expect(document.body.querySelector('[data-testid="collab-field-pill-state"]')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ⑤ collab=false 回归（现状保存链路原样）
+// ---------------------------------------------------------------------------
+
+describe("collab=false 回归", () => {
+  it("provider 零创建；8s 兜底防抖触发 DB 保存（既有行为）", async () => {
+    const { editor } = await renderUntilEditorReady({});
+    expect(mocks.getOrCreateProvider).not.toHaveBeenCalled();
+    expect(editor).not.toBeNull();
+
+    await insertText(editor!, "本地编辑");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600);
+      await vi.advanceTimersByTimeAsync(8_000 + 1_000);
+    });
+    expect(mocks.updateStoryFn).toHaveBeenCalledTimes(1);
+    const payload = mocks.updateStoryFn.mock.calls[0]![0] as {
+      data: { storyId: string; description: string };
+    };
+    expect(payload.data.storyId).toBe("story-1");
+    expect(payload.data.description).toContain("本地编辑");
+  });
+
+  it("meta 字段改动走既有 DB 通道（updateStoryFn）", async () => {
+    await renderUntilEditorReady({});
+    await openEditorAndPick("待规划", "待办");
+    expect(mocks.updateStoryFn).toHaveBeenCalledWith(
+      expect.objectContaining({ data: expect.objectContaining({ storyId: "story-1", state: "todo" }) }),
+    );
+  });
+
+  it("meta 字段落库后回传 onStoryPatch（列表/看板乐观更新通道）", async () => {
+    const onStoryPatch = vi.fn();
+    await renderUntilEditorReady({ onStoryPatch });
+    await openEditorAndPick("待规划", "待办");
+    expect(onStoryPatch).toHaveBeenCalledWith("story-1", { state: "todo" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ⑥ 降级模式（offline → DB 通道恢复；synced → 再短路）
+// ---------------------------------------------------------------------------
+
+describe("降级模式", () => {
+  it("offline：提示条出现 + 协同期未落库内容经 DB 通道补存 + 降级期编辑走 DB", async () => {
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: null });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+    expect(handle).toBeTruthy();
+
+    await insertText(editor!, "协同期编辑");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600 + 8_000);
+    });
+    expect(mocks.updateStoryFn).not.toHaveBeenCalled();
+
+    await act(async () => {
+      handle!.__setStatus("offline");
+    });
+    expect(bannerText("collab-offline-banner")).toBeTruthy();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+    expect(mocks.updateStoryFn).toHaveBeenCalledTimes(1);
+    const payload = mocks.updateStoryFn.mock.calls[0]![0] as {
+      data: { description: string };
+    };
+    expect(payload.data.description).toContain("协同期编辑");
+
+    // 降级期 meta 字段改动恢复 DB 通道
+    await openEditorAndPick("待规划", "待办");
+    expect(mocks.updateStoryFn).toHaveBeenCalledWith(
+      expect.objectContaining({ data: expect.objectContaining({ state: "todo" }) }),
+    );
+  });
+
+  it("synced 恢复：提示条消失 + DB 通道再短路（未到期 flush 被取消）", async () => {
+    // 种子快照让编辑器有内容：offline 转换的补存通道写入种子内容（T15 同构语义）
+    const snapshot = buildSnapshotBase64("协同快照内容");
+    const { editor } = await renderUntilEditorReady({ collab: true, collabSnapshot: snapshot });
+    const handle = rooms.get("entity:story:story-1")!;
+    expect(editor).not.toBeNull();
+    expect(handle).toBeTruthy();
+
+    await act(async () => {
+      handle!.__setStatus("offline");
+    });
+    expect(bannerText("collab-offline-banner")).toBeTruthy();
+    // 降级补存：协同期 Y 独占的内容（种子）经 DB 通道落库一次
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+    expect(mocks.updateStoryFn).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      handle!.__setStatus("synced");
+    });
+    expect(bannerText("collab-offline-banner")).toBeNull();
+
+    await insertText(editor!, "恢复后编辑");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600 + 8_000 + 1_000);
+    });
+    // 恢复后 Y 再度独占：不产生新的 DB 调用（仅降级窗口那一次）
+    expect(mocks.updateStoryFn).toHaveBeenCalledTimes(1);
+    expect(editor!.getHTML()).toContain("恢复后编辑");
+  });
+});