@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/__tests__/use-share-presence.test.ts

@@ -0,0 +1,555 @@
+// 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/>.
+
+// useSharePresence hook 层测试（§9 R4 分享页 presence）：
+//   ① 成员/访客分组数据源——远端 awareness state 按 kind 字段分成
+//      members/guests 两组，自身（member）也进组并带 selfClientId
+//   ② 访客昵称持久化与默认「访客」——localStorage 无昵称时上报 i18n
+//      默认昵称，持久化后逐字复用；自选颜色一次选定持久化
+//   ③ room 上限 50 超限（服务端拒连）——ticket 签发失败 no-op 不报错
+//      （不建连、状态 offline、console.warn 级别）
+//   ④ 访客全程 view-only——hook 从不请求实体 ticket（createCollabTicketFn
+//      恒不被调用，§9 share room 全部 view）
+//   ⑤ 单例引用计数——同 room 多组件共用一条连接，最后一个消费者卸载才销毁
+//
+// 依赖 mock：serverFns（share/member 双 ticket）、provider（FakeAwareness
+// 内存实现，不引真 y-protocols）、env。真 paraglide messages（vitest 独立
+// 编译产物，见 vitest.config.ts）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { m } from '@/paraglide/messages.js'
+import {
+  GUEST_BG_COLORS,
+  GUEST_COLOR_STORAGE_KEY,
+  GUEST_NICKNAME_STORAGE_KEY,
+  __resetSharePresenceForTests,
+} from '../use-share-presence'
+
+const mocks = vi.hoisted(() => ({
+  createSharePresenceTicketFn: vi.fn(),
+  createCollabTicketFn: vi.fn(),
+  getOrCreateProvider: vi.fn(),
+  destroyProvider: vi.fn(),
+  isCollabEnabled: vi.fn((): boolean => true),
+}))
+
+vi.mock('@/server/serverFns/collab', () => ({
+  createSharePresenceTicketFn: mocks.createSharePresenceTicketFn,
+  createCollabTicketFn: mocks.createCollabTicketFn,
+}))
+
+vi.mock('../provider', () => ({
+  getOrCreateProvider: mocks.getOrCreateProvider,
+  destroyProvider: mocks.destroyProvider,
+}))
+
+vi.mock('../env', () => ({ isCollabEnabled: mocks.isCollabEnabled }))
+
+import { useSharePresence } from '../use-share-presence'
+
+// ---------------------------------------------------------------------------
+// FakeAwareness / FakeProvider（内存实现，接口面与 hook 消费一致）
+// ---------------------------------------------------------------------------
+
+type UpdateHandler = (update: unknown) => void
+
+class FakeAwareness {
+  clientID = 1
+  localState: Record<string, unknown> | null = null
+  remotes = new Map<number, Record<string, unknown>>()
+  private listeners = new Set<UpdateHandler>()
+  writes: Array<Record<string, unknown> | null> = []
+
+  setLocalState(state: Record<string, unknown> | null): void {
+    this.localState = state
+    this.writes.push(state)
+    this.emit()
+  }
+
+  getStates(): Map<number, Record<string, unknown>> {
+    const all = new Map(this.remotes)
+    if (this.localState) all.set(this.clientID, this.localState)
+    return all
+  }
+
+  on(_event: string, handler: UpdateHandler): void {
+    this.listeners.add(handler)
+  }
+
+  off(_event: string, handler: UpdateHandler): void {
+    this.listeners.delete(handler)
+  }
+
+  emit(): void {
+    for (const handler of [...this.listeners]) {
+      handler({ added: [], updated: [], removed: [] })
+    }
+  }
+
+  addRemote(clientId: number, state: Record<string, unknown>): void {
+    this.remotes.set(clientId, state)
+    this.emit()
+  }
+}
+
+interface FakeHandle {
+  roomName: string
+  awareness: FakeAwareness
+  statusListener: ((status: string) => void) | null
+  onStatusChange(listener: (status: string) => void): () => void
+}
+
+function makeFakeHandle(roomName: string, awareness: FakeAwareness): FakeHandle {
+  const handle: FakeHandle = {
+    roomName,
+    awareness,
+    statusListener: null,
+    onStatusChange(listener) {
+      handle.statusListener = listener
+      listener('connecting') // 对齐 provider 语义：立即回放当前状态
+      return () => {
+        handle.statusListener = null
+      }
+    },
+  }
+  return handle
+}
+
+// ---------------------------------------------------------------------------
+// 真 base64url JWT 形态的假 ticket（payload 可被 hook 的解码器读取）
+// ---------------------------------------------------------------------------
+
+interface TicketPayload {
+  sub: string
+  name: string
+  room: string
+  role: string
+  kind: 'member' | 'guest'
+  avatarBrief?: { avatarConfig: Record<string, number> | null; bgShape: string; bgColor: string }
+  exp: number
+}
+
+function base64url(input: string): string {
+  return btoa(unescape(encodeURIComponent(input)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+function makeTicket(payload: TicketPayload): string {
+  return `${base64url('{"alg":"HS256"}')}.${base64url(JSON.stringify(payload))}.sig`
+}
+
+function memberTicket(room: string, sub = 'u-self', name = 'Alice'): string {
+  return makeTicket({
+    sub,
+    name,
+    room,
+    role: 'view',
+    kind: 'member',
+    avatarBrief: { avatarConfig: null, bgShape: 'circle', bgColor: '#fff' },
+    exp: Math.floor(Date.now() / 1000) + 60,
+  })
+}
+
+function guestTicket(room: string, sub = 'guest:aaa', name = '访客'): string {
+  return makeTicket({
+    sub,
+    name,
+    room,
+    role: 'view',
+    kind: 'guest',
+    avatarBrief: { avatarConfig: null, bgShape: '', bgColor: '' },
+    exp: Math.floor(Date.now() / 1000) + 60,
+  })
+}
+
+function remotePerson(
+  id: string,
+  name: string,
+  kind: 'member' | 'guest',
+  ts = Date.now(),
+) {
+  return {
+    user: {
+      id,
+      name,
+      avatarConfig: null,
+      bgShape: kind === 'member' ? 'circle' : '',
+      bgColor: kind === 'member' ? '#fff' : '#7c6cf0',
+    },
+    kind,
+    ts,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 挂载辅助
+// ---------------------------------------------------------------------------
+
+const SHARE_TOKEN = 'tok123'
+const ROOM = `share:${SHARE_TOKEN}`
+
+function resetMocks(): void {
+  mocks.createSharePresenceTicketFn.mockReset()
+  mocks.createCollabTicketFn.mockReset()
+  mocks.getOrCreateProvider.mockReset()
+  mocks.destroyProvider.mockReset()
+  mocks.isCollabEnabled.mockReset()
+  mocks.isCollabEnabled.mockReturnValue(true)
+}
+
+function mountShareHook(shareToken: string | null = SHARE_TOKEN) {
+  return renderHook(() =>
+    useSharePresence({ shareToken, designId: 'd1', designver: null }),
+  )
+}
+
+async function flushJoin(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  resetMocks()
+  __resetSharePresenceForTests()
+  localStorage.clear()
+  sessionStorage.clear()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------------------
+// ① 成员/访客分组数据源（kind 字段）
+// ---------------------------------------------------------------------------
+
+describe('useSharePresence 分组', () => {
+  it('远端 state 按 kind 分成 members / guests 两组，自身 member 也进组', async () => {
+    const awareness = new FakeAwareness()
+    const handle = makeFakeHandle(ROOM, awareness)
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(() => handle)
+
+    const { result } = mountShareHook()
+    await flushJoin()
+
+    // 自身 awareness local state 按 §9 schema 上报（kind: member）
+    expect(awareness.writes[0]).toMatchObject({
+      user: { id: 'u-self', name: 'Alice' },
+      kind: 'member',
+    })
+
+    act(() => handle.statusListener?.('synced'))
+    act(() => {
+      awareness.addRemote(2, remotePerson('u2', 'Bob', 'member'))
+      awareness.addRemote(3, remotePerson('guest:bbb', '访客', 'guest'))
+    })
+
+    expect(result.current.status).toBe('synced')
+    expect(result.current.selfClientId).toBe(1)
+    // 分组只看 kind：members = 自己 + 远端成员；guests = 远端访客
+    expect(result.current.members.map((p) => p.id)).toEqual(['u-self', 'u2'])
+    expect(result.current.guests.map((p) => p.id)).toEqual(['guest:bbb'])
+    expect(result.current.members[0]).toMatchObject({ kind: 'member', name: 'Alice' })
+    expect(result.current.guests[0]).toMatchObject({
+      kind: 'guest',
+      name: '访客',
+      bgColor: '#7c6cf0',
+    })
+  })
+
+  it('远端离线（快照重建）后分组同步摘除，畸形 state 丢弃不抛错', async () => {
+    const awareness = new FakeAwareness()
+    const handle = makeFakeHandle(ROOM, awareness)
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(() => handle)
+
+    const { result } = mountShareHook()
+    await flushJoin()
+
+    act(() => {
+      awareness.addRemote(2, remotePerson('guest:bbb', '访客', 'guest'))
+    })
+    expect(result.current.guests).toHaveLength(1)
+
+    act(() => {
+      awareness.addRemote(9, { broken: true } as unknown as Record<string, unknown>)
+    })
+    expect(result.current.guests).toHaveLength(1) // 畸形条目被 fail-closed 丢弃
+
+    act(() => {
+      awareness.remotes.delete(2)
+      awareness.emit()
+    })
+    expect(result.current.guests).toHaveLength(0)
+  })
+
+  it('provider offline：分组清空（降级不显示）', async () => {
+    const awareness = new FakeAwareness()
+    const handle = makeFakeHandle(ROOM, awareness)
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(() => handle)
+
+    const { result } = mountShareHook()
+    await flushJoin()
+    act(() => {
+      awareness.addRemote(2, remotePerson('u2', 'Bob', 'member'))
+    })
+    expect(result.current.members).toHaveLength(2)
+
+    act(() => handle.statusListener?.('offline'))
+    expect(result.current.status).toBe('offline')
+    expect(result.current.members).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ② 访客昵称持久化与默认「访客」
+// ---------------------------------------------------------------------------
+
+describe('useSharePresence 访客身份', () => {
+  it('localStorage 无昵称：上报 i18n 默认昵称，并持久化自选颜色', async () => {
+    const awareness = new FakeAwareness()
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: guestTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(
+      () => makeFakeHandle(ROOM, awareness),
+    )
+
+    mountShareHook()
+    await flushJoin()
+
+    expect(mocks.createSharePresenceTicketFn).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        shareToken: SHARE_TOKEN,
+        nickname: m.presence_share_guestDefault(),
+      }),
+    })
+    const color = localStorage.getItem(GUEST_COLOR_STORAGE_KEY)
+    expect(color).not.toBeNull()
+    expect(GUEST_BG_COLORS).toContain(color)
+  })
+
+  it('localStorage 已持久化昵称：逐字复用，颜色不重选', async () => {
+    const awareness = new FakeAwareness()
+    localStorage.setItem(GUEST_NICKNAME_STORAGE_KEY, '小明')
+    localStorage.setItem(GUEST_COLOR_STORAGE_KEY, '#e8734a')
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: guestTicket(ROOM, 'guest:ccc', '小明'),
+    })
+    mocks.getOrCreateProvider.mockImplementation(
+      () => makeFakeHandle(ROOM, awareness),
+    )
+
+    const { result } = mountShareHook()
+    await flushJoin()
+
+    expect(mocks.createSharePresenceTicketFn).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        shareToken: SHARE_TOKEN,
+        nickname: '小明',
+      }),
+    })
+    // ticket 解码的身份进入 awareness 上报（访客昵称 + 自选颜色）
+    expect(awareness.writes[0]).toMatchObject({
+      user: { id: 'guest:ccc', name: '小明', bgColor: '#e8734a' },
+      kind: 'guest',
+    })
+    expect(result.current.guests[0]).toMatchObject({ id: 'guest:ccc' })
+    expect(localStorage.getItem(GUEST_COLOR_STORAGE_KEY)).toBe('#e8734a')
+  })
+
+  it('密码保护 share：从 sessionStorage 现有 key 读密码随请求传', async () => {
+    const awareness = new FakeAwareness()
+    sessionStorage.setItem('share_pwd_d1_main', '1234')
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(
+      () => makeFakeHandle(ROOM, awareness),
+    )
+
+    mountShareHook()
+    await flushJoin()
+
+    expect(mocks.createSharePresenceTicketFn).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        shareToken: SHARE_TOKEN,
+        password: '1234',
+      }),
+    })
+  })
+
+  it('无密码 share：不传 password 字段', async () => {
+    const awareness = new FakeAwareness()
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(
+      () => makeFakeHandle(ROOM, awareness),
+    )
+
+    mountShareHook()
+    await flushJoin()
+
+    const call = mocks.createSharePresenceTicketFn.mock.calls[0][0] as {
+      data: Record<string, unknown>
+    }
+    expect('password' in call.data ? call.data.password : undefined).toBeUndefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ③ room 上限 50 超限（服务端拒签）→ no-op 不报错
+// ---------------------------------------------------------------------------
+
+describe('useSharePresence room 上限', () => {
+  it('ticket 签发被拒：不建连、状态 offline、console.warn，不抛错', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    mocks.createSharePresenceTicketFn.mockRejectedValue(
+      new Error('share room 连接数已达上限'),
+    )
+
+    const { result } = mountShareHook()
+    await flushJoin()
+
+    expect(mocks.getOrCreateProvider).not.toHaveBeenCalled()
+    expect(result.current.status).toBe('offline')
+    expect(result.current.members).toHaveLength(0)
+    expect(result.current.guests).toHaveLength(0)
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  it('shareToken 为空（路由数据未就绪）：no-op 不发请求', async () => {
+    const { result } = mountShareHook(null)
+    await flushJoin()
+
+    expect(mocks.createSharePresenceTicketFn).not.toHaveBeenCalled()
+    expect(mocks.getOrCreateProvider).not.toHaveBeenCalled()
+    expect(result.current.members).toHaveLength(0)
+  })
+
+  it('协同不可用（desktop / 无 WS URL）：全链路 no-op', async () => {
+    mocks.isCollabEnabled.mockReturnValue(false)
+    mountShareHook()
+    await flushJoin()
+
+    expect(mocks.createSharePresenceTicketFn).not.toHaveBeenCalled()
+    expect(mocks.getOrCreateProvider).not.toHaveBeenCalled()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ④ 访客全程 view-only：从不请求实体 ticket
+// ---------------------------------------------------------------------------
+
+describe('useSharePresence view-only 边界', () => {
+  it('member / guest 两条路径都只走 share presence ticket，实体 ticket 恒不请求', async () => {
+    const awareness = new FakeAwareness()
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(
+      () => makeFakeHandle(ROOM, awareness),
+    )
+
+    const { unmount } = mountShareHook()
+    await flushJoin()
+    expect(mocks.createCollabTicketFn).not.toHaveBeenCalled()
+
+    unmount()
+    __resetSharePresenceForTests()
+
+    // 访客路径同样只走 share presence ticket
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: guestTicket(ROOM),
+    })
+    mountShareHook()
+    await flushJoin()
+    expect(mocks.createCollabTicketFn).not.toHaveBeenCalled()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ⑤ 单例引用计数 + 生命周期
+// ---------------------------------------------------------------------------
+
+describe('useSharePresence 单例语义', () => {
+  it('同 room 多消费者共用一条连接；最后一个卸载才 destroyProvider', async () => {
+    const awareness = new FakeAwareness()
+    const handle = makeFakeHandle(ROOM, awareness)
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(() => handle)
+
+    const a = renderHook(() =>
+      useSharePresence({ shareToken: SHARE_TOKEN, designId: 'd1', designver: null }),
+    )
+    const b = renderHook(() =>
+      useSharePresence({ shareToken: SHARE_TOKEN, designId: 'd1', designver: null }),
+    )
+    await flushJoin()
+
+    expect(mocks.getOrCreateProvider).toHaveBeenCalledTimes(1)
+    expect(a.result.current.members).toHaveLength(1)
+    expect(b.result.current.members).toHaveLength(1)
+
+    a.unmount()
+    expect(mocks.destroyProvider).not.toHaveBeenCalled()
+
+    b.unmount()
+    expect(mocks.destroyProvider).toHaveBeenCalledWith(ROOM)
+    // 离场协议语义：置 null 使他人侧 awareness 摘除
+    expect(awareness.writes[awareness.writes.length - 1]).toBeNull()
+  })
+
+  it('心跳续报刷新 ts（15s 无交互不被 pruneStale 误摘）', async () => {
+    const awareness = new FakeAwareness()
+    mocks.createSharePresenceTicketFn.mockResolvedValue({
+      ticket: memberTicket(ROOM),
+    })
+    mocks.getOrCreateProvider.mockImplementation(
+      () => makeFakeHandle(ROOM, awareness),
+    )
+
+    mountShareHook()
+    await flushJoin()
+    const first = awareness.writes[0]!
+
+    const writesBefore = awareness.writes.length
+    vi.advanceTimersByTime(16_000)
+    expect(awareness.writes.length).toBeGreaterThan(writesBefore)
+    const latest = awareness.writes[awareness.writes.length - 1]!
+    expect(latest!.ts as number).toBeGreaterThan(first.ts as number)
+  })
+})

package/src/lib/collab/__tests__/user-color.test.ts

@@ -0,0 +1,53 @@
+// 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.
+
+// 用户光标颜色单元测试（规格 §6）：userId 哈希到固定 8 色板——
+// 确定性（同 id 恒同色）与色板范围（永不出板）两个性质用测试钉住。
+
+import { describe, expect, it } from 'vitest'
+import { COLLAB_USER_COLORS, getUserColor } from '../user-color'
+
+describe('getUserColor', () => {
+  it('色板为固定 8 色（规格 §6 口径）', () => {
+    expect(COLLAB_USER_COLORS).toHaveLength(8)
+    // 全部为 hex 数据值（光标/名牌直接上色，与主题变量无关）
+    for (const color of COLLAB_USER_COLORS) {
+      expect(color).toMatch(/^#[0-9a-f]{6}$/)
+    }
+    // 色板内无重复
+    expect(new Set(COLLAB_USER_COLORS).size).toBe(8)
+  })
+
+  it('确定性：同一 userId 恒返回同一颜色', () => {
+    for (const id of ['user-1', 'cuidabc123', '', '🙂-unicode-id']) {
+      expect(getUserColor(id)).toBe(getUserColor(id))
+    }
+  })
+
+  it('范围：任意 userId 都映射到色板内的颜色', () => {
+    const samples = [
+      '',
+      'a',
+      'user-1',
+      'user-2',
+      'cmabc123def456',
+      'x'.repeat(500),
+      '\u4f60\u597d',
+    ]
+    for (const id of samples) {
+      expect(COLLAB_USER_COLORS).toContain(getUserColor(id))
+    }
+  })
+
+  it('不同用户可分布到多个颜色（避免全员同色）', () => {
+    const colors = new Set<string>()
+    for (let i = 0; i < 64; i++) colors.add(getUserColor(`user-${i}`))
+    expect(colors.size).toBeGreaterThan(2)
+  })
+})