@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/bug/detail/bug-detail-body.tsx

@@ -18,7 +18,15 @@
 // BUG 详情主体（规格 §5.4 分区骨架）。peek 侧滑与 /bugs/$bugId 独立路由共用。
 // 本任务交付 1-6 分区（6=AI 复现报告卡片，任务 27）+ 7（AI 修复时间线，任务 22）+ 8。
 // 活动/评论 tab 数据由任务 12 接入。
-import { lazy, Suspense, useEffect, useRef, useState, type LazyExoticComponent, type ComponentType } from "react";
+//
+// 协同双模式（Yjs 多人协作任务 22，§7.1 entity:bug 行；结构对齐任务 20 的
+// story-detail-body）：collab=true 时字段（title/state/severity/assigneeId/
+// labelIds/env）接 useCollabFields、步骤（reproduceSteps.steps）接 useCollabSteps
+// 只读视图、全部保存通道短路——Y 是唯一写手；offline 降级恢复 DB 链路（轻量版
+// 取舍同 T20：降级期不做本地补写队列，DB 直写经 §5.3 门卫路由）。
+// S12 裁决：description 本期不接协同编辑——只读渲染恒走 loader DTO，不挂
+// Collaboration 扩展（room 结构自然预留：种子化/门卫转发/exporter 回写照常）。
+import { lazy, Suspense, useEffect, useMemo, useRef, useState, type LazyExoticComponent, type ComponentType, type ReactNode } from "react";
 import { Archive, CalendarClock, Hash, LoaderCircle, Sparkles } from "lucide-react";
 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
@@ -29,9 +37,16 @@ import { toast } from "@/components/ui/toast";
 import { requestBugFixFn, updateBugFn } from "@/server/serverFns/bug";
 import { formatTimestamp } from "@/lib/datetime";
 import { SOURCE_LABEL } from "@/shared/bug/constants";
-import type { BugDetail, BugStoryBrief } from "../types";
+import type { BugDetail, BugStoryBrief, ReproduceSteps } from "../types";
 import type { UserBrief } from "@/components/story/types";
 import { parseStoryDescription } from "@/components/story/types";
+import { buildRoomName } from "@allbluecn/collab-core/rooms";
+import { useSession } from "@/components/shared-kit/auth/auth-client";
+import { useCollabDoc } from "@/lib/collab/use-collab-doc";
+import type { CollabProviderHandle } from "@/lib/collab/provider";
+import { useCollabFields, type UseCollabFieldsResult } from "@/lib/collab/bindings/fields";
+import { useCollabSteps } from "@/lib/collab/bindings/steps";
+import { useSelfProfileBroadcast } from "@/lib/collab/use-self-profile-broadcast";
 import { PropsSection } from "./props-section";
 import { ReproduceStepsView } from "./reproduce-steps-view";
 import { ErrorContext } from "./error-context";
@@ -46,28 +61,188 @@ import type { NotionDocEditorProps } from "@/components/tiptap/notion-like";
 import { toastError } from "@/lib/toast-error";
 const NotionDocEditor = lazy(() => import("@/components/tiptap/notion-like").then((mod) => ({ default: mod.NotionDocEditor }))) as LazyExoticComponent<ComponentType<NotionDocEditorProps>>;
 
