@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/testcase/detail/case-detail-body.tsx

@@ -20,7 +20,15 @@
 // 关联 Bug）。编辑走 updateTestCaseFn expectedVersion 乐观锁（case-row 同口径：
 // 内容面乐观 bump、失败回滚到服务端收敛 DTO、只允许最新一次编辑收敛视图）。
 // 路由侧 key={case.id} 强挂载防 $id 导航复用实例（AGENTS.md 陷阱）。
-import { useCallback, useEffect, useRef, useState } from "react";
+//
+// 协同双模式（Yjs 多人协作任务 22，§7.1 entity:case 行；结构对齐任务 20/22
+// story/bug 详情）：collab=true 时字段（title/precondition/type/priority/
+// state/assigneeId）接 useCollabFields、steps 接 useCollabSteps + StepEditor
+// 粒度操作（步骤可编辑），Y 属主保存通道短路——Y 是唯一写手；非 Y 字段
+// （folderId/storyId/automation）照旧 serverFn 但不带 expectedVersion（协同
+// 落库 version 由服务端 exporter 维护，客户端版本基线不可信）；offline 降级
+// 恢复既有 DB 链路（乐观锁行为零变化）。
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link } from "@tanstack/react-router";
 import { useServerFn } from "@tanstack/react-start";
 import { ArrowLeft } from "lucide-react";
@@ -34,6 +42,14 @@ import type {
 import type { UserBrief } from "@/components/story/types";
 import type { FolderNodeDto } from "../folder-tree";
 import type { TestCaseUpdatePatch } from "../list/case-row";
+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 } from "@/lib/collab/bindings/fields";
+import { useCollabSteps, type CollabStepValue } from "@/lib/collab/bindings/steps";
+import { useSelfProfileBroadcast } from "@/lib/collab/use-self-profile-broadcast";
+import { StepEditor } from "../step-editor";
 import { CaseActivityTimeline } from "./activity";
 import { CaseExecHistory } from "./exec-history";
 import { CaseProperties } from "./properties";
@@ -51,16 +67,129 @@ const CONTENT_FIELDS: readonly (keyof TestCaseUpdatePatch)[] = [
   "priority",
 ];
 
