@allbluecn/web-app 0.4.22 → 0.5.0

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

@@ -39,6 +39,10 @@ const makeStory = (over: Partial<StoryListItem> & { id: string }): StoryListItem
   ...over,
 });
 
+const makeUser = (id: string): PagedStoriesArgs["users"][number] => ({
+  id, username: `user-${id}`, email: `${id}@test.dev`, avatarConfig: null, bgShape: null, bgColor: null,
+});
+
 const makeArgs = (over: Partial<PagedStoriesArgs> = {}): PagedStoriesArgs => ({
   filters: { projectId: undefined, search: undefined },
   conditions: [],
@@ -46,6 +50,7 @@ const makeArgs = (over: Partial<PagedStoriesArgs> = {}): PagedStoriesArgs => ({
   users: [],
   labels: [],
   projects: [],
+  minLoadingMs: 0,
   ...over,
 });
 
@@ -71,10 +76,40 @@ describe("usePagedStoryGroups", () => {
       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 }),
+      expect.objectContaining({ groupBy: "state", groupCount: 5, skip: 0, take: 100 }),
     );
   });
 
+  it("初始加载并行拉取：组 keys 与首屏 items 同时请求（1 个 RTT）", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 1 }, { key: "done", total: 1 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({
+      grouped: { todo: [makeStory({ id: "a", state: "todo" })], done: [makeStory({ id: "b", state: "done" })] },
+    });
+
+    const { result } = renderHook(() => usePagedStoryGroups(makeArgs()));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // 组 keys 请求与 items 请求都已发出（并行）
+    expect(h.listStoryGroupsFn).toHaveBeenCalledTimes(1);
+    expect(h.listAllGroupsItemsFn).toHaveBeenCalledTimes(1);
+    // items 直接按组 keys 组装，无需第二次请求
+    expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a"]);
+    expect(result.current.groups[1].items.map((s) => s.id)).toEqual(["b"]);
+  });
+
+  it("数据先于最短展示时间到达时，骨架保持到 minLoadingMs 后才切换", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 1 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a" })] } });
+
+    const { result } = renderHook(() => usePagedStoryGroups(makeArgs({ minLoadingMs: 200 })));
+    expect(result.current.isLoading).toBe(true);
+    // 数据已返回但骨架仍在最短展示窗口内（150ms < 200ms）
+    await new Promise((r) => setTimeout(r, 150));
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.isLoading).toBe(false), { timeout: 2000 });
+    expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a"]);
+  });
+
   it("loadMore 追加下一页并去重、更新 total/hasMore", async () => {
     h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 3 }] });
     h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: [makeStory({ id: "a" })] } });
@@ -270,4 +305,120 @@ describe("usePagedStoryGroups", () => {
       expect.objectContaining({ archived: true, projectId: undefined, search: "foo" }),
     );
   });
