@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/bindings/fields.ts

@@ -0,0 +1,463 @@
+// 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/>.
+
+// 字段级协同绑定层（规格 §7.1 / §3.1，任务 19；消费方：任务 20 Story 详情、
+// 任务 22 Bug/TestCase 详情、任务 21 exporter 落库回写）。
+//
+// ── entity room 的 Y 结构契约（本文件是字段层的 schema 文档，所有消费方
+// ── 必须遵守，禁止另起 key 约定）────────────────────────────────────────
+//
+// 一实体一 room（`entity:story:{id}` / `entity:bug:{id}` / `entity:case:{id}`，
+// 构造用 buildRoomName({ kind: 'entity-story', storyId }) 等——@allbluecn/
+// collab-core/rooms 与 web server/collab-permissions.ts 双镜像）。Y.Doc 内：
+//
+//   doc.getMap('fields'): Y.Map<fieldName, JSON 兼容值>
+//       字段值（title/state/priority/assignee/…）。写入值必须是 JSON 兼容
+//       类型（string/number/boolean/null/纯对象/数组）——Y 增量要跨网络同步
+//       并被 exporter 反序列化落库。冲突语义：Y.Map 天然 per-key LWW，两个
+//       客户端并发写同 key 确定性收敛（胜者由 (clock, clientID) 序在 merge
+//       时决定，无第三态），不同 key 并发互不吞。
+//   doc.getXmlFragment('description')
+//       富文本正文 fragment——任务 20 经 TipTap Collaboration configure 接入，
+//       本模块不触碰。
+//   doc.getArray('steps')（Bug/TestCase 独有）
+//       步骤列表 Y.Array<Y.Map>——任务 22 接入，本模块不触碰。
+//
+//   editing 标记走 awareness ephemeral，绝不写入 Y update（性能红线：字段值
+//   是用户操作级低频、editing 是 focus/blur 级高频，高频态只进 awareness，
+//   不产生 Y 增量、不落盘、不进快照）：
+//
+//     awareness state['editing:{fieldName}'] = { userId, name, ts }
+//       userId  编辑者 id（署名：options.identity → awareness.profile →
+//               `client:{clientID}` 降级，空名降级先例同协同头像）
+//       name    编辑者显示名（可为空串）
+//       ts      标记写入时刻（Date.now()，同字段多编辑者排序/多 tab 去重）
+//
+//     生命周期：setEditing(true) 写入 / setEditing(false) 摘除 / 持续编辑期间
+//     每 15s 心跳重写 ts（y-protocols 内置 15s 本地 state 自动续报
+//     _checkInterval——setLocalState(同值) 无条件 emit('update') 并被 provider
+//     全量转发，editing 标记在前台不会因超时被误摘；本模块心跳定位为 ts
+//     语义显式化：多 tab 去重/排序的新鲜度保证，非存活必需）/ 连接
+//     offline 自动摘除（对端靠 awareness 超时+removed 感知离场）/ 恢复 synced
+//     后对仍在编辑的字段重放（detach/attach 往返可能丢 local state，同
+//     use-share-presence 防御）/ 卸载 destroy 摘除。摘除是外科手术式（只删
+//     本模块写入的 editing:* key），不碰 profile 等兄弟字段。
+//
+// 分层：createFieldBinding 是无 React 依赖的核心（可脱离组件树单测——
+// bindings-fields.test.ts 用两个真实 Y.Doc + Awareness 直连验证），React
+// 侧 useCollabFields / useCollabField 是薄封装（useSyncExternalStore 订阅）。
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import * as Y from 'yjs'
+import type {
+  CollabAwareness,
+  CollabConnectionStatus,
+  CollabProviderHandle,
+} from '../provider'
+
+/** 字段值所在根 Y.Map 的 key（entity room Y 结构契约，见文件头） */
+export const COLLAB_FIELDS_MAP_KEY = 'fields'
+
+/** editing 标记的 awareness state key 前缀（`editing:{fieldName}`） */
+export const EDITING_KEY_PREFIX = 'editing:'
+
+/**
+ * editing 标记心跳（持续编辑期间重写 ts）：y-protocols 已内置 15s 本地
+ * state 自动续报（_checkInterval，setLocalState(同值) 无条件 emit('update')
+ * 并被 provider 全量转发），editing 标记在前台不会因超时被误摘——本模块
+ * 心跳定位为 ts 语义显式化（多 tab 去重/排序的新鲜度保证），非存活必需，
+ * 代价仅少量 awareness 流量。仅在本端有 editing 标记时运行。
+ */
+export const EDITING_REFRESH_MS = 15_000
+
+/** 一个远端编辑者（字段旁头像 pill 的数据源） */
+export interface FieldEditorInfo {
+  userId: string
+  name: string
+  ts: number
+  /** awareness clientID（多 tab 同人区分；React key） */
+  clientId: number
+}
+
+/** editing 署名（任务 20 从 session 传入；缺省走 profile/clientID 降级） */
+export interface FieldBindingIdentity {
+  userId: string
+  name: string
+}
+
+export interface FieldBindingOptions {
+  /** editing 标记署名；仅在 createFieldBinding 时生效（同 provider getTicket 惯例） */
+  identity?: FieldBindingIdentity
+}
+
+/**
+ * 绑定数据源（CollabProviderHandle 的结构子集——真实 handle 结构兼容直传；
+ * 测试用最小 fake 注入独立 Y.Doc + Awareness，不经网络）。
+ */
+export interface FieldBindingSource {
+  readonly doc: Y.Doc
+  /** noop 模式（协同不可用）为 null：editing 全链路 no-op，值读写照常 */
+  readonly awareness: CollabAwareness | null
+  /** 连接状态订阅（真实 handle 契约：订阅即回放当前状态） */
+  onStatusChange(listener: (status: CollabConnectionStatus) => void): () => void
+}
+
+export interface FieldBinding {
+  /** 单调递增变更计数（React useSyncExternalStore 快照缓存键） */
+  version(): number
+  /** 读字段值快照（每次现读 Y.Map；未写入的 key 为 undefined） */
+  readValues(fieldNames: readonly string[]): Record<string, unknown>
+  /**
+   * 远端 editing 标记快照：fieldName → 编辑者列表（ts 新者在前）。排除自身
+   * clientID（pill 只显示他人）；同 userId 多 client（双 tab）去重留最新。
+   */
+  readEditingBy(): Record<string, FieldEditorInfo[]>
+  /** 写字段值（Y.Map set；本地立即可见，连上后增量同步广播，per-key LWW） */
+  setValue(fieldName: string, value: unknown): void
+  /** 设置/清除本端 editing 标记（awareness ephemeral；noop 降级 no-op） */
+  setEditing(fieldName: string, editing: boolean): void
+  /** 订阅变更（值或 editing 任意变化；不立即回调），返回退订函数 */
+  subscribe(listener: () => void): () => void
+  /** 清理：摘 observer、摘本端 editing 标记（保留兄弟字段）、断状态订阅 */
+  destroy(): void
+}
+
+/** 校验一份 awareness editing 标记（fail-closed：畸形丢弃不抛错） */
+function parseEditor(raw: unknown, clientId: number): FieldEditorInfo | null {
+  if (typeof raw !== 'object' || raw === null) return null
+  const record = raw as Record<string, unknown>
+  if (typeof record.userId !== 'string' || record.userId.length === 0) return null
+  if (typeof record.name !== 'string') return null
+  if (typeof record.ts !== 'number' || !Number.isFinite(record.ts)) return null
+  return { userId: record.userId, name: record.name, ts: record.ts, clientId }
+}
+
+/** 从 awareness local state 读 profile 署名（collab-presence-header 广播） */
+function profileIdentity(awareness: CollabAwareness): FieldBindingIdentity | null {
+  const profile = awareness.getLocalState()?.profile as
+    | { id?: unknown; username?: unknown }
+    | undefined
+  if (
+    typeof profile?.id === 'string' &&
+    profile.id.length > 0 &&
+    typeof profile.username === 'string'
+  ) {
+    return { userId: profile.id, name: profile.username }
+  }
+  return null
+}
+
+export function createFieldBinding(
+  source: FieldBindingSource,
+  options: FieldBindingOptions = {},
+): FieldBinding {
+  const { awareness } = source
+  const fieldsMap = source.doc.getMap<unknown>(COLLAB_FIELDS_MAP_KEY)
+
+  let version = 0
+  let destroyed = false
+  const listeners = new Set<() => void>()
+  /** 本端仍在编辑的字段（offline 摘标记保留集合 → synced 重放 → 卸载清） */
+  const editingFields = new Set<string>()
+
+  const notify = () => {
+    version += 1
+    for (const listener of listeners) listener()
+  }
+
+  const onMapChange = () => notify()
+  fieldsMap.observe(onMapChange)
+
+  const onAwarenessUpdate = () => notify()
+  if (awareness) awareness.on('update', onAwarenessUpdate)
+
+  const resolveIdentity = (): FieldBindingIdentity => {
+    if (options.identity) return options.identity
+    if (awareness) {
+      const fromProfile = profileIdentity(awareness)
+      if (fromProfile) return fromProfile
+      return { userId: `client:${awareness.clientID}`, name: '' }
+    }
+    return { userId: 'client:0', name: '' }
+  }
+
+  /** 外科手术式摘除本端 editing:* key（保留 profile 等兄弟字段） */
+  const removeEditingKeys = (fieldNames: Iterable<string>) => {
+    if (!awareness) return
+    const local = awareness.getLocalState()
+    if (!local) return
+    const next: Record<string, unknown> = { ...local }
+    let changed = false
+    for (const fieldName of fieldNames) {
+      const key = EDITING_KEY_PREFIX + fieldName
+      if (key in next) {
+        delete next[key]
+        changed = true
+      }
+    }
+    if (changed) awareness.setLocalState(next)
+  }
+
+  const writeEditing = (fieldName: string, editing: boolean) => {
+    if (!awareness || destroyed) return
+    if (editing) {
+      editingFields.add(fieldName)
+      const { userId, name } = resolveIdentity()
+      awareness.setLocalStateField(EDITING_KEY_PREFIX + fieldName, {
+        userId,
+        name,
+        ts: Date.now(),
+      })
+      ensureEditingRefresh()
+    } else {
+      editingFields.delete(fieldName)
+      removeEditingKeys([fieldName])
+      if (editingFields.size === 0) stopEditingRefresh()
+    }
+  }
+
+  // 心跳（EDITING_REFRESH_MS）：持续编辑期间重写 ts 刷新新鲜度（存活由
+  // y-protocols 内置续报保证，见 EDITING_REFRESH_MS 注释）；无标记即停表。
+  let editingRefreshTimer: ReturnType<typeof setInterval> | null = null
+  function stopEditingRefresh(): void {
+    if (editingRefreshTimer) {
+      clearInterval(editingRefreshTimer)
+      editingRefreshTimer = null
+    }
+  }
+  function ensureEditingRefresh(): void {
+    if (!awareness || editingRefreshTimer || editingFields.size === 0) return
+    editingRefreshTimer = setInterval(() => {
+      if (editingFields.size === 0 || destroyed) {
+        stopEditingRefresh()
+        return
+      }
+      for (const fieldName of [...editingFields]) writeEditing(fieldName, true)
+    }, EDITING_REFRESH_MS)
+  }
+
+  const onStatus = (status: CollabConnectionStatus) => {
+    if (destroyed) return
+    if (status === 'offline') {
+      // 断连自动清：对端靠 awareness 超时/removed 感知离场；集合保留供重放；
+      // 心跳停表（offline 期间无需续报）
+      stopEditingRefresh()
+      removeEditingKeys(editingFields)
+    } else if (status === 'synced' && editingFields.size > 0) {
+      // 恢复重放（重取 profile 署名，可能已到达）；writeEditing 内重启心跳
+      for (const fieldName of [...editingFields]) writeEditing(fieldName, true)
+    }
+  }
+  const unsubscribeStatus = source.onStatusChange(onStatus)
+
+  return {
+    version: () => version,
+
+    readValues: (fieldNames) => {
+      const out: Record<string, unknown> = {}
+      for (const fieldName of fieldNames) out[fieldName] = fieldsMap.get(fieldName)
+      return out
+    },
+
+    readEditingBy: () => {
+      if (!awareness) return {}
+      // field → userId → 最新信息（同 userId 双 tab 去重）
+      const byField = new Map<string, Map<string, FieldEditorInfo>>()
+      for (const [clientId, state] of awareness.getStates()) {
+        if (clientId === awareness.clientID) continue // pill 只显示他人
+        for (const [key, raw] of Object.entries(state ?? {})) {
+          if (!key.startsWith(EDITING_KEY_PREFIX)) continue
+          const fieldName = key.slice(EDITING_KEY_PREFIX.length)
+          if (!fieldName) continue
+          const parsed = parseEditor(raw, clientId)
+          if (!parsed) continue
+          let perUser = byField.get(fieldName)
+          if (!perUser) {
+            perUser = new Map()
+            byField.set(fieldName, perUser)
+          }
+          const existing = perUser.get(parsed.userId)
+          if (!existing || parsed.ts >= existing.ts) perUser.set(parsed.userId, parsed)
+        }
+      }
+      const out: Record<string, FieldEditorInfo[]> = {}
+      for (const [fieldName, perUser] of byField) {
+        out[fieldName] = [...perUser.values()].sort((a, b) => b.ts - a.ts)
+      }
+      return out
+    },
+
+    setValue: (fieldName, value) => {
+      if (destroyed) return
+      if (fieldsMap.get(fieldName) === value) return // 原值短路（基础类型去噪）
+      fieldsMap.set(fieldName, value) // observe → notify
+    },
+
+    setEditing: writeEditing,
+
+    subscribe: (listener) => {
+      if (destroyed) return () => {}
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+
+    destroy: () => {
+      if (destroyed) return
+      destroyed = true
+      stopEditingRefresh()
+      fieldsMap.unobserve(onMapChange)
+      if (awareness) {
+        awareness.off('update', onAwarenessUpdate)
+        removeEditingKeys(editingFields)
+      }
+      editingFields.clear()
+      unsubscribeStatus()
+      listeners.clear()
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// React 封装（任务 20/22 消费面）
+// ---------------------------------------------------------------------------
+
+/** 内部快照（actions 稳定性独立于快照，不进 useSyncExternalStore 缓存） */
+interface FieldsSnapshot {
+  values: Record<string, unknown>
+  editingBy: Record<string, FieldEditorInfo[]>
+}
+
+const EMPTY_SNAPSHOT: FieldsSnapshot = { values: {}, editingBy: {} }
+
+export interface UseCollabFieldsResult {
+  /** 绑定字段值（未写入的 key 为 undefined；远端变更响应式更新） */
+  values: Record<string, unknown>
+  /** 远端 editing 标记（pill 数据源；自身不在内） */
+  editingBy: Record<string, FieldEditorInfo[]>
+  /** 写字段值（noop/未同步安全：本地 doc 立即可见，连上后增量广播） */
+  setValue(fieldName: string, value: unknown): void
+  /** 设置/清除本端 editing 标记（noop 降级 no-op） */
+  setEditing(fieldName: string, editing: boolean): void
+}
+
+/**
+ * 绑定一个 room 的多个字段（表单场景首选：一条 Y.Map observer + 一条
+ * awareness 订阅服务全部字段）。handle 为 null（SSR/noop 上游）时全链路
+ * 降级：values 恒空、editingBy 恒空、actions no-op。
+ *
+ * 生命周期边界（同 use-collab-doc 口径）：binding 随首个非 null handle 经
+ * useState 惰性初始化创建一次、卸载 effect 销毁；room/实体切换按既有惯例
+ * 由路由 key={id} 重建整树承接，handle 中途换实例不经本 hook 响应。lazy
+ * 路由双挂载是完整 unmount/remount（useState 重新初始化，路径安全）；应用
+ * 主树未启用 React StrictMode，若未来启用需复查「state 保留 + effect
+ * cleanup 销毁」的组合，届时改为 effect 内创建。
+ */
+export function useCollabFields(
+  handle: CollabProviderHandle | null,
+  fieldNames: readonly string[],
+  options?: FieldBindingOptions,
+): UseCollabFieldsResult {
+  // options 仅创建时生效（同 provider getTicket 惯例）：ref 只为拿到创建
+  // 时刻的值，避免 identity 字面量每渲染变化触发重建
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const fieldNamesRef = useRef(fieldNames)
+  fieldNamesRef.current = fieldNames
+  const fieldNamesKey = fieldNames.join('\u0000')
+
+  const [binding] = useState<FieldBinding | null>(() =>
+    handle ? createFieldBinding(handle, optionsRef.current) : null,
+  )
+  useEffect(() => () => binding?.destroy(), [binding])
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => binding?.subscribe(onStoreChange) ?? (() => {}),
+    [binding],
+  )
+
+  const cacheRef = useRef<{
+    version: number
+    key: string
+    snapshot: FieldsSnapshot
+  } | null>(null)
+  const getSnapshot = useCallback(() => {
+    if (!binding) return EMPTY_SNAPSHOT
+    const currentVersion = binding.version()
+    const cached = cacheRef.current
+    if (cached && cached.version === currentVersion && cached.key === fieldNamesKey) {
+      return cached.snapshot
+    }
+    const snapshot: FieldsSnapshot = {
+      values: binding.readValues(fieldNamesRef.current),
+      editingBy: binding.readEditingBy(),
+    }
+    cacheRef.current = { version: currentVersion, key: fieldNamesKey, snapshot }
+    return snapshot
+  }, [binding, fieldNamesKey])
+
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  const setValue = useCallback(
+    (fieldName: string, value: unknown) => binding?.setValue(fieldName, value),
+    [binding],
+  )
+  const setEditing = useCallback(
+    (fieldName: string, editing: boolean) => binding?.setEditing(fieldName, editing),
+    [binding],
+  )
+
+  return { values: snapshot.values, editingBy: snapshot.editingBy, setValue, setEditing }
+}
+
+export interface UseCollabFieldResult {
+  /** 当前字段值（未写入为 undefined） */
+  value: unknown
+  /** 远端编辑者列表（pill 数据源；ts 新者在前） */
+  editors: FieldEditorInfo[]
+  setValue(value: unknown): void
+  setEditing(editing: boolean): void
+}
+
+/** 单字段便捷封装（多字段表单请用 useCollabFields，共享单条订阅） */
+export function useCollabField(
+  handle: CollabProviderHandle | null,
+  fieldName: string,
+  options?: FieldBindingOptions,
+): UseCollabFieldResult {
+  const { values, editingBy, setValue, setEditing } = useCollabFields(
+    handle,
+    [fieldName],
+    options,
+  )
+  const setThisValue = useCallback(
+    (value: unknown) => setValue(fieldName, value),
+    [setValue, fieldName],
+  )
+  const setThisEditing = useCallback(
+    (editing: boolean) => setEditing(fieldName, editing),
+    [setEditing, fieldName],
+  )
+  return {
+    value: values[fieldName],
+    editors: editingBy[fieldName] ?? [],
+    setValue: setThisValue,
+    setEditing: setThisEditing,
+  }
+}