+/**
+ * entity room 的 Y 属主字段清单（任务 22）——与服务端
+ * serverFns/bug/bug-crud.ts 的 BUG_Y_OWNED_FIELDS 镜像，两侧必须同步维护
+ * （漏字段 = 旁路写互吞/协同态丢写）。
+ */
+const BUG_COLLAB_FIELDS = [
+  "title",
+  "state",
+  "severity",
+  "assigneeId",
+  "labelIds",
+  "env",
+] as const;
+
+/** 协同运行时状态（BugCollabGate render-prop 产物；结构对齐任务 20 口径） */
+interface BugCollabRuntimeState {
+  /** 会话是否就绪 */
+  ready: boolean;
+  /** provider offline（降级单机模式，提示条 + 旧保存链路） */
+  offline: boolean;
+  /** provider connecting（建连窗口，轻提示条；窗口内 Y 是唯一写手） */
+  connecting: boolean;
+  /** 协同写手活跃（connecting/synced 均算——Y 是唯一写手，DB 链路短路） */
+  collabActive: boolean;
+  /** room 连接句柄（字段/步骤 binding 数据源；null = 非协同/noop） */
+  handle: CollabProviderHandle | null;
+  /** 字段 editing 标记署名（session brief；null 走 binding 内 profile/clientID 降级） */
+  identity: { userId: string; name: string } | null;
+}
+
+/** 非协同分支的协同状态常量（稳定引用，行为与既有单机链路逐字一致） */
+const NON_COLLAB_STATE: BugCollabRuntimeState = {
+  ready: true,
+  offline: false,
+  connecting: false,
+  collabActive: false,
+  handle: null,
+  identity: null,
+};
+
+interface BugCollabGateProps {
+  bugId: string;
+  snapshot: string | null;
+  children: (state: BugCollabRuntimeState) => ReactNode;
+}
+
+/**
+ * 协同运行时装配（条件挂载于 collab 分支，非协同路径不产生任何协同 hook
+ * 观察/连接——结构对齐任务 20 StoryCollabGate；S12：无 TipTap Collaboration
+ * 配置，description 只读渲染不挂协同扩展）。
+ */
+function BugCollabGate({ bugId, snapshot, children }: BugCollabGateProps) {
+  const { data: session, isPending } = useSession();
+  const roomName = useMemo(
+    () => buildRoomName({ kind: "entity-bug", bugId }),
+    [bugId],
+  );
+  const { handle, status } = useCollabDoc({ roomName, snapshot });
+  // 自身 profile 广播：字段 binding 的 identity 缺省路径读 awareness profile
+  // 兜底署名（同 StoryCollabGate；Bug 详情无 presence 头像组，广播自持）
+  useSelfProfileBroadcast(handle);
+
+  // 会话就绪但拿不到 user（_nav beforeLoad 守卫下不应发生）时不进协同态：
+  // collabActive=false 让 DB 保存链路兜底，防「Y 无写手 + DB 短路」双失能
+  const sessionUsable = isPending || session?.user?.id != null;
+
+  return (
+    <>
+      {children({
+        ready: !isPending,
+        offline: status === "offline",
+        connecting: status === "connecting",
+        collabActive: sessionUsable && status !== null && status !== "offline",
+        handle,
+        identity:
+          session?.user?.id
+            ? { userId: session.user.id, name: session.user.name || session.user.id }
+            : null,
+      })}
+    </>
+  );
+}
+
 interface BugDetailBodyProps {
   bug: BugDetail;
   users: UserBrief[];
   labels: { id: string; name: string; color: string }[];
+  /** peek 紧凑元信息：ID+来源 左、累计+最近发生 右（justify-between） */
+  compactMeta?: boolean;
+  /** 二级页（面包屑已含 ID）：隐藏整个元信息行 */
+  hideIdentifierRow?: boolean;
   /** 任一属性编辑成功后回传服务端返回的完整 bug（peek/路由层同步本地状态） */
   onBugUpdate: (bug: BugDetail) => void;
+  /**
+   * 协同模式（Yjs 多人协作任务 22，§7.1 Bug 行）：true 时字段接
+   * useCollabFields、steps 接 useCollabSteps（只读视图），title/props/env
+   * 保存通道短路——Y 是唯一写手；offline 降级恢复 DB 链路。缺省 false =
+   * 现有单机链路逐字保留（peek 侧滑不传，恒单机）。
+   */
+  collab?: boolean;
+  /** SSR 协同快照（loader 并行取 getCollabSnapshotFn；collab=true 时必传，null = 空文档） */
+  collabSnapshot?: string | null;
 }
 
