@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/use-presence-report.ts

@@ -0,0 +1,176 @@
+// 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 上报 hook（R3，§8.1）——挂载于 _nav 布局（AppLayout）。
+// 职责：
+//   ① 引导：getPresenceRoomFn 拿团队 room（presence:team:{ownerId}）与
+//      USER_BRIEF_SELECT 口径的自身摘要（客户端 session 无 username/头像）
+//   ② 连接：getOrCreateProvider(presence room, 自定义 presence ticket)，
+//      与实体协同共享同一 WebSocket（多路复用，见 provider.ts 顶注释）
+//   ③ 上报：useLocation().pathname（响应式，禁用 useRouter().state.location
+//      的 stale 值）→ useThrottledCallback 2s（leading 首报即时、窗口内
+//      合并尾随）→ awareness.setLocalState（§8.1 schema，剥 query）
+//   ③′ 心跳：每 15s（对齐 awareness 协议 keepalive 节奏）用当前 pathname
+//      重报刷新 ts——ts 语义是「最后活跃」，仅靠路由变化续报会让挂机
+//      30s 的在线用户被 pruneStale 误摘（审查关键①）；y-protocols 的
+//      keepalive 只重发协议 meta，不刷新业务 ts 字段。tab 隐藏照常心跳
+//      （§8.1：隐藏不清除，保持模块位置语义）。
+//   ④ 接收：awareness 'update' → 全量快照 syncRemote（远端离线者自然摘除，
+//      自身过滤）+ pruneStale 兜底轮询
+//   ⑤ 摘除：provider offline → store 清空（setStatus 内语义）；卸载 →
+//      setLocalState(null)（他人侧 awareness removed）+ 清理心跳/prune
+//      定时器 + destroyProvider（presence room 生命周期跟随 _nav 挂载；
+//      实体协同 room 独立持有共享 socket 引用，互不影响）
+//
+// 协同不可用（desktop / 未配置 VITE_COLLAB_WS_URL）时全链路 no-op（§8.2
+// 降级为「不显示」）；tab 隐藏不清除（保持模块位置语义）。引导失败
+// （未登录/网络抖动）静默降级为不上报。幂等可重入：卸载同步清理全部
+// 副作用，重挂载重建（lazy 路由双挂载场景安全——destroy 先于重挂载
+// effect 执行，单例表按 roomName 重建）。
+
+import { useCallback, useEffect, useRef } from 'react'
+import { useLocation } from '@tanstack/react-router'
+import { useThrottledCallback } from '@/lib/pacer'
+import {
+  createPresenceTicketFn,
+  getPresenceRoomFn,
+} from '@/server/serverFns/collab-presence'
+import { destroyProvider, getOrCreateProvider } from './provider'
+import { isCollabEnabled } from './env'
+import { presenceActions } from './presence-store'
+import { PRESENCE_REPORT_THROTTLE_MS, buildPresenceState } from './module-map'
+import type { CollabAwareness } from './provider'
+import type { PresenceUser } from './presence-store'
+
+/** prune 兜底轮询间隔（与 store 侧过期口径一致；正常路径由 update 事件捎带） */
+const PRUNE_INTERVAL_MS = 30_000
+
+/**
+ * 心跳间隔（审查关键①）：对齐 awareness 协议 keepalive 节奏，保证
+ * store 侧 30s 摘除窗口内至少 1-2 次续报。setLocalState 内容变化（ts）
+ * 即触发 awareness 真实广播，远端 syncRemote 据此刷新该用户 ts。
+ */
+export const HEARTBEAT_INTERVAL_MS = 15_000
+
+/** awareness state 的自身识别形态（过滤 self 出 teammates 用） */
+interface AwarenessStateLike {
+  user?: { id?: unknown }
+}
+
+/**
+ * 全局 presence 上报。在 _nav 布局组件中调用一次即可。
+ */
+export function usePresenceReport(): void {
+  const pathname = useLocation().pathname
+  const awarenessRef = useRef<CollabAwareness | null>(null)
+  const userRef = useRef<PresenceUser | null>(null)
+  const pathnameRef = useRef(pathname)
+  pathnameRef.current = pathname
+
+  // §8.1：路由变化 → 2s 节流更新 awareness local state（leading 首报即时）
+  const reportLocation = useCallback((path: string) => {
+    const awareness = awarenessRef.current
+    const user = userRef.current
+    if (!awareness || !user) return
+    awareness.setLocalState(buildPresenceState(user, path, Date.now()))
+  }, [])
+  const throttledReport = useThrottledCallback(reportLocation, {
+    wait: PRESENCE_REPORT_THROTTLE_MS,
+  })
+
+  // §8.1：路由变化 → 2s 节流更新 awareness local state。只用节流调用——
+  // Throttler leading 即时首报（进新模块当次广播），窗口内快速导航合并为
+  // 一次尾随；此前的未节流直调使节流形同虚设（审查重要②，已删）。
+  useEffect(() => {
+    throttledReport(pathname)
+  }, [pathname, throttledReport])
+
+  useEffect(() => {
+    if (!isCollabEnabled()) return
+    let cancelled = false
+    let roomName: string | null = null
+    let unsubscribeStatus: (() => void) | null = null
+    let pruneTimer: ReturnType<typeof setInterval> | null = null
+    let heartbeatTimer: ReturnType<typeof setInterval> | null = null
+    let awareness: CollabAwareness | null = null
+
+    const onAwarenessUpdate = () => {
+      if (!awareness) return
+      const selfId = userRef.current?.id
+      const remotes = [...awareness.getStates().values()].filter(
+        (state) => (state as AwarenessStateLike | null)?.user?.id !== selfId,
+      )
+      presenceActions.syncRemote(remotes)
+      presenceActions.pruneStale()
+    }
+
+    getPresenceRoomFn()
+      .then((room) => {
+        if (cancelled) return
+        roomName = room.roomName
+        userRef.current = room.user
+        const provider = getOrCreateProvider(room.roomName, {
+          getTicket: async (name) => {
+            const { ticket } = await createPresenceTicketFn({
+              data: { roomName: name },
+            })
+            return ticket
+          },
+        })
+        const instance = provider.awareness
+        if (!instance) return // noop provider：协同不可用，静默降级
+        awareness = instance
+        awarenessRef.current = instance
+
+        unsubscribeStatus = provider.onStatusChange((status) => {
+          presenceActions.setStatus(status)
+          // 重连恢复后重放本机位置（detach/attach 往返可能丢 local state）
+          if (status === 'synced') reportLocation(pathnameRef.current)
+        })
+        instance.on('update', onAwarenessUpdate)
+        pruneTimer = setInterval(() => {
+          presenceActions.pruneStale()
+        }, PRUNE_INTERVAL_MS)
+        // 心跳续报（审查关键①）：挂机不导航也要刷新 ts，防 30s 误摘
+        heartbeatTimer = setInterval(() => {
+          reportLocation(pathnameRef.current)
+        }, HEARTBEAT_INTERVAL_MS)
+        // 引导完成即上报当前路径（进房互见不等下一次路由变化）
+        reportLocation(pathnameRef.current)
+        onAwarenessUpdate()
+      })
+      .catch(() => {
+        // 引导失败（未登录/网络抖动）：presence 静默降级为不上报
+      })
+
+    return () => {
+      cancelled = true
+      if (awareness) {
+        awareness.off('update', onAwarenessUpdate)
+        // 离场协议语义：置 null 使他人侧 awareness 触发 removed 摘除
+        awareness.setLocalState(null)
+      }
+      unsubscribeStatus?.()
+      if (pruneTimer) clearInterval(pruneTimer)
+      if (heartbeatTimer) clearInterval(heartbeatTimer)
+      awarenessRef.current = null
+      userRef.current = null
+      presenceActions.setStatus('offline')
+      if (roomName) destroyProvider(roomName)
+    }
+  }, [reportLocation])
+}

