@allbluecn/web-app 0.17.2 → 0.18.0

package/src/server/serverFns/bug/bug-display-options.ts

@@ -0,0 +1,161 @@
+// 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/>.
+
+// BUG 显示选项 per-user 持久化（照 story-display-options.ts 模式）。存储落点：
+// schema 无 User.bugDisplayOptions 字段且本期禁止迁移，借用 BugFilterView 的
+// per-user 保留行（name = BUG_DISPLAY_OPTIONS_VIEW_NAME，filters 存空数组），
+// 该行对 bug-views.ts 的保存视图 CRUD 不可见。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import { z } from "zod";
+import { requireAuth } from "@/server/auth-helpers";
+import { requireFeature } from "@/server/entitlements";
+import { isProEdition } from "@/server/pro-services";
+import {
+  BUG_DISPLAY_OPTIONS_VIEW_NAME,
+  BUG_GROUP_KEYS,
+  BUG_ORDER_KEYS,
+  BUG_ORDER_DIRECTIONS,
+  BUG_DISPLAY_PROPERTIES,
+  BUG_PAGE_SIZE_OPTIONS,
+  DEFAULT_BUG_DISPLAY_OPTIONS,
+  type BugDisplayOptions,
+  type BugDisplayProperty,
+  type BugGroupKey,
+  type BugOrderKey,
+  type BugOrderDirection,
+  type BugPageSize,
+} from "@/components/bug/display/types";
+import type { Prisma } from "@allbluecn/database";
+
+function toJson<T>(value: T): Prisma.InputJsonValue {
+  return value as unknown as Prisma.InputJsonValue;
+}
+
+/** 解析存储的 JSON 偏好，非法/缺失字段逐项回退默认值（照 story parseStoredOptions） */
+function parseStoredOptions(raw: unknown): BugDisplayOptions {
+  if (typeof raw !== "object" || raw === null) return { ...DEFAULT_BUG_DISPLAY_OPTIONS };
+  const o = raw as Record<string, unknown>;
+
+  const groupBy =
+    typeof o.groupBy === "string" && (BUG_GROUP_KEYS as readonly string[]).includes(o.groupBy)
+      ? (o.groupBy as BugGroupKey)
+      : DEFAULT_BUG_DISPLAY_OPTIONS.groupBy;
+  const orderBy =
+    typeof o.orderBy === "string" && (BUG_ORDER_KEYS as readonly string[]).includes(o.orderBy)
+      ? (o.orderBy as BugOrderKey)
+      : DEFAULT_BUG_DISPLAY_OPTIONS.orderBy;
+  const orderDir =
+    typeof o.orderDir === "string" && (BUG_ORDER_DIRECTIONS as readonly string[]).includes(o.orderDir)
+      ? (o.orderDir as BugOrderDirection)
+      : DEFAULT_BUG_DISPLAY_OPTIONS.orderDir;
+  const properties = Array.isArray(o.properties)
+    ? (o.properties as unknown[]).filter(
+        (p): p is BugDisplayProperty =>
+          typeof p === "string" && (BUG_DISPLAY_PROPERTIES as readonly string[]).includes(p),
+      )
+    : [];
+  const pageSize =
+    typeof o.pageSize === "number" && (BUG_PAGE_SIZE_OPTIONS as readonly number[]).includes(o.pageSize)
+      ? (o.pageSize as BugPageSize)
+      : DEFAULT_BUG_DISPLAY_OPTIONS.pageSize;
+
+  return {
+    groupBy,
+    orderBy,
+    orderDir,
+    properties: properties.length > 0 ? properties : [...DEFAULT_BUG_DISPLAY_OPTIONS.properties],
+    pageSize,
+  };
+}
+
+const optionsSchema = z.object({
+  groupBy: z.enum(BUG_GROUP_KEYS),
+  orderBy: z.enum(BUG_ORDER_KEYS),
+  orderDir: z.enum(BUG_ORDER_DIRECTIONS),
+  properties: z.array(z.enum(BUG_DISPLAY_PROPERTIES)),
+  pageSize: z.union([z.literal(100), z.literal(200), z.literal(500), z.literal(1000)]),
+});
+
+/** 订阅过期/降级兜底：已持久化的 500/1000 无权限时降级为 200（照 story 同一业务规则） */
+async function capPageSize(request: Request, pageSize: BugPageSize): Promise<BugPageSize> {
+  if (pageSize <= 200) return pageSize;
+  if (!isProEdition()) return 200;
+  try {
+    await requireFeature(request, "largePageSize");
+    return pageSize;
+  } catch {
+    return 200;
+  }
+}
+
+/** 获取当前用户持久化的 BUG 显示选项（非法/缺失字段已回退默认值） */
+export const getBugDisplayOptionsFn = createServerFn({ method: "GET" }).handler(async () => {
+  const prisma = await getPrisma();
+  const request = getRequest();
+  const session = await requireAuth(request);
+  const userId = session.user!.id!;
+
+  const row = await prisma.bugFilterView.findFirst({
+    where: { userId, name: BUG_DISPLAY_OPTIONS_VIEW_NAME },
+    orderBy: { createdAt: "asc" },
+    select: { displayOptions: true },
+  });
+  const options = parseStoredOptions(row?.displayOptions);
+  options.pageSize = await capPageSize(request, options.pageSize);
+  return options;
+});
+
+/** 保存当前用户的 BUG 显示选项，返回更新后的完整对象 */
+export const updateBugDisplayOptionsFn = createServerFn({ method: "POST" })
+  .validator(optionsSchema)
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma();
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+
+    // 服务端强制校验：pageSize > 200（500/1000）为 Pro 专属，前端锁定只是 UX
+    const options: BugDisplayOptions = {
+      ...data,
+      pageSize: await capPageSize(request, data.pageSize),
+    };
+
+    // 与 get 路径同一 orderBy：并发双保留行时读写对齐首行，避免保存后读不到
+    const existing = await prisma.bugFilterView.findFirst({
+      where: { userId, name: BUG_DISPLAY_OPTIONS_VIEW_NAME },
+      orderBy: { createdAt: "asc" },
+      select: { id: true },
+    });
+    if (existing) {
+      await prisma.bugFilterView.update({
+        where: { id: existing.id },
+        data: { displayOptions: toJson(options) },
+      });
+    } else {
+      await prisma.bugFilterView.create({
+        data: {
+          userId,
+          name: BUG_DISPLAY_OPTIONS_VIEW_NAME,
+          filters: toJson([]),
+          displayOptions: toJson(options),
+        },
+      });
+    }
+    return options;
+  });