-export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBodyProps) {
+export function BugDetailBody(props: BugDetailBodyProps) {
+  const { collab, collabSnapshot, ...bodyProps } = props;
+  // 协同双模式：collab=true 时 gate 组件持有 useSession/useCollabDoc（条件
+  // 挂载——非协同路径不产生任何协同 hook 观察/连接）；其余完全同分支。
+  if (collab) {
+    return (
+      <BugCollabGate bugId={bodyProps.bug.id} snapshot={collabSnapshot ?? null}>
+        {(collabState) => (
+          <BugDetailBodyInner {...bodyProps} collabEnabled collabState={collabState} />
+        )}
+      </BugCollabGate>
+    );
+  }
+  return <BugDetailBodyInner {...bodyProps} collabEnabled={false} collabState={NON_COLLAB_STATE} />;
+}
+
+function BugDetailBodyInner({
+  bug,
+  users,
+  labels,
+  onBugUpdate,
+  compactMeta = false,
+  hideIdentifierRow = false,
+  collabEnabled,
+  collabState,
+}: BugDetailBodyProps & { collabEnabled: boolean; collabState: BugCollabRuntimeState }) {
   const [title, setTitle] = useState(bug.title);
   const titleRef = useRef<HTMLInputElement>(null);
+  const titleFocusedRef = useRef(false);
   // 「AI 修复」请求成功后递增：驱动 FixTimeline 与活动流重取（fix_requested/run 落库）
   const [fixRefreshKey, setFixRefreshKey] = useState(0);
   const [fixRequesting, setFixRequesting] = useState(false);
+  // 「AI 修复」竞态守卫（BUG 模块交付时遗留竞态收口）：peek 上下条导航/路由跳转
+  // 会销毁旧详情实例（消费方 key={bug.id}），旧请求的迟到响应不得再 toast/setState
+  // ——否则「已发起」提示会弹在切换后的 BUG 上。三重校验：
+  //   fixSeqRef——同实例双击窗口内后发请求序号更大，旧响应整体作废；
+  //   bugIdRef——实例被复用且 bug 已变（防御性；key 约定下换 id 必重建）；
+  //   fixUnmountedRef——实例已卸载。命中任一：整体丢弃（不 setState 不 toast），
+  //   fixRequesting 不回置由实例销毁兜底。
+  const fixSeqRef = useRef(0);
+  const fixBugIdRef = useRef(bug.id);
+  fixBugIdRef.current = bug.id;
+  const fixUnmountedRef = useRef(false);
+  useEffect(() => () => { fixUnmountedRef.current = true; }, []);
   // 「AI 复现」run 结束后递增：驱动活动流重取（ai_repro_completed 落库）
   const [reproRefreshKey, setReproRefreshKey] = useState(0);
 
+  // ── 协同态运行时（任务 22）──────────────────────────────────────────
+  // 核心不变式（对齐任务 15/20）：任一时刻只有一条保存链路活跃。
+  //   collabActive（connecting/synced）→ Y 唯一写手，DB 全通道短路；
+  //   offline（降级单机）→ DB 通道恢复，Y 仅作展示源。
+  const fields = useCollabFields(
+    collabState.handle,
+    BUG_COLLAB_FIELDS,
+    collabState.identity ? { identity: collabState.identity } : undefined,
+  );
+  const collabSteps = useCollabSteps(collabState.handle);
+  const collabActiveRef = useRef(collabState.collabActive);
+  collabActiveRef.current = collabState.collabActive;
+
+  // 标题输入协同值流：Y 已写值实时回写本地输入（失焦时——聚焦期不打字），
+  // 未写 key 回退 loader 值。展示与保存通道共用 titleValue。
+  const fieldsValues = fields.values;
+  const yTitle = typeof fieldsValues.title === "string" ? fieldsValues.title : null;
   useEffect(() => {
-    setTitle(bug.title);
-  }, [bug.title]);
+    if (!collabEnabled) return;
+    if (yTitle === null) return;
+    if (titleFocusedRef.current) return;
+    setTitle((prev) => (prev === yTitle ? prev : yTitle));
+  }, [collabEnabled, yTitle]);
+
+  const titleValue =
+    collabEnabled && collabActiveRef.current && yTitle !== null ? yTitle : title;
 
   const saveTitle = async () => {
+    fields.setEditing("title", false);
+    // 协同写手活跃：Y 唯一写手，DB 通道短路（值已随输入即时写 Y）
+    if (collabEnabled && collabActiveRef.current) return;
     const next = title.trim();
     if (!next || next === bug.title) {
       setTitle(bug.title);
@@ -83,17 +258,33 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
     }
   };
 
+  // 协同标题通道：失焦写 Y（值流 onChange 已即时写——见 onChange 分派）
+  const handleTitleChange = (next: string) => {
+    setTitle(next);
+    if (collabEnabled && collabActiveRef.current) {
+      fields.setValue("title", next);
+    }
+  };
+
   const handleStoryChange = (story: BugStoryBrief | null) => {
     onBugUpdate({ ...bug, storyId: story?.id ?? null, story });
   };
 
   // 「AI 修复」（§10.3 手动触发）：created → toast + 时间线/活动流重取；