package/src/lib/collab/use-self-profile-broadcast.ts

@@ -0,0 +1,113 @@
+// 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/>.
+
+// 自身 profile 广播 hook（自 collab-presence-header 提取，任务 20 复用）：
+// 客户端 session 无 username/头像（见 use-presence-report 口径），经
+// getPresenceRoomFn 取 USER_BRIEF 后写入当前 room awareness 的 `profile`
+// 字段（与 Caret 的 `user` 字段并存，setLocalStateField 合并语义）。
+//
+// 消费方：CollabPresenceHeader（知识库编辑器头部头像组，任务 18）与
+// StoryCollabGate（Story 详情字段 editing 署名兜底，任务 20——binding 的
+// identity 缺省时 resolveIdentity 读 profile，无广播则 editing 标记降级为
+// client:{clientID} 署名）。
+//
+// 失败自愈（任务 18 审查修复①）：挂载首拉失败（网络抖动）后 brief 恒
+// null——若 synced 只做「重放」则是 no-op，整个长会话自己将永久以首字母
+// 示人。故 synced 分流：已有 brief → 重放（detach/attach 可能丢 local
+// state，同 use-presence-report 防御）；从未成功 → 重新拉取（inflight 守卫
+// 防并发重复请求）。引导持续失败则每次 synced 重试一次，静默降级不抛错。
+
+import { useEffect } from 'react'
+import { getPresenceRoomFn } from '@/server/serverFns/collab-presence'
+import type { CollabProviderHandle } from './provider'
+
+/** 在线协作者头像摘要（USER_BRIEF 口径） */
+export interface CollabPresenceUser {
+  id: string
+  username: string
+  avatarConfig?: Record<string, number> | null
+  bgShape?: string | null
+  bgColor?: string | null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** kernel AvatarConfig 形态校验（Record<string, number>，同 presence-store） */
+function isAvatarConfig(value: unknown): value is Record<string, number> {
+  return (
+    isRecord(value) && Object.values(value).every((v) => typeof v === 'number')
+  )
+}
+
+/** email 等多余字段不入 awareness（房间内所有人可见），只保留头像摘要字段 */
+function toAwarenessBrief(user: {
+  id: string
+  username: string
+  avatarConfig?: unknown
+  bgShape?: unknown
+  bgColor?: unknown
+}): CollabPresenceUser {
+  const brief: CollabPresenceUser = { id: user.id, username: user.username }
+  if (isAvatarConfig(user.avatarConfig)) brief.avatarConfig = user.avatarConfig
+  if (typeof user.bgShape === 'string') brief.bgShape = user.bgShape
+  if (typeof user.bgColor === 'string') brief.bgColor = user.bgColor
+  return brief
+}
+
+export function useSelfProfileBroadcast(handle: CollabProviderHandle | null): void {
+  useEffect(() => {
+    if (!handle) return
+    const awareness = handle.awareness
+    if (!awareness) return
+    let cancelled = false
+    let brief: CollabPresenceUser | null = null
+    let inflight = false
+    const publish = () => {
+      if (brief) awareness.setLocalStateField('profile', brief)
+    }
+    const fetchBrief = () => {
+      if (inflight) return
+      inflight = true
+      getPresenceRoomFn()
+        .then((room) => {
+          if (cancelled) return
+          brief = toAwarenessBrief(room.user)
+          publish()
+        })
+        .catch(() => {
+          // 引导失败（网络抖动等）：静默保留 null，待下次 synced 重拉
+        })
+        .finally(() => {
+          inflight = false
+        })
+    }
+    const ensureBrief = () => {
+      if (brief) publish()
+      else fetchBrief()
+    }
+    fetchBrief()
+    const unsubscribe = handle.onStatusChange((status) => {
+      if (status === 'synced') ensureBrief()
+    })
+    return () => {
+      cancelled = true
+      unsubscribe()
+    }
+  }, [handle])
+}