@allbluecn/web-app 0.3.0

package/src/components/story/display/__tests__/use-grouped-stories.test.ts

@@ -0,0 +1,72 @@
+// 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 { renderHook } from "@testing-library/react";
+import { useGroupedStories } from "../use-grouped-stories";
+import type { StoryListItem } from "../../types";
+import { DEFAULT_DISPLAY_OPTIONS } from "../types";
+
+const makeStory = (over: Partial<StoryListItem> & { id: string }): StoryListItem => ({
+  identifier: "STR-1", name: "t", description: null, state: "todo", priority: "medium", archived: false,
+  startDate: null, targetDate: null, boardOrder: 0, projectId: null, parentId: null, parent: null,
+  assignee: null, createdBy: { id: "u1", username: "u", email: "e", avatarConfig: null, bgShape: null, bgColor: null },
+  labels: [], createdAt: "2024-01-01", updatedAt: "2024-01-01",
+  ...over,
+});
+
+describe("useGroupedStories", () => {
+  it("默认按 state 分组", () => {
+    const { result } = renderHook(() => useGroupedStories({
+      stories: [makeStory({ id: "a", state: "todo" }), makeStory({ id: "b", state: "done" })],
+      filters: DEFAULT_DISPLAY_OPTIONS,
+      users: [], labels: [], projects: [],
+    }));
+    expect(result.current.find(g => g.key === "todo")?.items.length).toBe(1);
+  });
+
+  it("subGroupBy 嵌套二级分组", () => {
+    const { result } = renderHook(() => useGroupedStories({
+      stories: [
+        makeStory({ id: "a", state: "todo", priority: "urgent" }),
+        makeStory({ id: "b", state: "todo", priority: "low" }),
+      ],
+      filters: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "state", subGroupBy: "priority" },
+      users: [], labels: [], projects: [],
+    }));
+    const todoGroup = result.current.find(g => g.key === "todo");
+    expect(todoGroup?.subGroups?.length).toBe(2);
+  });
+
+  it("showEmptyGroups=false 过滤空组", () => {
+    const { result } = renderHook(() => useGroupedStories({
+      stories: [makeStory({ id: "a", state: "todo" })],
+      filters: { ...DEFAULT_DISPLAY_OPTIONS, showEmptyGroups: false },
+      users: [], labels: [], projects: [],
+    }));
+    expect(result.current.find(g => g.key === "done")).toBeUndefined();
+  });
+
+  it("showEmptyGroups=true 保留空组", () => {
+    const { result } = renderHook(() => useGroupedStories({
+      stories: [makeStory({ id: "a", state: "todo" })],
+      filters: { ...DEFAULT_DISPLAY_OPTIONS, showEmptyGroups: true },
+      users: [], labels: [], projects: [],
+    }));
+    expect(result.current.find(g => g.key === "done")).toBeDefined();
+  });
+});

package/src/components/story/display/__tests__/use-paged-story-groups.test.ts