-  // conflict → 结构化返回提示已存在（服务端不抛错）
+  // conflict → 结构化返回提示已存在（服务端不抛错）。
+  // 竞态守卫：响应返回时实例已卸载 / bug 已切换 / 序号被后发请求超越则整体丢弃
   const handleRequestFix = async () => {
     if (fixRequesting) return;
     setFixRequesting(true);
+    const seq = ++fixSeqRef.current;
+    const requestBugId = bug.id;
+    const stale = () =>
+      fixUnmountedRef.current ||
+      fixBugIdRef.current !== requestBugId ||
+      seq !== fixSeqRef.current;
     try {
-      const res = await requestBugFixFn({ data: { bugId: bug.id } });
+      const res = await requestBugFixFn({ data: { bugId: requestBugId } });
+      if (stale()) return;
       if (res.status === "created") {
         toast.success(m.bug_fix_requested_toast());
         setFixRefreshKey((k) => k + 1);
@@ -106,9 +297,12 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
         );
       }
     } catch (e) {
+      if (stale()) return;
       toastError(e, m.bug_fix_action_failed());
     } finally {
-      setFixRequesting(false);
+      // 丢弃分支不回置（严格「不 setState」）：按钮态随实例销毁重置；
+      // 仅同实例最新请求（seq 未被超越且未卸载未换 bug）有权回置
+      if (!stale()) setFixRequesting(false);
     }
   };
 
@@ -116,12 +310,81 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
   const hasErrorContext = bug.source !== "manual" || !!bug.stackSummary || !!bug.url || !!bug.userAgent;
   const sourceLabel = SOURCE_LABEL[bug.source]?.() ?? bug.source;
 