+/**
+ * entity room 的 Y 属主字段清单（任务 22）——与服务端
+ * serverFns/testcase/testcase-crud.ts 的 CASE_Y_OWNED_FIELDS 镜像，两侧必须
+ * 同步维护（漏字段 = 旁路写互吞/协同态丢写）。steps 面走 useCollabSteps
+ * （Y.Array），不在此列。
+ */
+const CASE_COLLAB_FIELDS = [
+  "title",
+  "precondition",
+  "type",
+  "priority",
+  "state",
+  "assigneeId",
+] as const;
+
+/** 协同运行时状态（CaseCollabGate render-prop 产物；结构对齐 bug 详情口径） */
+interface CaseCollabRuntimeState {
+  /** 会话是否就绪 */
+  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: CaseCollabRuntimeState = {
+  ready: true,
+  offline: false,
+  connecting: false,
+  collabActive: false,
+  handle: null,
+  identity: null,
+};
+
+interface CaseCollabGateProps {
+  caseId: string;
+  snapshot: string | null;
+  children: (state: CaseCollabRuntimeState) => React.ReactNode;
+}
+
+/**
+ * 协同运行时装配（条件挂载于 collab 分支，非协同路径不产生任何协同 hook
+ * 观察/连接——结构对齐 bug 详情 BugCollabGate）。
+ */
+function CaseCollabGate({ caseId, snapshot, children }: CaseCollabGateProps) {
+  const { data: session, isPending } = useSession();
+  const roomName = useMemo(
+    () => buildRoomName({ kind: "entity-case", caseId }),
+    [caseId],
+  );
+  const { handle, status } = useCollabDoc({ roomName, snapshot });
+  // 自身 profile 广播：字段 binding 的 identity 缺省路径读 awareness profile
+  // 兜底署名（同 story/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 CaseDetailBodyProps {
   testCase: TestCaseDetail;
   users: UserBrief[];
   folders: FolderNodeDto[];
   activities: TestCaseActivityItem[];
+  /**
+   * 协同模式（Yjs 多人协作任务 22，§7.1 Case 行）：true 时字段接
+   * useCollabFields、steps 接 useCollabSteps（StepEditor 粒度操作可编辑），
+   * Y 属主保存通道短路；非 Y 字段照旧 serverFn（不带 expectedVersion）。
+   * 缺省 false = 现有单机链路逐字保留。
+   */
+  collab?: boolean;
+  /** SSR 协同快照（loader 并行取 getCollabSnapshotFn；collab=true 时必传，null = 空文档） */
+  collabSnapshot?: string | null;
 }
 
 type DetailTab = "activity" | "exec" | "bugs" | "automation";
 
-export function CaseDetailBody({ testCase, users, folders, activities }: CaseDetailBodyProps) {
+export function CaseDetailBody(props: CaseDetailBodyProps) {
+  const { collab, collabSnapshot, ...bodyProps } = props;
+  // 协同双模式：collab=true 时 gate 组件持有 useSession/useCollabDoc（条件
+  // 挂载——非协同路径不产生任何协同 hook 观察/连接）；其余完全同分支。
+  if (collab) {
+    return (
+      <CaseCollabGate caseId={bodyProps.testCase.id} snapshot={collabSnapshot ?? null}>
+        {(collabState) => <CaseDetailBodyInner {...bodyProps} collabEnabled collabState={collabState} />}
+      </CaseCollabGate>
+    );
+  }
+  return <CaseDetailBodyInner {...bodyProps} collabEnabled={false} collabState={NON_COLLAB_STATE} />;
+}
+
+function CaseDetailBodyInner({
+  testCase,
+  users,
+  folders,
+  activities,
+  collabEnabled,
+  collabState,
+}: CaseDetailBodyProps & { collabEnabled: boolean; collabState: CaseCollabRuntimeState }) {
   const updateTestCase = useServerFn(updateTestCaseFn);
   const [caseState, setCaseState] = useState<TestCaseDetail>(testCase);
   const [name, setName] = useState(testCase.title);
@@ -72,13 +201,105 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
   const serverCaseRef = useRef<TestCaseDetail>(testCase);
   const storyRefRef = useRef<TestCaseStoryRef | null>(testCase.story);
   const editSeqRef = useRef(0);
+  const titleFocusedRef = useRef(false);
+
+  // ── 协同态运行时（任务 22）──────────────────────────────────────────
+  // 核心不变式（对齐任务 15/20/22 bug）：任一时刻只有一条保存链路活跃。
+  //   collabActive（connecting/synced）→ Y 唯一写手，Y 属主 DB 通道短路；
+  //   offline（降级单机）→ DB 通道恢复（乐观锁行为零变化）。
+  const fields = useCollabFields(
+    collabState.handle,
+    CASE_COLLAB_FIELDS,
+    collabState.identity ? { identity: collabState.identity } : undefined,
+  );
+  const collabSteps = useCollabSteps(collabState.handle);
+  const collabActiveRef = useRef(collabState.collabActive);
+  collabActiveRef.current = collabState.collabActive;
+
+  const fieldsValues = fields.values;
+
+  // 标题输入协同值流：Y 已写值实时回写本地输入（失焦时），未写 key 回退 loader 值
+  const yTitle = typeof fieldsValues.title === "string" ? fieldsValues.title : null;
+  useEffect(() => {
+    if (!collabEnabled) return;
+    if (yTitle === null) return;
+    if (titleFocusedRef.current) return;
+    setName((prev) => (prev === yTitle ? prev : yTitle));
+  }, [collabEnabled, yTitle]);
+
+  // 协同展示覆盖：Y 已写字段（非 undefined）覆盖 loader testCase 值——远端
+  // 字段变化实时回写 UI（§7.1「不再手动 F5」）。非协同恒等 testCase。
+  const effectiveCase = useMemo(() => {
+    if (!collabEnabled) return caseState;
+    const next: TestCaseDetail = { ...caseState };
+    if (typeof fieldsValues.title === "string") next.title = fieldsValues.title;
+    if (fieldsValues.precondition !== undefined) {
+      next.precondition = fieldsValues.precondition == null ? null : String(fieldsValues.precondition);
+    }
+    if (typeof fieldsValues.type === "string") next.type = fieldsValues.type as TestCaseDetail["type"];
+    if (typeof fieldsValues.priority === "string") next.priority = fieldsValues.priority as TestCaseDetail["priority"];
+    if (typeof fieldsValues.state === "string") next.state = fieldsValues.state as TestCaseDetail["state"];
+    if (fieldsValues.assigneeId !== undefined) {
+      next.assignee =
+        fieldsValues.assigneeId == null
+          ? null
+          : users.find((u) => u.id === fieldsValues.assigneeId) ?? null;
+    }
+    return next;
+  }, [collabEnabled, caseState, fieldsValues, users]);
 
   useEffect(() => {
-    setName(caseState.title);
-  }, [caseState.title]);
+    setName(effectiveCase.title);
+  }, [effectiveCase.title]);
 
   const applyPatch = useCallback(
     async (patch: TestCaseUpdatePatch, storyRef?: TestCaseStoryRef | null) => {
+      // ── 协同写手活跃：Y 属主字段写 Y（保存通道短路）；剩余非 Y 字段
+      // （folderId/storyId/automation）照旧 serverFn 但不带 expectedVersion——
+      // 协同落库 version+1 由服务端 exporter 维护，客户端版本基线不可信。
+      if (collabActiveRef.current) {
+        let rest: TestCaseUpdatePatch | undefined;
+        for (const [key, value] of Object.entries(patch)) {
+          if ((CASE_COLLAB_FIELDS as readonly string[]).includes(key)) {
+            fields.setValue(key, value as unknown);
+          } else {
+            rest = rest ?? {};
+            (rest as Record<string, unknown>)[key] = value;
+          }
+        }
+        if (rest === undefined) return;
+        // story 引用客户端 ref 锚定（同既有路径：服务端 Summary 不含 story）
+        const isStoryPatch = rest.storyId !== undefined;
+        const capturedStoryRef = isStoryPatch ? (storyRef ?? null) : undefined;
+        if (capturedStoryRef !== undefined) storyRefRef.current = capturedStoryRef;
+        setCaseState((prev) => {
+          const view: Partial<TestCaseDetail> = { ...rest };
+          if (rest!.assigneeId !== undefined) {
+            view.assignee = users.find((u) => u.id === rest!.assigneeId) ?? null;
+          }
+          if (capturedStoryRef !== undefined) view.story = capturedStoryRef;
+          return { ...prev, ...view };
+        });
+        try {
+          const updated = await updateTestCase({ data: { id: testCase.id, ...rest } });
+          const converged: TestCaseDetail = {
+            ...updated,
+            story: capturedStoryRef !== undefined ? capturedStoryRef : storyRefRef.current,
+          };
+          serverCaseRef.current = converged;
+          setCaseState((prev) => ({
+            ...converged,
+            // story 引用以客户端 ref 为准（服务端 Summary 不含 story）
+            story: prev.story,
+          }));
+        } catch (e) {
+          setCaseState(serverCaseRef.current);
+          toastError(e, m.testcase_row_updateFailed());
+        }
+        return;
+      }
+
+      // ── 非协同既有路径（逐字保留）：expectedVersion 乐观锁
       const seq = ++editSeqRef.current;
       const expectedVersion = versionRef.current;
       const bumped = CONTENT_FIELDS.some((k) => patch[k] !== undefined);
@@ -126,7 +347,7 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
         toastError(e, m.testcase_row_updateFailed());
       }
     },
-    [testCase.id, users, updateTestCase],
+    [testCase.id, users, updateTestCase, fields, fieldsValues.title],
   );
 
   const handleStoryChange = useCallback(
@@ -137,11 +358,28 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
   );
 
   const saveTitle = () => {
+    fields.setEditing("title", false);
+    // 协同写手活跃：Y 唯一写手，DB 通道短路（值已随输入即时写 Y）
+    if (collabEnabled && collabActiveRef.current) return;
     const trimmed = name.trim();
     if (!trimmed || trimmed === caseState.title) return;
     void applyPatch({ title: trimmed });
   };
 