+
+  describe("patchStory 乐观原地更新", () => {
+    const setup = async (
+      display: Partial<typeof DEFAULT_DISPLAY_OPTIONS> = {},
+      opts: { items?: StoryListItem[]; users?: PagedStoriesArgs["users"] } = {},
+    ) => {
+      // items 顺序模拟服务端已排序的返回（客户端不重排首屏数据）
+      const items = opts.items ?? [
+        makeStory({ id: "a", priority: "low", createdAt: "2024-01-01" }),
+        makeStory({ id: "b", priority: "high", createdAt: "2024-01-02" }),
+      ];
+      h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: items.length }] });
+      h.listAllGroupsItemsFn.mockResolvedValue({ grouped: { todo: items } });
+      const { result } = renderHook(() =>
+        usePagedStoryGroups(
+          makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, ...display }, users: opts.users ?? [] }),
+        ),
+      );
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      return result;
+    };
+
+    it("未触发分组/排序规则：原位替换，位置与分组不变", async () => {
+      const result = await setup({}, { users: [makeUser("u9")] });
+      const callsBefore = h.listStoryGroupsFn.mock.calls.length;
+
+      act(() =>
+        result.current.patchStory("a", { assigneeId: "u9" }),
+      );
+
+      const todo = result.current.groups[0];
+      expect(todo.items.map((s) => s.id)).toEqual(["a", "b"]); // 位置不变
+      expect(todo.items[0].assignee?.id).toBe("u9"); // 值已乐观更新
+      expect(h.listStoryGroupsFn.mock.calls.length).toBe(callsBefore); // 未触发 refresh
+    });
+
+    it("仅触发排序规则：组内重插，分组不变", async () => {
+      // 服务端 priority desc 已排序：b(high) 在前，a(low) 在后
+      const result = await setup(
+        { orderBy: "priority", orderDir: "desc" },
+        {
+          items: [
+            makeStory({ id: "b", priority: "high" }),
+            makeStory({ id: "a", priority: "low" }),
+          ],
+        },
+      );
+      expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["b", "a"]);
+
+      act(() => result.current.patchStory("a", { priority: "urgent" }));
+
+      expect(result.current.groups[0].key).toBe("todo"); // 分组不变
+      expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a", "b"]);
+      expect(result.current.groups[0].items[0].priority).toBe("urgent");
+    });
+
+    it("触发分组规则：回退全量 refresh", async () => {
+      const result = await setup();
+
+      act(() => result.current.patchStory("a", { state: "done" }));
+
+      expect(h.listStoryGroupsFn.mock.calls.length).toBeGreaterThan(1); // refresh 触发重新加载
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+    });
+
+    it("排序=updated 时任意字段编辑触发组内重插（updatedAt 变最新）", async () => {
+      // 服务端 updatedAt desc 已排序：b(01-02) 在前，a(01-01) 在后
+      const result = await setup(
+        { orderBy: "updated", orderDir: "desc" },
+        {
+          items: [
+            makeStory({ id: "b", updatedAt: "2024-01-02" }),
+            makeStory({ id: "a", updatedAt: "2024-01-01" }),
+          ],
+        },
+      );
+      expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["b", "a"]);
+
+      act(() => result.current.patchStory("a", { assigneeId: null }));
+
+      expect(result.current.groups[0].items.map((s) => s.id)).toEqual(["a", "b"]); // a 的 updatedAt 变最新
+    });
+
+    it("labels 分组维度被编辑时回退 refresh", async () => {
+      const result = await setup({ groupBy: "labels" });
+      const callsBefore = h.listStoryGroupsFn.mock.calls.length;
+
+      act(() => result.current.patchStory("a", { labelIds: ["l1"] }));
+
+      expect(h.listStoryGroupsFn.mock.calls.length).toBeGreaterThan(callsBefore);
+    });
+
+    it("子分组内未触发规则：原位替换且父组计数不变", async () => {
+      h.listStoryGroupsFn
+        .mockResolvedValueOnce({ groups: [{ key: "todo", total: 2 }] })
+        .mockResolvedValueOnce({ groups: [{ key: "u9", total: 2 }] });
+      h.listStoriesInGroupFn.mockResolvedValue({
+        items: [makeStory({ id: "a" }), makeStory({ id: "b" })],
+        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));
+
+      act(() => result.current.patchStory("a", { priority: "low" }));
+
+      const parent = result.current.groups[0];
+      expect(parent.subGroups?.[0].items.map((s) => s.id)).toEqual(["a", "b"]); // 位置不变
+      expect(parent.subGroups?.[0].items[0].priority).toBe("low");
+      expect(parent.totalCount).toBe(2); // 父组计数不变
+    });
+  });
 });

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

@@ -24,6 +24,8 @@ import { serializeFilters } from "../filters";
 import { listStoriesInGroupFn, listStoryGroupsFn, listAllGroupsItemsFn } from "@/server/serverFns/story";
 import { resolveGroupLabel, resolveGroupIcon, resolveGroupColor } from "./group-resolver";
 import type { DisplayOptions, GroupContext, GroupKey, GroupNode } from "./types";
