@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/story/views/timeline/__tests__/mappers.test.ts

@@ -0,0 +1,742 @@
+// 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, it, expect } from "vitest";
+import {
+  storyToGanttEvents,
+  buildGanttResources,
+  ganttSummaryProgress,
+  fromGanttRangeToStoryDates,
+  mergeStoryOverrides,
+  storyStateResourceId,
+  ganttGroupResourceId,
+  STORY_STATE_GANTT_COLOR,
+  PRIORITY_GANTT_COLOR,
+  type StoryGanttData,
+  type IterationBaseline,
+} from "../mappers";
+import { STATE_COLUMN_TINT, PRIORITY_COLUMN_TINT, resolveGroupColor } from "../../../display/group-resolver";
+import { STORY_STATES, STATE_LABEL, PRIORITY_LABEL, type StoryState } from "../../../constants";
+import { parseDate } from "@/lib/datetime";
+import type { StoryListItem } from "../../../types";
+import type { GroupContext } from "../../../display/types";
+import type { GanttEvent, GanttResource } from "@/components/reui/gantt/gantt-types";
+import { m } from "@/paraglide/messages.js";
+
+const makeStory = (
+  over: Partial<StoryListItem> & { id: string },
+): StoryListItem => ({
+  identifier: "STR-1",
+  name: `story-${over.id}`,
+  description: null,
+  state: "todo",
+  priority: "medium",
+  archived: false,
+  startDate: null,
+  targetDate: null,
+  boardOrder: 0,
+  projectId: "p1",
+  parentId: null,
+  parent: null,
+  assignee: null,
+  createdBy: {
+    id: "u1",
+    username: "u",
+    email: "e",
+    avatarConfig: null,
+    bgShape: null,
+    bgColor: null,
+  },
+  labels: [],
+  createdAt: "2026-01-01",
+  updatedAt: "2026-01-01",
+  ...over,
+});
+
+type Edge = { sourceId: string; targetId: string; type: string };
+
+const FULL_RANGE = { startDate: "2026-10-01", targetDate: "2026-10-03" };
+
+describe("storyToGanttEvents", () => {
+  it("test_story_to_event_full_range", () => {
+    // start=2026-10-01、target=2026-10-03 → end=2026-10-04（半开区间 +1 天）
+    const story = makeStory({ id: "s1", state: "in_progress", ...FULL_RANGE });
+    const events = storyToGanttEvents([story], []);
+    expect(events).toHaveLength(1);
+    const e = events[0]!;
+    expect(e.id).toBe("s1");
+    expect(e.title).toBe("story-s1");
+    expect(e.start.getTime()).toBe(parseDate("2026-10-01").getTime());
+    expect(e.end.getTime()).toBe(parseDate("2026-10-04").getTime());
+    expect(e.data?.story).toBe(story);
+    expect(e.resourceId).toBe("s1");
+    // progress：in_progress→50 / done→100 / 其他→0
+    // color 随 state
+    const byState = storyToGanttEvents(
+      STORY_STATES.map(({ value }) =>
+        makeStory({ id: `st-${value}`, state: value, ...FULL_RANGE }),
+      ),
+      [],
+    );
+    const progressOf = (state: StoryState) =>
+      byState.find((ev) => ev.data?.story.state === state)?.progress;
+    expect(progressOf("in_progress")).toBe(50);
+    expect(progressOf("done")).toBe(100);
+    expect(progressOf("todo")).toBe(0);
+    expect(progressOf("backlog")).toBe(0);
+    expect(progressOf("cancelled")).toBe(0);
+    const colorOf = (state: StoryState) =>
+      byState.find((ev) => ev.data?.story.state === state)?.color;
+    expect(colorOf("in_progress")).toBe("var(--color-amber-500)");
+    expect(colorOf("todo")).toBe("var(--color-blue-500)");
+    expect(colorOf("done")).toBe("var(--color-green-500)");
+    expect(colorOf("backlog")).toBe(STORY_STATE_GANTT_COLOR.backlog);
+    expect(colorOf("cancelled")).toBe(STORY_STATE_GANTT_COLOR.cancelled);
+  });
+
+  it("test_start_only_single_day", () => {
+    // 仅 startDate → 单日条形 end = start+1 天
+    const story = makeStory({ id: "s2", startDate: "2026-10-02" });
+    const [e] = storyToGanttEvents([story], []);
+    expect(e).toBeDefined();
+    expect(e!.start.getTime()).toBe(parseDate("2026-10-02").getTime());
+    expect(e!.end.getTime()).toBe(parseDate("2026-10-03").getTime());
+  });
+
+  it("test_milestone_rules", () => {
+    // 三值判定①：仅 targetDate → start===end===targetDate（菱形）
+    const targetOnly = makeStory({ id: "m1", targetDate: "2026-10-05" });
+    const [e1] = storyToGanttEvents([targetOnly], []);
+    expect(e1!.start.getTime()).toBe(parseDate("2026-10-05").getTime());
+    expect(e1!.end.getTime()).toBe(e1!.start.getTime());
+    // 三值判定②：startDate === targetDate → 同为菱形（拖动回写后重渲染稳定）
+    const sameDay = makeStory({
+      id: "m2",
+      startDate: "2026-10-05",
+      targetDate: "2026-10-05",
+    });
+    const [e2] = storyToGanttEvents([sameDay], []);
+    expect(e2!.start.getTime()).toBe(parseDate("2026-10-05").getTime());
+    expect(e2!.end.getTime()).toBe(e2!.start.getTime());
+    // 三值判定③：startDate < targetDate → 条形（end = target+1）
+    const bar = makeStory({
+      id: "m3",
+      startDate: "2026-10-01",
+      targetDate: "2026-10-03",
+    });
+    const [e3] = storyToGanttEvents([bar], []);
+    expect(e3!.end.getTime()).toBe(parseDate("2026-10-04").getTime());
+    expect(e3!.end.getTime()).not.toBe(e3!.start.getTime());
+  });
+
+  it("test_dependency_direction_target_view", () => {
+    // 依赖方向：story.dependencies = 以该 story 为 target 的边的 sourceId
+    // 仅取 type === "BLOCKS"（SS=STARTS_BEFORE / FF=FINISHES_BEFORE 不画）
+    const stories = ["S", "T", "U", "V", "W"].map((id) =>
+      makeStory({ id, ...FULL_RANGE }),
+    );
+    const edges: Edge[] = [
+      { sourceId: "S", targetId: "T", type: "BLOCKS" },
+      { sourceId: "T", targetId: "U", type: "BLOCKS" },
+      { sourceId: "S", targetId: "V", type: "STARTS_BEFORE" },
+      { sourceId: "S", targetId: "W", type: "FINISHES_BEFORE" },
+    ];
+    const events = storyToGanttEvents(stories, edges);
+    const depsOf = (id: string) =>
+      events.find((e) => e.id === id)?.dependencies;
+    expect(depsOf("T")).toEqual(["S"]); // 不含 V（SS 不画）
+    expect(depsOf("U")).toEqual(["T"]);
+    expect(depsOf("V")).toEqual([]); // SS 不画
+    expect(depsOf("W")).toEqual([]); // FF 不画
+    expect(depsOf("S")).toEqual([]);
+  });
+
+  it("test_cancelled_readonly", () => {
+    // state=cancelled → readOnly=true，其余 false
+    const events = storyToGanttEvents(
+      STORY_STATES.map(({ value }) =>
+        makeStory({ id: `ro-${value}`, state: value, ...FULL_RANGE }),
+      ),
+      [],
+    );
+    const readonlyOf = (state: StoryState) =>
+      events.find((e) => e.data?.story.state === state)?.readOnly;
+    expect(readonlyOf("cancelled")).toBe(true);
+    expect(readonlyOf("backlog")).toBe(false);
+    expect(readonlyOf("todo")).toBe(false);
+    expect(readonlyOf("in_progress")).toBe(false);
+    expect(readonlyOf("done")).toBe(false);
+  });
+
+  it("test_roundtrip_dates", () => {
+    // 全区间条形：story→event→回写还原出原 startDate/targetDate
+    const story = makeStory({ id: "r1", ...FULL_RANGE });
+    const [e] = storyToGanttEvents([story], []);
+    expect(
+      fromGanttRangeToStoryDates(e!.start, e!.end),
+    ).toEqual({ startDate: "2026-10-01", targetDate: "2026-10-03" });
+    // 菱形（仅 target 的原形态）：回写 {startDate:当日, targetDate:当日}
+    const milestone = makeStory({ id: "r2", targetDate: "2026-10-05" });
+    const [me] = storyToGanttEvents([milestone], []);
+    const written = fromGanttRangeToStoryDates(me!.start, me!.end);
+    expect(written).toEqual({ startDate: "2026-10-05", targetDate: "2026-10-05" });
+    // 回写后的 {当日, 当日} 重映射仍是零长度（形态往返稳定）
+    const [reme] = storyToGanttEvents(
+      [makeStory({ id: "r3", ...written })],
+      [],
+    );
+    expect(reme!.end.getTime()).toBe(reme!.start.getTime());
+  });
+
+  it("补充：无日期 story 不产生事件", () => {
+    const events = storyToGanttEvents([makeStory({ id: "nd" })], []);
+    expect(events).toHaveLength(0);
+  });
+
+  it("补充：倒挂区间保证 end >= start", () => {
+    const story = makeStory({
+      id: "inv",
+      startDate: "2026-10-03",
+      targetDate: "2026-10-01",
+    });
+    const [e] = storyToGanttEvents([story], []);
+    expect(e!.end.getTime()).toBeGreaterThan(e!.start.getTime());
+  });
+
+  it("补充：非法日期串不产生事件（与 calendar/mappers 同口径）", () => {
+    // parseDate("garbage") 返回 Invalid Date——无守卫时会产出 start/end 含
+    // NaN 时间戳的事件，违反 GanttEvent 的 end >= start 不变量
+    const events = storyToGanttEvents(
+      [
+        makeStory({ id: "bad-start", startDate: "garbage", targetDate: "2026-10-03" }),
+        makeStory({ id: "bad-target", startDate: "2026-10-01", targetDate: "garbage" }),
+      ],
+      [],
+    );
+    expect(events).toHaveLength(0);
+  });
+
+  it("补充：色值与 STATE_COLUMN_TINT 同色相锁定", () => {
+    for (const state of ["todo", "in_progress", "done"] as const) {
+      expect(STATE_COLUMN_TINT[state]?.backgroundColor).toContain(
+        STORY_STATE_GANTT_COLOR[state],
+      );
+    }
+  });
+
+  it("补充：priority 组色与 PRIORITY_COLUMN_TINT 同色相锁定（保活测试，R-11）", () => {
+    // var(--color-*) 若无工具类引用会被 Tailwind v4 tree-shake——与列 tint
+    // 同色相的锁定测试即保活哨兵（模式同上方 STATE 版）；PRIORITY_COLOR 的
+    // text-*-600 类也在源码使用，变量实际存活
+    expect(PRIORITY_GANTT_COLOR.low).toBe("var(--muted-foreground)");
+    expect(PRIORITY_GANTT_COLOR.none).toBe("var(--muted-foreground)");
+    for (const priority of ["urgent", "high", "medium"] as const) {
+      expect(PRIORITY_COLUMN_TINT[priority]?.backgroundColor).toContain(
+        PRIORITY_GANTT_COLOR[priority],
+      );
+    }
+  });
+});
+
+describe("buildGanttResources", () => {
+  it("test_resource_tree_hierarchy", () => {
+    // groupBy=none → parentId 层级树：父=组节点、子=叶子、孤儿挂根
+    const parent = makeStory({ id: "p", name: "parent" });
+    const child = makeStory({ id: "c", parentId: "p", name: "child" });
+    const orphan = makeStory({ id: "o", parentId: "missing", name: "orphan" });
+    const tree = buildGanttResources([parent, child, orphan], "none");
+    expect(tree).toHaveLength(2);
+    const pNode = tree.find((r) => r.id === "p");
+    const oNode = tree.find((r) => r.id === "o");
+    expect(pNode?.children?.map((c) => c.id)).toEqual(["c"]);
+    expect(pNode?.title).toBe("parent");
+    expect(oNode?.children).toBeUndefined();
+  });
+
+  it("补充：parentId 成环的 story 兜底挂根", () => {
+    const a = makeStory({ id: "a", parentId: "b" });
+    const b = makeStory({ id: "b", parentId: "a" });
+    const tree = buildGanttResources([a, b], "none");
+    expect(tree.map((r) => r.id).sort()).toEqual(["a", "b"]);
+    expect(tree.every((r) => !r.children)).toBe(true);
+  });
+
+  it("test_resource_tree_groupby", () => {
+    // groupBy=state、fixture 覆盖全部五态 → 5 个组节点 title 带计数
+    const stories = [
+      makeStory({ id: "b1", state: "backlog" }),
+      makeStory({ id: "t1", state: "todo" }),
+      makeStory({ id: "t2", state: "todo" }),
+      makeStory({ id: "i1", state: "in_progress" }),
+      makeStory({ id: "d1", state: "done" }),
+      makeStory({ id: "x1", state: "cancelled" }),
+    ];
+    const groups = buildGanttResources(stories, "state");
+    expect(groups).toHaveLength(5);
+    expect(groups.map((g) => g.id)).toEqual(
+      STORY_STATES.map((s) => storyStateResourceId(s.value)),
+    );
+    const expectedCounts: Record<StoryState, number> = {
+      backlog: 1,
+      todo: 2,
+      in_progress: 1,
+      done: 1,
+      cancelled: 1,
+    };
+    const expectedChildren: Record<StoryState, string[]> = {
+      backlog: ["b1"],
+      todo: ["t1", "t2"],
+      in_progress: ["i1"],
+      done: ["d1"],
+      cancelled: ["x1"],
+    };
+    for (const g of groups) {
+      const state = g.id.slice("state:".length) as StoryState;
+      expect(g.title).toBe(`${STATE_LABEL[state]()} (${expectedCounts[state]})`);
+      // 组节点 children = 该组需求的叶子行（id=story.id）
+      expect(g.children?.map((c) => c.id)).toEqual(expectedChildren[state]);
+    }
+  });
+
+  it("补充：未排期需求在 state 分组资源树里有对应叶子行", () => {
+    // 无 startDate/targetDate 的 story 不产生事件（时间轴无条形），
+    // 但 state 组 children 必须有它的叶子行——否则行树（settings.resources
+    // 是 reui 行的唯一来源）里没有该行，需求不可见不可点
+    const scheduled = makeStory({ id: "has-date", ...FULL_RANGE });
+    const unscheduled = makeStory({ id: "no-date", state: "todo" });
+    const groups = buildGanttResources([scheduled, unscheduled], "state");
+    const todoGroup = groups.find((g) => g.id === storyStateResourceId("todo"));
+    expect(todoGroup?.children?.map((c) => c.id)).toContain("no-date");
+    const events = storyToGanttEvents([scheduled, unscheduled], []);
+    expect(events).toHaveLength(1); // 只有已排期的产生条形
+    // 事件 resourceId 与叶子行 id 对齐：条形落在自己的叶子行上
+    const leafIds = new Set(
+      groups.flatMap((g) => g.children?.map((c) => c.id) ?? []),
+    );
+    for (const e of events) {
+      expect(leafIds.has(e.resourceId!)).toBe(true);
+    }
+  });
+});
+
+describe("ganttSummaryProgress", () => {
+  it("test_summary_progress", () => {
+    // 组内 events 2 done / 4 总 → 50；空 → null
+    // 汇总只看 data.state（叶子 progress 不参与，单一口径）
+    const stories = [
+      makeStory({ id: "d1", state: "done", ...FULL_RANGE }),
+      makeStory({ id: "d2", state: "done", ...FULL_RANGE }),
+      makeStory({ id: "t1", state: "todo", ...FULL_RANGE }),
+      makeStory({ id: "i1", state: "in_progress", ...FULL_RANGE }),
+    ];
+    const events = storyToGanttEvents(stories, []);
+    const resource: GanttResource = { id: "group", title: "group" };
+    const summary: number | null = ganttSummaryProgress({ resource, events });
+    expect(summary).toBe(50);
+    const empty: number | null = ganttSummaryProgress({
+      resource,
+      events: [] as GanttEvent<StoryGanttData>[],
+    });
+    expect(empty).toBeNull();
+  });
+
+  it("补充：0 done → 0 而非 null", () => {
+    const events = storyToGanttEvents(
+      [makeStory({ id: "t", ...FULL_RANGE })],
+      [],
+    );
+    expect(
+      ganttSummaryProgress({ resource: { id: "g", title: "g" }, events }),
+    ).toBe(0);
+  });
+});
+
+describe("fromGanttRangeToStoryDates", () => {
+  it("补充：end-1 天回写（半开区间还原）", () => {
+    expect(
+      fromGanttRangeToStoryDates(
+        parseDate("2026-10-01"),
+        parseDate("2026-10-04"),
+      ),
+    ).toEqual({ startDate: "2026-10-01", targetDate: "2026-10-03" });
+  });
+
+  it("补充：单日条形回写 {当日, 当日}（重映射为菱形的既定行为）", () => {
+    // start-only 的单日条形（end=start+1）回写后 start===target，
+    // 重渲染会变为菱形——半开模型下单日条形与菱形同日不可区分，
+    // 消费方（task 7）如需保留 target=null 需用 data.story 自行特判
+    expect(
+      fromGanttRangeToStoryDates(
+        parseDate("2026-10-02"),
+        parseDate("2026-10-03"),
+      ),
+    ).toEqual({ startDate: "2026-10-02", targetDate: "2026-10-02" });
+  });
+});
+
+describe("mergeStoryOverrides", () => {
+  it("服务端追平（ISO 完整形态）→ 摘除 override（返回原对象引用）", () => {
+    // 回归：服务端序列化是完整 ISO，override 是 date-only——
+    // 直接字符串比较恒不等会让摘除分支永不命中，拖拽过的行永久遮蔽刷新数据
+    const original = makeStory({
+      id: "s1",
+      startDate: "2026-10-02T00:00:00.000Z",
+      targetDate: "2026-10-06T00:00:00.000Z",
+    });
+    const overrides = new Map([
+      ["s1", { startDate: "2026-10-02", targetDate: "2026-10-06" }],
+    ]);
+    const merged = mergeStoryOverrides([original], overrides);
+    expect(merged[0]).toBe(original);
+  });
+
+  it("targetDate null 对 null 同样按日键判定追平", () => {
+    const original = makeStory({
+      id: "s2",
+      startDate: "2026-10-02T00:00:00.000Z",
+      targetDate: null,
+    });
+    const overrides = new Map([
+      ["s2", { startDate: "2026-10-02", targetDate: null }],
+    ]);
+    expect(mergeStoryOverrides([original], overrides)[0]).toBe(original);
+  });
+
+  it("日期不同且无在途提交 → 服务端已越过 override：放弃遮蔽（返回原对象）", () => {
+    const original = makeStory({
+      id: "s3",
+      startDate: "2026-10-01T00:00:00.000Z",
+      targetDate: "2026-10-05T00:00:00.000Z",
+    });
+    const overrides = new Map([
+      ["s3", { startDate: "2026-10-02", targetDate: "2026-10-06" }],
+    ]);
+    expect(mergeStoryOverrides([original], overrides)[0]).toBe(original);
+  });
+
+  it("日期不同且有在途提交（isPending）→ 继续遮蔽：合并 override", () => {
+    const original = makeStory({
+      id: "s3",
+      startDate: "2026-10-01T00:00:00.000Z",
+      targetDate: "2026-10-05T00:00:00.000Z",
+    });
+    const overrides = new Map([
+      ["s3", { startDate: "2026-10-02", targetDate: "2026-10-06" }],
+    ]);
+    const merged = mergeStoryOverrides([original], overrides, (id) => id === "s3");
+    expect(merged[0]).toEqual({
+      ...original,
+      startDate: "2026-10-02",
+      targetDate: "2026-10-06",
+    });
+  });
+
+  it("无 override 的 story 原样透传", () => {
+    const a = makeStory({ id: "a" });
+    const b = makeStory({ id: "b" });
+    const overrides = new Map([["b", { startDate: "2026-10-02", targetDate: null }]]);
+    const merged = mergeStoryOverrides([a, b], overrides);
+    expect(merged[0]).toBe(a);
+    // b 日期不同且无在途提交 → override 被摘（服务端真值）
+    expect(merged[1].startDate).toBeNull();
+    // 在途时才遮蔽
+    const masked = mergeStoryOverrides([a, b], overrides, (id) => id === "b");
+    expect(masked[1].startDate).toBe("2026-10-02");
+  });
+});
+
+// ── WP-A：多分组键 + 迭代基线 + 空组 + 组节点 id 统一（R-1） ─────────
+
+const EMPTY_CTX: GroupContext = { users: [], labels: [], projects: [] };
+
+describe("buildGanttResources 多分组键（WP-A）", () => {
+  it("priority 分组：组节点 id=R-1 形态、title 带计数、color=resolveGroupColor、children=叶子行", () => {
+    const stories = [
+      makeStory({ id: "pu", priority: "urgent" }),
+      makeStory({ id: "ph1", priority: "high" }),
+      makeStory({ id: "ph2", priority: "high" }),
+    ];
+    const groups = buildGanttResources(stories, "priority", { ctx: EMPTY_CTX });
+    expect(groups.map((g) => g.id)).toEqual(["priority:urgent", "priority:high"]);
+    expect(groups[0]!.title).toBe(`${PRIORITY_LABEL.urgent()} (1)`);
+    expect(groups[1]!.title).toBe(`${PRIORITY_LABEL.high()} (2)`);
+    // 组色 CSS 化（R-11）：PRIORITY_GANTT_COLOR 是 var(--color-*) 色值，
+    // 不再透传 resolver 的 Tailwind 类串（resolveGroupColor 仅供对照锁定）
+    expect(groups[0]!.color).toBe(PRIORITY_GANTT_COLOR.urgent);
+    expect(groups[0]!.color).toBe("var(--color-red-600)");
+    expect(groups[1]!.color).toBe(PRIORITY_GANTT_COLOR.high);
+    expect(groups[0]!.color).not.toBe(resolveGroupColor("urgent", "priority"));
+    // children = 叶子行（id=story.id、title=story.name，与 state 分支同构）
+    expect(groups[1]!.children?.map((c) => c.id)).toEqual(["ph1", "ph2"]);
+    expect(groups[1]!.children?.[0]).toEqual({ id: "ph1", title: "story-ph1" });
+  });
+
+  it("assignee 分组：无值成员归 unassigned 哨兵组，label 跟随 group-resolver 现有行为", () => {
+    const alice = {
+      id: "u9",
+      username: "张三",
+      email: "z@t",
+      avatarConfig: null,
+      bgShape: null,
+      bgColor: null,
+    };
+    const stories = [
+      makeStory({ id: "sa", assignee: alice }),
+      makeStory({ id: "sb", assignee: null }),
+    ];
+    const groups = buildGanttResources(stories, "assignee", {
+      ctx: { users: [alice], labels: [], projects: [] },
+    });
+    expect(groups.map((g) => g.id)).toEqual(["assignee:u9", "assignee:unassigned"]);
+    expect(groups[0]!.title).toBe("张三 (1)");
+    // 无值组文案由 group-resolver 内部解析（mappers 自身不吃 paraglide）
+    expect(groups[1]!.title).toBe(`${m.story_group_unassigned()} (1)`);
+    expect(groups[1]!.children?.map((c) => c.id)).toEqual(["sb"]);
+  });
+
+  it("labels/project 分组复用 group-resolver 语义（一 story 拆多组 + no-* 哨兵组）", () => {
+    const l1 = { id: "l1", name: "bug", color: "#f00" };
+    const l2 = { id: "l2", name: "ui", color: "#0f0" };
+    const labelGroups = buildGanttResources(
+      [makeStory({ id: "ml", labels: [l1, l2] })],
+      "labels",
+      { ctx: { users: [], labels: [l1, l2], projects: [] } },
+    );
+    expect(labelGroups.map((g) => g.id)).toEqual(["labels:l1", "labels:l2"]);
+    expect(labelGroups[0]!.children?.map((c) => c.id)).toEqual(["ml"]);
+    expect(labelGroups[1]!.children?.map((c) => c.id)).toEqual(["ml"]);
+
+    const projGroups = buildGanttResources(
+      [
+        makeStory({ id: "mp1", projectId: null }),
+        makeStory({ id: "mp2", projectId: "p1" }),
+      ],
+      "project",
+      {
+        ctx: {
+          users: [],
+          labels: [],
+          projects: [{ id: "p1", name: "主线", displayId: "M", icon: "" }],
+        },
+      },
+    );
+    expect(projGroups.map((g) => g.id)).toEqual(["project:no-project", "project:p1"]);
+    expect(projGroups.find((g) => g.id === "project:p1")!.title).toBe("主线 (1)");
+    expect(projGroups.find((g) => g.id === "project:no-project")!.children?.map((c) => c.id)).toEqual(["mp1"]);
+  });
+
+  it("iteration 分组：组节点带基线（ghost band）、无迭代组无基线、无迭代文案由调用方注入", () => {
+    const iterations: IterationBaseline[] = [
+      { id: "it1", start: parseDate("2026-10-01"), end: parseDate("2026-10-15") },
+    ];
+    const stories = [
+      makeStory({ id: "si1", iteration: { id: "it1", name: "Sprint 1" } }),
+      makeStory({ id: "si2", iteration: null }),
+    ];
+    const groups = buildGanttResources(stories, "iteration", {
+      iterations,
+      noIterationLabel: "无迭代",
+    });
+    expect(groups.map((g) => g.id)).toEqual(["iteration:it1", "iteration:no-iteration"]);
+    expect(groups[0]!.title).toBe("Sprint 1 (1)");
+    // 组色走 muted（R-11：assignee/labels/project/createdBy/iteration 均无
+    // 组色语义；「无迭代」组同为 iteration 键组节点，色一致）
+    expect(groups[0]!.color).toBe("var(--muted-foreground)");
+    expect(groups[1]!.color).toBe("var(--muted-foreground)");
+    // 基线窗口 = IterationBaseline 原样（半开区间口径由调用方决定，mappers 不加工）
+    expect(groups[0]!.baselineStart?.getTime()).toBe(parseDate("2026-10-01").getTime());
+    expect(groups[0]!.baselineEnd?.getTime()).toBe(parseDate("2026-10-15").getTime());
+    expect(groups[0]!.children?.map((c) => c.id)).toEqual(["si1"]);
+    // 无迭代组：无基线（baselineStart/End 成对缺省）
+    expect(groups[1]!.baselineStart).toBeUndefined();
+    expect(groups[1]!.baselineEnd).toBeUndefined();
+    expect(groups[1]!.title).toBe("无迭代 (1)");
+    expect(groups[1]!.children?.map((c) => c.id)).toEqual(["si2"]);
+    // 未注入 noIterationLabel → 回退哨兵 key 原文（mappers 纯函数不硬编码文案）
+    const fallback = buildGanttResources(stories, "iteration", { iterations });
+    expect(fallback[1]!.title).toBe("no-iteration (1)");
+  });
+
+  it("iteration 分组：未传 iterations 不设基线；showEmptyGroups 用 iterations 全集补零成员组", () => {
+    const stories = [makeStory({ id: "si1", iteration: { id: "it1", name: "Sprint 1" } })];
+    const noBaseline = buildGanttResources(stories, "iteration", {});
+    expect(noBaseline[0]!.baselineStart).toBeUndefined();
+    expect(noBaseline[0]!.baselineEnd).toBeUndefined();
+
+    const iterations: IterationBaseline[] = [
+      { id: "it1", start: parseDate("2026-10-01"), end: parseDate("2026-10-15") },
+      { id: "it2", start: parseDate("2026-10-16"), end: parseDate("2026-10-31") },
+    ];
+    // 零成员迭代组照样带基线（ghost band 可见、无叶子行），名称无成员可考时回退原始 id
+    const withEmpty = buildGanttResources(stories, "iteration", {
+      iterations,
+      showEmptyGroups: true,
+      noIterationLabel: "无迭代",
+    });
+    expect(withEmpty.map((g) => g.id)).toEqual([
+      "iteration:it1",
+      "iteration:it2",
+      "iteration:no-iteration",
+    ]);
+    const emptyIt2 = withEmpty.find((g) => g.id === "iteration:it2")!;
+    expect(emptyIt2.children).toEqual([]);
+    expect(emptyIt2.title).toBe("it2 (0)");
+    expect(emptyIt2.baselineStart?.getTime()).toBe(parseDate("2026-10-16").getTime());
+    expect(emptyIt2.baselineEnd?.getTime()).toBe(parseDate("2026-10-31").getTime());
+    const emptyNoIt = withEmpty.find((g) => g.id === "iteration:no-iteration")!;
+    expect(emptyNoIt.title).toBe("无迭代 (0)");
+    expect(emptyNoIt.baselineStart).toBeUndefined();
+    // 缺省 showEmptyGroups → 只输出有成员的组（现状维持）
+    const without = buildGanttResources(stories, "iteration", { iterations });
+    expect(without.map((g) => g.id)).toEqual(["iteration:it1"]);
+  });
+
+  it("showEmptyGroups=true：priority 展开全集（枚举序、空组计数 0）；缺省只输出非空组", () => {
+    const stories = [
+      makeStory({ id: "ph", priority: "high" }),
+      makeStory({ id: "pu", priority: "urgent" }),
+    ];
+    const off = buildGanttResources(stories, "priority", { ctx: EMPTY_CTX });
+    expect(off.map((g) => g.id)).toEqual(["priority:urgent", "priority:high"]);
+    const on = buildGanttResources(stories, "priority", {
+      ctx: EMPTY_CTX,
+      showEmptyGroups: true,
+    });
+    expect(on.map((g) => g.id)).toEqual([
+      "priority:urgent",
+      "priority:high",
+      "priority:medium",
+      "priority:low",
+      "priority:none",
+    ]);
+    const emptyMedium = on.find((g) => g.id === "priority:medium")!;
+    expect(emptyMedium.children).toEqual([]);
+    expect(emptyMedium.title).toBe(`${PRIORITY_LABEL.medium()} (0)`);
+  });
+
+  it("showEmptyGroups=true：state 补全零成员状态组（gantt 同色源）；缺省维持非空组", () => {
+    const stories = [makeStory({ id: "sd", state: "done" })];
+    const off = buildGanttResources(stories, "state");
+    expect(off.map((g) => g.id)).toEqual([storyStateResourceId("done")]);
+    const on = buildGanttResources(stories, "state", { showEmptyGroups: true });
+    expect(on).toHaveLength(5);
+    expect(on.map((g) => g.id)).toEqual(
+      STORY_STATES.map((s) => storyStateResourceId(s.value)),
+    );
+    const emptyBacklog = on.find((g) => g.id === storyStateResourceId("backlog"))!;
+    expect(emptyBacklog.children).toEqual([]);
+    expect(emptyBacklog.title).toBe(`${STATE_LABEL.backlog()} (0)`);
+    expect(emptyBacklog.color).toBe(STORY_STATE_GANTT_COLOR.backlog);
+  });
+
+  it("showEmptyGroups=true：assignee 依 ctx 枚举全集（用户 + unassigned 兜底）", () => {
+    const alice = {
+      id: "u9",
+      username: "张三",
+      email: "z@t",
+      avatarConfig: null,
+      bgShape: null,
+      bgColor: null,
+    };
+    const groups = buildGanttResources(
+      [makeStory({ id: "sa", assignee: alice })],
+      "assignee",
+      { ctx: { users: [alice], labels: [], projects: [] }, showEmptyGroups: true },
+    );
+    expect(groups.map((g) => g.id)).toEqual(["assignee:u9", "assignee:unassigned"]);
+    expect(groups[1]!.children).toEqual([]);
+  });
+
+  it("showEmptyGroups=true 且 ctx 缺失成员：组域外观察组并集追加，不丢需求", () => {
+    // 成员退队后仍被指派：resolver 自预留 unknown_user 文案兜底（生态预期内
+    // 场景）。交集语义会把它从资源树整体丢弃、用户只看到 (0) 空组——
+    // 并集语义（同 buildGroupMeta 规范合并）钉死：组域序在前、残余追加在后
+    const ghost = {
+      id: "u-gone",
+      username: "离队成员",
+      email: "g@t",
+      avatarConfig: null,
+      bgShape: null,
+      bgColor: null,
+    };
+    const groups = buildGanttResources(
+      [
+        makeStory({ id: "sa", assignee: ghost }),
+        makeStory({ id: "sb", assignee: null }),
+      ],
+      "assignee",
+      { ctx: { users: [], labels: [], projects: [] }, showEmptyGroups: true },
+    );
+    expect(groups.map((g) => g.id)).toEqual([
+      "assignee:unassigned",
+      "assignee:u-gone",
+    ]);
+    const ghostGroup = groups.find((g) => g.id === "assignee:u-gone")!;
+    // story 未丢：叶子行在、计数 1；文案走 resolver 的 unknown_user 兜底（ctx 查无此人）
+    expect(ghostGroup.title).toBe(`${m.story_group_unknown_user()} (1)`);
+    expect(ghostGroup.children?.map((c) => c.id)).toEqual(["sa"]);
+  });
+
+  it("iteration + showEmptyGroups：组域序在前、清单外残余迭代追加（与 resolver 五键同一并集策略）", () => {
+    const iterations: IterationBaseline[] = [
+      { id: "it1", start: parseDate("2026-10-01"), end: parseDate("2026-10-15") },
+    ];
+    const groups = buildGanttResources(
+      [
+        makeStory({ id: "sx", iteration: { id: "it-legacy", name: "历史迭代" } }),
+        makeStory({ id: "sy", iteration: { id: "it1", name: "Sprint 1" } }),
+      ],
+      "iteration",
+      { iterations, showEmptyGroups: true, noIterationLabel: "无迭代" },
+    );
+    // 观察序是 [it-legacy, it1]；并集后组域序在前：it1 → 无迭代 → 清单外残余
+    expect(groups.map((g) => g.id)).toEqual([
+      "iteration:it1",
+      "iteration:no-iteration",
+      "iteration:it-legacy",
+    ]);
+    const legacy = groups.find((g) => g.id === "iteration:it-legacy")!;
+    expect(legacy.title).toBe("历史迭代 (1)");
+    expect(legacy.children?.map((c) => c.id)).toEqual(["sx"]);
+    // 清单未覆盖 → 无基线数据，两字段成对缺省
+    expect(legacy.baselineStart).toBeUndefined();
+    expect(legacy.baselineEnd).toBeUndefined();
+  });
+
+  it("ctx 缺失：ctx 依赖键抛错（拒绝静默回落层级树）；priority/state/iteration 不需要 ctx", () => {
+    const stories = [makeStory({ id: "x" })];
+    for (const key of ["assignee", "labels", "createdBy", "project"] as const) {
+      expect(() => buildGanttResources(stories, key, {})).toThrow(/options\.ctx/);
+    }
+    expect(() => buildGanttResources(stories, "priority", {})).not.toThrow();
+    expect(() => buildGanttResources(stories, "state", {})).not.toThrow();
+    expect(() => buildGanttResources(stories, "iteration", {})).not.toThrow();
+  });
+
+  it("R-1：组节点 id 统一 ${groupKey}:${node.key}，storyStateResourceId 内部对齐同款", () => {
+    expect(storyStateResourceId("todo")).toBe("state:todo");
+    expect(ganttGroupResourceId("iteration", "it1")).toBe("iteration:it1");
+    // 组节点 id 与叶子行 id（story.id）空间不撞：组 id 恒带 `${groupKey}:` 前缀
+    const groups = buildGanttResources(
+      [makeStory({ id: "s1", priority: "high" })],
+      "priority",
+      { ctx: EMPTY_CTX },
+    );
+    expect(groups[0]!.id).toBe("priority:high");
+    expect(groups[0]!.children?.[0]!.id).toBe("s1");
+  });
+});