+  const handleTitleChange = (next: string) => {
+    setName(next);
+    if (collabEnabled && collabActiveRef.current) {
+      fields.setValue("title", next);
+    }
+  };
+
+  // 协同步骤编辑（§7.1 steps 行）：Y 已写步骤（服务端种子化保证非空——
+  // 防双端并发首写重复）时渲染可编辑 StepEditor，逐操作映射 Y 增量
+  // （插入/删除/移动/字段 LWW 各自一次 Y 写，并发语义见 bindings/steps）。
+  // 空数组（Y 无意见/降级期）回退既有只读视图。
+  const stepsEditable = collabEnabled && collabActiveRef.current && collabSteps.steps.length > 0;
+  const stepDrafts: CollabStepValue[] = collabSteps.steps;
+
   const tabLabels: Record<DetailTab, string> = {
     activity: m.testcase_detail_tabActivity(),
     exec: m.testcase_detail_tabExecHistory(),
@@ -151,6 +389,24 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
 
   return (
     <div className="flex h-full min-h-0 flex-col px-6" data-testid="case-detail">
+      {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 -mx-6 px-6 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 -mx-6 px-6 py-1.5 text-center"
+        >
+          {m.collab_offlineBanner()}
+        </div>
+      )}
       <div className="flex h-11 shrink-0 items-center gap-2">
         <Link
           to="/test-cases"
@@ -165,8 +421,15 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
         <div className="flex min-w-0 flex-1 flex-col gap-5 overflow-y-auto pb-8">
           <Input
             value={name}
-            onChange={(e) => setName(e.target.value)}
-            onBlur={saveTitle}
+            onChange={(e) => handleTitleChange(e.target.value)}
+            onFocus={() => {
+              titleFocusedRef.current = true;
+              fields.setEditing("title", true);
+            }}
+            onBlur={() => {
+              titleFocusedRef.current = false;
+              saveTitle();
+            }}
             aria-label={m.testcase_detail_titleAria()}
             className="border-0 px-0 text-2xl font-semibold shadow-none focus-visible:ring-0 md:text-2xl"
           />
@@ -176,7 +439,7 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
               {m.testcase_detail_precondition()}
             </h3>
             <p className="mt-1.5 whitespace-pre-wrap text-sm">
-              {caseState.precondition ?? "—"}
+              {effectiveCase.precondition ?? "—"}
             </p>
           </section>
 
@@ -184,27 +447,45 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
             <h3 className="text-sm font-medium text-muted-foreground">
               {m.testcase_detail_steps()}
             </h3>
-            <ol className="mt-2 space-y-2.5">
-              {caseState.steps.steps.map((step) => (
-                <li
-                  key={step.order}
-                  data-testid={`detail-step-row-${step.order}`}
-                  className="flex gap-2.5 text-sm"
-                >
-                  <span className="mt-0.5 flex size-5 shrink-0 items-center justify-center rounded-full bg-muted text-xs text-muted-foreground">
-                    {step.order}
-                  </span>
-                  <div className="min-w-0">
-                    <div className="whitespace-pre-wrap">{step.action}</div>
-                    {step.expected && (
-                      <div className="mt-0.5 text-xs text-muted-foreground">
-                        {m.testcase_peek_expected()}：{step.expected}
-                      </div>
-                    )}
-                  </div>
-                </li>
-              ))}
-            </ol>
+            {stepsEditable ? (
+              <div className="mt-2">
+                <StepEditor
+                  value={stepDrafts}
+                  onChange={() => {
+                    // granular 分派承载全部变更（整组回调在协同态不使用）
+                  }}
+                  granular={{
+                    onInsertStep: (index, step) =>
+                      collabSteps.insertStep(index, { action: step.action, expected: step.expected }),
+                    onRemoveStep: (index) => collabSteps.removeStep(index),
+                    onMoveStep: (from, to) => collabSteps.moveStep(from, to),
+                    onStepChange: (index, patch) => collabSteps.updateStep(index, patch),
+                  }}
+                />
+              </div>
+            ) : (
+              <ol className="mt-2 space-y-2.5">
+                {effectiveCase.steps.steps.map((step) => (
+                  <li
+                    key={step.order}
+                    data-testid={`detail-step-row-${step.order}`}
+                    className="flex gap-2.5 text-sm"
+                  >
+                    <span className="mt-0.5 flex size-5 shrink-0 items-center justify-center rounded-full bg-muted text-xs text-muted-foreground">
+                      {step.order}
+                    </span>
+                    <div className="min-w-0">
+                      <div className="whitespace-pre-wrap">{step.action}</div>
+                      {step.expected && (
+                        <div className="mt-0.5 text-xs text-muted-foreground">
+                          {m.testcase_peek_expected()}：{step.expected}
+                        </div>
+                      )}
+                    </div>
+                  </li>
+                ))}
+              </ol>
+            )}
           </section>
 
           <div data-testid="detail-tabs" className="mt-2">
@@ -235,7 +516,7 @@ export function CaseDetailBody({ testCase, users, folders, activities }: CaseDet
 
         <aside className="w-64 shrink-0 overflow-y-auto pb-8">
           <CaseProperties
-            testCase={caseState}
+            testCase={effectiveCase}
             users={users}
             folders={folders}
             onUpdate={(patch) => void applyPatch(patch)}