package/src/server/serverFns/bug/bug-fix.ts

@@ -0,0 +1,261 @@
+// 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/>.
+
+// AI 修复触发闭环 serverFn（任务 22，规格 §10.3）：
+// requestBugFixFn（详情头部「AI 修复」按钮）→ 无活跃 run 创建 pending(manual)
+// + BugActivity(fix_requested) + webhook(fix.requested)；cancelBugFixFn 活跃 run
+// → cancelled；listFixRunsFn 供详情「AI 修复」时间线分区（§5.4 第 7 分区）。
+// 纯净性：文件内仅 createServerFn 导出（serverFn split 不剥非 handler 导出，
+// 同 bug-comments.ts 先例）；权限与序列化助手下沉独立模块。
+import { getPrisma } from "@allbluecn/database/get-prisma";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import { z } from "zod";
+import { requireAuth } from "@/server/auth-helpers";
+import { fireBugWebhook } from "@/server/bug-report/webhook-out";
+import { assertBugProjectMember } from "@/server/bug/bug-permissions";
+
+/** 活跃修复任务状态集（与 server/mcp/tools.ts 的 ACTIVE_RUN_STATUSES 同口径；
+ * 值复制而非跨模块 import——tools.ts 属 MCP 服务器模块，客户端 split 会连带拉入） */
+const ACTIVE_RUN_STATUSES = ["pending", "claimed", "in_progress"] as const;
+
+const LIST_RUNS_LIMIT = 50;
+const LIST_PROGRESS_LIMIT = 200;
+
+/** run.summary JSON 契约（report_result 落库形状，§10.2） */
+export interface FixRunSummary {
+  result: string;
+  summaryText: string;
+  commitUrl: string | null;
+  prUrl: string | null;
+  changedFiles: string[];
+}
+
+export interface FixRunItem {
+  id: string;
+  status: string;
+  triggerType: string;
+  agentName: string | null;
+  claimedAt: string | null;
+  completedAt: string | null;
+  summary: FixRunSummary | null;
+  createdAt: string;
+}
+
+/** report_progress 过程记录（BugActivity action=fix_progress，metadata={phase,message}） */
+export interface FixProgressItem {
+  id: string;
+  agentName: string | null;
+  phase: string | null;
+  message: string | null;
+  createdAt: string;
+}
+
+type RunRow = {
+  id: string;
+  status: string;
+  triggerType: string;
+  agentName: string | null;
+  claimedAt: Date | null;
+  completedAt: Date | null;
+  summary: unknown;
+  createdAt: Date;
+};
+
+function castSummary(raw: unknown): FixRunSummary | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.result !== "string" || typeof obj.summaryText !== "string") return null;
+  return {
+    result: obj.result,
+    summaryText: obj.summaryText,
+    commitUrl: typeof obj.commitUrl === "string" ? obj.commitUrl : null,
+    prUrl: typeof obj.prUrl === "string" ? obj.prUrl : null,
+    changedFiles: Array.isArray(obj.changedFiles)
+      ? obj.changedFiles.filter((f): f is string => typeof f === "string")
+      : [],
+  };
+}
+
+function castRun(run: RunRow): FixRunItem {
+  return {
+    id: run.id,
+    status: run.status,
+    triggerType: run.triggerType,
+    agentName: run.agentName,
+    claimedAt: run.claimedAt ? run.claimedAt.toISOString() : null,
+    completedAt: run.completedAt ? run.completedAt.toISOString() : null,
+    summary: castSummary(run.summary),
+    createdAt: run.createdAt.toISOString(),
+  };
+}
+
+type ProgressRow = {
+  id: string;
+  agentName: string | null;
+  metadata: unknown;
+  createdAt: Date;
+};
+
+function castProgress(row: ProgressRow): FixProgressItem {
+  const meta =
+    typeof row.metadata === "object" && row.metadata !== null && !Array.isArray(row.metadata)
+      ? (row.metadata as Record<string, unknown>)
+      : {};
+  return {
+    id: row.id,
+    agentName: row.agentName,
+    phase: typeof meta.phase === "string" ? meta.phase : null,
+    message: typeof meta.message === "string" ? meta.message : null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+export const requestBugFixFn = createServerFn({ method: "POST" })
+  .validator(z.object({ bugId: z.string() }))
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma();
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+
+    const projectId = await assertBugProjectMember(data.bugId, userId);
+
+    const activeRun = await prisma.bugFixRun.findFirst({
+      where: { bugId: data.bugId, status: { in: [...ACTIVE_RUN_STATUSES] } },
+      orderBy: { createdAt: "desc" },
+    });
+    if (activeRun) {
+      // 冲突不抛错：结构化返回让 UI toast 提示已存在（§10.3 手动分支）
+      return { status: "conflict" as const, activeRun: castRun(activeRun) };
+    }
+
+    const bug = await prisma.bug.findUnique({
+      where: { id: data.bugId },
+      select: {
+        identifier: true,
+        title: true,
+        severity: true,
+        state: true,
+        url: true,
+        stackSummary: true,
+      },
+    });
+    if (!bug) throw new Error("BUG 不存在");
+
+    // 手动入队不受 pending 队列上限约束（§10.3：上限仅约束自动入队风暴）
+    const run = await prisma.bugFixRun.create({
+      data: {
+        bugId: data.bugId,
+        status: "pending",
+        triggerType: "manual",
+      },
+    });
+
+    await prisma.bugActivity.create({
+      data: {
+        bugId: data.bugId,
+        userId,
+        actorType: "user",
+        action: "fix_requested",
+      },
+    });
+
+    // webhook（fix.requested）任务 23 真实投递（§3.8 body 形状）
+    fireBugWebhook("fix.requested", {
+      projectId,
+      bug: {
+        id: data.bugId,
+        identifier: bug.identifier,
+        title: bug.title,
+        severity: bug.severity,
+        state: bug.state,
+        url: bug.url,
+        stackSummary: bug.stackSummary,
+      },
+      fixRunId: run.id,
+    });
+
+    return { status: "created" as const, run: castRun(run) };
+  });
+
+export const cancelBugFixFn = createServerFn({ method: "POST" })
+  .validator(z.object({ bugId: z.string() }))
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma();
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+
+    await assertBugProjectMember(data.bugId, userId);
+
+    const activeRun = await prisma.bugFixRun.findFirst({
+      where: { bugId: data.bugId, status: { in: [...ACTIVE_RUN_STATUSES] } },
+      orderBy: { createdAt: "desc" },
+    });
+    if (!activeRun) throw new Error("无活跃修复任务可取消");
+
+    // 条件更新防并发竞态（与 claim_fix 同款）：find 与 update 间隙 run 可能已被
+    // report_result 完结，count=0 即落空，不写 fix_cancelled 活动
+    const cancelled = await prisma.bugFixRun.updateMany({
+      where: { id: activeRun.id, status: { in: [...ACTIVE_RUN_STATUSES] } },
+      data: { status: "cancelled", completedAt: new Date() },
+    });
+    if (cancelled.count === 0) throw new Error("修复任务已完结，无需取消");
+
+    await prisma.bugActivity.create({
+      data: {
+        bugId: data.bugId,
+        userId,
+        actorType: "user",
+        action: "fix_cancelled",
+      },
+    });
+
+    return { ok: true as const, runId: activeRun.id };
+  });
+
+export const listFixRunsFn = createServerFn({ method: "GET" })
+  .validator(z.object({ bugId: z.string() }))
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma();
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+
+    await assertBugProjectMember(data.bugId, userId);
+
+    const [runs, progress] = await Promise.all([
+      prisma.bugFixRun.findMany({
+        where: { bugId: data.bugId },
+        orderBy: { createdAt: "desc" },
+        take: LIST_RUNS_LIMIT,
+      }),
+      // 过程记录无 runId 外键（BugActivity 无 run 维度），按 createdAt 窗口归属到
+      // 时间线各 run（fix-timeline.tsx 内归并），这里按时间正则取全量样本
+      prisma.bugActivity.findMany({
+        where: { bugId: data.bugId, action: "fix_progress" },
+        orderBy: { createdAt: "asc" },
+        take: LIST_PROGRESS_LIMIT,
+      }),
+    ]);
+
+    return {
+      runs: runs.map(castRun),
+      progress: progress.map(castProgress),
+    };
+  });

