@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,350 @@
+// 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 / §6）：awareness 远端 state 的 React 可订阅
+// 镜像。任务 10 侧边栏 PresenceAvatarStack 通过 useTeammates(byModule(...))
+// 消费；本模块不感知连接（awareness 订阅在 use-presence-report.ts 接线）。
+//
+// 数据流：awareness 'update' 事件 → parsePresenceState 校验（fail-closed，
+// 畸形远端 state 直接丢弃）→ applyRemote/syncRemote 按 userId 去重。
+// 同 userId 多 tab：同一用户两个 tab 是两个 awareness client，各持一份
+// state，按 ts 取最新（本模块唯一去重口径）。
+//
+// 断线摘除双保险：① 依赖 awareness 协议内建超时（默认 30s，远端消失以
+// removed 事件 → syncRemote 快照重建自然摘除）；② store 侧 pruneStale 按
+// ts 过期兜底（ts 语义=「最后活跃」：路由变化即时续报 + 上报方 15s 心跳
+// 续报刷新 ts，30s 无任何续报才视为离线——仅靠路由变化续报会把挂机的
+// 在线用户误摘，审查关键①）。provider 状态 offline 时整体清空（§8.2
+// 降级为「不显示」），connecting 不清空（等待重连后 awareness 全量快照
+// 重建）。
+
+import { Store } from '@tanstack/store'
+import { useStore } from '@tanstack/react-store'
+
+// ---------------------------------------------------------------------------
+// 类型（§8.1 awareness state schema 逐字）
+// ---------------------------------------------------------------------------
+
+/** 在场成员头像摘要（USER_BRIEF_SELECT 口径：id/username/avatarConfig/bgShape/bgColor） */
+export interface PresenceUser {
+  id: string
+  username: string
+  avatarConfig?: Record<string, number> | null
+  bgShape?: string | null
+  bgColor?: string | null
+}
+
+/** 页面区块（§8.1；list=模块列表页、detail=实体详情、board=看板、editor=编辑器） */
+export type PresenceSection = 'detail' | 'list' | 'board' | 'editor'
+
+/** 一级模块 key（§8.1 枚举开放：已知 key 见 module-map.ts MODULE_ROUTES） */
+export type PresenceModule = string
+
+/**
+ * awareness state（每人一份，§8.1 逐字）。
+ * route 为剥 query 的纯路径（脱敏）；entityTitle 详情页标题（tooltip 用）。
+ */
+export interface PresenceState {
+  user: PresenceUser
+  module: PresenceModule
+  route: string
+  entityTitle?: string
+  section?: PresenceSection
+  ts: number
+}
+
+/** presence provider 连接状态（对齐 provider.ts CollabConnectionStatus 三态） */
+export type PresenceStatus = 'connecting' | 'synced' | 'offline'
+
+/** store 侧过期口径：对齐 awareness 协议内建超时 30s */
+export const PRESENCE_STALE_MS = 30_000
+
+interface PresenceStoreState {
+  /** 远端队友（含本机其他 tab 的自己），key = user.id */
+  teammates: ReadonlyMap<string, PresenceState>
+  status: PresenceStatus
+}
+
+const INITIAL_STATE: PresenceStoreState = {
+  teammates: new Map(),
+  status: 'offline',
+}
+
+/** 全局单例（anyhub-store 同款 module-level store 惯例） */
+export const presenceStore = new Store<PresenceStoreState>(INITIAL_STATE)
+
+// ---------------------------------------------------------------------------
+// schema 校验（远端 state 不可信，fail-closed）
+// ---------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** kernel AvatarConfig 形态校验（Record<string, number>） */
+function isAvatarConfig(value: unknown): value is Record<string, number> {
+  return (
+    isRecord(value) && Object.values(value).every((v) => typeof v === 'number')
+  )
+}
+
+function parsePresenceUser(raw: unknown): PresenceUser | null {
+  if (!isRecord(raw)) return null
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return null
+  if (typeof raw.username !== 'string') return null
+  // 只保留 schema 字段（丢弃 email 等多余 PII，awareness 对全员可见）
+  const user: PresenceUser = { id: raw.id, username: raw.username }
+  if (isAvatarConfig(raw.avatarConfig)) user.avatarConfig = raw.avatarConfig
+  if (typeof raw.bgShape === 'string') user.bgShape = raw.bgShape
+  if (typeof raw.bgColor === 'string') user.bgColor = raw.bgColor
+  return user
+}
+
+/**
+ * 校验并归一一份 awareness state（§8.1 schema）。
+ * 任何字段缺失/类型不符返回 null（调用方丢弃，不抛错——远端 state 不可信）。
+ */
+export function parsePresenceState(raw: unknown): PresenceState | null {
+  if (!isRecord(raw)) return null
+  const user = parsePresenceUser(raw.user)
+  if (!user) return null
+  if (typeof raw.module !== 'string' || raw.module.length === 0) return null
+  if (typeof raw.route !== 'string') return null
+  if (typeof raw.ts !== 'number' || !Number.isFinite(raw.ts)) return null
+  const state: PresenceState = { user, module: raw.module, route: raw.route, ts: raw.ts }
+  if (typeof raw.entityTitle === 'string') state.entityTitle = raw.entityTitle
+  if (raw.section !== undefined) {
+    // 可选枚举字段出现即必须合法（fail-closed：畸形值整份拒绝）
+    if (
+      raw.section !== 'detail' &&
+      raw.section !== 'list' &&
+      raw.section !== 'board' &&
+      raw.section !== 'editor'
+    ) {
+      return null
+    }
+    state.section = raw.section
+  }
+  return state
+}
+
+/** 同 userId 多 tab 去重：取最新 ts（相等视为已存在，不替换保引用稳定） */
+function newer(a: PresenceState, b: PresenceState): boolean {
+  return a.ts > b.ts
+}
+
+// ---------------------------------------------------------------------------
+// actions（store 外部唯一写入口，全量不可变更新）
+// ---------------------------------------------------------------------------
+
+export const presenceActions = {
+  /**
+   * 应用一份远端 awareness state（增量）：校验 → 按 userId 以最新 ts upsert。
+   * 返回是否被采纳（畸形/过期 ts 为 false）。
+   */
+  applyRemote(raw: unknown): boolean {
+    const parsed = parsePresenceState(raw)
+    if (!parsed) return false
+    const existing = presenceStore.get().teammates.get(parsed.user.id)
+    if (existing && !newer(parsed, existing)) return false
+    presenceStore.setState((prev) => {
+      const teammates = new Map(prev.teammates)
+      teammates.set(parsed.user.id, parsed)
+      return { ...prev, teammates }
+    })
+    return true
+  },
+
+  /**
+   * 以远端 awareness 全量快照重建（awareness 'update' 事件后调用）：
+   * 同 userId 多 tab 去重取最新 ts；快照中消失的 userId（离线/关页被
+   * awareness 摘除）自然移除。畸形条目跳过不抛错。
+   */
+  syncRemote(rawStates: readonly unknown[]): void {
+    const byUser = new Map<string, PresenceState>()
+    for (const raw of rawStates) {
+      const parsed = parsePresenceState(raw)
+      if (!parsed) continue
+      const existing = byUser.get(parsed.user.id)
+      if (existing && !newer(parsed, existing)) continue
+      byUser.set(parsed.user.id, parsed)
+    }
+    presenceStore.setState((prev) => ({ ...prev, teammates: byUser }))
+  },
+
+  /** 精确摘除单人（awareness removed 事件定向清理用） */
+  remove(userId: string): void {
+    presenceStore.setState((prev) => {
+      if (!prev.teammates.has(userId)) return prev
+      const teammates = new Map(prev.teammates)
+      teammates.delete(userId)
+      return { ...prev, teammates }
+    })
+  },
+
+  /**
+   * store 侧过期兜底：摘除 ts 早于 now - PRESENCE_STALE_MS 的条目
+   * （awareness 超时事件丢失时的第二道防线），返回被摘除的 userId 列表。
+   */
+  pruneStale(now: number = Date.now()): string[] {
+    const cutoff = now - PRESENCE_STALE_MS
+    const pruned: string[] = []
+    presenceStore.setState((prev) => {
+      let changed = false
+      const teammates = new Map(prev.teammates)
+      for (const [userId, state] of teammates) {
+        if (state.ts < cutoff) {
+          teammates.delete(userId)
+          pruned.push(userId)
+          changed = true
+        }
+      }
+      return changed ? { ...prev, teammates } : prev
+    })
+    return pruned
+  },
+
+  /**
+   * presence provider 连接状态同步；offline 时清空 teammates
+   * （§8.2：WS 不可用 presence 退化为「不显示」而非展示过期位置）。
+   */
+  setStatus(status: PresenceStatus): void {
+    presenceStore.setState((prev) => {
+      if (prev.status === status) return prev
+      if (status === 'offline') {
+        return { status, teammates: new Map<string, PresenceState>() }
+      }
+      return { ...prev, status }
+    })
+  },
+
+  /** 清空队友（登出等场景；保留 status） */
+  clear(): void {
+    presenceStore.setState((prev) => ({ ...prev, teammates: new Map() }))
+  },
+}
+
+/** 测试隔离：恢复初始状态（不构成公开 API 契约） */
+export function __resetPresenceStoreForTests(): void {
+  presenceStore.setState(() => ({
+    teammates: new Map(INITIAL_STATE.teammates),
+    status: INITIAL_STATE.status,
+  }))
+}
+
+// ---------------------------------------------------------------------------
+// hooks（任务 10 消费面）
+// ---------------------------------------------------------------------------
+
+/** 浅比较数组（元素引用级）：selector 产出新数组时避免 useStore 死循环 */
+function areStateListsEqual(a: readonly PresenceState[], b: readonly PresenceState[]): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+/** avatarConfig 内容相等（Record<string, number>，键序无关；nullish 归一为 null） */
+function isAvatarConfigContentEqual(
+  a: Record<string, number> | null,
+  b: Record<string, number> | null,
+): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  const keys = Object.keys(a)
+  if (keys.length !== Object.keys(b).length) return false
+  return keys.every((k) => a[k] === b[k])
+}
+
+/**
+ * 单条 presence 内容相等：**忽略 ts**（心跳续报只前进 ts，展示内容不变）。
+ * 审查重要①配套：syncRemote 每次 awareness update 全量重建条目对象，
+ * 引用级相等必然不等 → 订阅方按内容级相等跳过空转重渲染。
+ */
+export function isPresenceContentEqual(a: PresenceState, b: PresenceState): boolean {
+  if (a === b) return true
+  return (
+    a.module === b.module &&
+    a.route === b.route &&
+    a.section === b.section &&
+    a.entityTitle === b.entityTitle &&
+    a.user.id === b.user.id &&
+    a.user.username === b.user.username &&
+    a.user.bgShape === b.user.bgShape &&
+    a.user.bgColor === b.user.bgColor &&
+    isAvatarConfigContentEqual(a.user.avatarConfig ?? null, b.user.avatarConfig ?? null)
+  )
+}
+
+/** 内容级列表相等（元素级 isPresenceContentEqual，顺序敏感） */
+export function arePresenceListsContentEqual(
+  a: readonly PresenceState[],
+  b: readonly PresenceState[],
+): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (!isPresenceContentEqual(a[i]!, b[i]!)) return false
+  }
+  return true
+}
+
+/**
+ * 订阅队友 presence。selfId 为登录用户 id（session 口径，调用方传入）——
+ * 命中者被排除（§8.2「本人头像不出现在自己侧边栏」）。selector 缺省返回
+ * 全部队友；配合 byModule(module) 按模块过滤。equality 缺省引用级；展示
+ * 类订阅方（行徽标等）传 arePresenceListsContentEqual 可消除心跳式
+ * state 重建（内容相等、ts 前进）引发的空转重渲染（审查重要①）。
+ */
+export function useTeammates(
+  selector?: (list: PresenceState[]) => PresenceState[],
+  selfId?: string | null,
+  equality: (a: PresenceState[], b: PresenceState[]) => boolean = areStateListsEqual,
+): PresenceState[] {
+  return useStore(
+    presenceStore,
+    (state) => {
+      const list = [...state.teammates.values()].filter(
+        (mate) => mate.user.id !== selfId,
+      )
+      return selector ? selector(list) : list
+    },
+    equality,
+  )
+}
+
+/**
+ * 按一级模块过滤的 selector（每模块单例，identity 稳定可安全内联调用）。
+ * 返回保持 store 内插入序（awareness client 序，无业务排序语义）。
+ */
+const byModuleSelectors = new Map<PresenceModule, (list: PresenceState[]) => PresenceState[]>()
+
+export function byModule(module: PresenceModule): (list: PresenceState[]) => PresenceState[] {
+  let selector = byModuleSelectors.get(module)
+  if (!selector) {
+    selector = (list) => list.filter((state) => state.module === module)
+    byModuleSelectors.set(module, selector)
+  }
+  return selector
+}
+
+/** 订阅 presence 连接状态（降级 UI 用：offline → 不渲染头像组） */
+export function usePresenceStatus(): PresenceStatus {
+  return useStore(presenceStore, (state) => state.status)
+}