@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/shared-kit/list-kit/kanban/__tests__/manual-order.test.ts

@@ -0,0 +1,35 @@
+// 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/>.
+
+import { describe, expect, it } from "vitest";
+import { manualOrderSwitchPatch } from "../manual-order";
+
+describe("manualOrderSwitchPatch", () => {
+  it("拖拽落库后按非手动排序展示时，切换为手动排序", () => {
+    expect(manualOrderSwitchPatch("created", true)).toEqual({ orderBy: "manual" });
+    expect(manualOrderSwitchPatch("updated", true)).toEqual({ orderBy: "manual" });
+  });
+
+  it("已是手动排序时不重复切换（避免 toast 噪音）", () => {
+    expect(manualOrderSwitchPatch("manual", true)).toBeNull();
+  });
+
+  it("没有实际落库排序时不切换", () => {
+    expect(manualOrderSwitchPatch("created", false)).toBeNull();
+    expect(manualOrderSwitchPatch("manual", false)).toBeNull();
+  });
+});

package/src/components/shared-kit/list-kit/kanban/drop-commit.ts

@@ -0,0 +1,212 @@
+// 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 / 复审 P1-8）。
+ *
+ * 从 story/views/kanban-view.tsx 的 drop 处理逻辑逐段参数化抽取：
+ * - resolveDropCommit：提交元数据 → 决策（跨列 move / 列内 reorder / 忽略）
+ * - commitDropDecision：决策 → 落库管线（成功延迟刷新 / 失败回滚 + toast）
+ * jsdom 不模拟 dnd-kit 真拖，拖拽语义测试走本文件导出的纯函数（任务 26/33/42 消费）。
+ */
+
+import { toast } from "@/components/ui/toast";
+import { toastError } from "@/lib/toast-error";
+import { m } from "@/paraglide/messages.js";
+import { storyIdFromInstanceKey } from "./instance-key";
+
+/** 列内排序落库产物：目标列全列索引（boardOrder = 提交后数组下标） */
+export interface ReorderEntry {
+  id: string;
+  boardOrder: number;
+}
+
+export type DropCommitDecision =
+  | { kind: "ignore"; reason: "notDroppable" | "noTarget" }
+  /** 跨列移动：onDropToColumn(itemKey, columnKey) 产物；subKey 为目标子分组（启用子分组时） */
+  | {
+      kind: "move";
+      itemKey: string;
+      columnKey: string;
+      subKey?: string;
+      orders: ReorderEntry[];
+    }
+  /** 列内排序：manualOrder 开启时触发 onReorder（全列索引）；
+   *  subKey = 同列跨子分组时按提交后排列解析出的子组归属（任务 42 必带③，蓝本
+   *  story kanban-view 同列拖子组也写子组字段），经 onSubGroupMove 落库 */
+  | { kind: "reorder"; itemKey: string; columnKey: string; subKey?: string; orders: ReorderEntry[] };
+
+export interface DropCommitParams {
+  /** dnd-kit active id（实例 key 或裸条目 id，均可解析） */
+  activeId: string;
+  activeContainer: string;
+  overContainer: string;
+  /** 提交后的乐观列（被拖卡已在新位置，取其排列推导 boardOrder 与子分组归属） */
+  nextValue: Record<string, ReadonlyArray<{ id: string }>>;
+  /**
+   * 列是否可放置（复审 P1-1，缺省 true）。false 的列上的任何 drop 提交
+   * （含列内）都被忽略——labels 等多值维度分组禁拖用。
+   */
+  columnDroppable?: (key: string) => boolean;
+  /** 子分组成员表（提交后的本地值）；缺省 = 未启用子分组，不解析 subKey */
+  membership?: Record<string, string>;
+  /** 拖拽落点 hover 的实例 id（lastOver 通道，供子分组归属判定） */
+  overItemId?: string;
+}
+
+/**
+ * 落点所属子分组（回落规则）：取「紧随其后的卡片」所属子分组（提交后的排列里被拖卡也在其中），
+ * 追加到列尾（其后无卡）时取前一张，最后回落到该卡自身。
+ *
+ * 提交时必须用这个而不是「成员表里的旧值」：成员表由渲染期同步，drop 那一帧还是旧值
+ * → 跨子分组拖动时判定「目标分区 == 原分区」而不发 patch（story kanban-drop-subgroup 回归）。
+ */
+export function resolveDropSubKey(
+  items: ReadonlyArray<{ id: string }>,
+  itemId: string,
+  membership: Record<string, string>,
+): string | undefined {
+  const index = items.findIndex((story) => story.id === itemId);
+  if (index === -1) return undefined;
+  return (
+    (items[index + 1] ? membership[items[index + 1].id] : undefined) ??
+    (items[index - 1] ? membership[items[index - 1].id] : undefined) ??
+    membership[itemId]
+  );
+}
+
+/**
+ * 落点子分组优先取「hover 到的那张卡」所属分组：
+ * hover 在某分组最后一张卡的下半区 → 插入位等于下一分组首张卡的下标，
+ * 但语义是追加到 hover 卡所在分组，否则会落进下一个分组（小分组尤其明显）。
+ * 没有 hover 卡（落在列空白/列尾）时回落到 resolveDropSubKey 相邻卡推断。
+ */
+export function resolveSubKeyForDrop(
+  items: ReadonlyArray<{ id: string }>,
+  itemId: string,
+  membership: Record<string, string>,
+  overKey: string,
+): string | undefined {
+  const overItemId = overKey ? storyIdFromInstanceKey(overKey) : "";
+  if (overItemId && membership[overItemId] != null) return membership[overItemId];
+  return resolveDropSubKey(items, itemId, membership);
+}
+
+/** 从提交元数据解析 drop 决策（纯函数，不改任何状态） */
+export function resolveDropCommit(params: DropCommitParams): DropCommitDecision {
+  const itemKey = storyIdFromInstanceKey(params.activeId);
+  const destKey = params.overContainer;
+  if (!destKey) return { kind: "ignore", reason: "noTarget" };
+  if (params.columnDroppable && !params.columnDroppable(destKey)) {
+    return { kind: "ignore", reason: "notDroppable" };
+  }
+  const destItems = params.nextValue[destKey] ?? [];
+  const orders: ReorderEntry[] = destItems.map((entry, index) => ({
+    id: entry.id,
+    boardOrder: index,
+  }));
+  if (params.activeContainer !== destKey) {
+    const subKey = params.membership
+      ? resolveSubKeyForDrop(
+          destItems,
+          itemKey,
+          params.membership,
+          params.overItemId ?? "",
+        )
+      : undefined;
+    return { kind: "move", itemKey, columnKey: destKey, subKey, orders };
+  }
+  // 同列（reorder）也解析子组归属：moveAcross 维度下同列跨子分组拖拽同样要落
+  // 子组字段（蓝本 story kanban-view 口径，任务 42 必带③）；纯组内排序解析出的
+  // subKey == 本地成员表现值，消费方权威比对后跳写
+  const subKey = params.membership
+    ? resolveSubKeyForDrop(destItems, itemKey, params.membership, params.overItemId ?? "")
+    : undefined;
+  return { kind: "reorder", itemKey, columnKey: destKey, subKey, orders };
+}
+
+export interface CommitDropDeps<T extends { id: string }> {
+  decision: DropCommitDecision;
+  /** meta.previousValue：忽略 / 失败时的乐观列回滚值 */
+  previousValue: Record<string, T[]>;
+  setColumns: (value: Record<string, T[]>) => void;
+  onDropToColumn: (
+    itemKey: string,
+    columnKey: string,
+    meta?: { subKey?: string },
+  ) => Promise<void>;
+  /**
+   * 同列跨子分组拖拽（reorder 决策带 subKey）的子组字段落库通道
+   * （任务 42 必带③）。在 onReorder 之前调用（蓝本：字段 patch 先于排序落库）；
+   * subKey 已与组件本地乐观成员表自洽，是否真写（与权威成员表同值跳写）与
+   * 成功 toast 由消费方负责。缺省不落库。
+   */
+  onSubGroupMove?: (itemKey: string, columnKey: string, subKey: string) => Promise<void>;
+  manualOrder?: {
+    onReorder: (orders: ReorderEntry[]) => Promise<void>;
+    onAutoSwitchManual?: () => Promise<void>;
+  };
+  /** 成功后的刷新（组件传 900ms 延迟静默包装，见 KanbanBoardView） */
+  onSuccess?: () => void;
+  /** 失败时的立即权威刷新 */
+  onRefresh?: () => void;
+  /** move 成功 toast 的落点文案（列 label，含子分组时「列-子组」） */
+  targetLabel?: string;
+}
+
+/**
+ * 提交管线（蓝本 handleValueCommit 的参数化形态）：决策 → 落库 → 成功刷新 / 失败回滚。
+ *
+ * - move：onDropToColumn → 成功 toast → manualOrder.onReorder（全列索引）→ onAutoSwitchManual
+ *   （是否需要切手动排序 + 提示由消费方判断，共享层不掌握排序键）
+ * - 失败：乐观列回滚 previousValue（即刻）+ onRefresh（权威源）+ toast.error
+ * - ignore：仅回滚（拖拽途中可能已把卡乐观移入禁拖列）
+ */
+export async function commitDropDecision<T extends { id: string }>(
+  deps: CommitDropDeps<T>,
+): Promise<void> {
+  const { decision } = deps;
+  if (decision.kind === "ignore") {
+    deps.setColumns(deps.previousValue);
+    return;
+  }
+  try {
+    if (decision.kind === "move") {
+      await deps.onDropToColumn(
+        decision.itemKey,
+        decision.columnKey,
+        decision.subKey != null ? { subKey: decision.subKey } : undefined,
+      );
+      toast.success(
+        m.list_kit_kanban_movedTo({ target: deps.targetLabel ?? decision.columnKey }),
+      );
+    }
+    if (decision.kind === "reorder" && decision.subKey != null && deps.onSubGroupMove) {
+      // 同列跨子分组：子组字段先落库（蓝本顺序），失败走统一回滚分支
+      await deps.onSubGroupMove(decision.itemKey, decision.columnKey, decision.subKey);
+    }
+    if (deps.manualOrder && decision.orders.length > 0) {
+      await deps.manualOrder.onReorder(decision.orders);
+      await deps.manualOrder.onAutoSwitchManual?.();
+    }
+    deps.onSuccess?.();
+  } catch (e) {
+    deps.setColumns(deps.previousValue);
+    deps.onRefresh?.();
+    toastError(e, m.list_kit_kanban_moveFailed());
+  }
+}