+  // 协同步骤展示流：Y 已写步骤（种子化/远端/本地写入）覆盖 loader DTO——
+  // 远端步骤变化实时回写只读视图（§7.1「不再手动 F5」）。空 Y.Array = Y 无
+  // 意见（业务 schema 步骤 min(1)），回退 DTO；expectedResult/actualResult
+  // 不归 Y，恒取 DTO。非协同恒等 DTO。
+  const effectiveSteps: ReproduceSteps | null = useMemo(() => {
+    if (!collabEnabled || collabSteps.steps.length === 0) return bug.reproduceSteps;
+    return {
+      steps: collabSteps.steps.map((step, index) => ({
+        order: index + 1,
+        action: step.action,
+        ...(step.expected !== "" && { expected: step.expected }),
+      })),
+      expectedResult: bug.reproduceSteps?.expectedResult,
+      actualResult: bug.reproduceSteps?.actualResult,
+    };
+  }, [collabEnabled, collabSteps.steps, bug.reproduceSteps]);
+
+  // 协同展示覆盖：Y 已写字段（非 undefined）覆盖 loader bug 值——远端字段
+  // 变化实时回写属性区（§7.1）。非协同恒等 bug。
+  const effectiveBug: BugDetail = useMemo(() => {
+    if (!collabEnabled) return bug;
+    const next: BugDetail = { ...bug };
+    if (typeof fieldsValues.title === "string") next.title = fieldsValues.title;
+    if (typeof fieldsValues.state === "string") next.state = fieldsValues.state as BugDetail["state"];
+    if (typeof fieldsValues.severity === "string") next.severity = fieldsValues.severity as BugDetail["severity"];
+    if (fieldsValues.assigneeId !== undefined) {
+      next.assignee =
+        fieldsValues.assigneeId == null
+          ? null
+          : users.find((u) => u.id === fieldsValues.assigneeId) ?? null;
+    }
+    if (Array.isArray(fieldsValues.labelIds)) {
+      const ids = fieldsValues.labelIds.filter((id): id is string => typeof id === "string");
+      next.labels = ids
+        .map((id) => labels.find((l) => l.id === id))
+        .filter((l): l is { id: string; name: string; color: string } => l != null);
+    }
+    if (fieldsValues.env !== undefined) {
+      next.env = fieldsValues.env == null ? null : String(fieldsValues.env);
+    }
+    return next;
+  }, [collabEnabled, bug, fieldsValues, users, labels]);
+
   return (
     <div className="flex min-h-0 flex-1 flex-col">
-      <div className="min-h-0 flex-1 overflow-y-auto" style={{ scrollbarGutter: "stable" } as React.CSSProperties}>
+      {collabEnabled && collabState.connecting && (
+        <div
+          data-testid="collab-connecting-banner"
+          role="status"
+          className="bg-sky-500/10 text-sky-700 dark:text-sky-400 border-b border-sky-500/20 text-xs px-4 py-1.5 text-center"
+        >
+          {m.collab_connectingBanner()}
+        </div>
+      )}
+      {collabEnabled && collabState.offline && (
+        <div
+          data-testid="collab-offline-banner"
+          role="status"
+          className="bg-amber-500/10 text-amber-700 dark:text-amber-400 border-b border-amber-500/20 text-xs px-4 py-1.5 text-center"
+        >
+          {m.collab_offlineBanner()}
+        </div>
+      )}
+      {/* data-slot：BugPanelHeader 顶栏滚动渐显标题的滚动源（story-detail-scroll 同款，capture 监听） */}
+      <div data-slot="bug-detail-scroll" className="min-h-0 flex-1 overflow-y-auto" style={{ scrollbarGutter: "stable" } as React.CSSProperties}>
         {/* ① 头部：identifier + 来源/计数元信息 + 标题行内编辑 */}
         <header className="space-y-1 px-6 pt-4 pb-3">
-          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+          <div
+            className={
+              compactMeta
+                ? "flex items-center justify-between gap-2 text-xs text-muted-foreground"
+                : "flex flex-wrap items-center gap-2 text-xs text-muted-foreground"
+            }
+          >
+            {!hideIdentifierRow && (
             <Tooltip>
               <TooltipTrigger
                 render={
@@ -141,14 +404,19 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
               </TooltipTrigger>
               <TooltipContent>{m.story_detail_clickToCopy()}</TooltipContent>
             </Tooltip>
+            )}
             <Badge variant="outline" className="px-1.5 py-0 text-xs font-normal">
               {sourceLabel}
             </Badge>
+            {hideIdentifierRow ? null : (
+            <>
             <span className="inline-flex items-center gap-1">
               <CalendarClock className="size-3" />
               {m.bug_list_occurrences({ count: bug.totalCount })}
             </span>
             <span>{m.bug_list_last_occur()} {formatTimestamp(bug.lastOccurAt)}</span>
+            </>
+            )}
             {bug.archived && (
               <Badge variant="outline" className="gap-1 px-1.5 py-0 text-xs font-normal">
                 <Archive className="size-3" />
@@ -159,9 +427,16 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
           <div className="flex items-start gap-2">
             <Input
               ref={titleRef}
-              value={title}
-              onChange={(e) => setTitle(e.target.value)}
-              onBlur={() => void saveTitle()}
+              value={titleValue}
+              onChange={(e) => handleTitleChange(e.target.value)}
+              onFocus={() => {
+                titleFocusedRef.current = true;
+                fields.setEditing("title", true);
+              }}
+              onBlur={() => {
+                titleFocusedRef.current = false;
+                void saveTitle();
+              }}
               onKeyDown={(e) => {
                 if (e.key === "Enter") {
                   e.preventDefault();
@@ -191,10 +466,25 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
           </div>
         </header>
 
-        {/* ② 属性区 */}
-        <PropsSection bug={bug} users={users} labels={labels} onBugUpdate={onBugUpdate} onStoryChange={handleStoryChange} />
+        {/* ② 属性区（协同态字段写手分派见 PropsSection collabProps） */}
+        <PropsSection
+          bug={effectiveBug}
+          users={users}
+          labels={labels}
+          onBugUpdate={onBugUpdate}
+          onStoryChange={handleStoryChange}
+          collabProps={
+            collabEnabled
+              ? {
+                  collabActive: collabActiveRef.current,
+                  setValue: fields.setValue,
+                  setEditing: fields.setEditing,
+                }
+              : undefined
+          }
+        />
 
-        {/* ③ 描述（TipTap 只读渲染） */}
+        {/* ③ 描述（TipTap 只读渲染；S12 裁决：协同期同样只读，不接 Collaboration） */}
         <section className="space-y-2 border-t px-6 py-4">
             <h3 className="text-sm font-semibold">{m.bug_create_description_label()}</h3>
             {descContent.markdown || descContent.html ? (
@@ -225,8 +515,8 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
             )}
         </section>
 
-        {/* ④ 复现步骤视图 */}
-        <ReproduceStepsView steps={bug.reproduceSteps} />
+        {/* ④ 复现步骤视图（协同态由 Y steps 驱动——远端变更实时刷新；只读） */}
+        <ReproduceStepsView steps={effectiveSteps} />
 
         {/* ⑤ 错误上下文（SDK/扩展/收集页来源）+ 事件样本时间线 */}
         {hasErrorContext && (
@@ -262,3 +552,11 @@ export function BugDetailBody({ bug, users, labels, onBugUpdate }: BugDetailBody
     </div>
   );
 }
+
+/** PropsSection 协同写手分派入参（collabEnabled 时由 BugDetailBody 注入） */
+export interface PropsSectionCollabProps {
+  /** 协同写手活跃（false = 降级走 DB 通道） */
+  collabActive: boolean;
+  setValue: UseCollabFieldsResult["setValue"];
+  setEditing: UseCollabFieldsResult["setEditing"];
+}

package/src/components/bug/detail/comment-item.tsx

@@ -35,6 +35,7 @@ import { toast } from "@/components/ui/toast";
 import type { BugCommentWithReplies } from "../types";
 import { formatRelative } from "./activity-timeline";
 import { CommentInput } from "./comment-input";
+import { CommentReactions } from "./comment-reactions";
 import { m } from "@/paraglide/messages.js";
 
 interface CommentItemProps {
@@ -96,11 +97,12 @@ export function CommentItem({ bugId, comment, onAppendComment, onRemoveComment }
 
   return (
     <div className="space-y-3">
-      <div className="flex gap-3">
+      {/* group/comment：hover 评论主体（不含回复区）时显出 CommentReactions 的快捷按钮 */}
+      <div className="group/comment flex gap-3">
         <UserAvatar
           name={comment.user.username}
           avatarConfig={comment.user.avatarConfig}
-          bgShape={comment.user.bgShape as "circle" | "rounded" | "square" | null}
+          bgShape={comment.user.bgShape}
           bgColor={comment.user.bgColor}
           size="sm"
           className="shrink-0"
@@ -159,6 +161,9 @@ export function CommentItem({ bugId, comment, onAppendComment, onRemoveComment }
             <p className="text-sm whitespace-pre-wrap">{displayContent}</p>
           )}
 
+          {/* 评论级表情回应（chips + hover 快捷 + picker）；空聚合时不占视觉位 */}
+          <CommentReactions commentId={comment.id} reactions={comment.reactions} />
+
           <div className="flex items-center gap-3">
             <button
               type="button"

package/src/components/bug/detail/comment-reactions.tsx

@@ -0,0 +1,138 @@
+// 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 评论级表情回应（任务 39，BUG 侧首个真实接线——story 的 reaction-bar 是零
+// 消费者死代码、story comment-item 的 handleReaction 无 JSX 调用点，均未照抄）。
+// 三段式：chips 渲染 listCommentsFn 聚合的 ReactionGroup（emoji+count+reacted
+// 高亮）+ hover 快捷常用 emoji（CSS group-hover 显隐，禁 React state）+
+// EmojiPicker 完整网格。乐观更新：点击即按 reacted 标记本地翻转（userIds 不动，
+// UI 不消费该字段），toggleBugCommentReactionFn 的权威聚合返回后整体覆盖；
+// 失败回滚 + toast。由 comment-item.tsx JSX 实际调用（死代码教训：必须有调用点）。
+import { useRef, useState } from "react";
+import { SmilePlus } from "lucide-react";
+import { EmojiPicker } from "@/components/shared-kit/comments/emoji-picker";
+import { toast } from "@/components/ui/toast";
+import { toggleBugCommentReactionFn } from "@/server/serverFns/bug";
+import type { ReactionGroup } from "@/components/story/types";
+import { m } from "@/paraglide/messages.js";
+
+/** hover 快捷回应（常用 3 个；完整选择走 picker） */
+const QUICK_EMOJIS = ["👍", "❤️", "🎉"];
+
+interface CommentReactionsProps {
+  commentId: string;
+  reactions: ReactionGroup[];
+}
+
+/** 本地乐观翻转一组聚合：未表态 +1 高亮、已表态 -1（减到 0 移除该 chip）、
+ * 全新 emoji 追加。userIds 保持原样/空数组——UI 只消费 emoji/count/reacted，
+ * 权威结果返回后整体覆盖 */
+function toggleGroupsLocally(groups: ReactionGroup[], emoji: string): ReactionGroup[] {
+  const idx = groups.findIndex((g) => g.emoji === emoji);
+  if (idx === -1) {
+    return [...groups, { emoji, count: 1, userIds: [], reacted: true }];
+  }
+  const group = groups[idx]!;
+  if (group.reacted) {
+    if (group.count <= 1) return groups.filter((g) => g.emoji !== emoji);
+    return groups.map((g, i) => (i === idx ? { ...g, count: g.count - 1, reacted: false } : g));
+  }
+  return groups.map((g, i) => (i === idx ? { ...g, count: g.count + 1, reacted: true } : g));
+}
+
+export function CommentReactions({ commentId, reactions }: CommentReactionsProps) {
+  // 乐观覆盖态：null 跟随 props；toggle 后先本地翻转、权威聚合返回再覆盖
+  const [override, setOverride] = useState<ReactionGroup[] | null>(null);
+  // 同一 emoji 连点防抖（story 级 pendingReactionsRef 同款守卫，实例级隔离）
+  const pendingRef = useRef<Set<string>>(new Set());
+  const display = override ?? reactions;
+
+  const toggle = async (emoji: string) => {
+    if (pendingRef.current.has(emoji)) return;
+    pendingRef.current.add(emoji);
+    const base = override ?? reactions;
+    setOverride(toggleGroupsLocally(base, emoji));
+    try {
+      const groups = await toggleBugCommentReactionFn({
+        data: { commentId, emoji },
+      });
+      setOverride(groups);
+    } catch (err) {
+      // 回滚到点击前状态。并发多 emoji 期间前者失败会连带重置后者的乐观态，
+      // 由后者的权威响应自愈——单表情失败是常态路径，不为极端并发加复杂度
+      setOverride(base);
+      toast.error(m.bug_comment_reactionFailed(), {
+        description: err instanceof Error ? err.message : m.bug_comment_retry(),
+      });
+    } finally {
+      pendingRef.current.delete(emoji);
+    }
+  };
+
+  const sorted = display.slice().sort((a, b) => b.count - a.count);
+
+  return (
+    // hover 域挂在评论主体（comment-item 的 avatar+内容行 group/comment）：
+    // 快捷按钮与 picker 触发器 hover 评论时显出，纯 CSS 无 React state
+    <div className="flex items-center gap-1">
+      {sorted.map((group) => (
+        <button
+          key={group.emoji}
+          type="button"
+          data-testid={`reaction-chip-${group.emoji}`}
+          aria-pressed={group.reacted}
+          onClick={() => void toggle(group.emoji)}
+          className={`flex h-6 items-center gap-1 rounded-full border px-2 text-xs transition-colors ${
+            group.reacted
+              ? "border-primary/40 bg-primary/10 text-foreground hover:bg-primary/20"
+              : "border-input bg-muted/50 text-muted-foreground hover:bg-muted"
+          }`}
+        >
+          <span>{group.emoji}</span>
+          <span className="text-[10px]">{group.count}</span>
+        </button>
+      ))}
+      <span
+        data-testid="quick-reactions"
+        // 触屏降级：hover:none 设备 group-hover 永不触发，快捷栏/picker 入口
+        // 恒隐藏不可达——媒体查询常显。Tailwind v4 无 hover:none 标准变体，
+        // 任意值变体为唯一表达（项目内首处，后续同场景照抄）
+        className="hidden items-center gap-0.5 group-hover/comment:inline-flex [@media(hover:none)]:inline-flex"
+      >
+        {QUICK_EMOJIS.map((emoji) => (
+          <button
+            key={emoji}
+            type="button"
+            onClick={() => void toggle(emoji)}
+            className="flex h-6 w-6 items-center justify-center rounded-full text-sm transition-colors hover:bg-muted"
+          >
+            {emoji}
+          </button>
+        ))}
+        <EmojiPicker onPick={(emoji) => void toggle(emoji)} width={320} height={380}>
+          <button
+            type="button"
+            aria-label={m.bug_comment_addReaction()}
+            className="flex h-6 w-6 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+          >
+            <SmilePlus className="size-3.5" />
+          </button>
+        </EmojiPicker>
+      </span>
+    </div>
+  );
+}