@@ -0,0 +1,273 @@
+// 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, vi, beforeEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import type { StoryListItem } from "../../types";
+import { DEFAULT_DISPLAY_OPTIONS } from "../types";
+import type { PagedStoriesArgs } from "../use-paged-story-groups";
+
+const h = vi.hoisted(() => ({
+  listStoriesInGroupFn: vi.fn(),
+  listStoryGroupsFn: vi.fn(),
+  listAllGroupsItemsFn: vi.fn(),
+}));
+
+vi.mock("@/server/serverFns/story", () => h);
+
+import { usePagedStoryGroups } from "../use-paged-story-groups";
+
+const makeStory = (over: Partial<StoryListItem> & { id: string }): StoryListItem => ({
+  identifier: "STR-1", name: "t", description: null, state: "todo", priority: "medium", archived: false,
+  startDate: null, targetDate: null, boardOrder: 0, projectId: null, parentId: null, parent: null,
+  assignee: null, createdBy: { id: "u1", username: "u", email: "e", avatarConfig: null, bgShape: null, bgColor: null },
+  labels: [], createdAt: "2024-01-01", updatedAt: "2024-01-01",
+  ...over,
+});
+
+const makeArgs = (over: Partial<PagedStoriesArgs> = {}): PagedStoriesArgs => ({
+  filters: { projectId: undefined, search: undefined },
+  conditions: [],
+  display: { ...DEFAULT_DISPLAY_OPTIONS },
+  users: [],
+  labels: [],
+  projects: [],
+  ...over,
+});
+
+describe("usePagedStoryGroups", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it("初始加载：拉取组 keys 并对每组并发取首屏", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 1 }, { key: "done", total: 0 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a", state: "todo" })] } });
+
+    const { result } = renderHook(() => usePagedStoryGroups(makeArgs()));
+    expect(result.current.isLoading).toBe(true);
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.groups.map((g) => g.key)).toEqual(["todo", "done"]);
+    expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a"]);
+    expect(result.current.groups[0].total).toBe(1);
+    expect(result.current.groups[0].hasMore).toBe(false);
+
+    expect(h.listStoryGroupsFn).toHaveBeenCalledWith({
+      data: expect.objectContaining({ archived: false, groupBy: "state" }),
+    });
+    expect(h.listAllGroupsItemsFn.mock.calls[0][0].data).toEqual(
+      expect.objectContaining({ groupBy: "state", groupCount: 2, skip: 0, take: 100 }),
+    );
+  });
+
+  it("loadMore 追加下一页并去重、更新 total/hasMore", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 3 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a" })] } });
+    h.listStoriesInGroupFn
+      .mockResolvedValueOnce({ items: [makeStory({ id: "b", state: "todo" }), makeStory({ id: "c", state: "todo" })], total: 3, hasMore: false });
+
+    const { result } = renderHook(() => usePagedStoryGroups(makeArgs()));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a"]);
+    expect(result.current.groups[0].hasMore).toBe(true);
+
+    await act(async () => {
+      result.current.loadMore("todo");
+    });
+    await waitFor(() => expect(result.current.groups[0].hasMore).toBe(false));
+
+    expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a", "b", "c"]);
+    expect(result.current.groups[0].total).toBe(3);
+    expect(h.listStoriesInGroupFn.mock.calls[0][0].data.skip).toBe(1);
+  });
+
+  it("hasMore=false 时 loadMore 不再发起请求", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 1 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a" })] } });
+
+    const { result } = renderHook(() => usePagedStoryGroups(makeArgs()));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const callsBefore = h.listStoriesInGroupFn.mock.calls.length;
+    act(() => {
+      result.current.loadMore("todo");
+    });
+    await waitFor(() => undefined);
+    expect(h.listStoriesInGroupFn.mock.calls.length).toBe(callsBefore);
+  });
+
+  it("subGroupBy 非 none 时按顶层组枚举子组并并发加载子组首屏，父组不装 item", async () => {
+    h.listStoryGroupsFn
+      .mockResolvedValueOnce({ groups: [{ key: "todo", total: 1 }, { key: "doing", total: 1 }] })
+      .mockResolvedValueOnce({ groups: [{ key: "unassigned", total: 1 }, { key: "u9", total: 0 }] })
+      .mockResolvedValueOnce({ groups: [{ key: "unassigned", total: 1 }] });
+    h.listStoriesInGroupFn
+      .mockResolvedValueOnce({ items: [makeStory({ id: "a" })], total: 1, hasMore: false })
+      .mockResolvedValueOnce({ items: [], total: 0, hasMore: false })
+      .mockResolvedValueOnce({ items: [makeStory({ id: "b" })], total: 1, hasMore: false });
+
+    const { result } = renderHook(() =>
+      usePagedStoryGroups(
+        makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "state", subGroupBy: "assignee" } }),
+      ),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(h.listStoryGroupsFn).toHaveBeenCalledTimes(3);
+    expect(h.listStoryGroupsFn.mock.calls[1][0].data).toEqual(
+      expect.objectContaining({ groupBy: "assignee", parentGroupBy: "state", parentGroupKey: "todo" }),
+    );
+    expect(h.listStoryGroupsFn.mock.calls[2][0].data).toEqual(
+      expect.objectContaining({ parentGroupBy: "state", parentGroupKey: "doing" }),
+    );
+
+    const todo = result.current.groups.find((g) => g.key === "todo")!;
+    expect(todo.items).toEqual([]);
+    expect(todo.subGroups?.map((sg) => sg.key)).toEqual(["unassigned", "u9"]);
+    expect(todo.subGroups?.[0].items.map((s) => s.id)).toEqual(["a"]);
+    expect(todo.subGroups?.[0].total).toBe(1);
+    const doing = result.current.groups.find((g) => g.key === "doing")!;
+    expect(doing.subGroups?.map((sg) => sg.key)).toEqual(["unassigned"]);
+    expect(doing.subGroups?.[0].items.map((s) => s.id)).toEqual(["b"]);
+
+    const subCall = h.listStoriesInGroupFn.mock.calls[0][0].data;
+    expect(subCall).toEqual(
+      expect.objectContaining({ groupBy: "state", groupKey: "todo", subGroupBy: "assignee", subGroupKey: "unassigned", skip: 0, take: 100 }),
+    );
+  });
+
+  it("loadMore 子组时携带 subGroupKey 并从子组已加载条数继续分页", async () => {
+    h.listStoryGroupsFn
+      .mockResolvedValueOnce({ groups: [{ key: "todo", total: 2 }] })
+      .mockResolvedValueOnce({ groups: [{ key: "unassigned", total: 2 }] });
+    h.listStoriesInGroupFn
+      .mockResolvedValueOnce({ items: [makeStory({ id: "a" })], total: 2, hasMore: true })
+      .mockResolvedValueOnce({ items: [makeStory({ id: "c" })], total: 2, hasMore: false });
+
+    const { result } = renderHook(() =>
+      usePagedStoryGroups(
+        makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "state", subGroupBy: "assignee" } }),
+      ),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const todo = result.current.groups[0];
+    expect(todo.subGroups?.[0].hasMore).toBe(true);
+
+    await act(async () => {
+      result.current.loadMore("todo", "unassigned");
+    });
+    await waitFor(() => expect(result.current.groups[0].subGroups?.[0].hasMore).toBe(false));
+
+    expect(h.listStoriesInGroupFn.mock.calls[1][0].data).toEqual(
+      expect.objectContaining({ groupBy: "state", groupKey: "todo", subGroupBy: "assignee", subGroupKey: "unassigned", skip: 1 }),
+    );
+    expect(result.current.groups[0].subGroups?.[0].items.map((s) => s.id)).toEqual(["a", "c"]);
+  });
+
+  it("无子组时 loadMore 不传 subGroupBy/subGroupKey（保持向后兼容）", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 3 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a" })] } });
+    h.listStoriesInGroupFn
+      .mockResolvedValueOnce({ items: [makeStory({ id: "b" }), makeStory({ id: "c" })], total: 3, hasMore: false });
+
+    const { result } = renderHook(() => usePagedStoryGroups(makeArgs()));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    // 手动修改 hasMore 以触发 loadMore
+    result.current.groups[0].hasMore = true;
+
+    await act(async () => {
+      result.current.loadMore("todo");
+    });
+    await waitFor(() => undefined);
+
+    const call = h.listStoriesInGroupFn.mock.calls[0][0].data;
+    expect(call.subGroupBy).toBe("none");
+    expect(call.subGroupKey).toBe("");
+  });
+
+  it("组 key（signature）变化时重置并重新加载", async () => {
+    h.listStoryGroupsFn
+      .mockResolvedValueOnce({ groups: [{ key: "todo", total: 1 }] })
+      .mockResolvedValueOnce({ groups: [{ key: "urgent", total: 1 }] });
+    h.listAllGroupsItemsFn
+      .mockResolvedValueOnce({ grouped: { todo: [makeStory({ id: "a" })] } })
+      .mockResolvedValueOnce({ grouped: { urgent: [makeStory({ id: "b" })] } });
+
+    const { result, rerender } = renderHook(
+      (args: PagedStoriesArgs) => usePagedStoryGroups(args),
+      { initialProps: makeArgs() },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(h.listStoryGroupsFn.mock.calls[0][0].data.groupBy).toBe("state");
+
+    rerender(makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "priority" } }));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.groups.map((g) => g.key)).toEqual(["urgent"]);
+    const calls = h.listStoryGroupsFn.mock.calls;
+    expect(calls[calls.length - 1][0].data.groupBy).toBe("priority");
+  });
+
+  it("groupBy=none 时构造「全部」组并加载（不调组列表）", async () => {
+    h.listStoriesInGroupFn.mockResolvedValue({ items: [makeStory({ id: "a" })], total: 1, hasMore: false });
+
+    const { result } = renderHook(() =>
+      usePagedStoryGroups(makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "none" } })),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(h.listStoryGroupsFn).not.toHaveBeenCalled();
+    expect(h.listAllGroupsItemsFn).not.toHaveBeenCalled();
+    expect(result.current.groups).toHaveLength(1);
+    expect(result.current.groups[0].key).toBe("all");
+    expect(result.current.groups[0].label).toBe("全部");
+    expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a"]);
+  });
+
+  it("空枚举组保留为空 items 且字段已补齐", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 1 }, { key: "done", total: 0 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a" })] } });
+
+    const { result } = renderHook(() =>
+      usePagedStoryGroups(makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, showEmptyGroups: true } })),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const done = result.current.groups.find((g) => g.key === "done");
+    expect(done).toBeDefined();
+    expect(done?.items).toEqual([]);
+    expect(done?.total).toBe(0);
+    expect(done?.hasMore).toBe(false);
+    expect(done?.label).toBe("已完成");
+  });
+
+  it("filters 归档态映射到 archived 参数", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 0 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: {} });
+
+    const { result } = renderHook(() =>
+      usePagedStoryGroups(makeArgs({ filters: { projectId: "__archived__", search: "foo" } })),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(h.listStoryGroupsFn.mock.calls[0][0].data).toEqual(
+      expect.objectContaining({ archived: true, projectId: undefined, search: "foo" }),
+    );
+  });
+});