package/src/components/shared-kit/list-kit/kanban/drop-layout.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute 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/>.
+
+/** 落点布局的纯计算（与渲染无关，便于单测） */
+
+export interface DropLayoutRow {
+  /** 行 key：卡片用 itemKey、子分组标题用 `h:<runKey>`（与渲染行一致） */
+  key: string;
+  /**
+   * 行类型。子分组标题也必须参与让位，否则落点在下半区时卡片会与标题重合
+   * （用户反馈：拖动时标题没跟着卡片走）。
+   */
+  kind: "card" | "header";
+  /** 被折叠的子分组：卡片不渲染，但仍占用数据下标（与 primitive 的 insertIndex 对齐） */
+  hidden?: boolean;
+}
+
+export interface DropLayout {
+  /** 需要让位的行（卡片/标题）→ translateY 位移（px） */
+  shifts: Map<string, number>;
+  /** 落点槽渲染在其上方的卡片 */
+  slotBefore: Set<string>;
+  /** 落点槽渲染在其下方的卡片（落点在末位时使用；无可见卡则为 null） */
+  slotAfter: string | null;
+  /** 落点槽渲染在其上方的子分组标题（「追加到上一子分组末尾」时，槽应在标题之上） */
+  slotBeforeHeader: string | null;
+}
+
+/**
+ * 计算拖拽落点的让位与插槽挂点。
+ *
+ * 让位语义：数据下标 >= insertIndex 的卡片统一下移 `step`（= 拖拽卡高 + 卡间距），
+ * 于是 `insertIndex` 处让出一块刚好容下落点槽的空隙。不区分跨列/同列——同列内
+ * 源卡也参与让位，视觉上等价于「卡片依次让开」，且不会出现重叠。
+ */
+export interface DropLayoutOptions {
+  /**
+   * 落点归属「上一子分组」（hover 在某分组最后一张卡的下半区 → 追加到该分组末尾）。
+   * 此时插入位恰好是下一分组首张卡的下标，但语义上应插在下一分组的**标题之前**，
+   * 所以该边界标题也要让位、落点槽挂在它上方（否则槽位与最终落位差一个标题行）。
+   */
+  appendToPreviousRun?: boolean;
+}
+
+export function computeDropLayout(
+  rows: DropLayoutRow[],
+  drop: { insertIndex: number } | null,
+  stepPx: number,
+  options?: DropLayoutOptions,
+): DropLayout {
+  const appendToPreviousRun = options?.appendToPreviousRun ?? false;
+  const shifts = new Map<string, number>();
+  const slotBefore = new Set<string>();
+  let slotAfter: string | null = null;
+  let slotBeforeHeader: string | null = null;
+  if (!drop) return { shifts, slotBefore, slotAfter, slotBeforeHeader };
+
+  let cardIndex = 0;
+  let lastVisibleKey: string | null = null;
+  for (const row of rows) {
+    if (row.kind === "header") {
+      // 标题位于插入点「之后」（其前方卡片数 > 插入位）才让位：插到某标题下第一张卡之前时，
+      // 该标题留在原位，让出的空隙正好在标题与卡片之间。
+      // 例外：落点归属上一子分组（追加到其末尾）时，边界标题（cardIndex === 插入位）也要让位，
+      // 空隙与落点槽都在该标题之上。
+      if (cardIndex > drop.insertIndex) {
+        shifts.set(row.key, stepPx);
+      } else if (appendToPreviousRun && cardIndex === drop.insertIndex) {
+        shifts.set(row.key, stepPx);
+        slotBeforeHeader = row.key;
+      }
+      continue;
+    }
+    if (cardIndex >= drop.insertIndex) shifts.set(row.key, stepPx);
+    // 归属上一子分组末尾时，落点槽由边界标题承担（见上方 header 分支）；
+    // 这里若同时给锚卡加槽，会出现两个淡化卡上下错位叠在一起。
+    if (cardIndex === drop.insertIndex && !appendToPreviousRun) slotBefore.add(row.key);
+    if (!row.hidden) lastVisibleKey = row.key;
+    cardIndex += 1;
+  }
+  // 落点在末位（含拖到空列 / 列尾）：槽挂在最后一张可见卡下方
+  if (drop.insertIndex >= cardIndex) slotAfter = lastVisibleKey;
+  return { shifts, slotBefore, slotAfter, slotBeforeHeader };
+}

