@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/shared-kit/list-kit/kanban/__tests__/kanban-board-view.test.tsx

@@ -0,0 +1,901 @@
+// 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/>.
+
+// KanbanBoardView 全能力共享看板（UI 对齐二期 PR-7a 任务 24）。
+// 拖拽语义测试策略（复审 P1-8）：jsdom 不模拟 dnd-kit 真拖——
+// 拖拽提交语义走组件导出的 drop 决策纯函数（resolveDropCommit / commitDropDecision，
+// 照 story views/__tests__/kanban-drop-subgroup.test.ts 先例）；
+// 渲染级仅点击 / 结构断言。
+
+import { act, cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useEffect, useState, type Dispatch, type ReactNode, type SetStateAction } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  commitDropDecision,
+  resolveDropCommit,
+  resolveDropSubKey,
+  resolveSubKeyForDrop,
+  type CommitDropDeps,
+  type DropCommitDecision,
+} from "../drop-commit";
+import {
+  KanbanBoardView,
+  KanbanGhostColumn,
+  type KanbanModuleConfig,
+} from "../kanban-board-view";
+import { Kanban, KanbanBoard } from "@/components/reui/kanban";
+
+const MockResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+if (typeof globalThis.ResizeObserver === "undefined") {
+  (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver =
+    MockResizeObserver;
+}
+
+const { toast, kanbanPropsRef } = vi.hoisted(() => ({
+  toast: {
+    success: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warning: vi.fn(),
+    loading: vi.fn(),
+    message: vi.fn(),
+    dismiss: vi.fn(),
+    promise: vi.fn(),
+  },
+  // 透传捕获 reui Kanban 的 props：jsdom 不模拟真拖，列提交分支经捕获的
+  // onValueChange/onValueCommit 直调（任务 42 审查修复的列拖拽失败断言）
+  kanbanPropsRef: { current: null as Record<string, unknown> | null },
+}));
+vi.mock("@/components/ui/toast", () => ({ toast }));
+vi.mock("@/components/reui/kanban", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@/components/reui/kanban")>();
+  const KanbanCapture = (props: Record<string, unknown>) => {
+    kanbanPropsRef.current = props;
+    const Real = actual.Kanban as unknown as (p: Record<string, unknown>) => ReactNode;
+    return <Real {...props} />;
+  };
+  return { ...actual, Kanban: KanbanCapture };
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+interface Item {
+  id: string;
+  name: string;
+}
+
+const item = (id: string): Item => ({ id, name: `card-${id}` });
+
+/* ------------------------------------------------------------------ */
+/* ① resolveDropCommit：跨列 → onDropToColumn(itemKey, columnKey) 产物  */
+/* ------------------------------------------------------------------ */
+
+describe("resolveDropCommit 跨列提交", () => {
+  it("跨列 drop 产出 move 决策：条目 id + 目标列 + 目标列全列索引", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t1",
+      activeContainer: "todo",
+      overContainer: "done",
+      nextValue: {
+        todo: [item("t2")],
+        done: [item("d1"), item("t1"), item("d2")],
+      },
+    });
+
+    assertMove(decision, {
+      itemKey: "t1",
+      columnKey: "done",
+      orders: [
+        { id: "d1", boardOrder: 0 },
+        { id: "t1", boardOrder: 1 },
+        { id: "d2", boardOrder: 2 },
+      ],
+    });
+  });
+
+  it("实例 id 与裸 id 都能解析出条目 id（activeId 兼容两种形态）", () => {
+    const decision = resolveDropCommit({
+      activeId: "t1",
+      activeContainer: "todo",
+      overContainer: "done",
+      nextValue: { todo: [], done: [item("t1")] },
+    });
+    assertMove(decision, {
+      itemKey: "t1",
+      columnKey: "done",
+      orders: [{ id: "t1", boardOrder: 0 }],
+    });
+  });
+
+  it("跨列且提供成员表时解析目标子分组（紧随其后的卡片优先）", () => {
+    // 提交后排列：[d1(high), t1, d2(low)] → t1 紧随其后是 d2 → 目标子分组 low（蓝本口径）
+    const decision = resolveDropCommit({
+      activeId: "todo::t1",
+      activeContainer: "todo",
+      overContainer: "done",
+      nextValue: { todo: [], done: [item("d1"), item("t1"), item("d2")] },
+      membership: { d1: "high", t1: "low", d2: "low" },
+    });
+    assertMove(decision, {
+      itemKey: "t1",
+      columnKey: "done",
+      subKey: "low",
+      orders: [
+        { id: "d1", boardOrder: 0 },
+        { id: "t1", boardOrder: 1 },
+        { id: "d2", boardOrder: 2 },
+      ],
+    });
+  });
+
+  it("跨列且被拖卡在列尾（其后无卡）时取前一张卡的子分组", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t1",
+      activeContainer: "todo",
+      overContainer: "done",
+      nextValue: { todo: [], done: [item("d1"), item("t1")] },
+      membership: { d1: "high" },
+    });
+    assertMove(decision, {
+      itemKey: "t1",
+      columnKey: "done",
+      subKey: "high",
+      orders: [
+        { id: "d1", boardOrder: 0 },
+        { id: "t1", boardOrder: 1 },
+      ],
+    });
+  });
+
+  it("跨列且 hover 卡带子分组时优先取 hover 卡归属", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t1",
+      activeContainer: "todo",
+      overContainer: "done",
+      nextValue: { todo: [], done: [item("d1"), item("t1")] },
+      membership: { d1: "high" },
+      overItemId: "done::d1",
+    });
+    assertMove(decision, {
+      itemKey: "t1",
+      columnKey: "done",
+      subKey: "high",
+      orders: [
+        { id: "d1", boardOrder: 0 },
+        { id: "t1", boardOrder: 1 },
+      ],
+    });
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* ② resolveDropCommit：manualOrder 开启时列内 → onReorder 全列索引产物  */
+/* ------------------------------------------------------------------ */
+
+describe("resolveDropCommit 列内提交", () => {
+  it("列内 drop 产出 reorder 决策：全列索引 boardOrder", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t2",
+      activeContainer: "todo",
+      overContainer: "todo",
+      nextValue: { todo: [item("t1"), item("t2"), item("t3")] },
+    });
+
+    expect(decision.kind).toBe("reorder");
+    if (decision.kind !== "reorder") return;
+    expect(decision.itemKey).toBe("t2");
+    expect(decision.columnKey).toBe("todo");
+    expect(decision.orders).toEqual([
+      { id: "t1", boardOrder: 0 },
+      { id: "t2", boardOrder: 1 },
+      { id: "t3", boardOrder: 2 },
+    ]);
+  });
+
+  // 任务 42 必带③（story kanban-drop-subgroup 蓝本口径）：同列跨子分组 drop
+  // 也按「提交后的相邻卡片 / hover 卡」解析子分组归属，reorder 决策携带 subKey，
+  // 供 commitDropDecision 经 onSubGroupMove 落库（蓝本同列拖子组会写子组字段）。
+  it("同列且提供成员表时解析子分组归属：reorder 决策携带 subKey", () => {
+    // 提交后排列：[t1(high), t2, t3(low)] → t2 紧随其后是 t3 → 目标子分组 low
+    const decision = resolveDropCommit({
+      activeId: "todo::t2",
+      activeContainer: "todo",
+      overContainer: "todo",
+      nextValue: { todo: [item("t1"), item("t2"), item("t3")] },
+      membership: { t1: "high", t2: "high", t3: "low" },
+    });
+
+    expect(decision.kind).toBe("reorder");
+    if (decision.kind !== "reorder") return;
+    expect(decision.subKey).toBe("low");
+  });
+
+  it("同列 hover 卡带子分组时优先取 hover 卡归属（appendToPreviousRun 语义）", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t3",
+      activeContainer: "todo",
+      overContainer: "todo",
+      nextValue: { todo: [item("t1"), item("t3"), item("t2")] },
+      membership: { t1: "high", t2: "low", t3: "low" },
+      overItemId: "todo::t1",
+    });
+
+    expect(decision.kind).toBe("reorder");
+    if (decision.kind !== "reorder") return;
+    expect(decision.subKey).toBe("high");
+  });
+
+  it("未提供成员表时 reorder 决策不带 subKey", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t2",
+      activeContainer: "todo",
+      overContainer: "todo",
+      nextValue: { todo: [item("t1"), item("t2")] },
+    });
+
+    expect(decision.kind).toBe("reorder");
+    if (decision.kind !== "reorder") return;
+    expect(decision.subKey).toBeUndefined();
+  });
+});
+
+describe("commitDropDecision 的 onReorder 接线", () => {
+  const reorderDecision: DropCommitDecision = {
+    kind: "reorder",
+    itemKey: "t2",
+    columnKey: "todo",
+    orders: [
+      { id: "t1", boardOrder: 0 },
+      { id: "t2", boardOrder: 1 },
+    ],
+  };
+
+  function baseDeps(): Omit<CommitDropDeps<Item>, "manualOrder" | "decision"> {
+    return {
+      previousValue: { todo: [item("t2"), item("t1")] },
+      setColumns: vi.fn(),
+      onDropToColumn: vi.fn().mockResolvedValue(undefined),
+    };
+  }
+
+  it("manualOrder 开启：列内 reorder 触发 onReorder（全列索引）+ onAutoSwitchManual", async () => {
+    const onReorder = vi.fn().mockResolvedValue(undefined);
+    const onAutoSwitchManual = vi.fn().mockResolvedValue(undefined);
+    const onSuccess = vi.fn();
+
+    await commitDropDecision({
+      ...baseDeps(),
+      decision: reorderDecision,
+      manualOrder: { onReorder, onAutoSwitchManual },
+      onSuccess,
+    });
+
+    expect(onReorder).toHaveBeenCalledTimes(1);
+    expect(onReorder.mock.calls[0][0]).toEqual(reorderDecision.orders);
+    expect(onAutoSwitchManual).toHaveBeenCalledTimes(1);
+    expect(onSuccess).toHaveBeenCalledTimes(1);
+    // 列内不触发 onDropToColumn
+    expect(toast.success).not.toHaveBeenCalled();
+  });
+
+  it("manualOrder 未开启：不触发 onReorder / onAutoSwitchManual", async () => {
+    await commitDropDecision({ ...baseDeps(), decision: reorderDecision });
+    expect(toast.success).not.toHaveBeenCalled();
+  });
+});
+
+// 任务 42 必带③：同列跨子分组拖拽的子组字段落库通道（story kanban-view 蓝本
+// 在同列也写子组字段 patch；通道的「同值跳写 + 成功 toast」由消费方权威比对后自负，
+// 共享层不掌握权威成员表与文案维度）。
+describe("commitDropDecision 的 onSubGroupMove 通道", () => {
+  const subGroupReorderDecision: DropCommitDecision = {
+    kind: "reorder",
+    itemKey: "t2",
+    columnKey: "todo",
+    subKey: "low",
+    orders: [
+      { id: "t1", boardOrder: 0 },
+      { id: "t2", boardOrder: 1 },
+    ],
+  };
+
+  function baseDeps(): Omit<CommitDropDeps<Item>, "manualOrder" | "decision"> {
+    return {
+      previousValue: { todo: [item("t2"), item("t1")] },
+      setColumns: vi.fn(),
+      onDropToColumn: vi.fn().mockResolvedValue(undefined),
+    };
+  }
+
+  it("reorder 带 subKey：先 onSubGroupMove 再 onReorder（蓝本：字段 patch 先于排序落库）", async () => {
+    const onSubGroupMove = vi.fn().mockResolvedValue(undefined);
+    const onReorder = vi.fn().mockResolvedValue(undefined);
+    const callOrder: string[] = [];
+    onSubGroupMove.mockImplementation(async () => {
+      callOrder.push("subGroupMove");
+    });
+    onReorder.mockImplementation(async () => {
+      callOrder.push("reorder");
+    });
+
+    await commitDropDecision({
+      ...baseDeps(),
+      decision: subGroupReorderDecision,
+      onSubGroupMove,
+      manualOrder: { onReorder },
+    });
+
+    expect(onSubGroupMove).toHaveBeenCalledTimes(1);
+    expect(onSubGroupMove).toHaveBeenCalledWith("t2", "todo", "low");
+    expect(callOrder).toEqual(["subGroupMove", "reorder"]);
+    // 成功 toast 归消费方（同值跳写时不应弹「已更新分组」）
+    expect(toast.success).not.toHaveBeenCalled();
+  });
+
+  it("reorder 不带 subKey（未启用子分组/不可跨区维度）：不触发 onSubGroupMove", async () => {
+    const onSubGroupMove = vi.fn().mockResolvedValue(undefined);
+    await commitDropDecision({
+      ...baseDeps(),
+      decision: { ...subGroupReorderDecision, subKey: undefined },
+      onSubGroupMove,
+      manualOrder: { onReorder: vi.fn().mockResolvedValue(undefined) },
+    });
+    expect(onSubGroupMove).not.toHaveBeenCalled();
+  });
+
+  it("未提供 onSubGroupMove：保持既有行为（仅 reorder 落库）", async () => {
+    const onReorder = vi.fn().mockResolvedValue(undefined);
+    await commitDropDecision({
+      ...baseDeps(),
+      decision: subGroupReorderDecision,
+      manualOrder: { onReorder },
+    });
+    expect(onReorder).toHaveBeenCalledTimes(1);
+    expect(toast.success).not.toHaveBeenCalled();
+  });
+
+  it("onSubGroupMove reject：乐观列回滚 + onRefresh + toast.error（不触发 onReorder）", async () => {
+    const setColumns = vi.fn();
+    const onRefresh = vi.fn();
+    const onReorder = vi.fn().mockResolvedValue(undefined);
+
+    await commitDropDecision({
+      ...baseDeps(),
+      decision: subGroupReorderDecision,
+      setColumns,
+      onSubGroupMove: vi.fn().mockRejectedValue(new Error("network down")),
+      manualOrder: { onReorder },
+      onRefresh,
+    });
+
+    expect(setColumns).toHaveBeenCalledWith(baseDeps().previousValue);
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+    expect(toast.error).toHaveBeenCalledTimes(1);
+    expect(onReorder).not.toHaveBeenCalled();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* ③ commit reject → 乐观列回滚 + toast（渲染级验证状态还原）            */
+/* ------------------------------------------------------------------ */
+
+describe("commitDropDecision 失败路径", () => {
+  const previousValue = { todo: [item("t1")], done: [] as Item[] };
+
+  /** 渲染级 harness：持有真实 React state，把列状态渲染为文本供断言 */
+  function RollbackHarness(props: {
+    run: (setColumns: Dispatch<SetStateAction<Record<string, Item[]>>>) => Promise<void>;
+  }) {
+    const [columns, setColumns] = useState<Record<string, Item[]>>(previousValue);
+    const [settled, setSettled] = useState(false);
+    useEffect(() => {
+      let cancelled = false;
+      props.run(setColumns).then(() => {
+        if (!cancelled) setSettled(true);
+      });
+      return () => {
+        cancelled = true;
+      };
+    }, []);
+    return (
+      <div data-testid="state">
+        {JSON.stringify(columns)}
+        {settled ? "|settled" : ""}
+      </div>
+    );
+  }
+
+  it("onDropToColumn reject：乐观列回滚 previousValue + onRefresh + toast.error", async () => {
+    const onDropToColumn = vi.fn().mockRejectedValue(new Error("network down"));
+    const onRefresh = vi.fn();
+    const onReorder = vi.fn().mockResolvedValue(undefined);
+
+    await act(async () => {
+      render(
+        <RollbackHarness
+          run={(setColumns) =>
+            commitDropDecision({
+              decision: {
+                kind: "move",
+                itemKey: "t1",
+                columnKey: "done",
+                subKey: "high",
+                orders: [{ id: "t1", boardOrder: 0 }],
+              },
+              previousValue,
+              setColumns,
+              onDropToColumn,
+              manualOrder: { onReorder },
+              onRefresh,
+              targetLabel: "完成-高",
+            })
+          }
+        />,
+      );
+    });
+
+    const state = screen.getByTestId("state").textContent ?? "";
+    // 渲染级：列状态已还原为提交前的乐观值
+    expect(state).toContain(JSON.stringify(previousValue));
+    expect(state).toContain("|settled");
+    expect(onDropToColumn).toHaveBeenCalledWith("t1", "done", { subKey: "high" });
+    // 失败后不再 reorder，且立即触发权威刷新
+    expect(onReorder).not.toHaveBeenCalled();
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+    expect(toast.error).toHaveBeenCalledTimes(1);
+    expect(toast.success).not.toHaveBeenCalled();
+  });
+
+  it("onReorder reject：同样回滚 + toast（move 已成功也整体回滚）", async () => {
+    const onDropToColumn = vi.fn().mockResolvedValue(undefined);
+    const onReorder = vi.fn().mockRejectedValue(new Error("reorder failed"));
+    const setColumns = vi.fn();
+
+    await commitDropDecision({
+      decision: {
+        kind: "move",
+        itemKey: "t1",
+        columnKey: "done",
+        orders: [{ id: "t1", boardOrder: 0 }],
+      },
+      previousValue,
+      setColumns,
+      onDropToColumn,
+      manualOrder: { onReorder },
+      onRefresh: vi.fn(),
+    });
+
+    expect(setColumns).toHaveBeenCalledWith(previousValue);
+    expect(toast.error).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignore 决策：仅回滚乐观列，不落库不刷新", async () => {
+    const onDropToColumn = vi.fn().mockResolvedValue(undefined);
+    const setColumns = vi.fn();
+
+    await commitDropDecision({
+      decision: { kind: "ignore", reason: "notDroppable" },
+      previousValue,
+      setColumns,
+      onDropToColumn,
+    });
+
+    expect(setColumns).toHaveBeenCalledTimes(1);
+    expect(setColumns).toHaveBeenCalledWith(previousValue);
+    expect(onDropToColumn).not.toHaveBeenCalled();
+    expect(toast.error).not.toHaveBeenCalled();
+  });
+
+  it("move 成功：onDropToColumn → onReorder → onSuccess（延迟刷新由组件包装）", async () => {
+    const onDropToColumn = vi.fn().mockResolvedValue(undefined);
+    const onReorder = vi.fn().mockResolvedValue(undefined);
+    const onSuccess = vi.fn();
+    const setColumns = vi.fn();
+
+    await commitDropDecision({
+      decision: {
+        kind: "move",
+        itemKey: "t1",
+        columnKey: "done",
+        orders: [{ id: "t1", boardOrder: 0 }],
+      },
+      previousValue,
+      setColumns,
+      onDropToColumn,
+      manualOrder: { onReorder },
+      onSuccess,
+      targetLabel: "完成",
+    });
+
+    expect(onDropToColumn).toHaveBeenCalledWith("t1", "done", undefined);
+    expect(onReorder).toHaveBeenCalledTimes(1);
+    expect(onSuccess).toHaveBeenCalledTimes(1);
+    expect(setColumns).not.toHaveBeenCalled();
+    expect(toast.success).toHaveBeenCalledTimes(1);
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* ④b columnDroppable=false 的列 drop 被忽略（P1-1 labels 禁拖口径）      */
+/* ------------------------------------------------------------------ */
+
+describe("resolveDropCommit columnDroppable 守卫", () => {
+  const notLabels = (key: string) => key !== "labels";
+
+  it("目标列 columnDroppable=false：跨列 drop 产出 ignore", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t1",
+      activeContainer: "todo",
+      overContainer: "labels",
+      nextValue: { todo: [], labels: [] },
+      columnDroppable: notLabels,
+    });
+    expect(decision).toEqual({ kind: "ignore", reason: "notDroppable" });
+  });
+
+  it("目标列 columnDroppable=false：列内 drop 同样被忽略", () => {
+    const decision = resolveDropCommit({
+      activeId: "labels::t1",
+      activeContainer: "labels",
+      overContainer: "labels",
+      nextValue: { labels: [item("t1"), item("t2")] },
+      columnDroppable: notLabels,
+    });
+    expect(decision).toEqual({ kind: "ignore", reason: "notDroppable" });
+  });
+
+  it("缺省 columnDroppable（未传）视为全部可放置", () => {
+    const decision = resolveDropCommit({
+      activeId: "todo::t1",
+      activeContainer: "todo",
+      overContainer: "labels",
+      nextValue: { todo: [], labels: [item("t1")] },
+    });
+    expect(decision.kind).toBe("move");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* 子分组落点判定（蓝本 resolveSubKeyForDrop / resolveDropSubKey 等价搬迁）*/
+/* ------------------------------------------------------------------ */
+
+describe("resolveSubKeyForDrop / resolveDropSubKey", () => {
+  const membership = { a: "high", b: "high", c: "medium", d: "low" };
+
+  it("hover 卡优先：追加到 hover 卡所属分组", () => {
+    const items = [item("a"), item("x"), item("b"), item("c")];
+    expect(resolveSubKeyForDrop(items, "x", membership, "a")).toBe("high");
+  });
+
+  it("无 hover 卡时回落到相邻卡规则", () => {
+    const items = [item("x"), item("c"), item("d")];
+    expect(resolveSubKeyForDrop(items, "x", membership, "done")).toBe("medium");
+  });
+
+  it("插到某卡之前取紧随其后那张卡的子分组", () => {
+    const items = [item("a"), item("x"), item("b"), item("c"), item("d")];
+    expect(resolveDropSubKey(items, "x", membership)).toBe("high");
+  });
+
+  it("追加到列尾取前一张卡的子分组", () => {
+    const items = [item("a"), item("b"), item("c"), item("x")];
+    expect(resolveDropSubKey(items, "x", membership)).toBe("medium");
+  });
+
+  it("找不到该卡时返回 undefined（调用方跳过）", () => {
+    expect(resolveDropSubKey([item("a")], "zzz", membership)).toBeUndefined();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* KanbanBoardView 渲染结构（jsdom 无布局 → 全量渲染路径，无虚拟化）        */
+/* ------------------------------------------------------------------ */
+
+describe("KanbanBoardView 渲染结构", () => {
+  function buildConfig(
+    overrides: Partial<KanbanModuleConfig<Item>> = {},
+  ): KanbanModuleConfig<Item> {
+    return {
+      columns: { todo: [item("t1"), item("t2")], done: [item("d1")] },
+      columnMeta: (key) => ({
+        label: key === "todo" ? "待办" : key === "done" ? "完成" : key,
+      }),
+      cardKey: (entry) => entry.id,
+      renderCard: (entry) => <div>{entry.name}</div>,
+      onOpenItem: vi.fn(),
+      onDropToColumn: vi.fn().mockResolvedValue(undefined),
+      capabilities: {},
+      ...overrides,
+    };
+  }
+
+  function renderView(config: KanbanModuleConfig<Item>) {
+    return render(<KanbanBoardView config={config} />);
+  }
+
+  it("渲染全部列与卡片（renderCard 产物），列头显示 label 与计数", () => {
+    const { container } = renderView(buildConfig());
+
+    expect(screen.getByText("待办")).toBeTruthy();
+    expect(screen.getByText("完成")).toBeTruthy();
+    expect(screen.getByText("card-t1")).toBeTruthy();
+    expect(screen.getByText("card-t2")).toBeTruthy();
+    expect(screen.getByText("card-d1")).toBeTruthy();
+    // 列头计数徽章：待办 2 / 完成 1
+    const counts = Array.from(
+      container.querySelectorAll('[data-slot="kanban-column"] .truncate + span, [data-slot="kanban-column"] span'),
+    ).map((el) => el.textContent);
+    expect(counts).toContain("2");
+    expect(counts).toContain("1");
+  });
+
+  it("点击卡片触发 onOpenItem（渲染级点击断言）", async () => {
+    const onOpenItem = vi.fn();
+    renderView(buildConfig({ onOpenItem }));
+
+    await userEvent.click(screen.getByText("card-t1"));
+    expect(onOpenItem).toHaveBeenCalledTimes(1);
+    // 条目经 applyInstanceKeys 附带 __instanceKey（蓝本同口径），断言业务字段
+    expect(onOpenItem).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "t1", name: "card-t1" }),
+    );
+  });
+
+  it("未开启 columnDrag 时不渲染列把手；开启后渲染", () => {
+    const { container: without } = renderView(buildConfig());
+    expect(
+      without.querySelectorAll('[data-slot="kanban-column-handle"]'),
+    ).toHaveLength(0);
+    cleanup();
+
+    const { container: withDrag } = renderView(
+      buildConfig({
+        capabilities: {
+          columnDrag: { onColumnOrderCommit: vi.fn().mockResolvedValue(undefined) },
+        },
+      }),
+    );
+    const handles = withDrag.querySelectorAll('[data-slot="kanban-column-handle"]');
+    expect(handles.length).toBeGreaterThanOrEqual(2);
+    // 把手带可访问名（共享层 i18n 文案）
+    expect(
+      withDrag.querySelector('[aria-label="拖动调整列顺序"]'),
+    ).toBeTruthy();
+  });
+
+  // 任务 42 审查修复回归：列拖拽 reject 只回滚乐观列序，共享层不再叠
+  // moveFailed toast（列序失败文案语义归消费方，如 story 的 columnOrderFailed；
+  // 卡移动/排序分支的共享 toast 不受影响）。
+  it("列拖拽 reject：乐观列序回滚 + 不弹共享 toast（消费方语义提示）", async () => {
+    const onColumnOrderCommit = vi.fn().mockRejectedValue(new Error("network down"));
+    renderView(
+      buildConfig({
+        capabilities: { columnDrag: { onColumnOrderCommit } },
+      }),
+    );
+
+    const columnLabels = () =>
+      Array.from(
+        document.querySelectorAll('[data-slot="kanban-column"] span.truncate'),
+      ).map((el) => el.textContent);
+    // 初渲染列序：待办(todo) 在前
+    expect(columnLabels()[0]).toBe("待办");
+
+    // 模拟列拖拽乐观态：done 已被拖到最前（onDragOver 经 onValueChange 提交）
+    const previousValue = { todo: [item("t1"), item("t2")], done: [item("d1")] };
+    const next = { done: [item("d1")], todo: [item("t1"), item("t2")] };
+    const props = kanbanPropsRef.current as {
+      onValueChange: (v: Record<string, Item[]>) => void;
+      onValueCommit: (v: Record<string, Item[]>, m: unknown) => Promise<void>;
+    };
+    await act(async () => {
+      props.onValueChange(next);
+    });
+    expect(columnLabels()[0]).toBe("完成");
+
+    // 提交落库失败 → 回滚到 previousValue（完成 回到第二位），无共享 toast
+    await act(async () => {
+      await props.onValueCommit(next, {
+        kind: "column",
+        event: { active: { id: "done" }, over: { id: "todo" } },
+        activeContainer: "done",
+        activeIndex: 0,
+        overContainer: "todo",
+        overIndex: 0,
+        previousValue,
+      });
+    });
+
+    expect(onColumnOrderCommit).toHaveBeenCalledWith(["done", "todo"]);
+    expect(columnLabels()[0]).toBe("待办");
+    expect(toast.error).not.toHaveBeenCalled();
+    expect(toast.success).not.toHaveBeenCalled();
+  });
+
+  it("提供 onLoadMoreColumn 时列尾渲染加载更多，点击回传列 key", async () => {
+    const onLoadMoreColumn = vi.fn();
+    const { container } = renderView(buildConfig({ onLoadMoreColumn }));
+
+    const buttons = Array.from(
+      container.querySelectorAll<HTMLButtonElement>("button"),
+    ).filter((el) => el.textContent === "加载更多");
+    expect(buttons).toHaveLength(2);
+
+    await userEvent.click(buttons[0]!);
+    expect(onLoadMoreColumn).toHaveBeenCalledWith("todo");
+  });
+
+  it("空列集合渲染空态文案", () => {
+    renderView(buildConfig({ columns: {} }));
+    expect(screen.getByText("暂无内容")).toBeTruthy();
+  });
+
+  it("columnMeta.count 缺省取列内条目数，传入时优先用 count", () => {
+    const { container } = renderView(
+      buildConfig({
+        columnMeta: (key) => ({
+          label: key,
+          count: key === "todo" ? 99 : undefined,
+        }),
+      }),
+    );
+    const texts = Array.from(container.querySelectorAll("span")).map(
+      (el) => el.textContent,
+    );
+    expect(texts).toContain("99");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* ④a 空目标列虚线壳（拖拽期虚显缺失列）：导出的 KanbanGhostColumn 结构断言 */
+/* ------------------------------------------------------------------ */
+
+describe("KanbanGhostColumn 空列虚线壳", () => {
+  it("渲染 border-dashed 虚线壳与列头（含 0 计数徽章）", () => {
+    const { container } = render(
+      <Kanban
+        value={{ todo: [item("t1")], ghostcol: [] }}
+        getItemValue={(entry: Item) => entry.id}
+        onValueChange={() => {}}
+      >
+        <KanbanBoard>
+          <KanbanGhostColumn
+            columnKey="ghostcol"
+            meta={{ label: "虚列" }}
+            isOver={false}
+            storyMap={{}}
+            renderGhost={() => null}
+          />
+        </KanbanBoard>
+      </Kanban>,
+    );
+
+    const shell = container.querySelector(".border-dashed");
+    expect(shell).toBeTruthy();
+    expect(shell!.className).toContain("border-muted-foreground/40");
+    expect(container.textContent).toContain("虚列");
+    expect(container.textContent).toContain("0");
+  });
+
+  it("isOver 时壳体高亮（border-primary + 不透明）", () => {
+    const { container } = render(
+      <Kanban
+        value={{ ghostcol: [] }}
+        getItemValue={(entry: Item) => entry.id}
+        onValueChange={() => {}}
+      >
+        <KanbanBoard>
+          <KanbanGhostColumn
+            columnKey="ghostcol"
+            meta={{ label: "虚列" }}
+            isOver
+            storyMap={{}}
+            renderGhost={() => null}
+          />
+        </KanbanBoard>
+      </Kanban>,
+    );
+    const shell = container.querySelector(".border-dashed");
+    expect(shell!.className).toContain("border-primary");
+    expect(shell!.className).toContain("opacity-100");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* capabilities.subGroups：子分组头渲染 + 折叠切换（吸附头机制的结构面）     */
+/* ------------------------------------------------------------------ */
+
+describe("KanbanBoardView 子分组（capabilities.subGroups）", () => {
+  function subGroupConfig(): KanbanModuleConfig<Item> {
+    return {
+      columns: { todo: [item("t1"), item("t2")] },
+      columnMeta: (key) => ({ label: key === "todo" ? "待办" : key }),
+      cardKey: (entry) => entry.id,
+      renderCard: (entry) => <div>{entry.name}</div>,
+      onOpenItem: vi.fn(),
+      onDropToColumn: vi.fn().mockResolvedValue(undefined),
+      capabilities: { subGroups: true },
+      subGrouping: {
+        membership: { t1: "high", t2: "low" },
+        meta: {
+          high: { key: "high", label: "高", order: 0 },
+          low: { key: "low", label: "低", order: 1 },
+        },
+        dimension: "priority",
+      },
+    };
+  }
+
+  it("列内按成员表切分区并渲染子分组头（含计数）", () => {
+    const { container } = render(<KanbanBoardView config={subGroupConfig()} />);
+
+    const headers = Array.from(
+      container.querySelectorAll("button[aria-expanded]"),
+    ).map((el) => el.textContent);
+    expect(headers).toHaveLength(2);
+    expect(headers[0]).toContain("高");
+    expect(headers[0]).toContain("1");
+    expect(headers[1]).toContain("低");
+  });
+
+  it("点击子分组头切换折叠（aria-expanded 翻转）", async () => {
+    const { container } = render(<KanbanBoardView config={subGroupConfig()} />);
+
+    const firstHeader = container.querySelector(
+      "button[aria-expanded]",
+    ) as HTMLButtonElement;
+    expect(firstHeader.getAttribute("aria-expanded")).toBe("true");
+
+    await userEvent.click(firstHeader);
+    expect(firstHeader.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("列头渲染「全部折叠」按钮（子分组存在时）", () => {
+    const { container } = render(<KanbanBoardView config={subGroupConfig()} />);
+    expect(
+      container.querySelector('[aria-label="折叠全部子分组"]'),
+    ).toBeTruthy();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+
+function assertMove(
+  decision: DropCommitDecision,
+  expected: {
+    itemKey: string;
+    columnKey: string;
+    subKey?: string;
+    orders: { id: string; boardOrder: number }[];
+  },
+) {
+  expect(decision.kind).toBe("move");
+  if (decision.kind !== "move") return;
+  expect(decision.itemKey).toBe(expected.itemKey);
+  expect(decision.columnKey).toBe(expected.columnKey);
+  expect(decision.orders).toEqual(expected.orders);
+  if (expected.subKey != null) expect(decision.subKey).toBe(expected.subKey);
+}