@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/__tests__/presence-store.test.ts

@@ -0,0 +1,414 @@
+// 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/>.
+
+// presence 数据层单元测试（§8.1 / 简报步骤 1）：
+//   ① awareness state schema 校验（fail-closed 拒绝畸形远端 state）
+//   ② 同 userId 多 tab 去重（取最新 ts）
+//   ③ syncRemote 全量快照重建（远端离线者自然消失）
+//   ④ 断线 30s 摘除（store 侧 ts 过期 prune + offline 清空）
+//   ⑤ selector byModule / useTeammates excludeSelf
+//   ⑥ module 归属 = 路由前缀匹配（与 sidebar-utils isPathActive 同口径）
+//   ⑦ 路由变化上报状态构造（剥 query）+ 2s 节流常量
+
+import { beforeEach, describe, expect, it } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import {
+  PRESENCE_STALE_MS,
+  __resetPresenceStoreForTests,
+  arePresenceListsContentEqual,
+  byModule,
+  parsePresenceState,
+  presenceActions,
+  presenceStore,
+  usePresenceStatus,
+  useTeammates,
+  type PresenceState,
+  type PresenceUser,
+} from '../presence-store'
+import {
+  MODULE_ROUTES,
+  buildPresenceState,
+  resolveModuleLocation,
+} from '../module-map'
+import { PRESENCE_REPORT_THROTTLE_MS } from '../module-map'
+import { workspaceRoutes } from '@/config/sidebar-routes'
+
+// ---------------------------------------------------------------------------
+// 测试夹具
+// ---------------------------------------------------------------------------
+
+function brief(id: string, username = id): PresenceUser {
+  return { id, username, bgShape: 'square', bgColor: '#fff' }
+}
+
+function state(
+  id: string,
+  module: string,
+  ts: number,
+  route = '/stories',
+  extra: Partial<PresenceState> = {},
+): PresenceState {
+  return { user: brief(id), module, route, ts, ...extra }
+}
+
+beforeEach(() => {
+  __resetPresenceStoreForTests()
+})
+
+// ---------------------------------------------------------------------------
+// ① schema 校验
+// ---------------------------------------------------------------------------
+
+describe('parsePresenceState', () => {
+  it('合法 state（§8.1 全字段）原样通过', () => {
+    const raw = {
+      user: brief('u1'),
+      module: 'stories',
+      route: '/stories/123',
+      entityTitle: '登录需求',
+      section: 'detail',
+      ts: 1000,
+    }
+    expect(parsePresenceState(raw)).toEqual(raw)
+  })
+
+  it('可选字段缺省（entityTitle/section）通过', () => {
+    const raw = { user: brief('u1'), module: 'bugs', route: '/bugs', ts: 1 }
+    expect(parsePresenceState(raw)).toEqual(raw)
+  })
+
+  it.each([
+    ['缺 user', { module: 'stories', route: '/stories', ts: 1 }],
+    ['user 缺 id', { user: { username: 'x' }, module: 'stories', route: '/', ts: 1 }],
+    ['缺 module', { user: brief('u1'), route: '/', ts: 1 }],
+    ['route 非字符串', { user: brief('u1'), module: 'stories', route: 7, ts: 1 }],
+    ['ts 非数字', { user: brief('u1'), module: 'stories', route: '/', ts: 'x' }],
+    ['非法 section', { user: brief('u1'), module: 'stories', route: '/', section: 'x', ts: 1 }],
+  ])('畸形 state（%s）返回 null（fail-closed）', (_name, raw) => {
+    expect(parsePresenceState(raw)).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ② applyRemote：upsert + 同 userId 多 tab 去重（取最新 ts）
+// ---------------------------------------------------------------------------
+
+describe('presenceActions.applyRemote', () => {
+  it('合法远端 state 按 userId upsert', () => {
+    expect(presenceActions.applyRemote(state('u1', 'stories', 100))).toBe(true)
+    expect(presenceStore.get().teammates.get('u1')?.ts).toBe(100)
+  })
+
+  it('同 userId 两 tab：保留最新 ts，只留一份', () => {
+    presenceActions.applyRemote(state('u1', 'stories', 100))
+    presenceActions.applyRemote(state('u1', 'stories', 200))
+    const kept = presenceStore.get().teammates
+    expect(kept.size).toBe(1)
+    expect(kept.get('u1')?.ts).toBe(200)
+  })
+
+  it('乱序到达：旧 ts 不覆盖新 ts', () => {
+    presenceActions.applyRemote(state('u1', 'stories', 200))
+    expect(presenceActions.applyRemote(state('u1', 'stories', 150))).toBe(false)
+    expect(presenceStore.get().teammates.get('u1')?.ts).toBe(200)
+  })
+
+  it('畸形 state 拒绝且不影响既有条目', () => {
+    presenceActions.applyRemote(state('u1', 'stories', 100))
+    expect(presenceActions.applyRemote({ user: { username: 'x' } })).toBe(false)
+    expect(presenceStore.get().teammates.get('u1')?.ts).toBe(100)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③ syncRemote：全量快照重建（远端 remove 语义）
+// ---------------------------------------------------------------------------
+
+describe('presenceActions.syncRemote', () => {
+  it('快照重建：消失的 userId 被摘除', () => {
+    presenceActions.syncRemote([
+      state('u1', 'stories', 100),
+      state('u2', 'bugs', 100),
+      state('u3', 'design', 100),
+    ])
+    expect(presenceStore.get().teammates.size).toBe(3)
+
+    // u3 离线（awareness removed）→ 新快照只有 u1/u2
+    presenceActions.syncRemote([state('u1', 'stories', 120), state('u2', 'bugs', 110)])
+    const teammates = presenceStore.get().teammates
+    expect([...teammates.keys()].sort()).toEqual(['u1', 'u2'])
+    expect(teammates.get('u1')?.ts).toBe(120)
+  })
+
+  it('同 userId 多 tab 快照去重取最新 ts', () => {
+    presenceActions.syncRemote([
+      state('u1', 'stories', 100),
+      state('u1', 'stories', 300, '/stories/9'),
+      state('u1', 'bugs', 200),
+    ])
+    const kept = presenceStore.get().teammates.get('u1')
+    expect(kept?.ts).toBe(300)
+    expect(kept?.module).toBe('stories')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ④ 断线摘除：store 侧 ts 过期（30s）+ offline 清空
+// ---------------------------------------------------------------------------
+
+describe('断线摘除', () => {
+  it('pruneStale：超过 30s 未续报的条目被摘除', () => {
+    const now = 1_000_000
+    presenceActions.applyRemote(state('fresh', 'stories', now - 10_000))
+    presenceActions.applyRemote(state('stale', 'bugs', now - PRESENCE_STALE_MS - 1))
+    const pruned = presenceActions.pruneStale(now)
+    expect(pruned).toEqual(['stale'])
+    expect([...presenceStore.get().teammates.keys()]).toEqual(['fresh'])
+  })
+
+  it('PRESENCE_STALE_MS 对齐 awareness 超时口径 30s', () => {
+    expect(PRESENCE_STALE_MS).toBe(30_000)
+  })
+
+  it('offline：清空 teammates 并标记（降级为不显示）', () => {
+    presenceActions.applyRemote(state('u1', 'stories', Date.now()))
+    presenceActions.setStatus('synced')
+    expect(presenceStore.get().status).toBe('synced')
+
+    presenceActions.setStatus('offline')
+    expect(presenceStore.get().status).toBe('offline')
+    expect(presenceStore.get().teammates.size).toBe(0)
+  })
+
+  it('connecting：不清空（等待重连后 awareness 快照重建）', () => {
+    presenceActions.setStatus('synced')
+    presenceActions.applyRemote(state('u1', 'stories', Date.now()))
+    presenceActions.setStatus('connecting')
+    expect(presenceStore.get().teammates.size).toBe(1)
+  })
+
+  it('remove：精确摘除单人不误伤他人', () => {
+    presenceActions.applyRemote(state('u1', 'stories', 1))
+    presenceActions.applyRemote(state('u2', 'bugs', 1))
+    presenceActions.remove('u1')
+    expect([...presenceStore.get().teammates.keys()]).toEqual(['u2'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ⑤ selector：byModule / useTeammates excludeSelf
+// ---------------------------------------------------------------------------
+
+describe('selectors', () => {
+  it('byModule 只留该模块的队友', () => {
+    const list = [
+      state('u1', 'stories', 1),
+      state('u2', 'bugs', 2),
+      state('u3', 'stories', 3),
+    ]
+    const stories = byModule('stories')(list)
+    expect(stories.map((s) => s.user.id)).toEqual(['u1', 'u3'])
+    expect(byModule('bugs')(list).map((s) => s.user.id)).toEqual(['u2'])
+  })
+
+  it('useTeammates：excludeSelf（selfId 来自登录 session）+ byModule', () => {
+    presenceActions.applyRemote(state('me', 'stories', 1))
+    presenceActions.applyRemote(state('alice', 'stories', 2))
+    presenceActions.applyRemote(state('bob', 'stories', 3))
+    presenceActions.applyRemote(state('carol', 'bugs', 4))
+
+    const { result } = renderHook(() =>
+      useTeammates(byModule('stories'), 'me'),
+    )
+    expect(result.current.map((s) => s.user.id).sort()).toEqual(['alice', 'bob'])
+  })
+
+  it('useTeammates：无 selector 时返回全部队友（仍排除 self）', () => {
+    presenceActions.applyRemote(state('me', 'dashboard', 1))
+    presenceActions.applyRemote(state('alice', 'stories', 2))
+    const { result } = renderHook(() => useTeammates(undefined, 'me'))
+    expect(result.current.map((s) => s.user.id)).toEqual(['alice'])
+  })
+
+  it('usePresenceStatus 反映连接状态', () => {
+    const { result } = renderHook(() => usePresenceStatus())
+    expect(result.current).toBe('offline')
+    act(() => presenceActions.setStatus('synced'))
+    expect(result.current).toBe('synced')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ⑤′ 内容级相等（审查重要①修复）：心跳式 state 重建（ts 变、内容不变）不重渲染
+// ---------------------------------------------------------------------------
+
+describe('arePresenceListsContentEqual', () => {
+  it('ts 不同（心跳续报）、其余相同 → 内容相等', () => {
+    const a = [state('u1', 'stories', 100, '/stories/1', { section: 'detail' })]
+    const b = [state('u1', 'stories', 200, '/stories/1', { section: 'detail' })]
+    expect(arePresenceListsContentEqual(a, b)).toBe(true)
+  })
+
+  it.each([
+    ['username 变化', (s: PresenceState) => [{ ...s, user: { ...s.user, username: 'renamed' } }]],
+    ['route 变化', (s: PresenceState) => [{ ...s, route: '/stories/9' }]],
+    ['entityTitle 变化', (s: PresenceState) => [{ ...s, entityTitle: '新标题' }]],
+    ['section 变化', (s: PresenceState) => [{ ...s, section: 'list' as const }]],
+    ['bgColor 变化', (s: PresenceState) => [{ ...s, user: { ...s.user, bgColor: '#000' } }]],
+    ['avatarConfig 键值变化', (s: PresenceState) => [{ ...s, user: { ...s.user, avatarConfig: { hair: 2 } } }]],
+    ['成员增减', (s: PresenceState) => [s, state('u2', 'stories', 100)]],
+  ])('%s → 内容不等', (_name, mutate) => {
+    const a = [state('u1', 'stories', 100, '/stories/1', {
+      section: 'detail',
+      entityTitle: '旧标题',
+    })]
+    const b = mutate(a[0]!)
+    expect(arePresenceListsContentEqual(a, b as PresenceState[])).toBe(false)
+  })
+
+  it('avatarConfig 内容相同、键序不同 → 内容相等', () => {
+    const a = [state('u1', 'stories', 100)]
+    a[0]!.user.avatarConfig = { hair: 1, skin: 2 }
+    const b = [state('u1', 'stories', 100)]
+    b[0]!.user.avatarConfig = { skin: 2, hair: 1 }
+    expect(arePresenceListsContentEqual(a, b)).toBe(true)
+  })
+})
+
+describe('useTeammates 心跳零重渲染（内容级 compare）', () => {
+  function renderCountingTeammates(equality?: typeof arePresenceListsContentEqual) {
+    let renders = 0
+    const { result } = renderHook(() => {
+      renders += 1
+      return useTeammates(byModule('stories'), null, equality)
+    })
+    return { result, renders: () => renders }
+  }
+
+  it('心跳式 state 重建（内容相等的新数组）→ 不重渲染', () => {
+    presenceActions.applyRemote(
+      state('u1', 'stories', 100, '/stories/1', { section: 'detail' }),
+    )
+    const { result, renders } = renderCountingTeammates(arePresenceListsContentEqual)
+    expect(result.current).toHaveLength(1)
+    const afterMount = renders()
+
+    act(() => {
+      presenceActions.applyRemote(
+        state('u1', 'stories', 200, '/stories/1', { section: 'detail' }),
+      )
+    })
+    // ts 已更新（store 真值前进），但内容相等 → 零重渲染
+    expect(presenceStore.get().teammates.get('u1')?.ts).toBe(200)
+    expect(renders()).toBe(afterMount)
+  })
+
+  it('内容真变（route 变化）→ 正常重渲染', () => {
+    presenceActions.applyRemote(
+      state('u1', 'stories', 100, '/stories/1', { section: 'detail' }),
+    )
+    const { result, renders } = renderCountingTeammates(arePresenceListsContentEqual)
+    const afterMount = renders()
+
+    act(() => {
+      presenceActions.applyRemote(
+        state('u1', 'stories', 200, '/stories/2', { section: 'detail' }),
+      )
+    })
+    expect(renders()).toBeGreaterThan(afterMount)
+    expect(result.current[0]?.route).toBe('/stories/2')
+  })
+
+  it('对照：默认引用级相等下，心跳式重建会重渲染（钉住两口径差异）', () => {
+    presenceActions.applyRemote(
+      state('u1', 'stories', 100, '/stories/1', { section: 'detail' }),
+    )
+    const { renders } = renderCountingTeammates()
+    const afterMount = renders()
+
+    act(() => {
+      presenceActions.applyRemote(
+        state('u1', 'stories', 200, '/stories/1', { section: 'detail' }),
+      )
+    })
+    expect(renders()).toBeGreaterThan(afterMount)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ⑥ module 归属：路由前缀匹配（isPathActive 同口径）
+// ---------------------------------------------------------------------------
+
+describe('resolveModuleLocation', () => {
+  it.each([
+    ['/stories', 'stories', 'list'],
+    ['/stories/123', 'stories', 'detail'],
+    ['/stories/123/steps', 'stories', 'detail'],
+    ['/bugs', 'bugs', 'list'],
+    ['/test-cases', 'test-cases', 'list'],
+    ['/test-cases/abc', 'test-cases', 'detail'],
+    ['/design', 'design', 'list'],
+    ['/knowledge', 'knowledge', 'list'],
+    ['/knowledge/laws', 'knowledge', 'detail'],
+    ['/dashboard', 'dashboard', undefined],
+    ['/harness', 'harness', undefined],
+  ])('%s → module=%s section=%s', (pathname, module, section) => {
+    expect(resolveModuleLocation(pathname)).toEqual({ module, section })
+  })
+
+  it('前缀不误伤：/bugs-x 不算 bugs（isPathActive 同口径）', () => {
+    expect(resolveModuleLocation('/bugs-x')?.module).not.toBe('bugs')
+  })
+
+  it('未知前缀返回 null（调用方回落 other）', () => {
+    expect(resolveModuleLocation('/settings/profile')).toBeNull()
+    expect(resolveModuleLocation('/')).toBeNull()
+  })
+
+  it('MODULE_ROUTES 与 sidebar-routes route.id/link 镜像一致（防漂移）', () => {
+    const mapById = new Map(MODULE_ROUTES.map((r) => [r.id, r]))
+    for (const route of workspaceRoutes) {
+      const mapped = mapById.get(route.id)
+      expect(mapped, `route.id=${route.id} 缺少 module-map 映射`).toBeDefined()
+      expect(mapped?.link).toBe(route.link)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ⑦ 上报状态构造：剥 query + 2s 节流常量
+// ---------------------------------------------------------------------------
+
+describe('buildPresenceState', () => {
+  it('剥 query：/stories/123?tab=a 保留纯路径', () => {
+    const built = buildPresenceState(brief('u1'), '/stories/123?tab=a&x=1', 99)
+    expect(built.route).toBe('/stories/123')
+    expect(built.module).toBe('stories')
+    expect(built.section).toBe('detail')
+    expect(built.ts).toBe(99)
+  })
+
+  it('未知路由回落 other 模块、无 section', () => {
+    const built = buildPresenceState(brief('u1'), '/settings/profile', 1)
+    expect(built.module).toBe('other')
+    expect(built.section).toBeUndefined()
+  })
+
+  it('节流口径 2s（pacer 统一）', () => {
+    expect(PRESENCE_REPORT_THROTTLE_MS).toBe(2000)
+  })
+})

package/src/lib/collab/__tests__/provider-handle-contract.test.ts

@@ -0,0 +1,89 @@
+// 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.
+
+// CollabProviderHandle on/off 事件契约测试（任务 15 审查 C1 修复）：
+// 走真实 provider 模块（buildHandle 产物），钉住编辑器扩展工厂的硬依赖——
+// @tiptap/extension-unique-id 协同态经 provider.on('synced') 建订阅、
+// provider.off 退订；handle 缺成员或 noop 抛错即 live 编辑器创建必崩。
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const mockIsDesktopEdition = vi.fn((): boolean => true) // 默认 noop 路径
+vi.mock('@/lib/edition-desktop', () => ({
+  isDesktopEdition: (): boolean => mockIsDesktopEdition(),
+}))
+
+const mockCreateCollabTicketFn = vi.fn()
+vi.mock('@/server/serverFns/collab', () => ({
+  createCollabTicketFn: (...args: unknown[]) => mockCreateCollabTicketFn(...args),
+}))
+
+// 最小 WebSocket 替身（EventTarget 风格，不建立真连接——只验事件委托）
+class MockWebSocket extends EventTarget {
+  url: string
+  readyState = 0
+  binaryType = 'blob'
+  constructor(url: string) {
+    super()
+    this.url = url
+  }
+  send(): void {}
+  close(): void {
+    this.readyState = 3
+    this.dispatchEvent(new CloseEvent('close', { code: 1000, reason: '' }))
+  }
+}
+
+import { HocuspocusProvider } from '@hocuspocus/provider'
+import {
+  __resetCollabForTests,
+  __setWebSocketPolyfillForTests,
+  getOrCreateProvider,
+} from '../provider'
+
+afterEach(() => {
+  __resetCollabForTests()
+  __setWebSocketPolyfillForTests(undefined)
+  vi.unstubAllEnvs()
+  vi.restoreAllMocks()
+})
+
+describe('CollabProviderHandle on/off 契约（C1）', () => {
+  it('noop handle：on/off 存在且安全空操作', () => {
+    const handle = getOrCreateProvider('doc:knowledge:noop-c1')
+    expect(typeof handle.on).toBe('function')
+    expect(typeof handle.off).toBe('function')
+    expect(() => {
+      const unsubscribe = handle.on('synced', () => {})
+      unsubscribe()
+      handle.off('synced', () => {})
+    }).not.toThrow()
+  })
+
+  it('live handle：on/off 透传底层 HocuspocusProvider（UniqueID synced 契约）', () => {
+    mockIsDesktopEdition.mockReturnValue(false)
+    // env.ts 刻意调用时读取 import.meta.env（SSR/测试双态安全先例）——
+    // stubEnv 注入 WS 地址即可进 live entry，无需真实服务
+    vi.stubEnv('VITE_COLLAB_WS_URL', 'ws://collab.test')
+    __setWebSocketPolyfillForTests(MockWebSocket as never)
+
+    const handle = getOrCreateProvider('doc:knowledge:live-c1')
+    expect(handle.awareness).not.toBeNull() // live entry：走真实 buildHandle 产物
+    const onSpy = vi.spyOn(HocuspocusProvider.prototype, 'on')
+    const offSpy = vi.spyOn(HocuspocusProvider.prototype, 'off')
+    const listener = vi.fn()
+
+    const unsubscribe = handle.on('synced', listener)
+    expect(onSpy).toHaveBeenCalledWith('synced', listener)
+    handle.off('synced', listener)
+    expect(offSpy).toHaveBeenCalledWith('synced', listener)
+    unsubscribe()
+    expect(offSpy).toHaveBeenCalledTimes(2) // 退订同样走 off
+  })
+})