@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/bug/views/board-view.tsx

@@ -0,0 +1,661 @@
+// 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 看板视图（UI 对齐三期 PR-10 任务 33）：消费共享 KanbanBoardView
+// （shared-kit/list-kit/kanban），testcase/views/board-view.tsx（任务 26）蓝本的
+// bug 裁剪版。
+// - 列 meta：state/severity 引 shared/bug/constants.ts 的 STATE/SEVERITY 表
+//   （图标 + colorToken bg-* 色族派生同色系浅底 tint，与 testcase META 表口径同构）；
+//   assignee 用用户花名册解析列名（unassigned 哨兵 = 未指派）；labels 仅入维度
+//   联合供 columnDroppable 禁拖守卫与扩展（设计 §7.1 复审 P2-6，列数据层尚无
+//   labels 桶分来源，见 bug-group-query 的 BUG_GROUP_BY_FIELD）。
+// - 卡片：identifier（font-mono，displayOptions.properties "id" 门控，任务 34）+
+//   标题（line-clamp-2）+ 行内编辑器
+//   （state/severity/assignee，displayOptions.properties 门控，button 形态）+
+//   UserAvatar；分组维度字段自动隐藏（groupBy=severity 不渲染 SeverityEditor，
+//   列头已表达该维度）。编辑走 updateBugFn 后 onPatchBug 乐观收敛（BugListRow
+//   同款两段式；分组触发字段由 paged core 自动 refresh，无需单独整板重拉通道）。
+// - 落点淡化卡（renderGhostCard）：排版一致的静态镜像，不挂 Popover/UserAvatar
+//   （蓝本 TaskCardGhost 的挂载成本口径，testcase board-view 同注）。
+// - 跨列拖拽 = 改分组字段：toGroupFieldPatch 列 key → updateBugFn patch
+//   （state→state / severity→severity / assignee→assigneeId（unassigned 哨兵 →
+//   null）/ labels/createdBy→无映射）；列内 reorder 由 manualOrder.onReorder 落
+//   reorderBugsFn（list-view 接线）。
+// - 列内子分组（任务 41，BUG-E 收尾）：capabilities.subGroups 开启 + subGrouping
+//   构造（buildBugSubGrouping 按列条目客户端分桶，story kanban-view 的
+//   buildMembership/buildSubMeta 同构形态）。数据面由 list-view 的 boardDisplay
+//   按用户 subGroupBy 选项双层拉取（任务 33 的强制 none 演进为「维度冲突才收敛」），
+//   列内条目按子组连续分区展平（buildRuns 前提）。createdBy 沿 story 口径
+//   moveAcross=false（创建人不可改，拖拽仅视觉分区）。
+// - config 引用稳定性（共享组件 memo 契约）：buildBoardConfig 的全部函数字段
+//   随 config 一起经组件内 useMemo 固定，消费方（list-view）传入的回调须
+//   useCallback/useMemo 保持引用稳定；subGrouping.membership 同受该契约约束
+//   （共享层 JSDoc：引用一变即重置组件本地乐观成员表）——组件内 useMemo 固定，
+//   仅在服务端权威 columns 变化时产生新引用。
+import { memo, useCallback, useMemo } from "react";
+import { Card, CardContent } from "@/components/ui/card";
+import { UserAvatar } from "@/components/shared-kit";
+import { updateBugFn } from "@/server/serverFns/bug";
+import type { BugListItem } from "../types";
+import type { UserBrief } from "@/components/story/types";
+import type { BugPatch } from "../display/use-paged-bug-groups";
+import type { BugDisplayProperty, BugGroupKey } from "../display/types";
+import { BUG_GROUP_DISPLAY_ORDER } from "../display/types";
+import { StateEditor } from "../inline-editors/state-editor";
+import { SeverityEditor } from "../inline-editors/severity-editor";
+import { AssigneeEditor } from "../inline-editors/assignee-editor";
+import {
+  BUG_STATE_ICON,
+  SEVERITY_COLOR,
+  SEVERITY_ICON,
+  SEVERITY_LABEL,
+  STATE_COLOR,
+  STATE_LABEL,
+  type BugSeverity,
+  type BugState,
+} from "@/shared/bug/constants";
+import {
+  KanbanBoardView,
+  type ColumnTint,
+  type KanbanColumnMeta,
+  type KanbanModuleConfig,
+  type KanbanSubGroupMeta,
+  type KanbanSubGrouping,
+} from "@/components/shared-kit/list-kit/kanban/kanban-board-view";
+import type { ReorderEntry } from "@/components/shared-kit/list-kit/kanban/drop-commit";
+import { extractTextColors } from "@/components/shared-kit/list-kit/level-badge";
+import { cn } from "@/lib/utils";
+import { m } from "@/paraglide/messages.js";
+import { toastError } from "@/lib/toast-error";
+
+/**
+ * 看板分组维度（设计 §7.1 bug 看板维度 = state/severity/assignee/labels）：
+ * state/severity/assignee 有列数据源（paged groups）；labels 仅守卫位——多对多
+ * 维度禁拖（columnDroppable），列数据层落地前不进看板分组下拉。
+ */
+export type BugBoardGroupDimension = "state" | "severity" | "assignee" | "labels";
+
+/**
+ * 看板子分组维度（任务 41，照任务 40 列表侧子组维度集）：state/severity/
+ * assignee/createdBy。labels 多对多不入（列表侧同款）；none 表示不启用。
+ */
+export type BugBoardSubGroupDimension = Exclude<BugGroupKey, "none">;
+
+/* ------------------------------------------------------------------ */
+/* 列 meta（label / icon / tint，STATE/SEVERITY 表单一来源派生）            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * tint 的合成基色/浓度与 testcase board-view / story group-resolver 同源
+ * （globals.css 的 --kanban-column-tint[-base]），列底色为「色相淡化成实色」，
+ * 吸附层与列 Card 同色。
+ */
+const TINT_ALPHA = "var(--kanban-column-tint)";
+const TINT_BASE = "var(--kanban-column-tint-base)";
+const NEUTRAL_TINT = "bg-muted";
+
+function mixTint(color: string): ColumnTint {
+  return { backgroundColor: `color-mix(in srgb, ${color} ${TINT_ALPHA}, ${TINT_BASE})` };
+}
+
+/**
+ * colorToken → 列底 tint：取 bg-* 色族类（如 bg-blue-500/15）派生同族实色
+ * color-mix；bg-muted 等无色相 token 回落中性浅底（closed/wontfix/low）。
+ * 色族变量由源码工具类保活（STATE_COLOR/SEVERITY_COLOR 的 bg-* 类随 constants.ts
+ * 被 Tailwind 扫描，--color-* 变量不被 tree-shake）。
+ */
+export function tintFromColorToken(colorToken: string): ColumnTint {
+  const bg = colorToken.split(" ").find((c) => c.startsWith("bg-"));
+  if (!bg) return {};
+  const family = /^bg-([a-z]+-\d+)/.exec(bg);
+  if (!family) return { className: NEUTRAL_TINT };
+  return mixTint(`var(--color-${family[1]})`);
+}
+
+/** 语义色串（形如 "bg-x/15 text-x-600 dark:text-x-400"）取 text-* 字色类作图标色
+ *  （testcase 任务 29 起复用 LevelBadge 的 extractTextColors：保留 dark: 变体） */
+function textColorOf(color: string | undefined): string | undefined {
+  return color ? extractTextColors(color) : undefined;
+}
+
+/** 列头 meta：state/severity 走 STATE/SEVERITY 表 + i18n label + colorToken tint；
+ *  assignee 用花名册解析（unassigned 哨兵）；labels/未知 key 兜底 */
+export function bugBoardColumnMeta(
+  groupBy: BugBoardGroupDimension,
+  key: string,
+  users: UserBrief[],
+): KanbanColumnMeta {
+  switch (groupBy) {
+    case "state": {
+      const state = key as BugState;
+      return {
+        label: STATE_LABEL[state]?.() ?? key,
+        icon: BUG_STATE_ICON[state],
+        iconClassName: textColorOf(STATE_COLOR[state]),
+        tint: tintFromColorToken(STATE_COLOR[state] ?? ""),
+      };
+    }
+    case "severity": {
+      const severity = key as BugSeverity;
+      return {
+        label: SEVERITY_LABEL[severity]?.() ?? key,
+        icon: SEVERITY_ICON[severity],
+        iconClassName: textColorOf(SEVERITY_COLOR[severity]),
+        tint: tintFromColorToken(SEVERITY_COLOR[severity] ?? ""),
+      };
+    }
+    case "assignee": {
+      if (key === "unassigned") return { label: m.bug_list_unassigned() };
+      return {
+        label: users.find((u) => u.id === key)?.username ?? m.bug_group_unknown_user(),
+      };
+    }
+    case "labels":
+      return { label: m.bug_column_labels() };
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* 跨列拖拽 patch 映射（列 key → updateBugFn 字段）                         */
+/* ------------------------------------------------------------------ */
+
+/** 未指派哨兵（与 deriveBugGroupKeyFromListRow 的 assignee 归并口径一致） */
+const UNASSIGNED_KEY = "unassigned";
+
+/** 列 key → updateBugFn patch（labels 多对多 / createdBy 不可改，均无单值映射，
+ *  返回空 = 不可落库；createdBy 供子分组维度复用本映射，任务 41） */
+export function toGroupFieldPatch(
+  groupBy: BugBoardGroupDimension | BugBoardSubGroupDimension,
+  columnKey: string,
+): BugPatch {
+  switch (groupBy) {
+    case "state":
+      return { state: columnKey as BugState };
+    case "severity":
+      return { severity: columnKey as BugSeverity };
+    case "assignee":
+      return { assigneeId: columnKey === UNASSIGNED_KEY ? null : columnKey };
+    case "labels":
+    case "createdBy":
+      return {};
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* 子分组构造（任务 41：membership 分桶 + meta，story buildSubMeta/           */
+/* buildMembership 同构形态；导出供测试对同一接线断言）                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * 条目 → 子组 key（客户端派生）。与 use-paged-bug-groups 的私有 deriveBugGroupKey
+ * / 服务端 deriveBugGroupKeyFromListRow 同一口径（assignee 缺失归并 unassigned）；
+ * 不直接喂 BugListRow 签名——BugListItem 是 ISO 日期的客户端形态（该先例同注）。
+ */
+export function deriveBugSubGroupKey(
+  subGroupBy: BugBoardSubGroupDimension,
+  bug: BugListItem,
+): string {
+  switch (subGroupBy) {
+    case "state":
+      return bug.state;
+    case "severity":
+      return bug.severity;
+    case "assignee":
+      return bug.assignee?.id ?? UNASSIGNED_KEY;
+    case "createdBy":
+      return bug.createdBy?.id ?? "";
+  }
+}
+
+/** 子组 label / icon / 色（列 meta 同源派生：STATE/SEVERITY 表 + 花名册） */
+function bugBoardSubGroupMeta(
+  subGroupBy: BugBoardSubGroupDimension,
+  key: string,
+  users: UserBrief[],
+): Pick<KanbanSubGroupMeta, "label" | "icon" | "color"> {
+  switch (subGroupBy) {
+    case "state": {
+      const state = key as BugState;
+      return {
+        label: STATE_LABEL[state]?.() ?? key,
+        icon: BUG_STATE_ICON[state],
+        color: textColorOf(STATE_COLOR[state]),
+      };
+    }
+    case "severity": {
+      const severity = key as BugSeverity;
+      return {
+        label: SEVERITY_LABEL[severity]?.() ?? key,
+        icon: SEVERITY_ICON[severity],
+        color: textColorOf(SEVERITY_COLOR[severity]),
+      };
+    }
+    case "assignee":
+      return {
+        label:
+          key === UNASSIGNED_KEY
+            ? m.bug_list_unassigned()
+            : (users.find((u) => u.id === key)?.username ?? m.bug_group_unknown_user()),
+      };
+    case "createdBy":
+      return {
+        label: users.find((u) => u.id === key)?.username ?? m.bug_group_unknown_user(),
+      };
+  }
+}
+
+/**
+ * 由看板列条目构造共享层 KanbanSubGrouping（story kanban-view 的
+ * buildSubMeta/buildMembership 同构）：
+ * - membership：条目 id → 子组 key（跨列合并；调用方 useMemo 固定引用——
+ *   共享层用它做渲染期同步，引用一变即重置拖拽乐观成员表）
+ * - meta：state/severity 按规范序（BUG_GROUP_DISPLAY_ORDER），其余维度按首现序
+ * - moveAcross：createdBy 不可改 → false（story GROUP_FIELD 口径），拖拽仅视觉分区
+ */
+export function buildBugSubGrouping(
+  subGroupBy: BugBoardSubGroupDimension,
+  columns: Record<string, BugListItem[]>,
+  users: UserBrief[],
+): KanbanSubGrouping {
+  const membership: Record<string, string> = {};
+  const firstSeen: string[] = [];
+  for (const items of Object.values(columns)) {
+    for (const bug of items) {
+      const key = deriveBugSubGroupKey(subGroupBy, bug);
+      membership[bug.id] = key;
+      if (!firstSeen.includes(key)) firstSeen.push(key);
+    }
+  }
+  // 子组头展示序：state/severity 有规范序（未知 key 排最后），与列条目实际顺序
+  // （服务端 sortBugGroupKeys 序）一致；无规范序维度保持首现序
+  const canonical = BUG_GROUP_DISPLAY_ORDER[subGroupBy];
+  const rank = canonical ? new Map(canonical.map((k, i) => [k, i])) : undefined;
+  const canonicalLen = canonical?.length ?? 0;
+  const orderedKeys = rank
+    ? [...firstSeen].sort(
+        (a, b) => (rank.get(a) ?? canonicalLen) - (rank.get(b) ?? canonicalLen),
+      )
+    : firstSeen;
+  const meta: Record<string, KanbanSubGroupMeta> = {};
+  for (const key of orderedKeys) {
+    meta[key] = {
+      key,
+      ...bugBoardSubGroupMeta(subGroupBy, key, users),
+      order: Object.keys(meta).length,
+    };
+  }
+  return {
+    membership,
+    meta,
+    dimension: subGroupBy,
+    moveAcross: subGroupBy !== "createdBy",
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* 卡片（updateBugFn → onPatchBug 两段式，BugListRow 同款口径裁剪版）          */
+/* ------------------------------------------------------------------ */
+
+interface BoardBugCardProps {
+  bug: BugListItem;
+  properties: BugDisplayProperty[];
+  groupBy: BugBoardGroupDimension;
+  users: UserBrief[];
+  /** 服务端落库成功后的乐观收敛回调（list-view 接 paged.patchBug） */
+  onPatchBug: (bugId: string, patch: BugPatch) => void;
+}
+
+export const BoardBugCard = memo(function BoardBugCard({
+  bug,
+  properties,
+  groupBy,
+  users,
+  onPatchBug,
+}: BoardBugCardProps) {
+  const updateField = useCallback(
+    async (patch: BugPatch) => {
+      try {
+        // BugListRow 同款：lastOccurAt 客户端允许 null（清除语义），服务端 z.string()
+        // 非可空 → 归一为 undefined（no-op；本卡编辑面不含该字段，保守对齐）
+        await updateBugFn({
+          data: { bugId: bug.id, ...patch, lastOccurAt: patch.lastOccurAt ?? undefined },
+        });
+        onPatchBug(bug.id, patch);
+      } catch (e) {
+        toastError(e, m.bug_row_update_failed());
+      }
+    },
+    [bug.id, onPatchBug],
+  );
+
+  const setState = useCallback(
+    (v: BugState) => void updateField({ state: v }),
+    [updateField],
+  );
+  const setSeverity = useCallback(
+    (v: BugSeverity) => void updateField({ severity: v }),
+    [updateField],
+  );
+  const setAssignee = useCallback(
+    (v: string | null) => void updateField({ assigneeId: v }),
+    [updateField],
+  );
+
+  // 分组维度字段自动隐藏：列头已表达该维度，卡内重复编辑器徒增噪点
+  // identifier（"id"）同为 properties 门控项（任务 34，与列表行同口径）
+  const showId = properties.includes("id");
+  const showState = properties.includes("state") && groupBy !== "state";
+  const showSeverity = properties.includes("severity") && groupBy !== "severity";
+  const showAssignee = properties.includes("assignee") && groupBy !== "assignee";
+
+  return (
+    <Card data-testid="bug-board-card" className="w-full gap-0 py-3">
+      <CardContent className="space-y-2.5 px-3">
+        <div className="flex items-center justify-between gap-1.5">
+          {showId && (
+            <span className="font-mono text-xs font-medium text-muted-foreground">
+              {bug.identifier}
+            </span>
+          )}
+          {/* 编辑器区拦截冒泡：打开弹层不触发卡片点击（peek）；ml-auto 兜底
+              identifier（id）关闭时编辑器仍右对齐（justify-between 单子元素左飘） */}
+          <div className="ml-auto flex shrink-0 items-center gap-1" onClick={(e) => e.stopPropagation()}>
+            {showState && <StateEditor value={bug.state} onChange={setState} variant="button" />}
+            {showSeverity && (
+              <SeverityEditor value={bug.severity} onChange={setSeverity} variant="button" />
+            )}
+            {showAssignee && (
+              <AssigneeEditor assignee={bug.assignee} users={users} onChange={setAssignee} variant="button" />
+            )}
+          </div>
+        </div>
+        <div className="line-clamp-2 text-sm leading-snug font-medium">{bug.title}</div>
+        <div className="flex flex-wrap items-center gap-1.5">
+          {showAssignee && bug.assignee && (
+            <UserAvatar
+              name={bug.assignee.username}
+              avatarConfig={bug.assignee.avatarConfig}
+              bgShape={bug.assignee.bgShape}
+              bgColor={bug.assignee.bgColor}
+              size="sm"
+            />
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+});
+
+/**
+ * 落点预览用的静态镜像：排版与 BoardBugCard 一致，但不挂 Popover/UserAvatar
+ * （蓝本 TaskCardGhost 口径：落点每次变化都要挂载/卸载，hooks 挂载成本不可忽略）。
+ * 首字母圆几乎零成本。
+ */
+const BoardBugCardGhost = memo(function BoardBugCardGhost({
+  bug,
+  properties,
+  groupBy,
+}: {
+  bug: BugListItem;
+  properties: BugDisplayProperty[];
+  groupBy: BugBoardGroupDimension;
+}) {
+  const showId = properties.includes("id");
+  const showState = properties.includes("state") && groupBy !== "state";
+  const showSeverity = properties.includes("severity") && groupBy !== "severity";
+  const showAssignee = properties.includes("assignee") && groupBy !== "assignee";
+  const StateIcon = BUG_STATE_ICON[bug.state];
+  const SeverityIcon = SEVERITY_ICON[bug.severity];
+  return (
+    <Card className="w-full gap-0 py-3">
+      <CardContent className="space-y-2.5 px-3">
+        <div className="flex items-center justify-between gap-1.5">
+          {showId && (
+            <span className="font-mono text-xs font-medium text-muted-foreground">
+              {bug.identifier}
+            </span>
+          )}
+          <div className="ml-auto flex shrink-0 items-center gap-1">
+            {showState && StateIcon && (
+              <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 text-xs">
+                <StateIcon
+                  className={cn(
+                    "size-3.5",
+                    textColorOf(STATE_COLOR[bug.state]),
+                  )}
+                />
+                {STATE_LABEL[bug.state]?.() ?? bug.state}
+              </span>
+            )}
+            {showSeverity && SeverityIcon && (
+              <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 text-xs">
+                <SeverityIcon
+                  className={cn(
+                    "size-3.5",
+                    textColorOf(SEVERITY_COLOR[bug.severity]),
+                  )}
+                />
+                {SEVERITY_LABEL[bug.severity]?.() ?? bug.severity}
+              </span>
+            )}
+          </div>
+        </div>
+        <div className="line-clamp-2 text-sm leading-snug font-medium">{bug.title}</div>
+        <div className="flex flex-wrap items-center gap-1.5">
+          {showAssignee && bug.assignee && (
+            <span className="flex size-6 shrink-0 items-center justify-center rounded-full bg-muted text-xs font-medium uppercase text-muted-foreground">
+              {bug.assignee.username.slice(0, 1)}
+            </span>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+});
+
+/* ------------------------------------------------------------------ */
+/* config 装配（组件内部经 useMemo 固定引用；导出供测试对同一接线断言）        */
+/* ------------------------------------------------------------------ */
+
+export interface BoardConfigDeps {
+  /** 服务端权威列集合（state/severity 全列集含空列，键序 = 列序——list-view 构造） */
+  columns: Record<string, BugListItem[]>;
+  groupBy: BugBoardGroupDimension;
+  /**
+   * 子分组维度开关（任务 41；none/缺省 = 不启用）。BugBoardView 内部经
+   * buildBugSubGrouping 构造 subGrouping 后一并传入 buildBoardConfig。
+   */
+  subGroupBy?: BugGroupKey;
+  /** 共享层子分组数据（capabilities.subGroups 开启时消费；见 buildBugSubGrouping） */
+  subGrouping?: KanbanSubGrouping;
+  properties: BugDisplayProperty[];
+  users: UserBrief[];
+  onOpenBug: (id: string) => void;
+  onLoadMoreColumn?: (columnKey: string) => void;
+  onPatchBug: (bugId: string, patch: BugPatch) => void;
+  onReorder: (orders: ReorderEntry[]) => Promise<void>;
+  onAutoSwitchManual?: () => Promise<void>;
+  /** 提交成功（共享层 900ms 延迟静默）/失败（立即）后的权威刷新 */
+  onRefresh?: () => void;
+  /** updateBugFn 的调用通道（组件注入 RPC；测试注入 mock） */
+  updateBug: (input: { bugId: string } & BugPatch) => Promise<unknown>;
+}
+
+/** 供测试对组件内同一接线断言（组件内部 useMemo(buildBoardConfig) 消费） */
+export function buildBoardConfig(deps: BoardConfigDeps): KanbanModuleConfig<BugListItem> {
+  const { groupBy, subGroupBy, properties, users, updateBug } = deps;
+  const hasSubGroups = !!subGroupBy && subGroupBy !== "none";
+  // 组件路径恒传 useMemo 产物（membership 引用稳定，见 BugBoardView）；未传时
+  // 现场构造兜底（直接调用 buildBoardConfig 的测试 / 防御路径）
+  const subGrouping =
+    hasSubGroups
+      ? (deps.subGrouping ?? buildBugSubGrouping(subGroupBy, deps.columns, users))
+      : undefined;
+  return {
+    columns: deps.columns,
+    columnMeta: (key) => bugBoardColumnMeta(groupBy, key, users),
+    cardKey: (item) => item.id,
+    renderCard: (item) => (
+      <BoardBugCard
+        bug={item}
+        properties={properties}
+        groupBy={groupBy}
+        users={users}
+        onPatchBug={deps.onPatchBug}
+      />
+    ),
+    renderGhostCard: (item) => (
+      <BoardBugCardGhost bug={item} properties={properties} groupBy={groupBy} />
+    ),
+    onOpenItem: (item) => deps.onOpenBug(item.id),
+    /**
+     * 列可放置性（复审 P2-6 / 二期 Task 24 ③ 归宿）：labels 多对多——「拖到列=设值」
+     * 语义不成立（一卡多标签无法由落列单值表达，设计 §7.1），labels 列禁拖入拖出。
+     * 同时堵死 Task 24 ③ 的假成功面：跨列 move 落到无 patch 映射的列时
+     * commitDropDecision 仍会走 onDropToColumn 成功分支弹「已移动」toast——
+     * columnDroppable=false 让 resolveDropCommit 直接产出 ignore 决策（决策层忽略 +
+     * 乐观列回滚），假成功 toast 不再可达。后续 labels 列数据源落地时，须同步
+     * 放开本守卫并补 toGroupFieldPatch 的 labels 映射（labelIds 全量写）。
+     */
+    columnDroppable: () => groupBy !== "labels",
+    onDropToColumn: async (itemKey, columnKey, meta) => {
+      const patch = toGroupFieldPatch(groupBy, columnKey);
+      // 子分组字段 patch（任务 41）：跨列 move 决策附带目标子分组且确有换区时合并
+      // （同值跳过零冗余写；moveAcross=false 维度共享层本就不带 subKey；与列分组
+      // 维度同值时以列字段为准）。子组对照表用服务端权威 membership——拖拽乐观
+      // 值只存在于共享组件本地，config 闭包里始终是权威值。
+      if (
+        meta?.subKey != null &&
+        subGrouping?.moveAcross &&
+        subGrouping.dimension !== groupBy
+      ) {
+        const subPatch = toGroupFieldPatch(
+          subGrouping.dimension as BugBoardSubGroupDimension,
+          meta.subKey,
+        );
+        if (
+          Object.keys(subPatch).length > 0 &&
+          meta.subKey !== subGrouping.membership[itemKey]
+        ) {
+          Object.assign(patch, subPatch);
+        }
+      }
+      if (Object.keys(patch).length === 0) return;
+      await updateBug({ bugId: itemKey, ...patch });
+      deps.onPatchBug(itemKey, patch);
+    },
+    onLoadMoreColumn: deps.onLoadMoreColumn,
+    capabilities: {
+      manualOrder: {
+        onReorder: deps.onReorder,
+        onAutoSwitchManual: deps.onAutoSwitchManual,
+      },
+      subGroups: hasSubGroups,
+    },
+    subGrouping: hasSubGroups ? subGrouping : undefined,
+    onRefresh: deps.onRefresh,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* 组件                                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface BugBoardViewProps {
+  columns: Record<string, BugListItem[]>;
+  groupBy: BugBoardGroupDimension;
+  /**
+   * 二级分组维度（任务 41；none/缺省 = 不启用）。与 groupBy 同值时由
+   * list-view 收敛为 none（boardDisplay），本组件不再兜底。
+   */
+  subGroupBy?: BugGroupKey;
+  properties: BugDisplayProperty[];
+  users: UserBrief[];
+  onOpenBug: (id: string) => void;
+  onLoadMoreColumn?: (columnKey: string) => void;
+  onPatchBug: (bugId: string, patch: BugPatch) => void;
+  onReorder: (orders: ReorderEntry[]) => Promise<void>;
+  onAutoSwitchManual?: () => Promise<void>;
+  onRefresh?: () => void;
+}
+
+export function BugBoardView(props: BugBoardViewProps) {
+  const {
+    columns,
+    groupBy,
+    subGroupBy,
+    properties,
+    users,
+    onOpenBug,
+    onLoadMoreColumn,
+    onPatchBug,
+    onReorder,
+    onAutoSwitchManual,
+    onRefresh,
+  } = props;
+
+  // 子分组构造（任务 41）：memo 契约要求 membership 引用稳定——仅在服务端权威
+  // columns / 维度 / 花名册变化时重建，禁止渲染期新建字面量（共享层 JSDoc：
+  // 引用一变即把组件本地乐观成员表重置回该值，拖拽中分区跳变）
+  const boardSubGrouping = useMemo(
+    () =>
+      subGroupBy && subGroupBy !== "none"
+        ? buildBugSubGrouping(subGroupBy, columns, users)
+        : undefined,
+    [subGroupBy, columns, users],
+  );
+
+  // 共享组件 memo 契约：config 函数字段引用稳定 → config 整体 useMemo，
+  // 依赖内的回调由消费方（list-view）useCallback 保证
+  const config = useMemo(
+    () =>
+      buildBoardConfig({
+        columns,
+        groupBy,
+        subGroupBy,
+        subGrouping: boardSubGrouping,
+        properties,
+        users,
+        onOpenBug,
+        onLoadMoreColumn,
+        onPatchBug,
+        onReorder,
+        onAutoSwitchManual,
+        onRefresh,
+        updateBug: (input) =>
+          updateBugFn({
+            data: { ...input, lastOccurAt: input.lastOccurAt ?? undefined },
+          }) as Promise<unknown>,
+      }),
+    [
+      columns,
+      groupBy,
+      subGroupBy,
+      boardSubGrouping,
+      properties,
+      users,
+      onOpenBug,
+      onLoadMoreColumn,
+      onPatchBug,
+      onReorder,
+      onAutoSwitchManual,
+      onRefresh,
+    ],
+  );
+
+  return <KanbanBoardView config={config} />;
+}