@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,1414 @@
+// 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/>.
+
+/**
+ * 全能力共享看板组件（UI 对齐二期设计 §4.5，任务 24）。
+ *
+ * 以 story/views/kanban-view.tsx（1593 行蓝本）逐段搬移参数化，不改算法：
+ * reui Kanban 装配、useSyncedState 渲染期同步、拖拽期空列虚显（虚线壳）、
+ * ghost 落点淡化卡、列内虚拟化（canVirtualize 渐进增强）、拖拽让位 transform、
+ * 子分组吸附头、900ms 延迟静默刷新、失败还原 + toast、手动排序触发。
+ *
+ * story 特有业务（分组字段 patch 映射、PeekPatch 通道、转移、保存视图接线）
+ * 留在消费方——经 config 回调接线（story 任务 42 / testcase 任务 26 / bug 任务 33）。
+ *
+ * memo 约定：config 内的函数字段（columnMeta/renderCard/renderGhostCard/cardKey）
+ * 须引用稳定（消费方 useMemo/useCallback），否则列内 memo 与 dnd 缓存全部失效。
+ */
+
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import {
+  Kanban,
+  KanbanBoard,
+  KanbanColumn,
+  KanbanColumnContent,
+  KanbanColumnHandle,
+  KanbanItem,
+  KanbanItemHandle,
+  KanbanOverlay,
+  useKanbanDropIndicator,
+  type KanbanCommitMeta,
+} from "@/components/reui/kanban";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader } from "@/components/ui/card";
+import {
+  ChevronRight,
+  ChevronsDownUp,
+  ChevronsUpDown,
+  GripVertical,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import { useSyncedState } from "@/lib/hooks/use-synced-state";
+import { m } from "@/paraglide/messages.js";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useDebouncedCallback } from "@/lib/pacer";
+import {
+  applyInstanceKeys,
+  buildStoryIndex,
+  itemKey,
+  storyIdFromInstanceKey,
+  type KanbanStoryItem,
+} from "./instance-key";
+import { computeDropLayout, type DropLayoutRow } from "./drop-layout";
+import {
+  computeFrozenSubHeader,
+  type FrozenSubHeader,
+} from "./frozen-header";
+import {
+  commitDropDecision,
+  resolveDropCommit,
+  resolveSubKeyForDrop,
+  type ReorderEntry,
+} from "./drop-commit";
+
+/* ------------------------------------------------------------------ */
+/* 契约类型（设计 §4.5 KanbanModuleConfig + 复审 P1-1 / 实施必要扩展）      */
+/* ------------------------------------------------------------------ */
+
+/** 列底色（与 story group-resolver 的 ColumnTint 同构：语义类 + 行内实色） */
+export interface ColumnTint {
+  className?: string;
+  backgroundColor?: string;
+}
+
+/** 列/子分组图标类型：LucideIcon 的宽化超集（story GroupNode.icon 直通，无需转换） */
+export type KanbanColumnIcon = ComponentType<{ className?: string }>;
+
+export interface KanbanColumnMeta {
+  label: string;
+  icon?: KanbanColumnIcon;
+  /** 图标附加色类（如 "text-red-500"）；缺省 text-muted-foreground */
+  iconClassName?: string;
+  tint?: ColumnTint;
+  /** 列头计数；缺省取列内条目数 */
+  count?: number;
+}
+
+export interface KanbanSubGroupMeta {
+  key: string;
+  label: string;
+  icon?: KanbanColumnIcon;
+  /** 空格分隔的 class 串，取 text-* 前缀作子分组头图标色（蓝本 GroupNode.color 口径） */
+  color?: string;
+  order: number;
+}
+
+/** 子分组数据（capabilities.subGroups 开启时消费；蓝本 buildSubMeta/buildMembership 的产物） */
+export interface KanbanSubGrouping {
+  /**
+   * 条目 id → 子分组 key（服务端权威值；拖拽期由组件本地乐观维护）。
+   * 引用稳定性要求：本表经 useSyncedState 渲染期同步——引用一变即把组件本地
+   * 乐观成员表重置回该值（拖拽中/落库未刷新窗口里的乐观归属会被覆盖，卡片
+   * 分区跳变）。消费方必须 useMemo/useCallback 固定引用，仅在服务端权威数据
+   * 变化时产生新引用；禁止每次渲染新建字面量。
+   */
+  membership: Record<string, string>;
+  meta: Record<string, KanbanSubGroupMeta>;
+  /** 子分组维度名（折叠存储键组成部分，如 "priority"） */
+  dimension: string;
+  /**
+   * 是否允许拖拽跨子分组（蓝本 canMoveAcrossSubGroups 口径）：缺省 true。
+   * false = 该维度不可改（如 createdBy），拖拽不更新成员表、move 决策不带 subKey，
+   * 子分组只做视觉分区（story 任务 42 对 GROUP_FIELD[subGroupBy] == null 的维度传 false）。
+   */
+  moveAcross?: boolean;
+  /** 折叠状态 localStorage 键；缺省退化为会话内状态 */
+  storageKey?: string;
+}
+
+export interface KanbanModuleConfig<T extends { id: string }> {
+  /** 服务端权威列集合（键序 = 列序；渲染期同步，拖拽乐观值不被覆盖） */
+  columns: Record<string, T[]>;
+  columnMeta: (key: string) => KanbanColumnMeta;
+  cardKey: (item: T) => string;
+  renderCard: (item: T) => ReactNode;
+  onOpenItem: (item: T) => void;
+  /** 跨列落库（分组字段 patch 由消费方映射）；启用子分组时附带目标子分组 */
+  onDropToColumn: (
+    itemKey: string,
+    columnKey: string,
+    meta?: { subKey?: string },
+  ) => Promise<void>;
+  /**
+   * 同列跨子分组拖拽的子组字段落库（任务 42 必带③；capabilities.subGroups +
+   * moveAcross 时 reorder 决策携带 subKey 后经此落库）。同值跳写与成功 toast
+   * 由消费方负责（共享层不掌握权威成员表）。缺省不落库（纯 reorder）。
+   */
+  onSubGroupMove?: (itemKey: string, columnKey: string, subKey: string) => Promise<void>;
+  /** 列尾加载更多（列级分页，testcase 看板消费） */
+  onLoadMoreColumn?: (columnKey: string) => void;
+  capabilities: {
+    /** 手动排序：onReorder 收目标列全列索引；排序键切换决策 + 提示由消费方承担 */
+    manualOrder?: {
+      onReorder: (orders: ReorderEntry[]) => Promise<void>;
+      onAutoSwitchManual?: () => Promise<void>;
+    };
+    subGroups?: boolean;
+    columnDrag?: {
+      onColumnOrderCommit: (order: string[]) => Promise<void>;
+    };
+  };
+  /**
+   * 复审 P1-1：列是否可放置（缺省 true）。false 的列上的 drop 提交被忽略
+   * （labels 等多值维度分组禁拖用，bug 任务 33 消费）。
+   */
+  columnDroppable?: (key: string) => boolean;
+  /** 提交成功（延迟 900ms 静默）/失败（立即）后的权威刷新 */
+  onRefresh?: () => void;
+  /** 拖拽期虚显的全量列 key（showEmptyGroups=false 时缺失列的虚线壳）；缺省无虚列 */
+  ghostColumnKeys?: string[];
+  subGrouping?: KanbanSubGrouping;
+  /** 落点淡化卡的静态镜像（蓝本 TaskCardGhost 的挂载成本口径）；缺省回落 renderCard */
+  renderGhostCard?: (item: T) => ReactNode;
+}
+
+/* ------------------------------------------------------------------ */
+/* 纯助手（蓝本逐段搬移，泛型化）                                          */
+/* ------------------------------------------------------------------ */
+
+/** 剔除虚显列残留：不在服务端列集合内且仍为空的 key（拖拽途中临时插入的隐藏列） */
+function stripEmptyExtra<T extends { id: string }>(
+  next: Record<string, T[]>,
+  serverColumns: Record<string, T[]>,
+): Record<string, T[]> {
+  const real = new Set(Object.keys(serverColumns));
+  let changed = false;
+  const kept: Record<string, T[]> = {};
+  for (const [key, items] of Object.entries(next)) {
+    if (!real.has(key) && items.length === 0) {
+      changed = true;
+      continue;
+    }
+    kept[key] = items;
+  }
+  return changed ? kept : next;
+}
+
+/**
+ * 列标题行内距：列头不使用下边框（去掉 border-b 后 CardHeader 基类的 `[.border-b]:pb-(--card-spacing)`
+ * 也不再生效），故此处只需常规内距。虚列标题行是纯 div（无该基类），两处必须共用此常量以免高度不一致。
+ */
+const COLUMN_HEADER_SPACING = "px-3 py-2.5";
+
+interface SubGroupRun<T extends { id: string }> {
+  key: string;
+  items: T[];
+}
+
+/** 按子分组顺序稳定排序（同一区内保持原排序） */
+function orderBySubGroups<T extends { id: string }>(
+  items: T[],
+  membership: Record<string, string>,
+  subMeta: Record<string, KanbanSubGroupMeta>,
+): T[] {
+  return [...items].sort(
+    (a, b) =>
+      (subMeta[membership[a.id] ?? ""]?.order ?? Number.MAX_SAFE_INTEGER) -
+      (subMeta[membership[b.id] ?? ""]?.order ?? Number.MAX_SAFE_INTEGER),
+  );
+}
+
+/**
+ * 列表面（列 Card 与列内吸附的子分组头）的底色渲染口径，必须完全一致：
+ * 基础 bg-card + tint 语义类，有行内色时行内色覆盖（tint 已是实色）。
+ * 抽成一处，避免吸附层与列 Card 两处漂移。
+ */
+function columnSurface(tint: ColumnTint) {
+  return {
+    className: cn("bg-card", tint.className),
+    style: tint.backgroundColor ? { backgroundColor: tint.backgroundColor } : undefined,
+  };
+}
+
+/** 依据成员表把列内卡片切成连续分区：渲染顺序 == 数组顺序，保证 sortable 索引与 DOM 顺序一致 */
+function buildRuns<T extends { id: string }>(
+  items: T[],
+  membership: Record<string, string>,
+  enabled: boolean,
+): SubGroupRun<T>[] {
+  if (!enabled) return [{ key: "", items }];
+  const runs: SubGroupRun<T>[] = [];
+  for (const item of items) {
+    const key = membership[item.id] ?? "";
+    const last = runs[runs.length - 1];
+    if (last && last.key === key) last.items.push(item);
+    else runs.push({ key, items: [item] });
+  }
+  return runs;
+}
+
+/* ------------------------------------------------------------------ */
+/* 子分组折叠状态（蓝本 story/display/use-collapsed-subgroups 等价机制）    */
+/* ------------------------------------------------------------------ */
+
+/** 折叠键 = 列 key + 子分组维度 + 子分组 key：同一子分组在各列内独立折叠 */
+export function collapseKey(
+  columnKey: string,
+  dimension: string,
+  subKey: string,
+): string {
+  return `${columnKey}:${dimension}:${subKey}`;
+}
+
+/**
+ * 子分组折叠状态。storageKey 提供时 localStorage 持久化（读写分居两个 effect，
+ * restore 用 skipWriteRef 抑制同一次 commit 内的默认值回写）；缺省退化为会话内状态。
+ */
+function useCollapsedSubGroups(storageKey?: string) {
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(
+    () => new Set<string>(),
+  );
+  const skipWriteRef = useRef(false);
+
+  useEffect(() => {
+    if (!storageKey) return;
+    let saved: string | null = null;
+    try {
+      saved = window.localStorage.getItem(storageKey);
+    } catch {
+      saved = null;
+    }
+    skipWriteRef.current = saved !== null;
+    let parsed: string[] = [];
+    try {
+      const raw: unknown = saved ? JSON.parse(saved) : null;
+      if (Array.isArray(raw)) {
+        parsed = raw.filter((value): value is string => typeof value === "string");
+      }
+    } catch {
+      parsed = [];
+    }
+    setCollapsed(new Set(parsed));
+  }, [storageKey]);
+
+  useEffect(() => {
+    if (!storageKey) return;
+    if (skipWriteRef.current) {
+      skipWriteRef.current = false;
+      return;
+    }
+    try {
+      window.localStorage.setItem(storageKey, JSON.stringify([...collapsed]));
+    } catch {
+      // 隐私模式 / 配额超限：折叠状态退化为会话内状态
+    }
+  }, [collapsed, storageKey]);
+
+  const toggle = useCallback((key: string) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }, []);
+
+  const setMany = useCallback((targets: readonly string[], value: boolean) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      for (const key of targets) {
+        if (value) next.add(key);
+        else next.delete(key);
+      }
+      return next;
+    });
+  }, []);
+
+  return { collapsed, toggle, setMany } as const;
+}
+
+/* ------------------------------------------------------------------ */
+/* 常量（蓝本搬移）                                                        */
+/* ------------------------------------------------------------------ */
+
+/** KanbanColumnContent 的 `gap-2`（0.5rem）像素值：落点槽定位与让位位移都要用它 */
+const COLUMN_ITEM_GAP_PX = 8;
+
+/** 列内虚拟化：预估行高（卡片会被 measureElement 实测纠正）与 overscan */
+const HEADER_ROW_ESTIMATE_PX = 28;
+const CARD_ROW_ESTIMATE_PX = 158;
+const COLUMN_ROW_OVERSCAN = 6;
+
+/**
+ * 落库后的服务端刷新延迟：落库时的乐观态已经按子分组自洽（见 handleValueChange），
+ * 立即 onRefresh 会让「提交 → 拉取 → 整板重算」在同一帧里多背 ~100ms 长任务。
+ * 延后静默刷新把这段挪出交互瞬间，期间由 presence/轮询兜底新鲜度。
+ */
+const DROP_REFRESH_DEBOUNCE_MS = 900;
+
+const EMPTY_MEMBERSHIP: Record<string, string> = {};
+const EMPTY_SUB_META: Record<string, KanbanSubGroupMeta> = {};
+
+/* ------------------------------------------------------------------ */
+/* 主组件                                                                 */
+/* ------------------------------------------------------------------ */
+
+type ColumnValue<T extends { id: string }> = Record<string, T[]>;
+
+export function KanbanBoardView<T extends { id: string }>({
+  config,
+}: {
+  config: KanbanModuleConfig<T>;
+}) {
+  const {
+    columns: sourceColumns,
+    columnMeta,
+    cardKey,
+    renderCard,
+    onOpenItem,
+    onDropToColumn,
+    onSubGroupMove,
+    onLoadMoreColumn,
+    capabilities,
+    columnDroppable,
+    onRefresh,
+    ghostColumnKeys,
+    subGrouping,
+    renderGhostCard,
+  } = config;
+  const { manualOrder, columnDrag } = capabilities;
+  const hasSubGroups = !!capabilities.subGroups && !!subGrouping;
+  /** 子分组是否可跨区改字段：不可改维度只做视觉分区（蓝本 canMoveAcrossSubGroups） */
+  const canMoveAcrossSubGroups = hasSubGroups && (subGrouping?.moveAcross ?? true);
+  const subMeta = hasSubGroups ? (subGrouping?.meta ?? EMPTY_SUB_META) : EMPTY_SUB_META;
+  const dimension = subGrouping?.dimension ?? "";
+  const serverMembership = hasSubGroups
+    ? (subGrouping?.membership ?? EMPTY_MEMBERSHIP)
+    : EMPTY_MEMBERSHIP;
+
+  const { collapsed: collapsedSubGroups, toggle: toggleSubGroup, setMany: setSubGroupsCollapsed } =
+    useCollapsedSubGroups(hasSubGroups ? subGrouping?.storageKey : undefined);
+
+  // 受控 value：拖拽过程 onValueChange 乐观更新，服务端刷新后回到权威值。
+  // 用渲染期同步而非 useEffect——切换分组维度时源值同批到达，
+  // effect 在 paint 后才跑会先提交一帧「新列头 + 旧列 key」。
+  const [columns, setColumns] = useSyncedState<ColumnValue<T>>(sourceColumns);
+
+  // 成员表：卡片 → 分区 key。初值取自服务端字段，拖拽跨越分区时即时更新（渲染分区用）。
+  // 必须与 columns 同样渲染期同步：卡片顺序已按服务端成员表排好，分区切分（buildRuns）
+  // 若用 effect 滞后一帧的本地成员表，两者错配会切出两个同 key 分区（duplicate key + 幽灵卡）。
+  const [membership, setMembership] =
+    useSyncedState<Record<string, string>>(serverMembership);
+  const membershipRef = useRef(membership);
+  useEffect(() => {
+    membershipRef.current = membership;
+  });
+
+  const activeIdRef = useRef<string | null>(null);
+  // 本次拖拽落点 hover 到的卡/列 id：onDragEnd 先于落库提交触发，先暂存供归属判定用
+  const lastOverRef = useRef<string>("");
+  // 拖拽中的活动卡片实例 id：跨列移动由 Kanban 在 onDragOver 即时提交，须冻结该 id
+  // 才能让 dnd-kit 继续在目标列里定位 active、overlay 还能查到卡片（见 applyInstanceKeys）
+  const [activeInstanceKey, setActiveInstanceKey] = useState<string | null>(null);
+
+  // 拖拽期虚显被隐藏的空列（ghostColumnKeys 里不在 columns 的 key）：
+  // 不补进 Kanban 的 value 的话 dnd-kit 认不出容器，卡片无处可放（KanbanColumnContent 也会直接抛错）
+  const [dragging, setDragging] = useState(false);
+  const universeKeys = useMemo(
+    () => ghostColumnKeys ?? Object.keys(sourceColumns),
+    [ghostColumnKeys, sourceColumns],
+  );
+
+  const ghostState = useMemo(() => {
+    if (!dragging) return null;
+    const missing = universeKeys.filter((key) => !(key in columns));
+    if (missing.length === 0) return null;
+    const withGhosts: ColumnValue<T> = { ...columns };
+    const keySet = new Set<string>();
+    for (const key of missing) {
+      withGhosts[key] = [];
+      keySet.add(key);
+    }
+    return { columns: withGhosts, keySet };
+  }, [columns, dragging, universeKeys]);
+
+  const handleValueChange = useCallback(
+    (next: Record<string, KanbanStoryItem<T>[]>) => {
+      const activeId = activeIdRef.current;
+      let members = membershipRef.current;
+      if (canMoveAcrossSubGroups && activeId) {
+        for (const items of Object.values(next)) {
+          if (!items.some((entry) => entry.id === activeId)) continue;
+          const target = resolveSubKeyForDrop(
+            items,
+            activeId,
+            members,
+            lastOverRef.current,
+          );
+          if (target && target !== members[activeId]) {
+            members = { ...members, [activeId]: target };
+            membershipRef.current = members;
+            setMembership(members);
+          }
+          break;
+        }
+      }
+      // 乐观顺序必须与本地成员表自洽：只按插入位摆放时，卡片会停在「原子分组」的位置却带
+      // 「新子分组」的成员标记 → buildRuns 把一列切成多个同名子分组（要等刷新才恢复）。
+      let ordered = stripEmptyExtra(next, sourceColumns);
+      if (hasSubGroups) {
+        const rebuilt: Record<string, KanbanStoryItem<T>[]> = {};
+        for (const [key, items] of Object.entries(ordered)) {
+          rebuilt[key] = orderBySubGroups(items, members, subMeta);
+        }
+        ordered = rebuilt;
+      }
+      setColumns(ordered);
+    },
+    [canMoveAcrossSubGroups, hasSubGroups, setColumns, setMembership, sourceColumns, subMeta],
+  );
+
+  // 落库后的服务端刷新改成延迟静默刷新（见 DROP_REFRESH_DEBOUNCE_MS），
+  // 刷新函数经 ref 取最新闭包（useDebouncedCallback 每次渲染可能返回新函数）
+  const refreshRef = useRef(onRefresh);
+  refreshRef.current = onRefresh;
+  const debouncedRefresh = useDebouncedCallback(() => refreshRef.current?.(), {
+    wait: DROP_REFRESH_DEBOUNCE_MS,
+  });
+  const debouncedRefreshRef = useRef(debouncedRefresh);
+  debouncedRefreshRef.current = debouncedRefresh;
+
+  const handleValueCommit = useCallback(
+    async (
+      next: Record<string, KanbanStoryItem<T>[]>,
+      meta: KanbanCommitMeta<KanbanStoryItem<T>>,
+    ) => {
+      // 列拖拽：持久化列顺序。失败仅回滚乐观列序，**不弹共享 moveFailed toast**——
+      // 列序失败的提示语义只有消费方知道（如 story 的 columnOrderFailed，卡移动/
+      // 排序分支的 moveFailed 对列序操作语义不准），消费方 catch 内自行 toast；
+      // 审查修复（任务 42）：共享 catch 曾叠加 moveFailed 造成双 toast。
+      if (meta.kind === "column") {
+        if (!columnDrag) return;
+        try {
+          await columnDrag.onColumnOrderCommit(Object.keys(next));
+        } catch {
+          setColumns(meta.previousValue);
+        }
+        return;
+      }
+
+      const decision = resolveDropCommit({
+        activeId: String(meta.event.active.id),
+        activeContainer: meta.activeContainer,
+        overContainer: meta.overContainer,
+        nextValue: next,
+        columnDroppable,
+        membership: canMoveAcrossSubGroups ? membershipRef.current : undefined,
+        overItemId: lastOverRef.current,
+      });
+
+      // 文案带上落点：「已更新分组到 已取消-高」（无子分组时只显示列名）
+      let targetLabel: string | undefined;
+      if (decision.kind === "move") {
+        const groupLabel =
+          columnMeta(decision.columnKey)?.label ?? decision.columnKey;
+        const subLabel =
+          decision.subKey != null ? subMeta[decision.subKey]?.label : undefined;
+        targetLabel = subLabel ? `${groupLabel}-${subLabel}` : groupLabel;
+      }
+
+      await commitDropDecision({
+        decision,
+        previousValue: meta.previousValue,
+        setColumns,
+        onDropToColumn,
+        onSubGroupMove,
+        manualOrder,
+        onRefresh: refreshRef.current,
+        onSuccess: debouncedRefreshRef.current,
+        targetLabel,
+      });
+    },
+    [
+      canMoveAcrossSubGroups,
+      columnDrag,
+      columnDroppable,
+      columnMeta,
+      manualOrder,
+      onDropToColumn,
+      onSubGroupMove,
+      setColumns,
+      subMeta,
+    ],
+  );
+
+  const baseColumns = ghostState?.columns ?? columns;
+  // 引用必须稳定：它是 Kanban 数据 context 与 KanbanColumnContent 的 itemIds 缓存键的一部分
+  const getItemValue = useCallback(
+    (entry: KanbanStoryItem<T>) => entry.__instanceKey ?? cardKey(entry),
+    [cardKey],
+  );
+  const renderColumns = useMemo<Record<string, KanbanStoryItem<T>[]>>(
+    () => applyInstanceKeys(baseColumns, activeInstanceKey),
+    [activeInstanceKey, baseColumns],
+  );
+  // overlay 按 dnd-kit 的 active id 反查卡片，索引须跟着冻结后的实例 id 走
+  const storyMap = useMemo(() => buildStoryIndex(renderColumns), [renderColumns]);
+  // 落点列高亮：跨列拖拽由 Kanban 在 onDragOver 即时把卡片移入目标列（落空列则追加列尾），
+  // 故「活动卡片当前所在列」即此刻的落点列，无需另起 pointer 追踪
+  const overColumnKey = useMemo(() => {
+    if (!activeInstanceKey) return null;
+    const activeId = storyIdFromInstanceKey(activeInstanceKey);
+    for (const [columnKey, items] of Object.entries(columns)) {
+      if (items.some((item) => item.id === activeId)) return columnKey;
+    }
+    return null;
+  }, [activeInstanceKey, columns]);
+  const columnKeys = Object.keys(renderColumns);
+
+  if (Object.keys(sourceColumns).length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
+        {m.list_kit_kanban_empty()}
+      </div>
+    );
+  }
+
+  const renderGhost = renderGhostCard ?? renderCard;
+
+  return (
+    <Kanban
+      value={renderColumns}
+      onValueChange={handleValueChange}
+      onValueCommit={handleValueCommit}
+      getItemValue={getItemValue}
+      restoreOnCancel
+      onDragStart={(event) => {
+        activeIdRef.current = storyIdFromInstanceKey(String(event.active.id));
+        setActiveInstanceKey(String(event.active.id));
+        setDragging(true);
+      }}
+      onDragEnd={(event) => {
+        lastOverRef.current = String(event?.over?.id ?? "");
+        activeIdRef.current = null;
+        setActiveInstanceKey(null);
+        setDragging(false);
+        setColumns((prev) => stripEmptyExtra(prev, sourceColumns));
+      }}
+      onDragCancel={() => {
+        activeIdRef.current = null;
+        setActiveInstanceKey(null);
+        setDragging(false);
+        setColumns((prev) => stripEmptyExtra(prev, sourceColumns));
+        // 取消拖拽：ReUI 已还原原始数组，成员表同步回服务端字段值
+        membershipRef.current = serverMembership;
+        setMembership(serverMembership);
+      }}
+      className="h-full min-h-0"
+    >
+      {/* pt-1 留出卡片 ring-1（outset box-shadow）的空间：容器 overflow-y-hidden 会裁掉贴边的 1px 上边框 */}
+      <KanbanBoard className="px-1 pt-1 pb-2">
+        {columnKeys.map((columnKey) => {
+          const meta = columnMeta(columnKey);
+          const Icon = meta?.icon;
+          const iconColor = meta?.iconClassName ?? "text-muted-foreground";
+          const items = renderColumns[columnKey] ?? [];
+          const isGhost = ghostState?.keySet.has(columnKey) ?? false;
+          const isOver = overColumnKey === columnKey;
+          const tint = meta?.tint ?? {};
+          const surface = columnSurface(tint);
+          const runs = buildRuns(items, membership, hasSubGroups);
+          const subKeys = runs.filter((run) => run.key).map((run) => run.key);
+          const subCollapseKeys = subKeys.map((subKey) =>
+            collapseKey(columnKey, dimension, subKey),
+          );
+          const allSubGroupsCollapsed =
+            subCollapseKeys.length > 0 &&
+            subCollapseKeys.every((key) => collapsedSubGroups.has(key));
+
+          if (isGhost) {
+            return (
+              <KanbanGhostColumn
+                key={columnKey}
+                columnKey={columnKey}
+                meta={meta}
+                isOver={isOver}
+                storyMap={storyMap}
+                renderGhost={renderGhost}
+              />
+            );
+          }
+
+          return (
+            <KanbanColumn
+              key={columnKey}
+              value={columnKey}
+              className="h-full w-72 shrink-0"
+            >
+              <Card
+                className={cn(
+                  "flex h-full min-h-0 flex-col gap-0 overflow-hidden py-0",
+                  surface.className,
+                  isOver && "ring-2 ring-primary",
+                )}
+                style={surface.style}
+              >
+                <CardHeader
+                  className={cn(
+                    "flex shrink-0 flex-row items-center justify-between gap-2",
+                    COLUMN_HEADER_SPACING,
+                  )}
+                >
+                  <div className="flex min-w-0 items-center gap-2">
+                    {Icon && <Icon className={cn("size-4 shrink-0", iconColor)} />}
+                    <span className="truncate text-sm font-semibold">
+                      {meta?.label ?? columnKey}
+                    </span>
+                    <Badge
+                      variant="secondary"
+                      className="h-5 shrink-0 rounded-sm border-border px-1.5 text-xs"
+                    >
+                      {meta?.count ?? items.length}
+                    </Badge>
+                  </div>
+                  <div className="flex shrink-0 items-center gap-1">
+                    {subCollapseKeys.length > 0 && (
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon-xs"
+                        aria-label={
+                          allSubGroupsCollapsed
+                            ? m.list_kit_kanban_expandAllSubGroups()
+                            : m.list_kit_kanban_collapseAllSubGroups()
+                        }
+                        onClick={() =>
+                          setSubGroupsCollapsed(subCollapseKeys, !allSubGroupsCollapsed)
+                        }
+                        className="text-muted-foreground opacity-0 transition-opacity group-hover/kanban-column:opacity-100 focus-visible:opacity-100"
+                      >
+                        {allSubGroupsCollapsed ? (
+                          <ChevronsUpDown className="size-4" />
+                        ) : (
+                          <ChevronsDownUp className="size-4" />
+                        )}
+                      </Button>
+                    )}
+                    {columnDrag && (
+                      <KanbanColumnHandle
+                        aria-label={m.list_kit_kanban_columnHandle()}
+                        className="rounded-md p-1 text-muted-foreground"
+                      >
+                        <GripVertical className="size-4" />
+                      </KanbanColumnHandle>
+                    )}
+                  </div>
+                </CardHeader>
+                {/* px-0 抵消 CardContent 基础类的 px-(--card-spacing)=24px：
+                    列内 padding 统一由滚动容器 p-2 提供，卡片宽度与虚拟化前一致（272px） */}
+                <CardContent className="min-h-0 flex-1 px-0">
+                  {/* 滚动容器下移到 ColumnItems（列内虚拟化需要一个由 virtualizer 掌握的滚动元素） */}
+                  <KanbanColumnContent
+                    value={columnKey}
+                    className="min-h-8 gap-2"
+                  >
+                    <ColumnItems
+                      items={items}
+                      storyMap={storyMap}
+                      columnKey={columnKey}
+                      membership={membership}
+                      hasSubGroups={hasSubGroups}
+                      tint={tint}
+                      subMeta={subMeta}
+                      dimension={dimension}
+                      collapsedSubGroups={collapsedSubGroups}
+                      onToggleSubGroup={toggleSubGroup}
+                      renderCard={renderCard}
+                      renderGhost={renderGhost}
+                      onOpenItem={onOpenItem}
+                    />
+                  </KanbanColumnContent>
+                  {onLoadMoreColumn && (
+                    <div className="px-2 pb-2">
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        className="w-full text-muted-foreground"
+                        onClick={() => onLoadMoreColumn(columnKey)}
+                      >
+                        {m.list_kit_kanban_loadMore()}
+                      </Button>
+                    </div>
+                  )}
+                </CardContent>
+              </Card>
+            </KanbanColumn>
+          );
+        })}
+      </KanbanBoard>
+      <KanbanOverlay>
+        {({ value, variant }) => {
+          const story = storyMap[String(value)];
+          if (variant !== "item" || !story) return null;
+          return (
+            <KanbanItem value={itemKey(story)} className="w-72">
+              <OpenableCard
+                item={story}
+                renderCard={renderCard}
+                onOpenItem={onOpenItem}
+              />
+            </KanbanItem>
+          );
+        }}
+      </KanbanOverlay>
+    </Kanban>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* 卡片包装：点击打开（蓝本 TaskCard 的 onClick 口径）                       */
+/* ------------------------------------------------------------------ */
+
+function OpenableCard<T extends { id: string }>({
+  item,
+  renderCard,
+  onOpenItem,
+}: {
+  item: T;
+  renderCard: (item: T) => ReactNode;
+  onOpenItem: (item: T) => void;
+}) {
+  return (
+    // 阻止冒泡到视图区 backdrop（消费方的面板关闭语义）：先打开新条目再被 backdrop 覆盖
+    <div
+      className={cn(!!onOpenItem && "cursor-pointer")}
+      onClick={
+        onOpenItem
+          ? (e) => {
+              e.stopPropagation();
+              onOpenItem(item);
+            }
+          : undefined
+      }
+    >
+      {renderCard(item)}
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* 列内卡片列表（蓝本 ColumnItems 逐段搬移，泛型化）                         */
+/* ------------------------------------------------------------------ */
+
+/** 列内扁平行：子分组标题 / 卡片（虚拟化的 item） */
+type ColumnRow<T extends { id: string }> =
+  | {
+      kind: "header";
+      key: string;
+      runKey: string;
+      label: string;
+      count: number;
+      collapse: string;
+      isCollapsed: boolean;
+      icon?: KanbanColumnIcon;
+      color?: string;
+    }
+  | { kind: "card"; key: string; story: KanbanStoryItem<T> };
+
+interface ColumnItemsProps<T extends { id: string }> {
+  items: KanbanStoryItem<T>[];
+  /** item key → 条目（跨列拖拽时落点渲染淡化卡需要取被拖卡数据） */
+  storyMap: Record<string, T>;
+  columnKey: string;
+  membership: Record<string, string>;
+  hasSubGroups: boolean;
+  /** 列底色（与列 Card 同源）：吸附子分组头必须用同色实底，否则滚动内容会从半透明底透出 */
+  tint: ColumnTint;
+  subMeta: Record<string, KanbanSubGroupMeta>;
+  dimension: string;
+  collapsedSubGroups: ReadonlySet<string>;
+  onToggleSubGroup: (key: string) => void;
+  renderCard: (item: T) => ReactNode;
+  renderGhost: (item: T) => ReactNode;
+  onOpenItem: (item: T) => void;
+}
+
+/**
+ * 列内卡片列表。拖拽期只有源/目标列的 items 引用变化（见 applyInstanceKeys 的列级引用保持），
+ * 其余列在此 bailout——否则每次 onDragOver 都会重建整板 200 张卡的元素并触发重新渲染。
+ */
+function ColumnItemsImpl<T extends { id: string }>({
+  items,
+  storyMap,
+  columnKey,
+  membership,
+  hasSubGroups,
+  tint,
+  subMeta,
+  dimension,
+  collapsedSubGroups,
+  onToggleSubGroup,
+  renderCard,
+  renderGhost,
+  onOpenItem,
+}: ColumnItemsProps<T>) {
+  const surface = columnSurface(tint);
+  const runs = useMemo(
+    () => buildRuns(items, membership, hasSubGroups),
+    [items, membership, hasSubGroups],
+  );
+  const drop = useKanbanDropIndicator(columnKey);
+  const ghostItem = drop?.itemId ? storyMap[drop.itemId] : undefined;
+
+  // 扁平行表（子分组标题 + 卡片）：列内虚拟化的数据源。
+  // 看板此前每列全量渲染（夹具 200 卡 → 205 个 droppable），dnd-kit 拖拽起手要逐个测量，
+  // 实测每次起手 ~130ms（生产）；虚拟化后每列只渲染视口内约 15 行，droppable 降到 ~80。
+  const rows = useMemo<ColumnRow<T>[]>(() => {
+    const out: ColumnRow<T>[] = [];
+    for (const run of runs) {
+      const sub = hasSubGroups ? subMeta[run.key] : undefined;
+      const collapse = collapseKey(columnKey, dimension, run.key);
+      const isCollapsed = sub ? collapsedSubGroups.has(collapse) : false;
+      if (sub) {
+        out.push({
+          kind: "header",
+          key: `h:${run.key}`,
+          runKey: run.key,
+          label: sub.label,
+          count: run.items.length,
+          collapse,
+          isCollapsed,
+          icon: sub.icon,
+          color: sub.color?.split(" ").find((c) => c.startsWith("text")),
+        });
+      }
+      if (isCollapsed) continue;
+      for (const story of run.items) {
+        out.push({ kind: "card", key: itemKey(story), story });
+      }
+    }
+    return out;
+  }, [collapsedSubGroups, columnKey, dimension, hasSubGroups, runs, subMeta]);
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+  // 渐进增强：只有能测出滚动容器高度（真实浏览器）才虚拟化。
+  // SSR / jsdom（无布局）保持全量渲染 → 测试与 hydration 都不受影响。
+  const [canVirtualize, setCanVirtualize] = useState(false);
+  useLayoutEffect(() => {
+    const el = scrollRef.current;
+    if (el && el.clientHeight > 0) setCanVirtualize(true);
+  }, []);
+  const rowVirtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: (index) =>
+      rows[index]?.kind === "header" ? HEADER_ROW_ESTIMATE_PX : CARD_ROW_ESTIMATE_PX,
+    overscan: COLUMN_ROW_OVERSCAN,
+    getItemKey: (index) => rows[index]?.key ?? index,
+    // 初始视口尺寸：首帧（以及 jsdom 无布局时）不至于算不出可见行而白屏
+    initialRect: { width: 288, height: 800 },
+  });
+  const virtualRows = rowVirtualizer.getVirtualItems();
+
+  // 吸附子分组头：列内纵向滚动时，活跃子分组标题吸附在列头（CardHeader）正下方，
+  // 并在下一个子分组头逼近时被顶出，与原生 sticky 的滑动观感一致。
+  // 普通 sticky 失效（列内行是绝对定位的虚拟化行），故按等价换算渲染一份
+  // 「位置 = 吸附位 + offset」的副本；未吸附（尚未滚到列顶）时不渲染，保持自然滑动。
+  const subHeaderIndexes = useMemo(
+    () =>
+      rows.reduce<number[]>(
+        (acc, r, i) => (r.kind === "header" ? [...acc, i] : acc),
+        [],
+      ),
+    [rows],
+  );
+  const [frozenSub, setFrozenSub] = useState<FrozenSubHeader | null>(null);
+  const frozenSubRef = useRef<FrozenSubHeader | null>(null);
+  const frozenRafRef = useRef<number | null>(null);
+
+  const recomputeFrozenSubHeader = useCallback(() => {
+    frozenRafRef.current = null;
+    const el = scrollRef.current;
+    if (!el) return;
+    const next = computeFrozenSubHeader(
+      el.scrollTop,
+      rowVirtualizer.measurementsCache,
+      subHeaderIndexes,
+    );
+    const prev = frozenSubRef.current;
+    // offset 逐像素变化，两者都相同才跳过提交（避免滚动期无谓重渲）
+    if (prev?.index === next?.index && prev?.offset === next?.offset) return;
+    frozenSubRef.current = next;
+    setFrozenSub(next);
+  }, [rowVirtualizer, subHeaderIndexes]);
+
+  // rAF 节流：滚动事件可能一帧多次触发
+  const handleColumnScroll = useCallback(() => {
+    if (frozenRafRef.current != null) return;
+    frozenRafRef.current = requestAnimationFrame(recomputeFrozenSubHeader);
+  }, [recomputeFrozenSubHeader]);
+
+  // 挂载 / 行测量变化（总高随测量增长）时同步冻结头，保证首屏就有正确值
+  useEffect(() => {
+    recomputeFrozenSubHeader();
+  }, [recomputeFrozenSubHeader, rowVirtualizer.getTotalSize()]);
+
+  // 未启用子分组 / 未虚拟化（SSR、jsdom 无布局）时不需要吸附层
+  useEffect(() => {
+    if (hasSubGroups && canVirtualize) return;
+    frozenSubRef.current = null;
+    setFrozenSub(null);
+  }, [hasSubGroups, canVirtualize]);
+
+  useEffect(() => {
+    return () => {
+      if (frozenRafRef.current != null) {
+        cancelAnimationFrame(frozenRafRef.current);
+      }
+    };
+  }, []);
+
+  // 拖拽落点：命中本列时算出「哪些卡让位」和「落点槽挂在哪张卡上」。
+  // 让位用 transform 实现（不改数据、不插 DOM）：插入真实占位元素会造成布局变化，
+  // dnd-kit 随即对 droppable 重新测量（拖拽期测量队列已空 → 全量 re-measure），
+  // 200 卡下就是卡顿主因；transform 不触发布局与重测，视觉上等价于卡片让位。
+  const dropLayoutRows: DropLayoutRow[] = [];
+  if (drop) {
+    for (const run of runs) {
+      const sub = hasSubGroups ? subMeta[run.key] : undefined;
+      const isCollapsed = sub
+        ? collapsedSubGroups.has(collapseKey(columnKey, dimension, run.key))
+        : false;
+      // 标题行也进落点行表（key 与渲染行一致：h:<runKey>），让位时与卡片一起下移
+      if (sub) dropLayoutRows.push({ key: `h:${run.key}`, kind: "header" });
+      for (const story of run.items) {
+        dropLayoutRows.push({ key: itemKey(story), kind: "card", hidden: isCollapsed });
+      }
+    }
+  }
+  // 落点语义判定：hover 在某分组「最后一张卡的下半区」时，插入位 = 该卡下标 + 1（= 下一分组
+  // 首张卡的下标），但语义是「追加到上一分组末尾」。此时让位与落点槽都要到下一分组的
+  // 标题之上，且卡片归属取 hover 卡的分组，否则会落进下一个分组（小分组尤其明显）。
+  const cardKeys: string[] = [];
+  for (const row of dropLayoutRows) {
+    if (row.kind === "card") cardKeys.push(row.key);
+  }
+  const hoveredCardIndex = drop ? cardKeys.indexOf(drop.overItemKey) : -1;
+  const anchorCardKey = drop ? cardKeys[drop.insertIndex] : undefined;
+  const overItemId = drop?.overItemKey
+    ? storyIdFromInstanceKey(drop.overItemKey)
+    : "";
+  const hoveredSub = overItemId ? membership[overItemId] : undefined;
+  const anchorSub = anchorCardKey
+    ? membership[storyIdFromInstanceKey(anchorCardKey)]
+    : undefined;
+  const appendToPreviousRun =
+    drop != null &&
+    hoveredCardIndex >= 0 &&
+    drop.insertIndex === hoveredCardIndex + 1 &&
+    hoveredSub != null &&
+    anchorSub != null &&
+    hoveredSub !== anchorSub;
+  const {
+    shifts: shiftByKey,
+    slotBefore: slotBeforeKeys,
+    slotAfter: slotAfterKey,
+    slotBeforeHeader: slotBeforeHeaderKey,
+  } = computeDropLayout(dropLayoutRows, drop, drop ? drop.height + COLUMN_ITEM_GAP_PX : 0, {
+    appendToPreviousRun,
+  });
+  // 空列（含拖拽期虚显的空列）没有挂点卡片，落点淡化卡改为渲染在列首
+  const emptyColumnDrop =
+    drop !== null && dropLayoutRows.length === 0 && drop.insertIndex >= 0;
+
+  // 让位 transform 命令式写（不走 React props）：跨列切换目标列时一次性要让 ~60 张卡换位，
+  // 走 props 会触发 60 棵子树重渲染（实测单帧 59ms）。这里直接写 style，且批量变更
+  // （进入/离开本列）时临时禁用 transition，避免 60 张卡同时起动画。
+  const dropLayerRef = useRef<HTMLDivElement>(null);
+  const appliedShiftsRef = useRef(new Map<string, number>());
+  const prevTargetRef = useRef<string | null>(null);
+  useLayoutEffect(() => {
+    const layer = dropLayerRef.current;
+    if (!layer) return;
+    const bulk = prevTargetRef.current !== (drop ? columnKey : null);
+    prevTargetRef.current = drop ? columnKey : null;
+
+    const applied = appliedShiftsRef.current;
+    const next = new Map<string, number>();
+    const changed: HTMLElement[] = [];
+    layer
+      .querySelectorAll<HTMLElement>("[data-card-key], [data-shift-key]")
+      .forEach((node) => {
+        // 卡片读 data-card-key；子分组标题读 data-shift-key（标题也要让位，见 computeDropLayout）
+        const key = node.dataset.cardKey ?? node.dataset.shiftKey ?? "";
+        const want = shiftByKey.get(key) ?? 0;
+        if (want) next.set(key, want);
+        if ((applied.get(key) ?? 0) === want) return;
+        if (bulk) {
+          node.style.transition = "none";
+          changed.push(node);
+        }
+        node.style.transform = want ? `translateY(${want}px)` : "";
+      });
+    if (bulk && changed.length > 0) {
+      // 下一帧再恢复 transition：让 transition:none 先被提交，避免 60 张卡同时起动画；
+      // 这里不能用强制 reflow（void layer.offsetHeight）——那是整列布局，实测单帧 50–60ms
+      requestAnimationFrame(() => {
+        changed.forEach((node) => {
+          node.style.transition = "";
+        });
+      });
+    }
+    appliedShiftsRef.current = next;
+  });
+
+  // 子分组标题按钮：列内行渲染与冻结层共用（保证两者视觉与交互完全一致）
+  const renderSubHeaderButton = (
+    row: Extract<ColumnRow<T>, { kind: "header" }>,
+  ) => (
+    <Button
+      type="button"
+      variant="ghost"
+      size="xs"
+      aria-expanded={!row.isCollapsed}
+      onClick={() => onToggleSubGroup(row.collapse)}
+      className="h-auto w-full justify-between gap-1.5 px-1 py-1 text-xs font-medium text-muted-foreground aria-expanded:bg-transparent hover:bg-accent/50"
+    >
+      <span className="flex min-w-0 items-center gap-1.5">
+        <ChevronRight
+          className={cn(
+            "size-3.5 shrink-0 transition-transform",
+            !row.isCollapsed && "rotate-90",
+          )}
+          aria-hidden
+        />
+        {row.icon && <row.icon className={cn("size-3.5 shrink-0", row.color)} />}
+        <span className="min-w-0 truncate">{row.label}</span>
+      </span>
+      <Badge
+        variant="secondary"
+        className="h-5 shrink-0 rounded-sm border-border px-1.5 text-xs"
+      >
+        {row.count}
+      </Badge>
+    </Button>
+  );
+
+  const renderRow = (row: ColumnRow<T> | undefined) => {
+    if (!row) return null;
+    if (row.kind === "header") {
+      // 包一层让位容器：拖拽落点在下半区时标题与卡片一起下移（否则卡片会压住标题）
+      const headerSlot = row.key === slotBeforeHeaderKey;
+      return (
+        <div data-shift-key={row.key} className={cn(headerSlot && "relative")}>
+        {headerSlot && ghostItem && (
+          <div
+            aria-hidden
+            data-slot="kanban-drop-slot"
+            className="pointer-events-none absolute inset-x-0 opacity-50"
+            style={{
+              height: drop?.height,
+              bottom: "100%",
+              marginBottom: COLUMN_ITEM_GAP_PX,
+            }}
+          >
+            {renderGhost(ghostItem)}
+          </div>
+        )}
+        {renderSubHeaderButton(row)}
+        </div>
+      );
+    }
+    const slotValue = slotBeforeKeys.has(row.key)
+      ? "before"
+      : slotAfterKey === row.key
+        ? "after"
+        : null;
+    return (
+      // pb-2 = 原 KanbanColumnContent 的 gap-2（行绝对定位后 flex gap 失效，改行内间距）
+      <div className="pb-2">
+        <CardSlot
+          story={row.story}
+          slot={slotValue}
+          // 只给真正渲染落点的那 1-2 张卡传 ghostItem：进/出目标列时若整列
+          // 都收到它，几十张卡的 prop 同时变化 → 大量子树重渲染（实测单帧 59ms）
+          ghostItem={slotValue ? ghostItem : undefined}
+          slotHeight={drop?.height ?? 0}
+          renderCard={renderCard}
+          renderGhost={renderGhost}
+          onOpenItem={onOpenItem}
+        />
+      </div>
+    );
+  };
+
+  // 吸附层数据：仅当列内启用了子分组、且已虚拟化（真实浏览器）时生效。
+  // 拖拽期隐藏，避免与落点淡化卡/让位层叠冲突。
+  const frozenRow =
+    !drop && frozenSub != null ? rows[frozenSub.index] : undefined;
+  const frozenHeaderRow =
+    frozenRow?.kind === "header" ? frozenRow : undefined;
+
+  return (
+    <div className="relative min-h-0 flex-1">
+      <div
+        ref={scrollRef}
+        onScroll={handleColumnScroll}
+        className="h-full overflow-y-auto p-2"
+      >
+        <div
+          ref={dropLayerRef}
+          className="relative w-full"
+          style={{ height: canVirtualize ? rowVirtualizer.getTotalSize() : undefined }}
+        >
+          {emptyColumnDrop && ghostItem && (
+            <div
+              aria-hidden
+              data-slot="kanban-drop-slot"
+              className="pointer-events-none absolute inset-x-0 top-0 opacity-50"
+              style={{ height: drop?.height }}
+            >
+              {renderGhost(ghostItem)}
+            </div>
+          )}
+          {canVirtualize
+            ? virtualRows.map((vRow) => (
+                <div
+                  key={vRow.key}
+                  data-index={vRow.index}
+                  ref={rowVirtualizer.measureElement}
+                  className="absolute top-0 left-0 w-full"
+                  style={{ transform: `translateY(${vRow.start}px)` }}
+                >
+                  {renderRow(rows[vRow.index])}
+                </div>
+              ))
+            : rows.map((row) => (
+                <div key={row.key} className="w-full">
+                  {renderRow(row)}
+                </div>
+              ))}
+        </div>
+      </div>
+      {/* 吸附子分组头：与在流子分组头同款渲染，吸附在列内**滚动容器顶边**
+          （= 列头 CardHeader 正下方），并被下一个子分组头顶出。
+          外层 overflow-hidden 负责在顶出阶段裁掉超出容器上缘的部分。
+          底色（columnSurface，与列 Card 同源）挂在**满宽层**上，恰好覆盖组头行自身
+          的盒子（inset-x-0 + 无纵向内边距）：内层只需 px-2 与滚动容器的 p-2 横向对齐，
+          若底色跟着内边距走，左右/上会留 8px 透明缝隙漏出下层卡片。
+          纵向**不留任何内边距**：吸附位由 computeFrozenSubHeader 锚在容器顶边
+          （SUB_HEADER_STICKY_PAD 抵消内容盒 p-2 偏移），组头越过容器顶边前本层根本不渲染
+          ——上滑由在流组头自己完成，故上方无需遮挡带；多留内边距会把紧邻首卡顶部一起盖住。 */}
+      {canVirtualize && frozenHeaderRow && frozenSub && (
+        <div
+          data-slot="kanban-frozen-sub-header"
+          className="pointer-events-none absolute inset-0 z-10 overflow-hidden"
+        >
+          <div
+            className={cn("absolute inset-x-0 top-0", surface.className)}
+            style={{ ...surface.style, transform: `translateY(${frozenSub.offset}px)` }}
+          >
+            <div className="pointer-events-auto px-2">
+              {renderSubHeaderButton(frozenHeaderRow)}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+const ColumnItems = memo(ColumnItemsImpl) as typeof ColumnItemsImpl;
+
+/* ------------------------------------------------------------------ */
+/* 单张卡（含落点让位与落点槽）——蓝本 CardSlot 逐段搬移                     */
+/* ------------------------------------------------------------------ */
+
+interface CardSlotProps<T extends { id: string }> {
+  story: KanbanStoryItem<T>;
+  slot: "before" | "after" | null;
+  /** 落点预览用的淡化卡数据（= 被拖卡片） */
+  ghostItem?: T;
+  slotHeight: number;
+  renderCard: (item: T) => ReactNode;
+  renderGhost: (item: T) => ReactNode;
+  onOpenItem: (item: T) => void;
+}
+
+/**
+ * 单张卡（含落点让位与落点槽）。
+ *
+ * 必须独立 memo：落点每次变化只影响「让位边界」那 1-2 张卡，但落点 store 一变
+ * 会让 ColumnItems 整个重渲染；若卡片直接在 ColumnItems 里就地渲染，每次落点变化
+ * 都要重渲染整列（实测 62 卡列 ≈14ms/次 → 拖拽掉到 30fps）。memo 后只有
+ * shift / slot 真正变化的卡片参与重渲染。
+ */
+function CardSlotImpl<T extends { id: string }>({
+  story,
+  slot,
+  ghostItem,
+  slotHeight,
+  renderCard,
+  renderGhost,
+  onOpenItem,
+}: CardSlotProps<T>) {
+  return (
+    <div
+      // 让位位移与落点槽都在可滚动列内变更：不给卡片独立合成层时，任何一次变更
+      // 都会让整片可见卡片重绘（实测列内变更 ~14ms/次 → 拖拽掉到 30fps）。
+      // will-change 提升为合成层后变更只走合成，实测回到无指示器基线（中位 8ms/帧）。
+      //
+      // 让位 transform 不在 React 里写（见 ColumnItems 的 useLayoutEffect）：跨列时
+      // 一次性要让 ~60 张卡换位，走 props 会触发 60 棵子树重渲染（实测单帧 59ms）；
+      // 命令式直接改 style 只花几十次样式写入，且 memo 全 bail。
+      className="relative transition-transform duration-150 ease-out will-change-transform"
+      data-card-key={itemKey(story)}
+    >
+      {slot && (
+        <div
+          aria-hidden
+          data-slot="kanban-drop-slot"
+          className="pointer-events-none absolute inset-x-0"
+          style={
+            slot === "before"
+              ? { bottom: "100%", marginBottom: COLUMN_ITEM_GAP_PX }
+              : { top: "100%", marginTop: COLUMN_ITEM_GAP_PX }
+          }
+        >
+          {ghostItem ? (
+            // 落点预览 = 被拖卡片的淡化副本（与列内拖拽时源卡 opacity-50 观感一致，
+            // 对齐官方 demo 的「淡化卡落在目标位」效果，而非只画一个虚线边框）
+            <div className="opacity-50">{renderGhost(ghostItem)}</div>
+          ) : (
+            <div
+              className="rounded-md border-2 border-dashed border-border/70 bg-muted/20"
+              style={{ height: slotHeight }}
+            />
+          )}
+        </div>
+      )}
+      <KanbanItem value={itemKey(story)}>
+        <KanbanItemHandle>
+          <OpenableCard item={story} renderCard={renderCard} onOpenItem={onOpenItem} />
+        </KanbanItemHandle>
+      </KanbanItem>
+    </div>
+  );
+}
+
+const CardSlot = memo(CardSlotImpl) as typeof CardSlotImpl;
+
+/* ------------------------------------------------------------------ */
+/* 空列（拖拽期虚显的 ghost 列）——蓝本 ghost 分支 + GhostColumnDrop         */
+/* ------------------------------------------------------------------ */
+
+interface GhostColumnDropProps<T extends { id: string }> {
+  columnKey: string;
+  storyMap: Record<string, T>;
+  renderGhost: (item: T) => ReactNode;
+}
+
+/**
+ * 空列（拖拽期虚显的 ghost 列）里的落点淡化卡。
+ *
+ * 空列渲染的是虚线壳、不含 ColumnItems，因此不会自动订阅落点指示 —— 不单独订阅的话，
+ * 拖到空列时只看到一个空虚线框（用户反馈的「空看板拖动没有淡化卡」）。
+ */
+function GhostColumnDropImpl<T extends { id: string }>({
+  columnKey,
+  storyMap,
+  renderGhost,
+}: GhostColumnDropProps<T>) {
+  const drop = useKanbanDropIndicator(columnKey);
+  const story = drop?.itemId ? storyMap[drop.itemId] : undefined;
+  if (!drop || !story) return null;
+  return (
+    <div
+      aria-hidden
+      data-slot="kanban-drop-slot"
+      className="pointer-events-none opacity-50"
+      style={{ height: drop.height }}
+    >
+      {renderGhost(story)}
+    </div>
+  );
+}
+
+const GhostColumnDrop = memo(GhostColumnDropImpl) as typeof GhostColumnDropImpl;
+
+interface KanbanGhostColumnProps<T extends { id: string }> {
+  columnKey: string;
+  meta?: KanbanColumnMeta;
+  isOver: boolean;
+  storyMap: Record<string, T>;
+  renderGhost: (item: T) => ReactNode;
+}
+
+/** 拖拽期虚显的空列：虚线壳 + 列头（0 计数）+ 落点淡化卡订阅 */
+function KanbanGhostColumnImpl<T extends { id: string }>({
+  columnKey,
+  meta,
+  isOver,
+  storyMap,
+  renderGhost,
+}: KanbanGhostColumnProps<T>) {
+  const Icon = meta?.icon;
+  const iconColor = meta?.iconClassName ?? "text-muted-foreground";
+  return (
+    <KanbanColumn value={columnKey} className="h-full w-72 shrink-0">
+      <div
+        className={cn(
+          "flex h-full min-h-0 flex-col overflow-hidden rounded-xl border border-dashed border-muted-foreground/40 bg-muted/20 opacity-70",
+          isOver && "border-primary opacity-100",
+        )}
+      >
+        <div
+          className={cn(
+            "flex shrink-0 items-center gap-2",
+            COLUMN_HEADER_SPACING,
+          )}
+        >
+          {Icon && <Icon className={cn("size-4 shrink-0", iconColor)} />}
+          <span className="truncate text-sm font-semibold">
+            {meta?.label ?? columnKey}
+          </span>
+          <Badge
+            variant="secondary"
+            className="h-5 shrink-0 rounded-sm border-border px-1.5 text-xs"
+          >
+            0
+          </Badge>
+        </div>
+        <div className="min-h-0 flex-1 overflow-y-auto p-2">
+          <KanbanColumnContent value={columnKey} className="min-h-8 gap-2">
+            <GhostColumnDrop
+              columnKey={columnKey}
+              storyMap={storyMap}
+              renderGhost={renderGhost}
+            />
+          </KanbanColumnContent>
+        </div>
+      </div>
+    </KanbanColumn>
+  );
+}
+
+export const KanbanGhostColumn = memo(
+  KanbanGhostColumnImpl,
+) as typeof KanbanGhostColumnImpl;