@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/collab/provider.ts

@@ -0,0 +1,378 @@
+// 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/>.
+
+// 协同客户端连接单例管理（§6）。
+//
+// ── 多路复用决策（2026-10-07 实测，HocuspocusProvider@4.7.0）──────────────
+// 结论：采用 HocuspocusProviderWebsocket 共享单连接（多 room 复用一条
+// WebSocket），回退方案（每 room 独立连接）不需要。
+// 实测证据（apps/collab/src/__tests__/multiplex.test.ts，真 server 随机端口）：
+//   ① 双 room 双活内容隔离 ✓ ② 并发建连/断开 20 轮无卡死、无串 room ✓
+//   ③ 即建即断竞态 10 轮不抛错 ✓ ④ 全套连续 10 次运行全绿 ✓
+// 已证 4.7 约束：共享连接按 effectiveName 键控，同一 room 同时只允许一个
+// provider（重复 attach 抛错）——本模块 entries 单例表天然保证；服务端
+// （@hocuspocus/server@4.7）onAuthenticate 按文档执行，room 级 ticket 在
+// 共享连接下成立，单 room 鉴权失败不断开整条连接。
+// ──────────────────────────────────────────────────────────────────────
+//
+// 连接流程：serverFn 取 ticket（token 为 async 函数，每次 onOpen 重新取，
+// 60s exp 的 ticket 过期即由重连自动重取）→ HocuspocusProvider 建连 →
+// 鉴权失败（PermissionDenied/token 获取失败）按指数退避 detach/attach 重试
+// （1s 起步 ×2，30s 封顶，对齐 use-notifications 的 sse-transport 参数），
+// 连续 6 次失败进入 offline；socket 级连接失败由 provider 内置 retry 承接
+// （同参数 + maxAttempts 6），耗尽同样进入 offline。
+//
+// 纪律：本目录禁止 import @/server/** 非 serverFns 子路径与
+// @allbluecn/database（ESLint no-restricted-imports 守护）；严禁引入
+// @hocuspocus/server（P0 级客户端 bundle 污染）。
+
+import {
+  HocuspocusProvider,
+  HocuspocusProviderWebsocket,
+  WebSocketStatus,
+} from '@hocuspocus/provider'
+import * as Y from 'yjs'
+import { createCollabTicketFn } from '@/server/serverFns/collab'
+import { getCollabWsUrl, isCollabEnabled } from './env'
+
+/**
+ * awareness 实例类型（从 provider getter 派生，避免 apps/web 直依赖
+ * y-protocols——pnpm 严格隔离下非直接依赖不可 import）。
+ * noop 模式无 provider 实例，handle.awareness 为 null（presence 降级不渲染）。
+ */
+export type CollabAwareness = NonNullable<HocuspocusProvider['awareness']>
+
+/** 连接状态机（任务 15 降级模式消费）：connecting 建连/重试中、synced 可协同、offline 不可用 */
+export type CollabConnectionStatus = 'connecting' | 'synced' | 'offline'
+
+type StatusListener = (status: CollabConnectionStatus) => void
+
+/** 退避参数：对齐 sse-transport（use-notifications 重连先例）1s ×2 30s 封顶 */
+const RECONNECT_INITIAL_DELAY = 1000
+const RECONNECT_FACTOR = 2
+const RECONNECT_MAX_DELAY = 30000
+/** 连续失败上限：达到即 offline（auth 与 socket 两条路径同一口径） */
+const MAX_ATTEMPTS = 6
+
+/** 指数退避：第 n 次失败的等待时长（n 从 1 计） */
+function backoffDelay(failures: number): number {
+  return Math.min(
+    RECONNECT_INITIAL_DELAY * RECONNECT_FACTOR ** (failures - 1),
+    RECONNECT_MAX_DELAY,
+  )
+}
+
+interface LiveEntry {
+  kind: 'live'
+  roomName: string
+  socketUrl: string
+  doc: Y.Doc
+  provider: HocuspocusProvider
+  status: CollabConnectionStatus
+  listeners: Set<StatusListener>
+  authFailures: number
+  retryTimer: ReturnType<typeof setTimeout> | null
+  /** 自定义 ticket 获取（presence/share 等非实体 room）；缺省走实体 ticket serverFn */
+  getTicket?: TicketFetcher
+  handle: CollabProviderHandle
+}
+
+interface NoopEntry {
+  kind: 'noop'
+  roomName: string
+  doc: Y.Doc
+  status: 'offline'
+  listeners: Set<StatusListener>
+  handle: CollabProviderHandle
+}
+
+type Entry = LiveEntry | NoopEntry
+
+/** 自定义 ticket 获取器（getOrCreateProvider opts.getTicket） */
+type TicketFetcher = (roomName: string) => Promise<string>
+
+/** room → 连接条目（单例表；同一 room 重复调用返回同一实例） */
+const entries = new Map<string, Entry>()
+
+// ---------------------------------------------------------------------------
+// 共享 socket 池（多路复用决策落地：每服务地址一条 WebSocket，引用计数管理）
+// ---------------------------------------------------------------------------
+
+interface SharedSocket {
+  socket: HocuspocusProviderWebsocket
+  refCount: number
+}
+
+const sharedSockets = new Map<string, SharedSocket>()
+
+/** 测试注入口：替换底层 WebSocket 实现（生产走浏览器原生 WebSocket） */
+type WebSocketPolyfillConstructor = abstract new (
+  url: string,
+) => EventTarget & {
+  send(data: ArrayBuffer | Uint8Array): void
+  close(): void
+  readyState: number
+}
+let webSocketPolyfillOverride: WebSocketPolyfillConstructor | undefined
+
+function liveEntries(): LiveEntry[] {
+  return [...entries.values()].filter(
+    (entry): entry is LiveEntry => entry.kind === 'live',
+  )
+}
+
+function acquireSharedSocket(url: string): SharedSocket {
+  const existing = sharedSockets.get(url)
+  if (existing) {
+    existing.refCount += 1
+    return existing
+  }
+  const socket = new HocuspocusProviderWebsocket({
+    url,
+    delay: RECONNECT_INITIAL_DELAY,
+    initialDelay: 0,
+    factor: RECONNECT_FACTOR,
+    maxDelay: RECONNECT_MAX_DELAY,
+    maxAttempts: MAX_ATTEMPTS,
+    jitter: false,
+    WebSocketPolyfill: webSocketPolyfillOverride,
+    onStatus: ({ status }) => {
+      if (status !== WebSocketStatus.Disconnected) return
+      // 网络断开：未 offline 的活连接回到 connecting（重连后 onOpen 自动重鉴权）
+      for (const entry of liveEntries()) {
+        if (entry.status === 'synced') setEntryStatus(entry, 'connecting')
+      }
+    },
+    onMaxAttemptsFailed: () => {
+      // socket 级重试耗尽：所有活连接进入 offline
+      for (const entry of liveEntries()) setEntryStatus(entry, 'offline')
+    },
+  })
+  const shared: SharedSocket = { socket, refCount: 1 }
+  sharedSockets.set(url, shared)
+  return shared
+}
+
+function releaseSharedSocket(url: string): void {
+  const shared = sharedSockets.get(url)
+  if (!shared) return
+  shared.refCount -= 1
+  if (shared.refCount <= 0) {
+    sharedSockets.delete(url)
+    shared.socket.destroy()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 状态机与鉴权失败重试
+// ---------------------------------------------------------------------------
+
+function setEntryStatus(entry: Entry, status: CollabConnectionStatus): void {
+  if (entry.status === status) return
+  entry.status = status
+  for (const listener of entry.listeners) listener(status)
+}
+
+/**
+ * 鉴权失败（PermissionDenied / ticket 获取失败）：detach 后按指数退避
+ * re-attach。attach 到已连接 socket 会重新走 onOpen → sendToken（新 ticket）。
+ * 共享 socket 上其余 room 不受影响（服务端按文档拒绝，连接存活）。
+ */
+function handleAuthFailure(entry: LiveEntry): void {
+  if (entry.retryTimer) return
+  entry.authFailures += 1
+  if (entry.authFailures >= MAX_ATTEMPTS) {
+    // 上限：进入 offline，停止重试（重建 provider 才能恢复）
+    entry.provider.detach()
+    setEntryStatus(entry, 'offline')
+    return
+  }
+  setEntryStatus(entry, 'connecting')
+  const delay = backoffDelay(entry.authFailures)
+  entry.provider.detach()
+  entry.retryTimer = setTimeout(() => {
+    entry.retryTimer = null
+    if (entries.get(entry.roomName) !== entry) return // 已销毁
+    entry.provider.attach()
+  }, delay)
+}
+
+function createLiveEntry(roomName: string, getTicket?: TicketFetcher): LiveEntry {
+  const url = getCollabWsUrl()
+  const shared = acquireSharedSocket(url)
+  const doc = new Y.Doc()
+  // token 为 async 函数：每次 onOpen（含重连）都重新取 ticket，60s exp 的
+  // 过期 ticket 由重连自然重取，无需独立刷新逻辑；getTicket 覆盖仅在建连
+  // 时生效（单例表按 roomName 键控，同 room 的后续调用共享首个 fetcher）
+  const fetchTicket: TicketFetcher = getTicket ?? (async (name) => {
+    const { ticket } = await createCollabTicketFn({ data: { roomName: name } })
+    return ticket
+  })
+  const provider = new HocuspocusProvider({
+    websocketProvider: shared.socket,
+    name: roomName,
+    document: doc,
+    token: async () => fetchTicket(roomName),
+    onSynced: ({ state }) => {
+      if (!state) return
+      entry.authFailures = 0 // 完整恢复：清零退避计数
+      setEntryStatus(entry, 'synced')
+    },
+    onAuthenticationFailed: () => handleAuthFailure(entry),
+  })
+  const entry: LiveEntry = {
+    kind: 'live',
+    roomName,
+    socketUrl: url,
+    doc,
+    provider,
+    status: 'connecting',
+    listeners: new Set(),
+    authFailures: 0,
+    retryTimer: null,
+    getTicket,
+    handle: null as unknown as CollabProviderHandle,
+  }
+  entry.handle = buildHandle(entry)
+  entries.set(roomName, entry)
+  provider.attach()
+  return entry
+}
+
+function createNoopEntry(roomName: string): NoopEntry {
+  const entry: NoopEntry = {
+    kind: 'noop',
+    roomName,
+    doc: new Y.Doc(),
+    status: 'offline',
+    listeners: new Set(),
+    handle: null as unknown as CollabProviderHandle,
+  }
+  entry.handle = buildHandle(entry)
+  entries.set(roomName, entry)
+  return entry
+}
+
+// ---------------------------------------------------------------------------
+// 公开 API
+// ---------------------------------------------------------------------------
+
+export interface CollabProviderHandle {
+  readonly roomName: string
+  /** 协同 Y.Doc（noop 模式为本地空文档，编辑器可单机使用） */
+  readonly doc: Y.Doc
+  /**
+   * awareness 实例（presence 读写 local/remote state 用）。live 模式由
+   * provider 构造器同步创建（恒非 null）；noop 模式（协同不可用）为
+   * null——消费方按「降级不渲染」处理，不抛错。
+   */
+  readonly awareness: CollabAwareness | null
+  getStatus(): CollabConnectionStatus
+  /** 订阅状态变化；立即以当前状态回调一次，返回退订函数 */
+  onStatusChange(listener: StatusListener): () => void
+  /**
+   * 透传底层 provider 事件（UniqueID 协同态监听 'synced' 再补 ID——
+   * 编辑器扩展工厂的契约面，缺成员即编辑器创建崩溃）。noop 安全空操作。
+   * on 返回退订函数；off 幂等移除。
+   */
+  on(event: string, listener: (...args: unknown[]) => unknown): () => void
+  off(event: string, listener: (...args: unknown[]) => unknown): void
+  destroy(): void
+}
+
+function buildHandle(entry: Entry): CollabProviderHandle {
+  return {
+    roomName: entry.roomName,
+    doc: entry.doc,
+    awareness: entry.kind === 'live' ? entry.provider.awareness : null,
+    getStatus: () => entry.status,
+    onStatusChange: (listener) => {
+      entry.listeners.add(listener)
+      listener(entry.status) // 立即回放当前状态
+      return () => entry.listeners.delete(listener)
+    },
+    on: (event, listener) => {
+      if (entry.kind !== 'live') return () => {}
+      entry.provider.on(event, listener)
+      return () => entry.provider.off(event, listener)
+    },
+    off: (event, listener) => {
+      if (entry.kind !== 'live') return
+      entry.provider.off(event, listener)
+    },
+    destroy: () => destroyProvider(entry.roomName),
+  }
+}
+
+/** getOrCreateProvider 建连选项（仅在首次创建该 room 时生效） */
+export interface CollabProviderOptions {
+  /**
+   * 自定义 ticket 获取（presence:team:* 等非实体 room 必传，缺省走
+   * createCollabTicketFn 实体 ticket——presence room 会被其入口拒绝）。
+   * 同 room 已存在单例时本参数被忽略（复用首个连接与 fetcher）。
+   */
+  getTicket?: (roomName: string) => Promise<string>
+}
+
+/**
+ * 取 room 协同连接（单例）：已存在直接复用；协同不可用（desktop 版 /
+ * 未配置 VITE_COLLAB_WS_URL）返回 noop（全方法安全空操作，状态恒 offline、
+ * awareness 为 null）。
+ */
+export function getOrCreateProvider(
+  roomName: string,
+  options?: CollabProviderOptions,
+): CollabProviderHandle {
+  const existing = entries.get(roomName)
+  if (existing) return existing.handle
+  const entry = isCollabEnabled()
+    ? createLiveEntry(roomName, options?.getTicket)
+    : createNoopEntry(roomName)
+  return entry.handle
+}
+
+/** 销毁 room 连接：清理重试定时器、从共享 socket 摘除（最后一个销毁时关连接） */
+export function destroyProvider(roomName: string): void {
+  const entry = entries.get(roomName)
+  if (!entry) return
+  entries.delete(roomName)
+  if (entry.kind === 'live') {
+    if (entry.retryTimer) clearTimeout(entry.retryTimer)
+    entry.provider.destroy()
+    releaseSharedSocket(entry.socketUrl)
+  }
+  entry.listeners.clear()
+  entry.doc.destroy()
+}
+
+// ---------------------------------------------------------------------------
+// 测试钩子（不构成公开 API 契约）
+// ---------------------------------------------------------------------------
+
+/** 注入 mock WebSocket（单元测试用；传 undefined 还原原生实现） */
+export function __setWebSocketPolyfillForTests(
+  polyfill: WebSocketPolyfillConstructor | undefined,
+): void {
+  webSocketPolyfillOverride = polyfill
+}
+
+/** 清空全部连接与共享 socket 池（单元测试隔离用） */
+export function __resetCollabForTests(): void {
+  for (const roomName of [...entries.keys()]) destroyProvider(roomName)
+  for (const [, shared] of sharedSockets) shared.socket.destroy()
+  sharedSockets.clear()
+}

package/src/lib/collab/use-collab-doc.ts

@@ -0,0 +1,100 @@
+// 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.
+
+// 实体 room 的协同文档 hook（规格 §6 文件树 use-collab-doc.ts）。
+//
+// 职责（任务 15 消费口径）：
+//   ① getOrCreateProvider 单例建连（noop 环境 desktop/未配置 WS 返回 noop）
+//   ② SSR 快照预水合：loader 传来的 base64 update 在建连前 applyUpdate 进
+//      provider doc——水合目标就是连接 doc 本身（非旁路副本），provider
+//      建连后的增量同步直接续在同一份 Y.Doc 上（§6 水合链路）
+//   ③ 状态订阅：connecting/synced/offline 状态机暴露给编辑器降级消费
+//   ④ 卸载销毁（room 单例引用随页面离开释放；lazy 路由双挂载是完整
+//      unmount/remount——useState 重新初始化重建连接，路径安全；应用主树
+//      未启用 React StrictMode，若未来启用需复查「state 保留 + effect
+//      cleanup 销毁」的组合，届时改为 effect 内创建）
+//
+// 返回 null 的情形：SSR（服务端不建连——HocuspocusProvider/WebSocket 是
+// 纯浏览器资源，模块级单例表也不能在服务端累积）。消费方按「协同不可用」
+// 处理：NotionDocEditor 以 immediatelyRender:false 仅在客户端创建编辑器，
+// 服务端返回 null 不产生 DOM 差异。
+
+import { useEffect, useState } from 'react'
+import * as Y from 'yjs'
+import {
+  getOrCreateProvider,
+  type CollabConnectionStatus,
+  type CollabProviderHandle,
+} from './provider'
+
+/** base64 → bytes（客户端安全，无 node:crypto；同 use-share-presence 口径） */
+function base64ToBytes(base64: string): Uint8Array {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+export interface UseCollabDocOptions {
+  roomName: string
+  /** loader 并行取回的 SSR 快照（base64；null = 空文档/首次协同打开） */
+  snapshot: string | null
+}
+
+export interface UseCollabDocResult {
+  /** room 连接句柄（SSR 为 null；doc 已完成快照预水合） */
+  handle: CollabProviderHandle | null
+  /** 连接状态机（handle 为 null 时恒 null） */
+  status: CollabConnectionStatus | null
+}
+
+export function useCollabDoc(options: UseCollabDocOptions): UseCollabDocResult {
+  const { roomName, snapshot } = options
+
+  // 建连 + 预水合（useState 惰性初始化：每实例恰好一次；快照幂等，Y update
+  // 重复应用无副作用）。roomName 按实体 key 变化时组件整树重建（route
+  // key={id}），无需响应 roomName 变化。
+  const [handle] = useState<CollabProviderHandle | null>(() => {
+    if (import.meta.env.SSR) return null
+    const created = getOrCreateProvider(roomName)
+    if (snapshot) {
+      try {
+        // yjs 13.6.x：applyUpdate 是模块级导出（Doc 实例方法已移除）
+        Y.applyUpdate(created.doc, base64ToBytes(snapshot))
+      } catch (error) {
+        // 快照损坏不阻塞编辑：降级为空文档增量同步
+        console.error('collab snapshot decode failed:', error)
+      }
+    }
+    return created
+  })
+
+  const status = useCollabStatus(handle)
+
+  // 卸载销毁：页面离开释放 room 连接（presence hook 同口径）
+  useEffect(() => {
+    return () => {
+      handle?.destroy()
+    }
+  }, [handle])
+
+  return { handle, status }
+}
+
+/** 订阅 provider 状态机（useCollabDoc 内部用；单独导出便于测试） */
+export function useCollabStatus(handle: CollabProviderHandle | null): CollabConnectionStatus | null {
+  const [status, setStatus] = useState<CollabConnectionStatus | null>(() =>
+    handle ? handle.getStatus() : null,
+  )
+  useEffect(() => {
+    if (!handle) return
+    return handle.onStatusChange(setStatus)
+  }, [handle])
+  return status
+}

package/src/lib/collab/use-presence-list-refresh.ts

@@ -0,0 +1,142 @@
+// 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/>.
+
+// 列表实时刷新 hook（任务 24，§7.1「列表查询缓存 observe 失效刷新」）。
+//
+// 控制者裁决落地（task-24 派发上下文）：列表页不建连实体 room（每行建连
+// 不可取，性能红线），远端字段变更感知走 presence 弱信号组合——
+//   ① presence 信号：本模块内「正在看实体」的成员集合（id+route 签名）
+//      变化（成员进出实体页）→ 防抖刷新对应列表。协同编辑者保存后离开
+//      实体页（presence 变化）时，停留在列表页的其他成员随即看到新数据。
+//   ② 窗口回前台刷新（refetchOnWindowFocus 惯例）。
+//   ③ 适度轮询（refetchInterval 惯例，默认 60s）：覆盖「编辑者保存后停留
+//      在详情页、列表读者无任何操作」的无信号窗口。
+// 已知边界（报告备案）：协同态编辑不 bump DB updatedAt、落库走 collab
+// debounce，编辑者停留详情页期间列表只能靠 ②③ 兜底；实时性由
+// refetchInterval 上限决定，属裁决接受的取舍。
+//
+// 数据源约束：story/bug/testcase 列表页均为「serverFn 直调 + 本地 state」
+// （禁 react-query），故本 hook 不做 invalidateQueries，而是接收调用方的
+// refresh 回调（列表页既有重拉入口，内部自带 signature 防过期）。
+//
+// 自身 presence 不过滤（不传 selfId）：本机其他 tab 打开实体同样构成
+// 「实体可能已变更」信号，刷新无害且有益。
+//
+// section 口径：仅统计 section === 'detail' 的成员（buildPresenceState
+// 启发式：模块根路径=list、更深路径=detail）；成员在列表页进出不改变
+// 列表数据，不作信号。旧端 presence 无 section（缺省 undefined）但 route
+// 指向实体深路径时按在看处理（宽松兼容，多刷一次无害）——见
+// isEntityViewer。
+
+import { useEffect, useRef } from 'react'
+import { useStore } from '@tanstack/react-store'
+import { useDebouncedCallback } from '@/lib/pacer'
+import { presenceStore } from './presence-store'
+import { MODULE_ROUTES } from './module-map'
+import type { PresenceState } from './presence-store'
+
+/** presence 变化 → 刷新的防抖窗口（合并 awareness 快照重建的连发） */
+export const PRESENCE_LIST_REFRESH_DEBOUNCE_MS = 1000
+
+/** 轮询兜底间隔（refetchInterval 惯例；0 关闭） */
+export const PRESENCE_LIST_REFRESH_POLL_MS = 60_000
+
+/** 实体在看判定：detail section，或旧端无 section 但路由深于模块根 */
+function isEntityViewer(state: PresenceState): boolean {
+  if (state.section === 'detail') return true
+  if (state.section) return false
+  // 无 section（旧端兼容）：以模块根路径深度判定（深于根 = 实体页）
+  const def = MODULE_ROUTES.find((r) => r.module === state.module)
+  return def != null && state.route.startsWith(`${def.link}/`)
+}
+
+/** 在看者集合签名（id+route 排序拼接）：ts 心跳不改签名，进出实体才改 */
+export function entityViewersSignature(list: readonly PresenceState[]): string {
+  return list
+    .filter(isEntityViewer)
+    .map((s) => `${s.user.id}@${s.route}`)
+    .sort()
+    .join('|')
+}
+
+export interface UsePresenceListRefreshArgs {
+  /** 一级模块 key（§8.1，如 stories/bugs/test-cases） */
+  module: string
+  /** 列表重拉回调（列表页既有 refresh 入口，闭包始终取最新） */
+  refresh: () => void
+  /** 轮询间隔 ms（默认 60s；传 0 关闭轮询） */
+  pollIntervalMs?: number
+  /** presence 信号防抖窗口 ms（默认 1s；测试可调小） */
+  debounceMs?: number
+}
+
+/**
+ * presence 驱动的列表刷新。在列表页组件挂载处调用一次；refresh 回调用
+ * 列表页既有重拉函数（无需 memo 稳定，hook 内部经 ref 取最新闭包）。
+ */
+export function usePresenceListRefresh({
+  module,
+  refresh,
+  pollIntervalMs = PRESENCE_LIST_REFRESH_POLL_MS,
+  debounceMs = PRESENCE_LIST_REFRESH_DEBOUNCE_MS,
+}: UsePresenceListRefreshArgs): void {
+  // 审查重要①：签名计算下沉 store selector——快照是签名字符串（默认
+  // Object.is 值相等），心跳式全量重建（id+route 不变的新对象）不再触发
+  // 挂载组件（StoryListView 等重型列表体）的空转重渲染。模块过滤收进
+  // selector（原 byModule 前置口径不变），跨模块 presence 噪声不进签名。
+  const signature = useStore(
+    presenceStore,
+    (state) =>
+      entityViewersSignature(
+        [...state.teammates.values()].filter((s) => s.module === module),
+      ),
+  )
+
+  // refresh 恒取最新闭包（列表页筛选状态变化后重拉取当次筛选）
+  const refreshRef = useRef(refresh)
+  refreshRef.current = refresh
+  const debouncedRefresh = useDebouncedCallback(
+    () => refreshRef.current(),
+    { wait: debounceMs },
+  )
+  // useDebouncedCallback 每次渲染可能返回新函数（number-drag-input 同款
+  // 稳定化口径）：effect 经 ref 间接调用，避免订阅/定时器反复重建
+  const debouncedRef = useRef(debouncedRefresh)
+  debouncedRef.current = debouncedRefresh
+
+  // ① presence 信号：签名变化（挂载初值除外）→ 防抖刷新
+  const prevSignature = useRef(signature)
+  useEffect(() => {
+    if (prevSignature.current === signature) return
+    prevSignature.current = signature
+    debouncedRef.current()
+  }, [signature])
+
+  // ② 窗口回前台刷新 + ③ 轮询兜底（presence 不可用时列表仍有新鲜度下限）
+  useEffect(() => {
+    const onVisibilityChange = () => {
+      if (document.visibilityState === 'visible') debouncedRef.current()
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange)
+    const pollTimer =
+      pollIntervalMs > 0 ? setInterval(() => debouncedRef.current(), pollIntervalMs) : null
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibilityChange)
+      if (pollTimer) clearInterval(pollTimer)
+    }
+  }, [pollIntervalMs])
+}