package/src/components/story/display/constants.ts

@@ -0,0 +1,106 @@
+// 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 { CircleDotDashed, ArrowUpDown, User, Tag, UserPlus, Trees, X, CircleFadingArrowUp, ArrowDownUp, Plus, RefreshCw, CalendarPlus2, CalendarCheck, Hash, GitBranch, Paperclip, LayoutList, FolderKanban, type LucideIcon } from "lucide-react";
+import type { StoryView } from "../views/view-switcher";
+import type { GroupKey, OrderKey, DisplayProperty } from "./types";
+import { ALL_DISPLAY_PROPERTIES } from "./types";
+
+export const GROUP_LABELS: Record<GroupKey, string> = {
+  state: "group.state",
+  priority: "group.priority",
+  assignee: "group.assignee",
+  labels: "group.labels",
+  createdBy: "group.createdBy",
+  project: "group.project",
+  none: "group.none",
+};
+
+export const ORDER_LABELS: Record<OrderKey, string> = {
+  manual: "order.manual",
+  created: "order.created",
+  updated: "order.updated",
+  startDate: "order.startDate",
+  dueDate: "order.dueDate",
+  priority: "order.priority",
+};
+
+export const PROPERTY_LABELS: Record<DisplayProperty, string> = {
+  id: "property.id",
+  project: "property.project",
+  assignee: "property.assignee",
+  startDate: "property.startDate",
+  dueDate: "property.dueDate",
+  labels: "property.labels",
+  priority: "property.priority",
+  state: "property.state",
+  subCount: "property.subCount",
+  attachmentCount: "property.attachmentCount",
+};
+
+export const GROUP_ICONS: Record<GroupKey, LucideIcon> = {
+  state: CircleDotDashed,
+  priority: CircleFadingArrowUp,
+  assignee: User,
+  labels: Tag,
+  createdBy: UserPlus,
+  project: Trees,
+  none: X,
+};
+
+export const ORDER_ICONS: Record<OrderKey, LucideIcon> = {
+  manual: ArrowDownUp,
+  created: Plus,
+  updated: RefreshCw,
+  startDate: CalendarPlus2,
+  dueDate: CalendarCheck,
+  priority: ArrowUpDown,
+};
+
+export const PROPERTY_ICONS: Record<DisplayProperty, LucideIcon> = {
+  id: Hash,
+  project: FolderKanban,
+  assignee: User,
+  startDate: CalendarPlus2,
+  dueDate: CalendarCheck,
+  labels: Tag,
+  priority: ArrowUpDown,
+  state: LayoutList,
+  subCount: GitBranch,
+  attachmentCount: Paperclip,
+};
+
+export type LayoutSupport = Record<
+  StoryView,
+  { groupBy: boolean; subGroupBy: boolean; orderBy: boolean; properties: boolean; options: boolean }
+>;
+
+export const LAYOUT_SUPPORT: LayoutSupport = {
+  list:     { groupBy: true,  subGroupBy: true,  orderBy: true,  properties: true,  options: true  },
+  board:    { groupBy: true,  subGroupBy: true,  orderBy: true,  properties: true,  options: true  },
+  table:    { groupBy: false, subGroupBy: false, orderBy: true,  properties: true,  options: true  },
+  calendar: { groupBy: false, subGroupBy: false, orderBy: true,  properties: false, options: false },
+  timeline: { groupBy: false, subGroupBy: false, orderBy: true,  properties: false, options: true  },
+};
+
+export const LAYOUT_PROPERTIES: Record<StoryView, DisplayProperty[]> = {
+  list:     ["id", "assignee", "startDate", "dueDate", "labels", "priority", "state"],
+  board:    ["id", "assignee", "startDate", "dueDate", "labels", "priority", "state"],
+  table:    [...ALL_DISPLAY_PROPERTIES],
+  calendar: [],
+  timeline: [],
+};