@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -15,7 +15,7 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-import React, { lazy, Suspense, useCallback, useEffect, useRef, useState, type LazyExoticComponent, type ComponentType } from "react";
+import React, { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState, type LazyExoticComponent, type ComponentType, type ReactElement, type ReactNode } from "react";
 import {
   ChevronsDownUp,
   ChevronsUpDown,
@@ -27,7 +27,6 @@ import {
   ClockArrowUp,
 } from "lucide-react";
 import { UserAvatar } from "@/components/shared-kit";
-import { Input } from "@/components/ui/input";
 
 import { Skeleton } from "@/components/ui/skeleton";
 import { Button } from "@/components/ui/button";
@@ -39,8 +38,9 @@ import { toast } from "@/components/ui/toast";
 import type { StoryDetail, UserBrief, CommentWithReplies, ActivityItem, ReactionGroup, RelationsData } from "../types";
 import { parseStoryDescription, serializeStoryDescription } from "../types";
 import type { StoryState } from "../constants";
+import type { StoryPatch } from "../display/group-fields";
 import { ActivityTabs } from "./activity-tabs";
-import { EmojiPicker } from "./emoji-picker";
+import { EmojiPicker } from "@/components/shared-kit/comments/emoji-picker";
 import { StoryAiToolbar } from "../ai/story-ai-toolbar";
 import { useStoryAiModel } from "../ai/use-story-ai-model";
 import { StateEditor, PriorityEditor, AssigneeEditor, DateEditor } from "../inline-editors";
@@ -53,6 +53,15 @@ import { useDebouncer } from "@/lib/pacer";
 
 import type { NotionDocEditorProps } from "@/components/tiptap/notion-like";
 import { errorMessage } from "@/lib/toast-error";
+import { buildRoomName } from "@allbluecn/collab-core/rooms";
+import { getUserColor } from "@/lib/collab/user-color";
+import { useCollabDoc } from "@/lib/collab/use-collab-doc";
+import type { CollabProviderHandle } from "@/lib/collab/provider";
+import { useCollabFields } from "@/lib/collab/bindings/fields";
+import { useSelfProfileBroadcast } from "@/lib/collab/use-self-profile-broadcast";
+import type { NotionEditorCollabExtensions } from "@/components/tiptap/notion-like/editor-extensions";
+import { FieldEditingPill } from "@/components/collab/field-editing-pill";
+import { useSession } from "@/components/shared-kit/auth/auth-client";
 const NotionDocEditor = lazy(() => import("@/components/tiptap/notion-like").then(m => ({ default: m.NotionDocEditor }))) as LazyExoticComponent<ComponentType<NotionDocEditorProps>>;
 
 /**
@@ -66,29 +75,136 @@ const NotionDocEditor = lazy(() => import("@/components/tiptap/notion-like").the
  */
 const DESCRIPTION_FLUSH_DEBOUNCE_MS = 8000;
 
-export function StoryDetailBody({
-  story,
-  users,
-  comments,
-  activities,
-  currentUserId,
-  layout = "split",
-  identifier,
-  project,
-  noScroll,
-  labels,
-  stories,
-  projects,
-  iterations,
-  relationsData,
-  onRelationsUpdate,
-  onAppendActivities,
-  onAppendComment,
-  onRemoveComment,
-  onStoryUpdate,
-  onNavigateInPanel,
-  breadcrumbItems,
-}: {
+/**
+ * 协同态绑定 fields Y.Map 的字段清单（entity room Y 结构契约，§7.1 Story 行）。
+ * 覆盖本组件全部 DB 写通道对应的字段：标题/状态/优先级/负责人/起止日期/标签/
+ * 父需求——协同写手活跃期这些字段一律写 Y（exporter 落库），DB 通道短路。
+ * iteration 在本组件只做本地 UI 回显（无 serverFn 写通道），不入 Y。
+ */
+const STORY_COLLAB_FIELDS = [
+  "name",
+  "state",
+  "priority",
+  "assigneeId",
+  "startDate",
+  "targetDate",
+  "labelIds",
+  "parentId",
+] as const;
+
+/** 协同运行时状态（StoryCollabGate render-prop 产物；结构对齐任务 15 口径） */
+interface StoryCollabRuntimeState {
+  /** 协同配置（null = 会话未就绪/协同不可用，编辑器暂不挂载协同扩展） */
+  config: NotionEditorCollabExtensions | null;
+  /** 会话是否就绪（协同配置稳定后再挂编辑器，防 caret user 半截装配） */
+  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: StoryCollabRuntimeState = {
+  config: null,
+  ready: true,
+  offline: false,
+  connecting: false,
+  collabActive: false,
+  handle: null,
+  identity: null,
+};
+
+interface StoryCollabGateProps {
+  storyId: string;
+  snapshot: string | null;
+  children: (state: StoryCollabRuntimeState) => ReactNode;
+}
+
+/**
+ * 协同运行时装配（条件挂载于 collab 分支，非协同路径不产生任何协同 hook
+ * 观察/连接——结构对齐任务 15 CollabDocGate）：会话 brief（caret 用户 + 字段
+ * editing 署名）+ entity room 建连/快照预水合/状态订阅。
+ */
+function StoryCollabGate({ storyId, snapshot, children }: StoryCollabGateProps) {
+  const { data: session, isPending } = useSession();
+  const roomName = useMemo(
+    () => buildRoomName({ kind: "entity-story", storyId }),
+    [storyId],
+  );
+  const { handle, status } = useCollabDoc({ roomName, snapshot });
+  // 自身 profile 广播：字段 binding 的 identity 缺省路径（会话 pending 期间
+  // 创建 binding）读 awareness profile 兜底署名——无广播则 editing 标记降级
+  // 为 client:{clientID}（远端 pill 无名）。Story 详情无 presence 头像组，
+  // 广播在本 gate 自持（hook 自 collab-presence-header 提取复用）。
+  useSelfProfileBroadcast(handle);
+
+  const user = session?.user?.id
+    ? {
+        name: session.user.name || session.user.id,
+        color: getUserColor(session.user.id),
+      }
+    : null;
+
+  const config: NotionEditorCollabExtensions | null =
+    handle && user
+      ? {
+          ydoc: handle.doc,
+          // noop/awareness 缺失时不挂 Caret（扩展工厂按 provider 判定）
+          provider: handle.awareness ? handle : null,
+          user,
+        }
+      : null;
+
+  // I1 钉住（同任务 15）：扩展集在编辑器创建时冻结，config 一旦非空就沿用
+  // 首个非空值——防中途回落 null 时 stale 内容经仍在位的 Collaboration 插件
+  // 写进 Y 并同步给协作者（协同内容静默回滚）。
+  const pinnedConfigRef = useRef<NotionEditorCollabExtensions | null>(null);
+  if (pinnedConfigRef.current === null && config !== null) {
+    pinnedConfigRef.current = config;
+  }
+  const effectiveConfig = pinnedConfigRef.current;
+
+  // 会话就绪但拿不到 user（_nav beforeLoad 守卫下不应发生）时不进协同态：
+  // collabActive=false 让 DB 保存链路兜底，防「编辑器非 Y 绑定 + DB 短路」双失能
+  const sessionUsable = isPending || user != null;
+
+  return (
+    <>
+      {children({
+        config: effectiveConfig,
+        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,
+      })}
+    </>
+  );
+}
+
+/** 详情面板可回写视图（列表/看板乐观更新）的字段集合——与 StoryPatch 对齐。
+ *  projectId 不在其中（项目归属变更走专门的转移流程，不在此通道）。 */
+const PATCHABLE_FIELDS = new Set<keyof StoryPatch>([
+  "name",
+  "state",
+  "priority",
+  "assigneeId",
+  "startDate",
+  "targetDate",
+]);
+
+export interface StoryDetailBodyProps {
   story: StoryDetail;
   users: UserBrief[];
   comments: CommentWithReplies[];
@@ -114,14 +230,152 @@ export function StoryDetailBody({
   onAppendComment?: (comment: CommentWithReplies) => void;
   onRemoveComment?: (commentId: string) => void;
   onStoryUpdate?: (s: StoryDetail) => void;
+  /** 字段落库成功后的补丁回调（PeekPanel 回写列表/看板做乐观更新） */
+  onStoryPatch?: (storyId: string, patch: StoryPatch) => void;
   onNavigateInPanel?: (targetId: string, targetIdentifier?: string, relationKind?: "child" | "dependency") => void;
+  onOpenEntity?: (entity: import("../types").StoryEntityOverlay) => void;
+  /** 用例/BUG 行的面板内叠加打开（peek 传入；缺省整页跳转） */
   /** 内嵌面板导航面包屑（在面板内跳转时替代单层 identifier 显示） */
   breadcrumbItems?: Array<{ identifier?: string; projectId?: string; label: string; onClick?: () => void }>;
-}) {
+  /** 编辑器实例就绪回调（透传 NotionDocEditor.onEditorReady；测试观察点） */
+  onEditorReady?: (editor: Editor) => void;
+  /**
+   * 协同模式（Yjs 多人协作任务 20，规格 §7.1 Story 行）：true 时 description
+   * 接 Collaboration（Y fragment 'default'）+ 字段接 useCollabFields，全部
+   * 保存通道（8s 防抖 / 失焦 / 卸载 / meta 字段 / 标签 / 父需求）短路——
+   * Y 是唯一写手；offline 降级恢复 DB 链路。缺省 false = 现有单机链路逐字保留。
+   */
+  collab?: boolean;
+  /** SSR 协同快照（loader 并行取 getCollabSnapshotFn；collab=true 时必传，null = 空文档） */
+  collabSnapshot?: string | null;
+}
+
+/** memo：顶栏滚动标题等轻量 state 翻转时，详情巨树（面板/行列表）必须整体跳过
+ * 重渲染，否则越阈一次卡几百毫秒、标题延迟出现。调用方回调需 useCallback 稳定。 */
+export const StoryDetailBody = React.memo(function StoryDetailBody(props: StoryDetailBodyProps) {
+  const { collab, collabSnapshot, ...bodyProps } = props;
+  // 协同双模式：collab=true 时 gate 组件持有 useSession/useCollabDoc（条件
+  // 挂载——非协同路径不产生任何协同 hook 观察/连接）；其余完全同分支。
+  if (collab) {
+    return (
+      <StoryCollabGate storyId={bodyProps.story.id} snapshot={collabSnapshot ?? null}>
+        {(collabState) => (
+          <StoryDetailBodyInner
+            {...bodyProps}
+            collabEnabled
+            collabState={collabState}
+          />
+        )}
+      </StoryCollabGate>
+    );
+  }
+  return (
+    <StoryDetailBodyInner
+      {...bodyProps}
+      collabEnabled={false}
+      collabState={NON_COLLAB_STATE}
+    />
+  );
+});
+
+function StoryDetailBodyInner({
+  story,
+  users,
+  comments,
+  activities,
+  currentUserId,
+  layout = "split",
+  identifier,
+  project,
+  noScroll,
+  labels,
+  stories,
+  projects,
+  iterations,
+  relationsData,
+  onRelationsUpdate,
+  onAppendActivities,
+  onAppendComment,
+  onRemoveComment,
+  onStoryUpdate,
+  onStoryPatch,
+  onNavigateInPanel,
+  onOpenEntity,
+  breadcrumbItems,
+  onEditorReady: onEditorReadyProp,
+  collabEnabled,
+  collabState,
+}: StoryDetailBodyProps & { collabEnabled: boolean; collabState: StoryCollabRuntimeState }) {
   const [name, setName] = useState(story.name);
+  // 本详情页会话内新建的标签（labels prop/loader 清单不含；并入后 chip 才能渲染名字）
+  const [createdLabels, setCreatedLabels] = useState<{ id: string; name: string; color: string }[]>([]);
+  const mergedLabels = useMemo(() => {
+    const base = [...(labels ?? []), ...createdLabels];
+    const seen = new Set<string>();
+    return base.filter((l) => (seen.has(l.id) ? false : (seen.add(l.id), true)));
+  }, [labels, createdLabels]);
+  const handleLabelCreated = (label: { id: string; name: string; color: string }) => {
+    setCreatedLabels((prev) => (prev.some((l) => l.id === label.id) ? prev : [...prev, label]));
+  };
   useEffect(() => {
     setName(story.name);
   }, [story.name]);
+
+  // ── 协同态运行时（任务 20）──────────────────────────────────────────
+  // 核心不变式（对齐任务 15）：任一时刻只有一条保存链路活跃。
+  //   collabActive（connecting/synced）→ Y 唯一写手，DB 全通道短路；
+  //   offline（降级单机）→ DB 通道恢复，Y 仅作编辑器内部内容源。
+  const fields = useCollabFields(
+    collabState.handle,
+    STORY_COLLAB_FIELDS,
+    collabState.identity ? { identity: collabState.identity } : undefined,
+  );
+  const collabActiveRef = useRef(collabState.collabActive);
+  collabActiveRef.current = collabState.collabActive;
+
+  // 协同态展示覆盖：Y 已写的字段（非 undefined）覆盖 loader story 值——
+  // 远端字段变化实时回写本地 UI（§7.1「不再手动 F5」）。非协同恒等 story。
+  const fieldsValues = fields.values;
+  const effectiveStory = useMemo(() => {
+    if (!collabEnabled) return story;
+    const next: StoryDetail = { ...story };
+    if (typeof fieldsValues.name === "string") next.name = fieldsValues.name;
+    if (typeof fieldsValues.state === "string") next.state = fieldsValues.state as StoryDetail["state"];
+    if (typeof fieldsValues.priority === "string") next.priority = fieldsValues.priority as StoryDetail["priority"];
+    if (fieldsValues.assigneeId !== undefined) {
+      next.assignee =
+        fieldsValues.assigneeId == null
+          ? null
+          : users.find((u) => u.id === fieldsValues.assigneeId) ?? null;
+    }
+    if (fieldsValues.startDate !== undefined) next.startDate = fieldsValues.startDate as string | null;
+    if (fieldsValues.targetDate !== undefined) next.targetDate = fieldsValues.targetDate as string | null;
+    if (Array.isArray(fieldsValues.labelIds)) {
+      const ids = fieldsValues.labelIds as string[];
+      next.labels = mergedLabels.filter((l) => ids.includes(l.id));
+    }
+    if (fieldsValues.parentId !== undefined) {
+      const parentId = fieldsValues.parentId as string | null;
+      next.parentId = parentId;
+      if (!parentId) {
+        next.parent = null;
+      } else {
+        const found = stories?.find((s) => s.id === parentId);
+        next.parent = found
+          ? { id: found.id, title: found.name, status: found.state, identifier: found.identifier }
+          : null;
+      }
+    }
+    return next;
+  }, [collabEnabled, story, fieldsValues, users, mergedLabels, stories]);
+
+  // 协同：远端 name 改动实时回写本地输入框（与既有 story.name 回显同语义；
+  // 本地 blur 写 Y 后 yName 变化与本地值一致，setName 幂等）
+  const yName = collabEnabled ? fieldsValues.name : undefined;
+  useEffect(() => {
+    if (typeof yName === "string") setName(yName);
+  }, [yName]);
+
   const parsedDesc = parseStoryDescription(story.description);
   const [descContent, setDescContent] = useState(parsedDesc);
   const [saving, setSaving] = useState(false);
@@ -194,6 +448,7 @@ export function StoryDetailBody({
 
   const onEditorReady = useCallback((editor: Editor) => {
     editorRef.current = editor;
+    onEditorReadyProp?.(editor);
     requestAnimationFrame(checkOverflow);
     editor.on("focus", () => {
       setExpanded(true);
@@ -201,7 +456,7 @@ export function StoryDetailBody({
     editor.on("update", () => {
       requestAnimationFrame(checkOverflow);
     });
-  }, [checkOverflow]);
+  }, [checkOverflow, onEditorReadyProp]);
 
   // Click outside the editor area → unfocus
   useEffect(() => {
@@ -219,12 +474,19 @@ export function StoryDetailBody({
     setIsEditorFocused(true);
   }, []);
 
+  // 保存通道守卫（审查重点 #3）：协同写手活跃期 DB 通道全部短路——Y 是唯一
+  // 写手（exporter 落库，任务 21）；降级（offline）自动恢复。防御性收敛在
+  // 各通道入口，未来新增调用点不需要记得检查协同态。
   const updateField = async (field: string, value: string | null) => {
+    if (collabEnabled && collabActiveRef.current) return;
     setSaving(true);
     try {
       const res = await updateStoryFn({ data: { storyId: story.id, [field]: value } });
       const updated = { ...story, ...res.story } as unknown as StoryDetail;
       onStoryUpdate?.(updated);
+      if (onStoryPatch && PATCHABLE_FIELDS.has(field as keyof StoryPatch)) {
+        onStoryPatch(story.id, { [field]: value } as StoryPatch);
+      }
       if (res.activities.length > 0) onAppendActivities?.(res.activities);
     } catch (err) {
       toast.error(m.story_detail_saveFailed(), {
@@ -236,11 +498,13 @@ export function StoryDetailBody({
   };
 
   const updateLabels = async (labelIds: string[]) => {
+    if (collabEnabled && collabActiveRef.current) return;
     setSaving(true);
     try {
       const res = await updateStoryFn({ data: { storyId: story.id, labelIds } });
       const updated = { ...story, ...res.story } as unknown as StoryDetail;
       onStoryUpdate?.(updated);
+      onStoryPatch?.(story.id, { labelIds });
       if (res.activities.length > 0) onAppendActivities?.(res.activities);
     } catch (err) {
       toast.error(m.story_detail_saveFailed(), {
@@ -252,6 +516,7 @@ export function StoryDetailBody({
   };
 
   const updateParent = async (parentId: string | null) => {
+    if (collabEnabled && collabActiveRef.current) return;
     setSaving(true);
     try {
       const res = await updateStoryFn({ data: { storyId: story.id, parentId } });
@@ -277,8 +542,52 @@ export function StoryDetailBody({
     }
   };
 
+  // 协同 name 通道：blur 写 Y（远端 pill 由 setEditing 标记）
+  const handleCollabNameBlur = () => {
+    fields.setEditing("name", false);
+    const trimmed = name.trim();
+    if (!trimmed || trimmed === effectiveStory.name) return;
+    fields.setValue("name", trimmed);
+  };
+
+  // 协同字段写手分派：collabActive → Y（本地立即生效 + 增量广播）；降级 → DB
+  const fieldWrite = (field: string, value: string | null) => {
+    if (collabEnabled && collabActiveRef.current) {
+      fields.setValue(field, value);
+      return;
+    }
+    updateField(field, value);
+  };
+
+  const collabWriteParent = (parentId: string | null) => {
+    if (collabEnabled && collabActiveRef.current) {
+      fields.setValue("parentId", parentId);
+      return;
+    }
+    updateParent(parentId);
+  };
+
+  const collabWriteLabels = (labelIds: string[]) => {
+    if (collabEnabled && collabActiveRef.current) {
+      fields.setValue("labelIds", labelIds);
+      return;
+    }
+    updateLabels(labelIds);
+  };
+
+  // 卸载守卫：卸载后 flush 的成功回调不得再触发（peek 面板内导航时旧 body
+  // 的落盘成功若仍回写 onStoryUpdate，会把已切换到的新需求数据污染成旧的）
+  const unmountedRef = useRef(false);
+  useEffect(() => {
+    return () => {
+      unmountedRef.current = true;
+    };
+  }, []);
   const flushDescription = useCallback(() => {
     flushDebouncer.cancel();
+    // 协同写手活跃（connecting/synced）：描述的 DB 通道短路（Y 唯一写手）；
+    // 失焦 / 卸载 / 兜底防抖三条触发路径都汇聚到这里，一处守卫全覆盖
+    if (collabEnabled && collabActiveRef.current) return;
     const content = pendingDescRef.current;
     if (!content) return;
     pendingDescRef.current = null;
@@ -288,13 +597,18 @@ export function StoryDetailBody({
     updateStoryFn({ data: { storyId: story.id, description: json } })
       .then((res) => {
         lastPersistedRef.current = json;
+        // 落库成功即数据安全；卸载后（面板内已切到其他需求）不再回写视图
+        if (unmountedRef.current) return;
         const updated = { ...story, ...res.story } as unknown as StoryDetail;
         onStoryUpdate?.(updated);
         if (res.activities.length > 0) onAppendActivities?.(res.activities);
       })
-      .catch((err) => toast.error(m.story_detail_saveFailed(), { description: errorMessage(err, m.story_comment_retry()) }))
+      .catch((err) => {
+        if (unmountedRef.current) return;
+        toast.error(m.story_detail_saveFailed(), { description: errorMessage(err, m.story_comment_retry()) });
+      })
       .finally(() => setSaving(false));
-  }, [story.id, story, onAppendActivities, onStoryUpdate, flushDebouncer]);
+  }, [story.id, story, onAppendActivities, onStoryUpdate, flushDebouncer, collabEnabled]);
 
   // 用 ref 持有最新 flush 实现，避免 handleDescriptionChange / 失焦 / 卸载 effect
   // 依赖 flushDescription 的 deps 变化而反复触发。
@@ -305,11 +619,52 @@ export function StoryDetailBody({
 
   // 编辑器内容变化时只累积最新内容到 pendingDescRef，不立即保存。
   // 兜底防抖避免用户长时间不操作也最终落盘（防崩溃丢数据）。
+  // 协同态（含远端 update 触发的 onChange）：Y 已吸收全部事务（Collaboration
+  // 扩展挂载于编辑器），不进 pendingDescRef、不武装 8s 兜底防抖——8s 防抖让位。
   const handleDescriptionChange = useCallback((content: { html: string; markdown: string }) => {
-    pendingDescRef.current = content;
     setIsDescEmpty(!content.markdown.trim());
+    if (collabEnabled && collabActiveRef.current) {
+      // descContent 仅供 AI 工具栏取新鲜正文（content prop 已被协同配置忽略）
+      setDescContent(content);
+      return;
+    }
+    pendingDescRef.current = content;
     flushDebouncer.maybeExecute();
-  }, [flushDebouncer]);
+  }, [flushDebouncer, collabEnabled]);
+
+  // 降级/恢复切换语义（核心不变式：任一时刻只有一条保存链路活跃）：
+  //   切 offline 瞬间——把编辑器当前内容（含协同期 Y 独占、未落库的编辑）搬进
+  //   pendingDescRef 并立即 flush，旧 DB 链路由此接管；切回 collabActive 瞬间
+  //   ——清除 DB 保存意图（未到期的兜底防抖到期时被 flushDescription 守卫
+  //   短路），Y 继续增量同步，无内容丢失、无双写。
+  const prevCollabActiveRef = useRef(collabState.collabActive);
+  useEffect(() => {
+    if (!collabEnabled) return;
+    if (prevCollabActiveRef.current === collabState.collabActive) return;
+    prevCollabActiveRef.current = collabState.collabActive;
+    if (!collabState.collabActive) {
+      const ed = editorRef.current;
+      if (ed && !ed.isDestroyed) {
+        pendingDescRef.current = {
+          html: ed.getHTML(),
+          markdown:
+            (ed.storage.markdown as { manager?: { serialize?: (json: unknown) => string } } | undefined)
+              ?.manager?.serialize?.(ed.getJSON()) ?? "",
+        };
+        flushDescriptionRef.current();
+      }
+    } else {
+      pendingDescRef.current = null;
+      flushDebouncer.cancel();
+    }
+  }, [collabState.collabActive, collabEnabled, flushDebouncer]);
+
+  // 协同：描述编辑标记随编辑器焦点写/摘 awareness（远端见 description pill）
+  const setDescEditing = fields.setEditing;
+  useEffect(() => {
+    if (!collabEnabled) return;
+    setDescEditing("description", isEditorFocused);
+  }, [isEditorFocused, collabEnabled, setDescEditing]);
 
   // 编辑器失焦 → 立即提交本次编辑会话累积的内容（一次连续编辑 = 一条活动记录）
   useEffect(() => {
@@ -326,37 +681,76 @@ export function StoryDetailBody({
 
   const handleAiApply = useCallback((newMarkdown: string) => {
     if (editorRef.current) {
+      // 协同态 setContent 经 Collaboration 插件写进 Y（增量广播给协作者）
       editorRef.current.commands.setContent(newMarkdown);
     }
     const newContent = { html: newMarkdown, markdown: newMarkdown };
     setDescContent(newContent);
     setIsDescEmpty(!newMarkdown.trim());
+    // 协同写手活跃：DB 通道短路（Y 已含 AI 改写结果，exporter 落库）
+    if (collabEnabled && collabActiveRef.current) return;
     const json = serializeStoryDescription(newMarkdown, newMarkdown);
     lastPersistedRef.current = json;
     updateField("description", json);
-  }, [updateField]);
+  }, [updateField, collabEnabled]);
 
   // 截止日期已过期（未完成/未取消）→ 红色，与子需求列表样式一致
+  // （协同态读 effectiveStory——远端改 state/targetDate 实时生效）
   const dueOverdue = !!(
-    story.targetDate &&
-    story.state !== "done" &&
-    story.state !== "cancelled" &&
-    new Date(story.targetDate.slice(0, 10)) < new Date(new Date().toISOString().slice(0, 10))
+    effectiveStory.targetDate &&
+    effectiveStory.state !== "done" &&
+    effectiveStory.state !== "cancelled" &&
+    new Date(effectiveStory.targetDate.slice(0, 10)) < new Date(new Date().toISOString().slice(0, 10))
   );
 
+  // 协同：字段旁 pill 包装（仅协同态挂载；非协同保持原 JSX 结构逐字一致）
+  const withPill = (fieldName: string, editor: ReactElement) =>
+    collabEnabled ? (
+      <div className="flex items-center gap-1">
+        {editor}
+        <FieldEditingPill fieldName={fieldName} editors={fields.editingBy[fieldName]} users={users} />
+      </div>
+    ) : (
+      editor
+    );
+
+  // 协同：popover 编辑器的 open 状态外泄为 editing 标记（open=写、close=摘）
+  const editMarkProps = (fieldName: string) =>
+    collabEnabled
+      ? { onOpenChange: (open: boolean) => fields.setEditing(fieldName, open) }
+      : {};
+
   const metaBar = (
-    <div className="flex flex-wrap items-center gap-2 px-6">
-      <StateEditor value={story.state} onChange={(v) => updateField("state", v)} variant="button" />
-      <PriorityEditor value={story.priority} onChange={(v) => updateField("priority", v)} variant="button" />
-      <AssigneeEditor assignee={story.assignee} users={users} onChange={(v) => updateField("assigneeId", v)} variant="button" />
-      <DateEditor value={story.startDate} onChange={(v) => updateField("startDate", v)} label={m.story_detail_startDate()} icon={CalendarPlus2} />
-      <DateEditor value={story.targetDate} onChange={(v) => updateField("targetDate", v)} label={m.story_detail_dueDate()} icon={CalendarCheck} overdue={dueOverdue} />
+    <div className="flex flex-wrap items-center gap-2 px-3">
+      {withPill("state", <StateEditor value={effectiveStory.state} onChange={(v) => fieldWrite("state", v)} variant="button" {...editMarkProps("state")} />)}
+      {withPill("priority", <PriorityEditor value={effectiveStory.priority} onChange={(v) => fieldWrite("priority", v)} variant="button" {...editMarkProps("priority")} />)}
+      {withPill("assigneeId", <AssigneeEditor assignee={effectiveStory.assignee} users={users} onChange={(v) => fieldWrite("assigneeId", v)} variant="button" {...editMarkProps("assigneeId")} />)}
+      {withPill("startDate", <DateEditor value={effectiveStory.startDate} onChange={(v) => fieldWrite("startDate", v)} label={m.story_detail_startDate()} icon={CalendarPlus2} {...editMarkProps("startDate")} />)}
+      {withPill("targetDate", <DateEditor value={effectiveStory.targetDate} onChange={(v) => fieldWrite("targetDate", v)} label={m.story_detail_dueDate()} icon={CalendarCheck} overdue={dueOverdue} {...editMarkProps("targetDate")} />)}
     </div>
   );
 
   const main = (
     <>
-      <div className="flex items-start justify-between gap-4 px-6">
+      {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>
+      )}
+      <div className="flex items-start justify-between gap-4 px-3">
         <div className="flex-1 space-y-4">
           <div className="flex items-center gap-2">
             {breadcrumbItems && breadcrumbItems.length > 0 ? (
@@ -412,16 +806,31 @@ export function StoryDetailBody({
             )}
           </div>
           {/* {saving && <span className="text-xs text-muted-foreground">保存中...</span>} */}
-          <Input
+          <textarea
             value={name}
+            rows={1}
+            aria-label={m.story_inline_titlePlaceholder()}
             onChange={(e) => setName(e.target.value)}
-            onBlur={saveName}
-            className="border-0 px-0 text-2xl md:text-2xl font-semibold shadow-none focus-visible:ring-0"
+            onFocus={collabEnabled ? () => fields.setEditing("name", true) : undefined}
+            onBlur={collabEnabled ? handleCollabNameBlur : saveName}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && !e.shiftKey) {
+                e.preventDefault();
+                e.currentTarget.blur();
+              }
+            }}
+            className="block w-full resize-none border-0 px-0 text-2xl leading-8 md:text-2xl font-semibold shadow-none outline-none field-sizing-content bg-transparent dark:bg-transparent focus:bg-input/30 dark:focus:bg-input/30"
           />
         </div>
       </div>
       {metaBar}
       <div ref={editorContainerRef} className={`relative notion-full-width${!isEditorFocused && isDescEmpty ? " story-editor-no-placeholder" : ""}`} style={{ "--notion-content-width": "1fr", "--notion-margin-width": "0px" } as React.CSSProperties} onPointerDown={onEditorPointerDown}>
+        {/* 协同：description 编辑 pill（编辑器右上角；§10.1 字段型行） */}
+        {collabEnabled && (
+          <div className="absolute top-2 right-4 z-10">
+            <FieldEditingPill fieldName="description" editors={fields.editingBy.description} users={users} />
+          </div>
+        )}
         <div className={!expanded && needsTruncation ? "max-h-[90px] overflow-hidden" : ""}>
           <Suspense fallback={
             <div className="flex flex-col space-y-2 p-3 min-h-24">
@@ -430,17 +839,20 @@ export function StoryDetailBody({
               <Skeleton className="h-4 w-2/3" />
             </div>
           }>
-            <NotionDocEditor
-              key={story.id}
-              content={descContent}
-              onChange={handleDescriptionChange}
-              showHeader={false}
-              hideInsertButton
-              hideAi
-              editorClassName="story-editor !ml-0"
-              onEditorReady={onEditorReady}
-              disableMobileFullscreen
-            />
+            {collabState.ready && (
+              <NotionDocEditor
+                key={story.id}
+                content={collabState.config ? undefined : descContent}
+                onChange={handleDescriptionChange}
+                showHeader={false}
+                hideInsertButton
+                hideAi
+                editorClassName="story-editor !ml-0"
+                onEditorReady={onEditorReady}
+                disableMobileFullscreen
+                collab={collabState.config ?? undefined}
+              />
+            )}
           </Suspense>
         </div>
                 {!isEditorFocused && isDescEmpty && (
@@ -452,14 +864,14 @@ export function StoryDetailBody({
           <div className="absolute bottom-0 left-0 right-0 h-16 bg-gradient-to-t from-background to-transparent pointer-events-none" />
         )}
       </div>
-      <div className="px-6">
+      <div className="px-3">
         <div className="flex items-center gap-2">
           <div className="flex min-w-0 flex-1 items-center gap-1.5">
             {needsTruncation && (
               <Button
                 variant="ghost"
                 size="sm"
-                className="h-6 shrink-0 pl-0 pr-2 text-xs text-muted-foreground"
+                className="h-6 shrink-0 -ml-2 px-2 text-xs text-muted-foreground"
                 onClick={() => setExpanded(!expanded)}
               >
                 {expanded ? (
@@ -535,7 +947,7 @@ export function StoryDetailBody({
                 <Button
                   variant="ghost"
                   size="sm"
-                  className="h-7 gap-1 pl-0 pr-2 text-xs text-muted-foreground"
+                  className="h-7 gap-1 px-2 text-xs text-muted-foreground"
                 >
                   <SmilePlus className="size-3.5" />
                   {m.story_detail_addReaction()}
@@ -571,33 +983,36 @@ export function StoryDetailBody({
             storyId={story.id}
             storyIdentifier={identifier}
             projectId={story.projectId}
+            storyUpdatedAt={effectiveStory.updatedAt}
             data={relationsData}
             onRefresh={onRelationsUpdate ?? (() => { })}
             onAppendActivities={onAppendActivities}
             users={users}
             projects={projects?.map((p) => ({ ...p, displayId: p.displayId ?? null }))}
-            labels={labels}
+            labels={mergedLabels}
             onNavigateInPanel={onNavigateInPanel}
+            onOpenEntity={onOpenEntity}
           />
         </div>
       )}
 
       <StoryProperties
         story={{
-          id: story.id,
-          name: story.name,
-          description: story.description,
-          parentId: story.parentId,
-          parent: story.parent,
-          labels: story.labels,
-          projectId: story.projectId,
-          iteration: story.iteration ?? null,
+          id: effectiveStory.id,
+          name: effectiveStory.name,
+          description: effectiveStory.description,
+          parentId: effectiveStory.parentId,
+          parent: effectiveStory.parent,
+          labels: effectiveStory.labels,
+          projectId: effectiveStory.projectId,
+          iteration: effectiveStory.iteration ?? null,
         }}
-        labels={labels}
+        labels={mergedLabels}
         projects={projects}
         iterations={iterations}
-        onParentChange={updateParent}
-        onLabelsChange={updateLabels}
+        onParentChange={collabWriteParent}
+        onLabelsChange={collabWriteLabels}
+        onLabelCreated={handleLabelCreated}
         onIterationChange={(it) => {
           if (onStoryUpdate) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -607,7 +1022,7 @@ export function StoryDetailBody({
         onActivities={onAppendActivities}
       />
 
-      <div className="px-6 py-3  space-y-3.5">
+      <div className="px-3 py-3  space-y-3.5">
         <div className="flex items-center gap-2 text-xs">
           <CircleUser className="size-4 shrink-0 text-muted-foreground" />
           <span className="text-muted-foreground shrink-0">{m.story_detail_createdBy()}</span>
@@ -632,7 +1047,10 @@ export function StoryDetailBody({
 
   if (layout === "stack") {
     return (
-      <div className={`flex min-h-0 flex-1 flex-col ${noScroll ? "" : "overflow-y-auto"}`}>
+      <div
+        data-slot="story-detail-scroll"
+        className={`flex min-h-0 flex-1 flex-col overflow-x-hidden ${noScroll ? "" : "overflow-y-auto"}`}
+      >
         <div className="flex-1 space-y-4 pt-6 pb-6">{main}</div>
       </div>
     );
@@ -640,7 +1058,14 @@ export function StoryDetailBody({
 
   return (
     <div className={`flex min-h-0 flex-1 ${noScroll ? "" : "overflow-hidden"}`}>
-      <div className={`flex-1 space-y-4 pt-6 pb-6 ${noScroll ? "" : "overflow-y-auto"}`}>{main}</div>
+      {/* padding 放内层：sticky（tabs/面板头）的约束矩形是滚动容器减去 padding，
+          padding 挂在滚动层会让吸顶元素永远留一条 padding 高的缝 */}
+      <div
+        data-slot="story-detail-scroll"
+        className={`flex-1 overflow-x-hidden ${noScroll ? "" : "overflow-y-auto"}`}
+      >
+        <div className="space-y-4 pt-6 pb-6">{main}</div>
+      </div>
     </div>
   );
 }