package/src/server/serverFns/bug/bug-group-query.ts

@@ -0,0 +1,209 @@
+// 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/>.
+
+// BUG 分组查询纯函数。独立文件保证 serverFn 模块纯净（照 bug-list-query.ts 先例）：
+// bug-groups.ts 只准导出 createServerFn。依赖仅客户端安全常量 + type-only Prisma
+//（运行时零服务端依赖），任务 8 客户端乐观重插可复用 compareBugsByOrderKey。
+import type { Prisma } from "@allbluecn/database";
+import { BUG_STATES, BUG_SEVERITIES, severityRank, type BugSeverity } from "@/shared/bug/constants";
+import {
+  BUG_GROUP_DISPLAY_ORDER,
+  type BugGroupKey,
+  type BugOrderKey,
+} from "@/components/bug/display/types";
+import { BUG_LIST_SELECT, type BugListRow } from "@/components/bug/types";
+
+/** prisma.groupBy 的 by 字段映射（assignee/createdBy 用外键列分组计数） */
+export const BUG_GROUP_BY_FIELD: Record<Exclude<BugGroupKey, "none">, Prisma.BugScalarFieldEnum> = {
+  state: "state",
+  severity: "severity",
+  assignee: "assigneeId",
+  createdBy: "createdById",
+};
+
+/** 计数行（prisma.bug.groupBy 返回，扁平外键列）→ 组 key；assignee null 归并 unassigned */
+export function deriveBugGroupKeyFromCountRow(
+  groupBy: BugGroupKey,
+  row: Record<string, unknown>,
+): string | null {
+  switch (groupBy) {
+    case "state":
+      return (row.state as string | undefined) ?? null;
+    case "severity":
+      return (row.severity as string | undefined) ?? null;
+    case "assignee":
+      return (row.assigneeId as string | null) ?? "unassigned";
+    case "createdBy":
+      return (row.createdById as string | undefined) ?? null;
+    default:
+      return null;
+  }
+}
+
+/** 列表行（BUG_LIST_SELECT 关联对象形态）→ 组 key；assignee 缺失归并 unassigned */
+export function deriveBugGroupKeyFromListRow(groupBy: BugGroupKey, row: BugListRow): string | null {
+  switch (groupBy) {
+    case "state":
+      return row.state ?? null;
+    case "severity":
+      return row.severity ?? null;
+    case "assignee":
+      return row.assignee?.id ?? "unassigned";
+    case "createdBy":
+      return row.createdBy?.id ?? null;
+    default:
+      return null;
+  }
+}
+
+/** 组 key 按显示顺序排序（state=BUG_STATES rank 序、severity=critical→low；未知 key 排最后） */
+export function sortBugGroupKeys(groupBy: BugGroupKey, keys: string[]): string[] {
+  const order = BUG_GROUP_DISPLAY_ORDER[groupBy];
+  if (!order) return keys;
+  const rank = new Map(order.map((k, i) => [k, i]));
+  return [...keys].sort((a, b) => (rank.get(a) ?? order.length) - (rank.get(b) ?? order.length));
+}
+
+/** 组值 → where 片段（listBugsInGroupFn 按组过滤用；unassigned = 未指派） */
+export function buildBugGroupFilter(groupBy: BugGroupKey, groupKey: string): Prisma.BugWhereInput {
+  switch (groupBy) {
+    case "state":
+      return groupKey ? { state: groupKey } : {};
+    case "severity":
+      return groupKey ? { severity: groupKey } : {};
+    case "assignee":
+      if (groupKey === "unassigned") return { assigneeId: null };
+      return groupKey ? { assigneeId: groupKey } : {};
+    case "createdBy":
+      return groupKey ? { createdById: groupKey } : {};
+    default:
+      return {};
+  }
+}
+
+/**
+ * OrderKey → DB 排序字段。manual：P1 无拖拽排序，录入序 = createdAt（与项目内
+ * sequenceId 同序）；severity 为 String 列，DB 字典序 ≠ rank 序，返回 null 走
+ * fetchBugsInSeverityRankOrder 分层查询（rank 全序 + 分页正确）。
+ */
+const BUG_ORDER_FIELD: Record<BugOrderKey, Prisma.BugScalarFieldEnum | null> = {
+  manual: "createdAt",
+  created: "createdAt",
+  updated: "updatedAt",
+  severity: null,
+};
+
+/** [主键, id asc] tiebreaker：同键行全序确定，跨批次分页不抖动（与 story 同构） */
+export function buildBugOrderBy(orderBy: BugOrderKey, dir: "asc" | "desc"): Prisma.BugOrderByWithRelationInput[] {
+  const field = BUG_ORDER_FIELD[orderBy];
+  const d: "asc" | "desc" = dir === "asc" ? "asc" : "desc";
+  return field ? [{ [field]: d }, { id: "asc" }] : [{ id: "asc" }];
+}
+
+/** severity rank 降序分层（BUG_SEVERITIES 数组序），asc 反转；分层查询逐层填页 */
+export function bugSeverityTiers(dir: "asc" | "desc"): BugSeverity[] {
+  const tiers = BUG_SEVERITIES.map((s) => s.value);
+  return dir === "asc" ? [...tiers].reverse() : tiers;
+}
+
+/** 分层查询用的 bug delegate 最小结构类型（避免依赖生成 client 的 delegate 命名） */
+interface BugFetchDelegate {
+  findMany(args: {
+    where: Prisma.BugWhereInput;
+    orderBy: Prisma.BugOrderByWithRelationInput[];
+    skip: number;
+    take: number;
+    /** 必传：结果直接喂 castBugUsers，缺 select 时关联字段（labels/assignee/…）不存在 */
+    select: typeof BUG_LIST_SELECT;
+  }): Promise<unknown[]>;
+  count(args: { where: Prisma.BugWhereInput }): Promise<number>;
+}
+
+/**
+ * severity rank 全序取页（DB 字典序无法表达 rank，按 rank 分层逐层填页保证分页正确）：
+ * skip 之前先数层内总量跳层，再在目标层 take 补齐；层内 id asc 与全序 tiebreaker 一致。
+ */
+export async function fetchBugsInSeverityRankOrder(
+  bug: BugFetchDelegate,
+  where: Prisma.BugWhereInput,
+  skip: number,
+  take: number,
+  dir: "asc" | "desc",
+): Promise<BugListRow[]> {
+  const collected: BugListRow[] = [];
+  let skipRemaining = skip;
+  for (const tier of bugSeverityTiers(dir)) {
+    if (collected.length >= take) break;
+    const tierWhere: Prisma.BugWhereInput = { ...where, severity: tier };
+    if (skipRemaining > 0) {
+      const tierTotal = await bug.count({ where: tierWhere });
+      if (skipRemaining >= tierTotal) {
+        skipRemaining -= tierTotal;
+        continue;
+      }
+    }
+    const batch = (await bug.findMany({
+      where: tierWhere,
+      orderBy: [{ id: "asc" }],
+      skip: skipRemaining,
+      take: take - collected.length,
+      // 与非 severity 分支一致：BUG_LIST_SELECT 保证关联字段齐全（castBugUsers 前置）
+      select: BUG_LIST_SELECT,
+    })) as BugListRow[];
+    skipRemaining = 0;
+    collected.push(...batch);
+  }
+  return collected;
+}
+
+/** 组内排序比较行（BugListItem cast 后形态：日期 ISO 字符串、severity String 枚举） */
+export interface BugOrderCompareRow {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  severity: string;
+}
+
+/** 与服务端 [主键, id asc] tiebreaker 全序一致的组内比较（severity 走 severityRank） */
+export function compareBugsByOrderKey(
+  a: BugOrderCompareRow,
+  b: BugOrderCompareRow,
+  orderBy: BugOrderKey,
+  dir: "asc" | "desc",
+): number {
+  let c = 0;
+  switch (orderBy) {
+    case "manual":
+    case "created":
+      c = a.createdAt.localeCompare(b.createdAt);
+      break;
+    case "updated":
+      c = a.updatedAt.localeCompare(b.updatedAt);
+      break;
+    case "severity":
+      c = severityRank(a.severity as BugSeverity) - severityRank(b.severity as BugSeverity);
+      break;
+  }
+  if (c !== 0) return dir === "asc" ? c : -c;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+/** state 空组 key 全集（BUG_STATES 数组序 = rank 序；showEmptyGroups 用） */
+export const BUG_STATE_GROUP_KEYS: string[] = BUG_STATES.map((s) => s.value);
+
+/** severity 空组 key 全集（BUG_SEVERITIES 数组序 = rank 降序，critical 最前） */
+export const BUG_SEVERITY_GROUP_KEYS: string[] = BUG_SEVERITIES.map((s) => s.value);