@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/__tests__/bindings-fields.test.ts

@@ -0,0 +1,496 @@
+// 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.
+
+// 字段级 binding 层测试（任务 19，规格 §7.1）：
+// 用两个真实 Y.Doc + 两个真实 Awareness 实例模拟双客户端——不经网络，
+// Y 侧直接 Y.applyUpdate 合并、awareness 侧走 encodeAwarenessUpdate →
+// applyAwarenessUpdate 真协议路径（快且确定）。
+// 覆盖简报四场景：① 字段读写同步 Y.Map ② setEditing → 远端 observer 收到
+// ③ 并发改同字段 LWW merge 一致 ④ editing 标记断连自动清；另补 noop 降级
+// 与卸载清理（外科手术式摘除不碰 profile 等兄弟字段）。
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+import {
+  Awareness,
+  applyAwarenessUpdate,
+  encodeAwarenessUpdate,
+} from 'y-protocols/awareness'
+import { act, renderHook } from '@testing-library/react'
+import type { CollabAwareness, CollabConnectionStatus, CollabProviderHandle } from '../provider'
+import {
+  COLLAB_FIELDS_MAP_KEY,
+  EDITING_REFRESH_MS,
+  createFieldBinding,
+  useCollabFields,
+  useCollabField,
+  type FieldBinding,
+  type FieldBindingSource,
+} from '../bindings/fields'
+
+// ---------------------------------------------------------------------------
+// 双客户端仿真：真实 Y.Doc + 真实 Awareness + 可手控的 status 状态机
+// ---------------------------------------------------------------------------
+
+interface TestClient {
+  doc: Y.Doc
+  awareness: Awareness
+  binding: FieldBinding
+  /** 手动推动连接状态机（fake handle 的 onStatusChange 契约：立即回放） */
+  setStatus(status: CollabConnectionStatus): void
+  /** 把本端 awareness 状态经真协议编码广播到对方（模拟远端到达） */
+  broadcastAwarenessTo(other: Awareness): void
+  /** 把本端 Y doc 全量合并到对方 doc（模拟远端同步） */
+  syncDocTo(other: Y.Doc): void
+}
+
+const cleanups: Array<() => void> = []
+
+function makeClient(options?: Parameters<typeof createFieldBinding>[1]): TestClient {
+  const doc = new Y.Doc()
+  const awareness = new Awareness(doc)
+  const statusListeners = new Set<(status: CollabConnectionStatus) => void>()
+  let status: CollabConnectionStatus = 'connecting'
+  const source: FieldBindingSource = {
+    doc,
+    awareness: awareness as unknown as CollabAwareness,
+    onStatusChange(listener) {
+      statusListeners.add(listener)
+      listener(status) // 真实 handle 契约：订阅即回放当前状态
+      return () => statusListeners.delete(listener)
+    },
+  }
+  const binding = createFieldBinding(source, options)
+  cleanups.push(() => {
+    binding.destroy()
+    awareness.destroy()
+    doc.destroy()
+  })
+  return {
+    doc,
+    awareness,
+    binding,
+    setStatus(next) {
+      status = next
+      for (const listener of statusListeners) listener(next)
+    },
+    broadcastAwarenessTo(other) {
+      const update = encodeAwarenessUpdate(awareness, [awareness.clientID])
+      applyAwarenessUpdate(other, update, 'test-wire')
+    },
+    syncDocTo(other) {
+      Y.applyUpdate(other, Y.encodeStateAsUpdate(doc))
+    },
+  }
+}
+
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup()
+  vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ①：字段读写同步 Y.Map
+// ---------------------------------------------------------------------------
+
+describe('字段读写同步 Y.Map', () => {
+  it('setValue 写入 fields Y.Map，readValues 读回', () => {
+    const a = makeClient()
+    a.binding.setValue('title', '登录页改版')
+    expect(a.doc.getMap<number | string>(COLLAB_FIELDS_MAP_KEY).get('title')).toBe(
+      '登录页改版',
+    )
+    expect(a.binding.readValues(['title', 'missing'])).toEqual({
+      title: '登录页改版',
+      missing: undefined,
+    })
+  })
+
+  it('远端 Y 合并后 readValues 反映远端值，且 subscribe 收到通知', () => {
+    const a = makeClient()
+    const b = makeClient()
+    const notified = vi.fn()
+    a.binding.subscribe(notified)
+
+    b.binding.setValue('priority', 'high')
+    expect(notified).not.toHaveBeenCalled() // 本端写不触发对端订阅
+    a.syncDocTo(b.doc) // b → a 方向即远端到达（a 本无数据）
+    b.syncDocTo(a.doc)
+
+    expect(a.binding.readValues(['priority'])).toEqual({ priority: 'high' })
+    expect(notified).toHaveBeenCalled()
+  })
+
+  it('subscribe 退订后不再通知', () => {
+    const a = makeClient()
+    const notified = vi.fn()
+    const unsubscribe = a.binding.subscribe(notified)
+    unsubscribe()
+    a.binding.setValue('title', 'x')
+    expect(notified).not.toHaveBeenCalled()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ②：setEditing → 远端 observer 收到 awareness
+// ---------------------------------------------------------------------------
+
+describe('editing 标记走 awareness（真协议双端到达）', () => {
+  it('setEditing(true) 本端写入 schema，远端 observer 收到并可在 editingBy 读到', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    const b = makeClient({ identity: { userId: 'u-b', name: '乙' } })
+    const notified = vi.fn()
+    a.binding.subscribe(notified)
+
+    b.binding.setEditing('title', true)
+
+    // 本端 schema：awareness local state 的 editing:{field} 字段
+    const local = b.awareness.getLocalState()
+    expect(local?.['editing:title']).toMatchObject({
+      userId: 'u-b',
+      name: '乙',
+    })
+    expect(typeof local?.['editing:title']?.ts).toBe('number')
+
+    // 真协议到达对端：encode → apply（不经网络）
+    b.broadcastAwarenessTo(a.awareness)
+
+    expect(notified).toHaveBeenCalled()
+    expect(a.binding.readEditingBy()).toEqual({
+      title: [
+        {
+          userId: 'u-b',
+          name: '乙',
+          ts: expect.any(Number),
+          clientId: b.awareness.clientID,
+        },
+      ],
+    })
+  })
+
+  it('setEditing(false) 摘除标记，远端同步消失', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    const b = makeClient({ identity: { userId: 'u-b', name: '乙' } })
+    b.binding.setEditing('title', true)
+    b.broadcastAwarenessTo(a.awareness)
+    expect(a.binding.readEditingBy()['title']).toHaveLength(1)
+
+    b.binding.setEditing('title', false)
+    expect(b.awareness.getLocalState()?.['editing:title']).toBeUndefined()
+    b.broadcastAwarenessTo(a.awareness)
+    expect(a.binding.readEditingBy()['title']).toBeUndefined()
+  })
+
+  it('自身标记不出现在自己的 editingBy（pill 只显示他人）', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    a.binding.setEditing('title', true)
+    // 本端状态已写（schema 断言在上一用例覆盖）——自身必须被 editingBy 排除
+    expect(a.binding.readEditingBy()).toEqual({})
+  })
+
+  it('同 userId 多 client（双 tab）去重保留最新 ts', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    const b1 = makeClient({ identity: { userId: 'u-b', name: '乙' } })
+    const b2 = makeClient({ identity: { userId: 'u-b', name: '乙' } })
+    b1.binding.setEditing('title', true)
+    b2.binding.setEditing('title', true)
+    b1.broadcastAwarenessTo(a.awareness)
+    b2.broadcastAwarenessTo(a.awareness)
+    const editors = a.binding.readEditingBy()['title'] ?? []
+    expect(editors).toHaveLength(1)
+    expect(editors[0]?.userId).toBe('u-b')
+  })
+
+  it('identity 缺省时回退 awareness.profile，再降级 client:', () => {
+    const a = makeClient()
+    // 有 profile（collab-presence-header 广播的字段）：用它署名
+    a.awareness.setLocalStateField('profile', { id: 'u-x', username: '小明' })
+    a.binding.setEditing('desc', true)
+    expect(a.awareness.getLocalState()?.['editing:desc']).toMatchObject({
+      userId: 'u-x',
+      name: '小明',
+    })
+
+    // 无 profile 无 identity：clientID 降级（署名空名先例）
+    const b = makeClient()
+    b.binding.setEditing('desc', true)
+    const marker = b.awareness.getLocalState()?.['editing:desc'] as {
+      userId: string
+      name: string
+    }
+    expect(marker.userId).toBe(`client:${b.awareness.clientID}`)
+    expect(marker.name).toBe('')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ③：两个虚拟客户端并发改同字段 → merge 后一致（per-key LWW）
+// ---------------------------------------------------------------------------
+
+describe('并发写同字段 LWW（Y.Map per-key 语义）', () => {
+  it('同字段并发写：双向 merge 后两副本一致', () => {
+    const a = makeClient()
+    const b = makeClient()
+    // 并发：各自写同字段，互不知情（无同步）
+    a.binding.setValue('title', 'from-A')
+    b.binding.setValue('title', 'from-B')
+
+    // 双向全量合并（不经网络，直接 applyUpdate）
+    a.syncDocTo(b.doc)
+    b.syncDocTo(a.doc)
+
+    const va = a.binding.readValues(['title']).title
+    const vb = b.binding.readValues(['title']).title
+    expect(va).toBe(vb) // 收敛一致 = LWW 语义成立
+    expect(['from-A', 'from-B']).toContain(va) // 且必是两写者之一（无第三态）
+  })
+
+  it('不同字段并发写：per-key 合并互不吞（优于整包覆盖）', () => {
+    const a = makeClient()
+    const b = makeClient()
+    a.binding.setValue('title', '并发标题')
+    b.binding.setValue('priority', 'high')
+    a.syncDocTo(b.doc)
+    b.syncDocTo(a.doc)
+
+    const expected = { title: '并发标题', priority: 'high' }
+    expect(a.binding.readValues(['title', 'priority'])).toEqual(expected)
+    expect(b.binding.readValues(['title', 'priority'])).toEqual(expected)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 场景 ④：editing 标记断连自动清
+// ---------------------------------------------------------------------------
+
+describe('editing 标记断连清理与恢复', () => {
+  it('offline 摘除本端全部 editing 标记；恢复 synced 后重放（仍在编辑）', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    a.binding.setEditing('title', true)
+    a.binding.setEditing('priority', true)
+    expect(Object.keys(a.awareness.getLocalState() ?? {})).toContain(
+      'editing:title',
+    )
+
+    a.setStatus('offline')
+    const afterOffline = a.awareness.getLocalState() ?? {}
+    expect(afterOffline['editing:title']).toBeUndefined()
+    expect(afterOffline['editing:priority']).toBeUndefined()
+
+    a.setStatus('synced')
+    const afterRecover = a.awareness.getLocalState() ?? {}
+    expect(afterRecover['editing:title']).toMatchObject({ userId: 'u-a' })
+    expect(afterRecover['editing:priority']).toMatchObject({ userId: 'u-a' })
+  })
+
+  it('已 blur 的字段 offline 后不重放', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    a.binding.setEditing('title', true)
+    a.binding.setEditing('title', false)
+    a.setStatus('offline')
+    a.setStatus('synced')
+    expect(a.awareness.getLocalState()?.['editing:title']).toBeUndefined()
+  })
+
+  it('destroy 摘除标记且外科手术式保留兄弟字段（profile）', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    a.awareness.setLocalStateField('profile', { id: 'u-a', username: '甲' })
+    a.binding.setEditing('title', true)
+
+    a.binding.destroy()
+    const local = a.awareness.getLocalState() ?? {}
+    expect(local['editing:title']).toBeUndefined()
+    expect(local['profile']).toEqual({ id: 'u-a', username: '甲' })
+  })
+
+  it('持续编辑期间心跳刷新 ts（多 tab 去重/排序的新鲜度保证，非存活必需）', () => {
+    vi.useFakeTimers()
+    try {
+      const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+      a.binding.setEditing('title', true)
+      const before = (
+        a.awareness.getLocalState()?.['editing:title'] as { ts: number }
+      ).ts
+
+      vi.advanceTimersByTime(EDITING_REFRESH_MS + 1000)
+      const after = (
+        a.awareness.getLocalState()?.['editing:title'] as { ts: number }
+      ).ts
+      expect(after).toBeGreaterThan(before)
+
+      // blur 后心跳停表：标记不再被重写（也不会复活已摘除的标记）
+      a.binding.setEditing('title', false)
+      const spy = vi.spyOn(a.awareness, 'setLocalStateField')
+      vi.advanceTimersByTime(EDITING_REFRESH_MS * 2)
+      expect(spy).not.toHaveBeenCalled()
+      expect(a.awareness.getLocalState()?.['editing:title']).toBeUndefined()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// noop 降级（awareness 为 null：desktop / 未配置 WS）
+// ---------------------------------------------------------------------------
+
+describe('noop 降级（awareness null）', () => {
+  function makeNoopClient(): TestClient & { source: FieldBindingSource } {
+    const doc = new Y.Doc()
+    const statusListeners = new Set<(status: CollabConnectionStatus) => void>()
+    let status: CollabConnectionStatus = 'offline'
+    const source: FieldBindingSource = {
+      doc,
+      awareness: null,
+      onStatusChange(listener) {
+        statusListeners.add(listener)
+        listener(status)
+        return () => statusListeners.delete(listener)
+      },
+    }
+    const binding = createFieldBinding(source, { identity: { userId: 'u', name: 'n' } })
+    cleanups.push(() => {
+      binding.destroy()
+      doc.destroy()
+    })
+    return {
+      doc,
+      awareness: null as unknown as Awareness,
+      binding,
+      source,
+      setStatus(next) {
+        status = next
+        for (const listener of statusListeners) listener(next)
+      },
+      broadcastAwarenessTo() {},
+      syncDocTo() {},
+    }
+  }
+
+  it('值读写照常（本地 doc），editing 全链路 no-op 不抛错', () => {
+    const a = makeNoopClient()
+    a.binding.setValue('title', '单机值')
+    expect(a.binding.readValues(['title'])).toEqual({ title: '单机值' })
+    expect(() => a.binding.setEditing('title', true)).not.toThrow()
+    expect(() => a.binding.setEditing('title', false)).not.toThrow()
+    expect(a.binding.readEditingBy()).toEqual({})
+    expect(() => a.setStatus('offline')).not.toThrow()
+    expect(() => a.setStatus('synced')).not.toThrow()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// React 封装（useCollabFields / useCollabField——任务 20 消费面冒烟）
+// ---------------------------------------------------------------------------
+
+/** 最小 fake handle（CollabProviderHandle 结构全量，on/off 空实现） */
+function makeFakeHandle(client: TestClient): CollabProviderHandle {
+  const statusListeners = new Set<(status: CollabConnectionStatus) => void>()
+  const status: CollabConnectionStatus = 'synced'
+  return {
+    roomName: 'entity:story:test',
+    doc: client.doc,
+    awareness: client.awareness as unknown as CollabAwareness,
+    getStatus: () => status,
+    onStatusChange(listener) {
+      statusListeners.add(listener)
+      listener(status)
+      return () => statusListeners.delete(listener)
+    },
+    on: () => () => {},
+    off: () => {},
+    destroy: () => {},
+  }
+}
+
+describe('useCollabFields React 封装', () => {
+  it('values 响应式：本端 setValue 与远端 Y 合并都触发重渲染', async () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    const b = makeClient()
+    cleanups.push(() => {
+      b.binding.destroy()
+      b.awareness.destroy()
+      b.doc.destroy()
+    })
+    const handle = makeFakeHandle(a)
+    const { result } = renderHook(() =>
+      useCollabFields(handle, ['title', 'priority']),
+    )
+    expect(result.current.values).toEqual({ title: undefined, priority: undefined })
+
+    act(() => {
+      result.current.setValue('title', '钩子写入')
+    })
+    expect(result.current.values.title).toBe('钩子写入')
+
+    act(() => {
+      b.binding.setValue('priority', 'high')
+      b.syncDocTo(a.doc)
+    })
+    expect(result.current.values.priority).toBe('high')
+  })
+
+  it('editingBy 响应远端 awareness 到达；单字段便捷封装 exposes editors', async () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    const b = makeClient({ identity: { userId: 'u-b', name: '乙' } })
+    cleanups.push(() => {
+      b.binding.destroy()
+      b.awareness.destroy()
+      b.doc.destroy()
+    })
+    const handle = makeFakeHandle(a)
+    const { result } = renderHook(() =>
+      useCollabField(handle, 'title', { identity: { userId: 'u-a', name: '甲' } }),
+    )
+    expect(result.current.editors).toEqual([])
+
+    act(() => {
+      b.binding.setEditing('title', true)
+      b.broadcastAwarenessTo(a.awareness)
+    })
+    expect(result.current.editors).toHaveLength(1)
+    expect(result.current.editors[0]?.userId).toBe('u-b')
+
+    act(() => {
+      result.current.setValue('标题覆盖写入')
+      result.current.setEditing(true)
+    })
+    expect(a.doc.getMap(COLLAB_FIELDS_MAP_KEY).get('title')).toBe('标题覆盖写入')
+    expect(a.awareness.getLocalState()?.['editing:title']).toMatchObject({
+      userId: 'u-a',
+    })
+  })
+
+  it('卸载后本端 editing 标记被清（destroy 接线）', () => {
+    const a = makeClient({ identity: { userId: 'u-a', name: '甲' } })
+    const handle = makeFakeHandle(a)
+    const { result, unmount } = renderHook(() =>
+      useCollabFields(handle, ['title']),
+    )
+    act(() => {
+      result.current.setEditing('title', true)
+    })
+    expect(a.awareness.getLocalState()?.['editing:title']).toBeDefined()
+
+    unmount()
+    expect(a.awareness.getLocalState()?.['editing:title']).toBeUndefined()
+  })
+
+  it('handle 为 null（SSR/noop 上游）全链路降级', () => {
+    const { result } = renderHook(() => useCollabFields(null, ['title']))
+    expect(result.current.values).toEqual({ title: undefined })
+    expect(result.current.editingBy).toEqual({})
+    expect(() => {
+      act(() => {
+        result.current.setValue('title', 'x')
+        result.current.setEditing('title', true)
+      })
+    }).not.toThrow()
+  })
+})