+import type { StoryPatch } from "./group-fields";
+import { PRIORITY_RANK, STORY_PRIORITIES, STORY_STATES } from "../constants";
 
 /** 服务端按组分页的组节点：在 GroupNode 上标记 total/hasMore/loading */
 export interface PagedGroupNode extends GroupNode {
@@ -43,6 +45,8 @@ export interface PagedStoriesArgs {
   projects: GroupContext["projects"];
   /** 仅 view === "list" 时启用分页预取，避免非 list 视图发起无谓请求 */
   enabled?: boolean;
+  /** 首屏骨架最短展示时长（ms），保证加载动画可见；测试可传 0 跳过 */
+  minLoadingMs?: number;
 }
 
 type PageState = {
@@ -72,11 +76,297 @@ function buildGroupParams(filters: StoryFilters, conditions: FilterCondition[]):
 
 const UNGROUPED_KEY = "all";
 
+/** 单层分组并行拉取时的组数估算（决定服务端批量拉取条数，宁大勿小保证每组首屏有数据） */
+const GROUP_COUNT_ESTIMATE: Partial<Record<GroupKey, number>> = {
+  state: STORY_STATES.length,
+  priority: STORY_PRIORITIES.length,
+};
+
+function estimateGroupCount(groupBy: GroupKey, users: UserBrief[]): number {
+  const known = GROUP_COUNT_ESTIMATE[groupBy];
+  if (known != null) return known;
+  // 负责人/创建人按项目成员数+未指派估算，项目等其他维度兜底 10
+  return Math.max(users.length + 1, 10);
+}
+
+/** 分组维度 → 触发重新分组的 patch 字段（null 表示该维度不受行内编辑影响） */
+const GROUP_TRIGGER_FIELD: Record<GroupKey, keyof StoryPatch | "labels" | null> = {
+  state: "state",
+  priority: "priority",
+  assignee: "assigneeId",
+  project: "projectId",
+  createdBy: null,
+  labels: "labels",
+  none: null,
+};
+
+/** 排序方式 → 触发组内重排的 patch 字段（"any" 表示任意更新都触发，如 updated） */
+const ORDER_TRIGGER_FIELD: Record<string, keyof StoryPatch | "any" | null> = {
+  manual: null,
+  created: null,
+  updated: "any",
+  startDate: "startDate",
+  dueDate: "targetDate",
+  priority: "priority",
+};
+
+type PatchContext = {
+  users: UserBrief[];
+  labels: { id: string; name: string; color: string }[];
+  groupBy: GroupKey;
+  subGroupBy: GroupKey;
+  orderBy: string;
+  orderDir: "asc" | "desc";
+};
+
+/** "refresh"：触发分组规则（或客户端无法精确挪组）；null：未找到行；数组：乐观更新后的 groups */
+type PatchResult = PagedGroupNode[] | "refresh" | null;
+
+function patchTouches(trigger: keyof StoryPatch | "labels" | "any" | null, patch: StoryPatch): boolean {
+  if (!trigger) return false;
+  if (trigger === "any") return true;
+  return patch[trigger as keyof StoryPatch] !== undefined;
+}
+
+/** 与服务端 deriveGroupKey 保持一致的客户端组 key 派生；labels 返回 null（无法精确归属） */
+function deriveStoryGroupKey(groupBy: GroupKey, s: StoryListItem): string | null {
+  switch (groupBy) {
+    case "state":
+      return s.state ?? null;
+    case "priority":
+      return s.priority ?? null;
+    case "assignee":
+      return s.assignee?.id ?? "unassigned";
+    case "createdBy":
+      return s.createdBy?.id ?? null;
+    case "project":
+      return s.projectId ?? "no-project";
+    default:
+      return null;
+  }
+}
+
+/** 把 StoryPatch 合并进 StoryListItem（id → 完整对象，供乐观显示），并刷新 updatedAt */
+function applyStoryPatch(story: StoryListItem, patch: StoryPatch, ctx: PatchContext): StoryListItem {
+  const next: StoryListItem = { ...story, updatedAt: new Date().toISOString() };
+  if (patch.state !== undefined) next.state = patch.state;
+  if (patch.priority !== undefined) next.priority = patch.priority;
+  if (patch.assigneeId !== undefined) {
+    next.assignee = patch.assigneeId
+      ? ctx.users.find((u) => u.id === patch.assigneeId) ?? story.assignee
+      : null;
+  }
+  if (patch.startDate !== undefined) next.startDate = patch.startDate;
+  if (patch.targetDate !== undefined) next.targetDate = patch.targetDate;
+  if (patch.labelIds !== undefined) {
+    next.labels = patch.labelIds
+      .map((id) => ctx.labels.find((l) => l.id === id))
+      .filter((l): l is { id: string; name: string; color: string } => l != null);
+  }
+  return next;
+}
+
+/** null = +∞（对齐 PostgreSQL：asc nulls last / desc nulls first） */
+function cmpNullable(x: string | null, y: string | null): number {
+  if (x === y) return 0;
+  if (x == null) return 1;
+  if (y == null) return -1;
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+
+/** 与服务端 [主键, id asc] tiebreaker 全序一致的组内比较 */
+function compareByOrder(a: StoryListItem, b: StoryListItem, orderBy: string, dir: "asc" | "desc"): number {
+  let c = 0;
+  switch (orderBy) {
+    case "priority":
+      c = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+      break;
+    case "startDate":
+      c = cmpNullable(a.startDate, b.startDate);
+      break;
+    case "dueDate":
+      c = cmpNullable(a.targetDate, b.targetDate);
+      break;
+    case "created":
+      c = cmpNullable(a.createdAt, b.createdAt);
+      break;
+    case "updated":
+      c = cmpNullable(a.updatedAt, b.updatedAt);
+      break;
+    case "manual":
+      c = a.boardOrder - b.boardOrder;
+      break;
+  }
+  if (c !== 0) return dir === "asc" ? c : -c;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+/** 在已加载 items 内找 moved 的插入位置（未加载页边界为近似，refresh 后校正） */
+function findInsertIndex(items: StoryListItem[], moved: StoryListItem, orderBy: string, dir: "asc" | "desc"): number {
+  for (let i = 0; i < items.length; i++) {
+    if (compareByOrder(items[i], moved, orderBy, dir) > 0) return i;
+  }
+  return items.length;
+}
+
+function reinsert(items: StoryListItem[], storyId: string, nextStory: StoryListItem, orderBy: string, dir: "asc" | "desc"): StoryListItem[] {
+  const rest = items.filter((s) => s.id !== storyId);
+  rest.splice(findInsertIndex(rest, nextStory, orderBy, dir), 0, nextStory);
+  return rest;
+}
+
+/** total 字段首屏可能为 undefined（组级 total），只在有值时维护 */
+function bumpTotal(node: PagedGroupNode, delta: number): PagedGroupNode {
+  return { ...node, total: node.total != null ? node.total + delta : node.total };
+}
+
+function recountParentTotalCount(group: PagedGroupNode): PagedGroupNode {
+  if (!group.subGroups?.length) return group;
+  return {
+    ...group,
+    totalCount: group.subGroups.reduce((sum, sg) => sum + (sg.total ?? sg.items.length), 0),
+  };
+}
+
+/**
+ * 行内编辑乐观更新：
+ * - 未触发分组/排序规则 → 原位替换（位置不变）
+ * - 仅触发排序规则 → 在（子）分组内移除重插，不动分组
+ * - 触发分组规则（或 labels 等无法精确挪组的场景）→ 返回 "refresh" 交给全量重拉
+ */
+function applyPatchToGroups(groups: PagedGroupNode[], storyId: string, patch: StoryPatch, ctx: PatchContext): PatchResult {
+  // 定位行：先子组模式，再顶层直挂模式
+  for (let gi = 0; gi < groups.length; gi++) {
+    const g = groups[gi];
+    const subGroups = g.subGroups ?? [];
+    for (let si = 0; si < subGroups.length; si++) {
+      const idx = subGroups[si].items.findIndex((s) => s.id === storyId);
+      if (idx < 0) continue;
+      const nextStory = applyStoryPatch(subGroups[si].items[idx], patch, ctx);
+      return patchInParentWithSubGroups(groups, gi, si, nextStory, patch, ctx);
+    }
+    const idx = g.items.findIndex((s) => s.id === storyId);
+    if (idx >= 0) {
+      const nextStory = applyStoryPatch(g.items[idx], patch, ctx);
+      return patchInFlatGroups(groups, gi, nextStory, patch, ctx);
+    }
+  }
+  return null;
+}
+
+/** 行在父组 g 的子组 si 内：父组（顶层维度）不变，仅可能在兄弟子组间挪动 */
+function patchInParentWithSubGroups(
+  groups: PagedGroupNode[],
+  gi: number,
+  si: number,
+  nextStory: StoryListItem,
+  patch: StoryPatch,
+  ctx: PatchContext,
+): PatchResult {
+  const g = groups[gi];
+  const subGroups = g.subGroups ?? [];
+  const source = subGroups[si];
+
+  const subTrigger = GROUP_TRIGGER_FIELD[ctx.subGroupBy];
+  const topTrigger = GROUP_TRIGGER_FIELD[ctx.groupBy];
+  // 顶层分组维度被编辑（或 labels）→ 跨父组挪动，交给 refresh
+  if (patchTouches(topTrigger, patch) || subTrigger === "labels") return "refresh";
+
+  let targetSub = source;
+  let moved = false;
+  if (patchTouches(subTrigger, patch)) {
+    const nextKey = deriveStoryGroupKey(ctx.subGroupBy, nextStory);
+    if (nextKey == null) return "refresh";
+    if (nextKey !== source.key) {
+      const ti = subGroups.findIndex((sg) => sg.key === nextKey);
+      if (ti < 0) return "refresh"; // 目标组未显示（showEmptyGroups=false 且为空）
+      targetSub = subGroups[ti];
+      moved = true;
+    }
+  }
+
+  const orderTrigger = patchTouches(ORDER_TRIGGER_FIELD[ctx.orderBy] ?? null, patch);
+  if (!moved && !orderTrigger) {
+    // 原位替换
+    return replaceInSubGroups(groups, gi, si, (items) => items.map((s) => (s.id === nextStory.id ? nextStory : s)));
+  }
+  const nextItems = moved && !orderTrigger
+    ? targetSub.items.concat(nextStory)
+    : reinsert(targetSub.items, nextStory.id, nextStory, ctx.orderBy, ctx.orderDir);
+  const updatedTarget = bumpTotal({ ...targetSub, items: nextItems }, moved ? 1 : 0);
+  const updatedSource = moved ? bumpTotal(source, -1) : null;
+  return replaceSubNodes(groups, gi, source.key, targetSub.key, updatedSource, updatedTarget);
+}
+
+/** 行直接挂在顶层组 items（无子组模式） */
+function patchInFlatGroups(
+  groups: PagedGroupNode[],
+  gi: number,
+  nextStory: StoryListItem,
+  patch: StoryPatch,
+  ctx: PatchContext,
+): PatchResult {
+  const trigger = GROUP_TRIGGER_FIELD[ctx.groupBy];
+  const groupTriggered = patchTouches(trigger, patch);
+  if (!groupTriggered) {
+    // 未触发分组规则：原位替换或组内重插
+    const orderTrigger = patchTouches(ORDER_TRIGGER_FIELD[ctx.orderBy] ?? null, patch);
+    if (!orderTrigger) {
+      return groups.map((g, i) =>
+        i === gi ? { ...g, items: g.items.map((s) => (s.id === nextStory.id ? nextStory : s)) } : g,
+      );
+    }
+    return groups.map((g, i) =>
+      i === gi ? { ...g, items: reinsert(g.items, nextStory.id, nextStory, ctx.orderBy, ctx.orderDir) } : g,
+    );
+  }
+  // 分组维度被编辑（含 labels）→ 交给 refresh
+  return "refresh";
+}
+
+function replaceInSubGroups(
+  groups: PagedGroupNode[],
+  gi: number,
+  si: number,
+  mapItems: (items: StoryListItem[]) => StoryListItem[],
+): PagedGroupNode[] {
+  return groups.map((g, i) => {
+    if (i !== gi) return g;
+    return recountParentTotalCount({
+      ...g,
+      subGroups: (g.subGroups ?? []).map((sg, j) => (j === si ? { ...sg, items: mapItems(sg.items) } : sg)),
+    });
+  });
+}
+
+function replaceSubNodes(
+  groups: PagedGroupNode[],
+  gi: number,
+  sourceKey: string,
+  targetKey: string,
+  updatedSource: PagedGroupNode | null,
+  updatedTarget: PagedGroupNode,
+): PagedGroupNode[] {
+  return groups.map((g, i) => {
+    if (i !== gi) return g;
+    return recountParentTotalCount({
+      ...g,
+      subGroups: (g.subGroups ?? []).map((sg) => {
+        if (sg.key === sourceKey && updatedSource) return updatedSource;
+        if (sg.key === targetKey) return updatedTarget;
+        return sg;
+      }),
+    });
+  });
+}
+
 export function usePagedStoryGroups(args: PagedStoriesArgs): {
   groups: PagedGroupNode[];
   isLoading: boolean;
   loadMore: (groupKey: string, subGroupKey?: string) => void;
   refresh: () => void;
+  /** 行内编辑乐观更新：未触发分组/排序规则时保持位置原地替换，仅触发排序时组内重插，触发分组时回退全量 refresh */
+  patchStory: (storyId: string, patch: StoryPatch) => void;
 } {
   const { filters, conditions, display, users, labels, projects, enabled = true } = args;
   const { t } = useTranslation("story");
@@ -129,21 +419,52 @@ export function usePagedStoryGroups(args: PagedStoriesArgs): {
   useEffect(() => {
     if (!enabled) return;
     let alive = true;
+    const startedAt = performance.now();
     setState((s) => ({ ...s, isLoading: true }));
 
     const ctx: GroupContext = { users, labels, projects };
     const base = buildGroupParams(filters, conditions);
+    // 单层分组（state/priority/assignee/createdBy/project）：组 keys 与首屏 items 并行拉取，1 个 RTT 完成首屏
+    const isSingleLayer = subGroupBy === "none" && groupBy !== "none" && groupBy !== "labels";
+    // 骨架最短展示：本地数据太快到达时保证加载动画至少完整起跳可见，消除「刚播一帧就消失」的闪烁
+    const minLoadingMs = args.minLoadingMs ?? 800;
+
+    const settleWithMinDelay = (settle: () => void) => {
+      const remaining = minLoadingMs - (performance.now() - startedAt);
+      if (remaining <= 0) {
+        settle();
+        return;
+      }
+      const timer = setTimeout(() => {
+        if (alive) settle();
+      }, remaining);
+      // alive 由外层 cleanup 置 false，超时触发时不会再 setState
+      void timer;
+    };
 
     (async () => {
       try {
-        const groupInfos =
+        const [groupInfosResult, preloadedItems] = await Promise.all([
           groupBy === "none"
-            ? [{ key: UNGROUPED_KEY, total: 0 }]
-            : (
-                await listStoryGroupsFn({
-                  data: { ...base, groupBy, showEmptyGroups: display.showEmptyGroups },
-                })
-              ).groups;
+            ? Promise.resolve({ groups: [{ key: UNGROUPED_KEY, total: 0 }] })
+            : listStoryGroupsFn({
+                data: { ...base, groupBy, showEmptyGroups: display.showEmptyGroups },
+              }),
+          isSingleLayer
+            ? listAllGroupsItemsFn({
+                data: {
+                  ...base,
+                  groupBy,
+                  orderBy: display.orderBy,
+                  orderDir: display.orderDir,
+                  skip: 0,
+                  take: pageSize,
+                  groupCount: estimateGroupCount(groupBy, users),
+                },
+              })
+            : Promise.resolve(null),
+        ]);
+        const groupInfos = groupInfosResult.groups;
 
         const scaffolds: PagedGroupNode[] = groupInfos.map((g) => ({
           key: g.key,
@@ -155,7 +476,13 @@ export function usePagedStoryGroups(args: PagedStoriesArgs): {
           total: g.total,
         }));
 
-        if (subGroupBy !== "none") {
+        if (isSingleLayer && preloadedItems) {
+          const itemsByGroup = preloadedItems.grouped as Record<string, StoryListItem[]>;
+          scaffolds.forEach((s) => {
+            s.items = itemsByGroup[s.key] ?? [];
+            s.hasMore = s.total != null ? s.items.length < s.total : s.items.length >= pageSize;
+          });
+        } else if (subGroupBy !== "none") {
           // 子组模式：按顶层组枚举子组 keys，并并发加载各子组首屏；父组不直接装 item
           await Promise.all(
             scaffolds.map(async (g) => {
@@ -203,24 +530,8 @@ export function usePagedStoryGroups(args: PagedStoriesArgs): {
               g.totalCount = subScaffolds.reduce((sum, sg) => sum + (sg.total ?? sg.items.length), 0);
             }),
           );
-        } else if (groupBy !== "none" && groupBy !== "labels") {
-          const itemsData = await listAllGroupsItemsFn({
-            data: {
-              ...base,
-              groupBy,
-              orderBy: display.orderBy,
-              orderDir: display.orderDir,
-              skip: 0,
-              take: pageSize,
-              groupCount: groupInfos.length,
-            },
-          }).catch(() => ({ grouped: {} as Record<string, StoryListItem[]> }));
-          const itemsByGroup = itemsData.grouped as Record<string, StoryListItem[]>;
-          scaffolds.forEach((s) => {
-            s.items = itemsByGroup[s.key] ?? [];
-            s.hasMore = s.total != null ? s.items.length < s.total : s.items.length >= pageSize;
-          });
         } else {
+          // 无分组 / labels 分组：每组单独拉首屏
           const loaded = await Promise.all(
             scaffolds.map((g) =>
               listStoriesInGroupFn({
@@ -235,9 +546,13 @@ export function usePagedStoryGroups(args: PagedStoriesArgs): {
           });
         }
 
-        if (alive) setState({ sig, groups: scaffolds, isLoading: false });
+        settleWithMinDelay(() => {
+          if (alive) setState({ sig, groups: scaffolds, isLoading: false });
+        });
       } catch {
-        if (alive) setState((s) => ({ ...s, isLoading: false }));
+        settleWithMinDelay(() => {
+          if (alive) setState((s) => ({ ...s, isLoading: false }));
+        });
       }
     })();
 
@@ -358,5 +673,32 @@ export function usePagedStoryGroups(args: PagedStoriesArgs): {
 
   const refresh = useCallback(() => setRefreshTick((t) => t + 1), []);
 
-  return { groups: state.groups, isLoading: state.isLoading, loadMore, refresh };
+  const patchStory = useCallback(
+    (storyId: string, patch: StoryPatch) => {
+      const req = requestRef.current;
+      const snapshot = stateRef.current;
+      if (snapshot.sig !== req.sig) {
+        refresh();
+        return;
+      }
+      const result = applyPatchToGroups(snapshot.groups, storyId, patch, {
+        users: args.users,
+        labels: args.labels,
+        groupBy: req.groupBy,
+        subGroupBy: req.subGroupBy,
+        orderBy: req.orderBy,
+        orderDir: req.orderDir,
+      });
+      if (result === "refresh") {
+        refresh();
+        return;
+      }
+      if (result == null) return;
+      setState((prev) => (prev.sig !== snapshot.sig ? prev : { ...prev, groups: result }));
+    },
+    // users/labels 经 args 读取以避免闭包过期；refresh 引用稳定
+    [args.users, args.labels, refresh],
+  );
+
+  return { groups: state.groups, isLoading: state.isLoading, loadMore, refresh, patchStory };
 }