@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/shared-kit/list-kit/filters/types.ts

@@ -0,0 +1,68 @@
+// 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/>.
+
+// list-kit filters 纯类型层（设计 §4.6：serverFn 可安全 import——
+// 仅 import type 与纯函数，零 React/组件依赖；LucideIcon 为 type-only import，
+// 编译期擦除）。
+//
+// 序列化兼容契约：serializeFilters/deserializeFilters 自
+// story/filters/filter-types.ts 逐字节搬移（唯一差异是给
+// FilterCondition/FilterFieldConfig 加了 K 泛型参数——story/bug 的 property
+// key 联合不同构，泛型参数让两侧各自窄化实例化，运行时擦除零影响）。
+// 存量保存视图 DB Json（story_filter_views / bug_filter_views 的 filters 列）
+// 的存储形状必须保持不变，修改序列化逻辑属破坏性变更。
+
+import type { LucideIcon } from "lucide-react";
+
+export type FilterOperator =
+  | "is" | "is_not" | "is_any_of" | "is_not_any_of" | "is_empty" | "is_not_empty"
+  | "before" | "after" | "on_or_before" | "on_or_after" | "between"
+  | "contains" | "not_contains";
+
+export interface FilterCondition<K extends string = string> {
+  id: string;
+  property: K;
+  operator: FilterOperator;
+  value: string;
+}
+
+export type FilterFieldType = "select" | "multi_select" | "user" | "date" | "text";
+
+export interface FilterFieldConfig<K extends string = string> {
+  key: K;
+  label: () => string;
+  icon: LucideIcon;
+  fieldType: FilterFieldType;
+  operators: FilterOperator[];
+  defaultOperator: FilterOperator;
+  defaultValue?: string;
+}
+
+export function serializeFilters(conditions: FilterCondition[]): string | undefined {
+  if (conditions.length === 0) return undefined;
+  return JSON.stringify(conditions.map(({ id, property, operator, value }) => ({ id, property, operator, value })));
+}
+
+export function deserializeFilters(json: string | undefined): FilterCondition[] {
+  if (!json) return [];
+  try {
+    const parsed = JSON.parse(json) as FilterCondition[];
+    return Array.isArray(parsed) ? parsed.filter((c) => c.property && c.operator) : [];
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,45 @@
+// 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/>.
+
+export interface FrozenHeader {
+  groupIdx: number;
+  subIdx: number | null;
+}
+
+export function computeFrozenHeader(
+  scrollTop: number,
+  measurements: ReadonlyArray<{ start: number } | undefined>,
+  groupHeaderIndexes: readonly number[],
+  subGroupHeaderIndexes: readonly number[],
+  parentGroupOfSub: ReadonlyMap<number, number>,
+): FrozenHeader | null {
+  // overscroll（macOS 橡皮筋）下 scrollTop 可能为负，钳制后保证首个组头不被误判为「无活跃组头」
+  const threshold = Math.max(0, scrollTop) + 1;
+  let groupIdx: number | null = null;
+  for (const i of groupHeaderIndexes) {
+    const m = measurements[i];
+    if (m && m.start <= threshold) groupIdx = i;
+  }
+  if (groupIdx == null) return null;
+
+  let subIdx: number | null = null;
+  for (const i of subGroupHeaderIndexes) {
+    const m = measurements[i];
+    if (m && m.start <= threshold && parentGroupOfSub.get(i) === groupIdx) subIdx = i;
+  }
+  return { groupIdx, subIdx };
+}

package/src/components/shared-kit/list-kit/icon-semantics.ts

@@ -0,0 +1,50 @@
+// 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 type { LucideIcon } from "lucide-react";
+import {
+  TableProperties,
+  SquareKanban,
+  Trees,
+  ListFilter,
+  ListFilterPlus,
+  ChartNoAxesGantt,
+  MoreHorizontal,
+  Plus,
+  Search,
+  Download,
+  BrushCleaning,
+} from "lucide-react";
+
+/**
+ * 列表工具栏图标语义单一事实源（list-kit）。
+ *
+ * 常量名描述「用途」，值描述「长什么样」——消费方一律 import 语义常量，
+ * 禁止直接 import lucide 图标表达同一语义，避免同一含义在多个文件各挂一个
+ * 图标名、换图标时漏改。语义不匹配的用法不要硬套，保留直接 import。
+ */
+export const VIEW_LIST_ICON: LucideIcon = TableProperties;
+export const VIEW_BOARD_ICON: LucideIcon = SquareKanban;
+export const ALL_PROJECTS_ICON: LucideIcon = Trees;
+export const FILTER_ICON: LucideIcon = ListFilter;
+export const FILTER_ACTIVE_ICON: LucideIcon = ListFilterPlus;
+export const DISPLAY_ICON: LucideIcon = ChartNoAxesGantt;
+export const MORE_ICON: LucideIcon = MoreHorizontal;
+export const CREATE_ICON: LucideIcon = Plus;
+export const SEARCH_ICON: LucideIcon = Search;
+export const EXPORT_ICON: LucideIcon = Download;
+export const BATCH_CLEAR_ICON: LucideIcon = BrushCleaning;

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

@@ -0,0 +1,139 @@
+// 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/>.
+
+import { describe, expect, it } from "vitest";
+import { computeDropLayout, type DropLayoutRow } from "../drop-layout";
+
+const rows = (...keys: string[]): DropLayoutRow[] =>
+  keys.map((key) => ({ key, kind: "card", hidden: false }));
+const withHeader = (headerKey: string, ...keys: string[]): DropLayoutRow[] => [
+  { key: headerKey, kind: "header" },
+  ...rows(...keys),
+];
+
+describe("computeDropLayout", () => {
+  it("无落点时不让位、不渲染插槽", () => {
+    const { shifts, slotBefore, slotAfter } = computeDropLayout(rows("a", "b"), null, 120);
+    expect(shifts.size).toBe(0);
+    expect(slotBefore.size).toBe(0);
+    expect(slotAfter).toBeNull();
+  });
+
+  it("插到中间：从插入位起的卡片让位，插槽挂在该卡上方", () => {
+    const { shifts, slotBefore, slotAfter } = computeDropLayout(
+      rows("a", "b", "c", "d"),
+      { insertIndex: 2 },
+      120,
+    );
+    expect([...shifts.entries()]).toEqual([["c", 120], ["d", 120]]);
+    expect([...slotBefore]).toEqual(["c"]);
+    expect(slotAfter).toBeNull();
+  });
+
+  it("插到首位：全部卡片让位", () => {
+    const { shifts, slotBefore } = computeDropLayout(rows("a", "b"), { insertIndex: 0 }, 120);
+    expect([...shifts.entries()]).toEqual([["a", 120], ["b", 120]]);
+    expect([...slotBefore]).toEqual(["a"]);
+  });
+
+  it("插到末位：不让位，插槽挂在最后一张可见卡下方", () => {
+    const { shifts, slotBefore, slotAfter } = computeDropLayout(
+      rows("a", "b"),
+      { insertIndex: 2 },
+      120,
+    );
+    expect(shifts.size).toBe(0);
+    expect(slotBefore.size).toBe(0);
+    expect(slotAfter).toBe("b");
+  });
+
+  it("折叠子分组的卡片仍占数据下标，但不作为插槽挂点", () => {
+    const withHidden: DropLayoutRow[] = [
+      { key: "a", kind: "card", hidden: false },
+      { key: "b", kind: "card", hidden: true },
+      { key: "c", kind: "card", hidden: false },
+    ];
+    const { shifts, slotBefore, slotAfter } = computeDropLayout(withHidden, { insertIndex: 2 }, 120);
+    expect([...shifts.entries()]).toEqual([["c", 120]]);
+    expect([...slotBefore]).toEqual(["c"]);
+    expect(slotAfter).toBeNull();
+  });
+
+  it("末位落点跳过折叠卡片，挂到最后一张可见卡", () => {
+    const withHidden: DropLayoutRow[] = [
+      { key: "a", kind: "card", hidden: false },
+      { key: "b", kind: "card", hidden: true },
+    ];
+    const { slotAfter } = computeDropLayout(withHidden, { insertIndex: 2 }, 120);
+    expect(slotAfter).toBe("a");
+  });
+
+  it("空列（无可见卡）时无可挂点", () => {
+    const { shifts, slotAfter } = computeDropLayout([], { insertIndex: 0 }, 120);
+    expect(shifts.size).toBe(0);
+    expect(slotAfter).toBeNull();
+  });
+
+  it("子分组标题：位于插入点之后（其前方卡片数 > 插入位）才让位", () => {
+    // 行序：标题H1、卡a、卡b、标题H2、卡c、卡d
+    const layout = computeDropLayout(withHeader("H1", "a", "b", "H2", "c", "d"), { insertIndex: 2 }, 100);
+    // 插到卡 c 之前（下标 2）：H1/a/b 不动，H2 与 c/d 一起下移
+    expect(layout.shifts.get("H1")).toBeUndefined();
+    expect(layout.shifts.get("a")).toBeUndefined();
+    expect(layout.shifts.get("b")).toBeUndefined();
+    expect(layout.shifts.get("H2")).toBe(100);
+    expect(layout.shifts.get("c")).toBe(100);
+    expect(layout.shifts.get("d")).toBe(100);
+  });
+
+  it("插到某标题下第一张卡之前时，该标题留在原位", () => {
+    // 行序：卡a、卡b、标题H、卡c → 插到卡 c 之前（下标 2）：H 不动，只有 c 下移
+    const layout = computeDropLayout(
+      [...rows("a", "b"), { key: "H", kind: "header" as const }, { key: "c", kind: "card" as const }],
+      { insertIndex: 2 },
+      100,
+    );
+    expect(layout.shifts.get("H")).toBeUndefined();
+    expect(layout.shifts.get("c")).toBe(100);
+  });
+
+  it("追加到上一子分组末尾：边界标题也一起让位，落点槽挂在标题之上", () => {
+    // 行序：卡a、卡b、标题H、卡c → 落点在 b 之下（insertIndex=2）且归属上一分组
+    const layout = computeDropLayout(
+      [...rows("a", "b"), { key: "H", kind: "header" as const }, { key: "c", kind: "card" as const }],
+      { insertIndex: 2 },
+      100,
+      { appendToPreviousRun: true },
+    );
+    expect(layout.shifts.get("a")).toBeUndefined();
+    expect(layout.shifts.get("b")).toBeUndefined();
+    expect(layout.shifts.get("H")).toBe(100); // 标题让位
+    expect(layout.shifts.get("c")).toBe(100);
+    expect(layout.slotBeforeHeader).toBe("H"); // 槽挂在标题之上
+    expect([...layout.slotBefore]).toEqual([]); // 锚卡侧不得再挂一个槽（否则两卡重叠）
+  });
+
+  it("未标记追加时边界标题不让位（插入下一分组开头）", () => {
+    const layout = computeDropLayout(
+      [...rows("a", "b"), { key: "H", kind: "header" as const }, { key: "c", kind: "card" as const }],
+      { insertIndex: 2 },
+      100,
+    );
+    expect(layout.shifts.get("H")).toBeUndefined();
+    expect(layout.slotBeforeHeader).toBeNull();
+  });
+});

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

@@ -0,0 +1,111 @@
+// 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/>.
+
+import { describe, it, expect } from "vitest";
+import {
+  computeFrozenSubHeader,
+  SUB_HEADER_STICKY_PAD,
+} from "../frozen-header";
+
+// 列内平铺行（index → start / size），子分组头高 36：
+//   0 subA  0      ← 内容盒坐标系原点，容器顶边在 -SUB_HEADER_STICKY_PAD(-8)
+//   1 card  36
+//   2 card 120
+//   3 subB 200
+//   4 card 236
+const measurements = [
+  { start: 0, size: 36 },
+  { start: 36, size: 84 },
+  { start: 120, size: 80 },
+  { start: 200, size: 36 },
+  { start: 236, size: 84 },
+];
+const subHeaderIndexes = [0, 3];
+
+const compute = (scrollTop: number) =>
+  computeFrozenSubHeader(scrollTop, measurements, subHeaderIndexes);
+
+describe("computeFrozenSubHeader", () => {
+  it("首屏（未滚动）：组头在流里可见，不渲染吸附层", () => {
+    expect(compute(0)).toBeNull();
+  });
+
+  it("锚点在滚动容器顶边：组头上缘越过容器顶边前（内容盒 p-2 偏移内）不渲染", () => {
+    // 组头 start=0 时其容器坐标 = 内容盒顶 - scrollTop，即 scrollTop <
+    // SUB_HEADER_STICKY_PAD 时组头仍在上内边距带内自然上滑，
+    // 此时渲染吸附层（锚在内容盒顶）就会把紧贴组头底边的首卡上边框盖掉
+    // （用户反馈的「上边框还是被裁了」）。
+    for (let top = 0; top < SUB_HEADER_STICKY_PAD; top++) {
+      expect(compute(top)).toBeNull();
+    }
+    expect(compute(SUB_HEADER_STICKY_PAD)).toEqual({ index: 0, offset: 0 });
+  });
+
+  it("越过容器顶边：吸附在容器顶（offset 0）", () => {
+    expect(compute(8)).toEqual({ index: 0, offset: 0 });
+    expect(compute(50)).toEqual({ index: 0, offset: 0 });
+    expect(compute(163)).toEqual({ index: 0, offset: 0 });
+    // 下一个组头上缘（容器坐标）= 当前组头高（36）时仍无位移
+    expect(compute(172)).toEqual({ index: 0, offset: 0 });
+  });
+
+  it("下一个组头逼近：被逐像素顶出（offset = 下一个头上缘容器坐标 - 头高）", () => {
+    expect(compute(180)?.offset).toBe(-8);
+    expect(compute(198)?.offset).toBe(-26);
+    expect(compute(207)?.offset).toBe(-35);
+  });
+
+  it("滚动到下一个子组头越过容器顶边：切换为该子组头并重新吸附", () => {
+    // 容器坐标恰好为 0 的边界不留容差：上一组头已被顶出到 bottom=0，切换无跳变
+    expect(compute(207)?.index).toBe(0);
+    expect(compute(208)).toEqual({ index: 3, offset: 0 });
+    expect(compute(300)).toEqual({ index: 3, offset: 0 });
+  });
+
+  it("滚过末尾：吸附头停在最后一个子组头", () => {
+    expect(compute(10000)).toEqual({ index: 3, offset: 0 });
+  });
+
+  it("负数 scrollTop（overscroll）不崩：组头仍在流里可见，返回 null", () => {
+    expect(compute(-5)).toBeNull();
+  });
+
+  it("无子分组头（未启用子分组）：返回 null", () => {
+    expect(computeFrozenSubHeader(100, measurements, [])).toBeNull();
+  });
+
+  it("组头未滚到容器顶边（容器坐标 start > scrollTop）：无活跃组头，保持自然滑动", () => {
+    // 首个子分组头 start=40，容器坐标 = 40 - scrollTop + SUB_HEADER_STICKY_PAD
+    const far = [
+      { start: 40, size: 36 },
+      { start: 200, size: 36 },
+    ];
+    expect(computeFrozenSubHeader(0, far, [0])).toBeNull();
+    expect(computeFrozenSubHeader(30, far, [0])).toBeNull();
+    expect(computeFrozenSubHeader(39, far, [0])).toBeNull();
+    // start=40 的组头到 scrollTop=48 才越过容器顶边（48 - SUB_HEADER_STICKY_PAD = 40）
+    expect(computeFrozenSubHeader(47, far, [0])).toBeNull();
+    expect(computeFrozenSubHeader(48, far, [0])).toEqual({ index: 0, offset: 0 });
+  });
+
+  it("测量的组头被忽略；全缺失时返回 null", () => {
+    expect(computeFrozenSubHeader(10000, [{ start: 0, size: 36 }], [0, 3])).toEqual(
+      { index: 0, offset: 0 },
+    );
+    expect(computeFrozenSubHeader(0, [], [0, 3])).toBeNull();
+  });
+});

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

@@ -0,0 +1,130 @@
+// 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 {
+  applyInstanceKeys,
+  buildStoryIndex,
+  instanceKeyOf,
+  itemKey,
+  storyIdFromInstanceKey,
+} from "../instance-key";
+import type { StoryListItem } from "../../../../story/types";
+
+function story(id: string): StoryListItem {
+  return { id } as StoryListItem;
+}
+
+/** 回归守卫：修复前渲染层直接用 story.id 作 dnd id，同一需求出现在多个标签列时 id 重复，
+ * dnd-kit 的 droppable 注册表后写覆盖先写 → 落点解析错列（卡片漂移）。 */
+describe("看板实例 id（重复需求跨列）", () => {
+  it("同一需求在不同列得到互不相同的实例 id", () => {
+    const columns = {
+      "label::前端": [story("s1"), story("s2")],
+      "label::后端": [story("s1")],
+    };
+    const keyed = applyInstanceKeys(columns);
+    const allKeys = Object.values(keyed).flat().map(itemKey);
+    expect(allKeys).toHaveLength(3);
+    expect(new Set(allKeys).size).toBe(3);
+  });
+
+  it("列 key 含 `::` 时仍能解析回需求 id", () => {
+    const key = instanceKeyOf("label::前端", "cmushvu3z02a1mw8oa58t5b4h");
+    expect(storyIdFromInstanceKey(key)).toBe("cmushvu3z02a1mw8oa58t5b4h");
+    expect(storyIdFromInstanceKey("cmushvu3z02a1mw8oa58t5b4h")).toBe(
+      "cmushvu3z02a1mw8oa58t5b4h",
+    );
+  });
+
+  it("拖到另一列后重算实例 id（列归属随落点变化）", () => {
+    const moved = applyInstanceKeys({ "label::后端": [story("s1")] });
+    expect(itemKey(moved["label::后端"][0])).toBe(instanceKeyOf("label::后端", "s1"));
+  });
+
+  it("归属未变的卡片保持对象引用（TaskCard memo 依赖引用稳定）", () => {
+    const first = applyInstanceKeys({ "state::todo": [story("s1")] });
+    const second = applyInstanceKeys(first);
+    expect(second["state::todo"][0]).toBe(first["state::todo"][0]);
+  });
+});
+
+/** 回归守卫：拖拽期跨列移动（vendored Kanban 在 onDragOver 就改容器）会让实例 id 中途重算，
+ * dnd-kit 记的 active id 是拖拽开始时的旧 id → 目标列 SortableContext 里找不到 active，
+ * 卡片不让位；overlay 用旧 id 查 story 也查不到 → 浮动卡片消失。故拖拽期须冻结活动卡片的实例 id。 */
+describe("拖拽期冻结活动卡片实例 id", () => {
+  const dragged = { ...story("s1"), __instanceKey: instanceKeyOf("backlog", "s1") };
+
+  it("跨列移动后活动卡片保留拖拽开始时的实例 id", () => {
+    const keyed = applyInstanceKeys(
+      { backlog: [], todo: [dragged] },
+      instanceKeyOf("backlog", "s1"),
+    );
+    expect(itemKey(keyed.todo[0])).toBe(instanceKeyOf("backlog", "s1"));
+  });
+
+  it("未传冻结 key（拖拽结束）时恢复正常重算", () => {
+    const keyed = applyInstanceKeys({ backlog: [], todo: [dragged] });
+    expect(itemKey(keyed.todo[0])).toBe(instanceKeyOf("todo", "s1"));
+  });
+
+  it("冻结只作用于携带该 key 的卡片，同列其他卡片照常重算", () => {
+    const other = { ...story("s2"), __instanceKey: instanceKeyOf("backlog", "s2") };
+    const keyed = applyInstanceKeys(
+      { backlog: [], todo: [other, dragged] },
+      instanceKeyOf("backlog", "s1"),
+    );
+    expect(itemKey(keyed.todo[0])).toBe(instanceKeyOf("todo", "s2"));
+    expect(itemKey(keyed.todo[1])).toBe(instanceKeyOf("backlog", "s1"));
+  });
+
+  it("冻结的卡片归属未变时仍保持对象引用", () => {
+    const first = applyInstanceKeys(
+      { backlog: [dragged] },
+      instanceKeyOf("backlog", "s1"),
+    );
+    const second = applyInstanceKeys(first, instanceKeyOf("backlog", "s1"));
+    expect(second.backlog[0]).toBe(first.backlog[0]);
+  });
+});
+
+/** 回归守卫：overlay 用 dnd-kit 的 active id 反查卡片，active id 是拖拽开始时的实例 id；
+ * 跨列移动后该卡片所在列的 key 已变，索引必须同时含原始 id 与实例 id 才能查到。 */
+describe("卡片索引（overlay 反查）", () => {
+  it("同时按原始 id 与实例 id 建索引", () => {
+    const keyed = applyInstanceKeys({ "state::todo": [story("s1")] });
+    const index = buildStoryIndex(keyed);
+    expect(index["s1"]?.id).toBe("s1");
+    expect(index[instanceKeyOf("state::todo", "s1")]?.id).toBe("s1");
+  });
+
+  it("跨列移动后仍能用拖拽开始时的实例 id 查到卡片", () => {
+    const dragged = { ...story("s1"), __instanceKey: instanceKeyOf("backlog", "s1") };
+    const keyed = applyInstanceKeys(
+      { backlog: [], todo: [dragged] },
+      instanceKeyOf("backlog", "s1"),
+    );
+    const index = buildStoryIndex(keyed);
+    expect(index[instanceKeyOf("backlog", "s1")]?.id).toBe("s1");
+  });
+
+  it("虚列（未落库的空列 key）中的卡片同样可查", () => {
+    const keyed = applyInstanceKeys({ "user::u9": [story("s1")] });
+    const index = buildStoryIndex(keyed);
+    expect(index[instanceKeyOf("user::u9", "s1")]?.id).toBe("s1");
+  });
+});