package/src/components/shared-kit/list-kit/kanban/frozen-header.ts

@@ -0,0 +1,88 @@
+// 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 <http://www.gnu.org/licenses/>.
+
+/**
+ * 看板列内「吸附子分组头」判定。
+ *
+ * 列内只有一级子分组（父分组 = 列头 CardHeader，恒定可见、不参与列内滚动），
+ * 但行是绝对定位的虚拟化行，CSS sticky 不生效，故用「等价换算」得到原生
+ * sticky 的观感。
+ *
+ * **锚点必须是滚动容器顶边（scrollport top），不是内容盒顶**：滚动容器有
+ * p-2 上内边距，行测量起点（内容盒坐标系）比容器坐标系低
+ * SUB_HEADER_STICKY_PAD(8)px。活跃阈值 / 吸附位 / 顶出量三者必须同锚 ——
+ * 历史实现的锚点在内容盒顶（吸附位、阈值、顶出量都少算 8px），等价于把吸附层
+ * 下移 8px：组头本身已随内容上滑 8px 时吸附层仍停在原位，于是在「几乎没滚动」
+ * 的区间里就把紧贴组头底边的首张卡上边框盖掉（用户反馈「上边框还是被裁了」）。
+ *
+ * - 组头未滚到容器顶边时返回 null（在流渲染，自己自然上滑，吸附层完全不参与）
+ * - 越过容器顶边后吸附在容器顶（offset = 0）
+ * - 下一个组头逼近时被顶出（offset 为负），与原生 sticky 被顶开的位移一致
+ *
+ * 边界（容器坐标恰好 0）不留容差：此刻吸附层与在流组头**像素重合**，切换无视觉跳变；
+ * 留 1px 容差反而会让吸附层比在流组头高 1px（同一行画两遍、错开 1px）。
+ *
+ * @param scrollTop 列内滚动容器的 scrollTop
+ * @param measurements 虚拟化行测量（start 以内容盒顶端为原点，size 为行高）
+ * @param subHeaderIndexes 子分组头行在 rows 中的下标（升序）
+ * @returns 活跃子分组头的行下标与位移；未越过容器顶边 / 无可用测量时返回 null
+ */
+export interface FrozenSubHeader {
+  /** 活跃子分组头的行下标 */
+  index: number;
+  /** 相对容器顶边的纵向位移（px，<= 0）：被下一个组头顶出时为负 */
+  offset: number;
+}
+
+/** 列内滚动容器上内边距（= kanban-view.tsx 滚动容器的 p-2 与吸附层内容盒的 px-2）。
+ *  吸附层挂在容器坐标系（top-0 = 容器顶边），行测量 start 在内容盒坐标系，
+ *  判定阈值 / 吸附位 / 顶出量必须同时计入本值，否则吸附层早 8px 落下、裁掉首卡上边框。 */
+export const SUB_HEADER_STICKY_PAD = 8;
+
+export function computeFrozenSubHeader(
+  scrollTop: number,
+  measurements: ReadonlyArray<{ start: number; size: number } | undefined>,
+  subHeaderIndexes: readonly number[],
+): FrozenSubHeader | null {
+  // overscroll（macOS 橡皮筋）下 scrollTop 可能为负，钳制避免首个子组头失效
+  const top = Math.max(0, scrollTop);
+  // 换算到内容盒坐标系：组头上缘到达容器顶边 ⇔ m.start <= top - SUB_HEADER_STICKY_PAD
+  const threshold = top - SUB_HEADER_STICKY_PAD;
+
+  let active = -1;
+  let activePos = -1;
+  for (let k = 0; k < subHeaderIndexes.length; k++) {
+    const m = measurements[subHeaderIndexes[k]];
+    if (m && m.start <= threshold) {
+      active = subHeaderIndexes[k];
+      activePos = k;
+    }
+  }
+  if (active < 0) return null;
+
+  const activeSize = measurements[active]?.size ?? 0;
+  let offset = 0;
+  for (let k = activePos + 1; k < subHeaderIndexes.length; k++) {
+    const m = measurements[subHeaderIndexes[k]];
+    if (!m) continue;
+    // 下一个组头上缘（容器坐标 start - threshold）进入「容器顶边 + 当前组头高」时开始上推
+    offset = Math.min(0, m.start - threshold - activeSize);
+    break;
+  }
+
+  return { index: active, offset };
+}

package/src/components/shared-kit/list-kit/kanban/instance-key.ts

@@ -0,0 +1,83 @@
+// 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/>.
+
+/** 同一条目可同时落在多个标签列，而 dnd-kit 要求 droppable/draggable id 全局唯一。
+ * 渲染层用「列 key + 条目 id」合成实例 id，拖拽提交时再解析回条目 id。
+ * 泛型化（UI 对齐二期设计 §4.5）：条目类型只约束 `id: string`，与 story 解耦，
+ * 供 testcase / bug 等模块的看板复用（函数名沿用 story 时期的口径）。 */
+export type KanbanStoryItem<T extends { id: string } = { id: string }> = T & {
+  __instanceKey?: string;
+};
+
+const INSTANCE_SEP = "::";
+
+export function instanceKeyOf(columnKey: string, itemId: string): string {
+  return `${columnKey}${INSTANCE_SEP}${itemId}`;
+}
+
+/** 列 key 本身可能含 `::`（如 `label::xxx`），故从最后一个分隔符切分 */
+export function storyIdFromInstanceKey(id: string): string {
+  const at = id.lastIndexOf(INSTANCE_SEP);
+  return at === -1 ? id : id.slice(at + INSTANCE_SEP.length);
+}
+
+/** 渲染层 id：优先用合成实例 id */
+export function itemKey<T extends { id: string }>(item: T): string {
+  return (item as KanbanStoryItem<T>).__instanceKey ?? item.id;
+}
+
+/** 按当前列归属重写实例 id：对象已归属正确列时保持原引用（卡片 memo 依赖引用稳定）。
+ * `frozenKey` 为拖拽中的活动卡片实例 id——vendored Kanban 在 onDragOver 就提交跨列移动，
+ * 此刻若跟着重算，dnd-kit 手里的 active id（拖拽开始时捕获）会从目标列 SortableContext 中
+ * 消失（其余卡片不让位），overlay 也查不到条目（浮动卡片消失）。故拖拽期冻结该卡的 id。 */
+export function applyInstanceKeys<T extends { id: string }>(
+  columns: Record<string, T[]>,
+  frozenKey?: string | null,
+): Record<string, KanbanStoryItem<T>[]> {
+  const keyed: Record<string, KanbanStoryItem<T>[]> = {};
+  for (const [columnKey, items] of Object.entries(columns)) {
+    let changed = false;
+    const mapped: KanbanStoryItem<T>[] = items.map((item) => {
+      const keyedItem = item as KanbanStoryItem<T>;
+      const instanceKey =
+        frozenKey != null && keyedItem.__instanceKey === frozenKey
+          ? frozenKey
+          : instanceKeyOf(columnKey, item.id);
+      if (keyedItem.__instanceKey === instanceKey) return keyedItem;
+      changed = true;
+      return { ...item, __instanceKey: instanceKey };
+    });
+    // 未发生改写的列保留原数组引用：下游按列 memo 与 SortableContext 都以此为 bailout 依据
+    keyed[columnKey] = changed ? mapped : (items as KanbanStoryItem<T>[]);
+  }
+  return keyed;
+}
+
+/** overlay 按 dnd-kit 的 active id 反查卡片：需同时索引原始条目 id 与实例 id
+ * （拖拽期活动卡片的实例 id 被冻结为出发列 key，已不等于其当前所在列的 key） */
+export function buildStoryIndex<T extends { id: string }>(
+  keyed: Record<string, KanbanStoryItem<T>[]>,
+): Record<string, T> {
+  const map: Record<string, T> = {};
+  for (const items of Object.values(keyed)) {
+    for (const item of items) {
+      map[item.id] = item;
+      map[itemKey(item)] = item;
+    }
+  }
+  return map;
+}