create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/api/activity/transports.ts

@@ -0,0 +1,271 @@
+import { ActivityError } from './errors'
+import type {
+  IActivityTransportAdapter,
+  IActivityTransportConnectContext,
+  ICreatePollingActivityTransportOptions,
+  ICreateSseActivityTransportOptions,
+  ICreateWebSocketActivityTransportOptions,
+  TActivityEventInput,
+} from './types'
+
+const nDefaultConnectTimeoutMs = 10_000
+
+function fnValidatePositiveDuration(nValue: number, strField: string) {
+  if (!Number.isFinite(nValue) || nValue <= 0) {
+    throw new ActivityError(
+      'INVALID_TRANSPORT_CONFIG',
+      `${strField} 必须是大于 0 的有限毫秒数。`
+    )
+  }
+  return nValue
+}
+
+function fnCreateAbortError() {
+  return new DOMException('活动连接已取消。', 'AbortError')
+}
+
+/** 使用生成客户端创建顺序执行、不会请求重叠的轮询 Adapter。 */
+export function fnCreatePollingActivityTransport({
+  fnPoll,
+  nIntervalMs: nIntervalInput = 30_000,
+}: ICreatePollingActivityTransportOptions): IActivityTransportAdapter {
+  const nIntervalMs = fnValidatePositiveDuration(nIntervalInput, 'nIntervalMs')
+  return Object.freeze({
+    strTransport: 'polling' as const,
+    fnConnect: async (objContext: IActivityTransportConnectContext) => {
+      let bIsClosed = false
+      let nTimer: ReturnType<typeof setTimeout> | undefined
+      let strLastEventId = objContext.strLastEventId
+      const fnClose = () => {
+        bIsClosed = true
+        if (nTimer !== undefined) clearTimeout(nTimer)
+        nTimer = undefined
+      }
+      const fnPollOnce = async () => {
+        const objEvents = await fnPoll({
+          objScope: objContext.objScope,
+          objSignal: objContext.objSignal,
+          ...(strLastEventId ? { strLastEventId } : {}),
+        })
+        if (bIsClosed || objContext.objSignal.aborted) return
+        objContext.fnOnEvent(objEvents)
+        const arrEvents = Array.isArray(objEvents) ? objEvents : [objEvents]
+        strLastEventId = arrEvents.at(-1)?.strEventId ?? strLastEventId
+      }
+      const fnScheduleNextPoll = () => {
+        if (bIsClosed || objContext.objSignal.aborted) return
+        nTimer = setTimeout(() => {
+          void fnPollOnce()
+            .then(fnScheduleNextPoll)
+            .catch((objCaughtError) => {
+              if (!bIsClosed && !objContext.objSignal.aborted) {
+                objContext.fnOnDisconnect(
+                  objCaughtError instanceof Error
+                    ? objCaughtError
+                    : new Error('轮询请求抛出了非标准错误。', {
+                        cause: objCaughtError,
+                      })
+                )
+              }
+            })
+        }, nIntervalMs)
+      }
+
+      objContext.objSignal.addEventListener('abort', fnClose, { once: true })
+      await fnPollOnce()
+      if (bIsClosed || objContext.objSignal.aborted) throw fnCreateAbortError()
+      fnScheduleNextPoll()
+      return Object.freeze({ fnClose })
+    },
+  })
+}
+
+function fnCreateTextStreamConnection(
+  objContext: IActivityTransportConnectContext,
+  {
+    fnCloseStream,
+    fnParseMessage,
+    fnSetHandlers,
+    nConnectTimeoutMs,
+    strTransport,
+  }: {
+    fnCloseStream: () => void
+    fnParseMessage: (
+      strData: string
+    ) => TActivityEventInput | readonly TActivityEventInput[]
+    fnSetHandlers: (objHandlers: {
+      fnOnClose: (objError: Error) => void
+      fnOnError: () => void
+      fnOnMessage: (strData: string) => void
+      fnOnOpen: () => void
+    }) => void
+    nConnectTimeoutMs: number
+    strTransport: 'sse' | 'websocket'
+  }
+) {
+  return new Promise<{ readonly fnClose: () => void }>(
+    (fnResolve, fnReject) => {
+      let bIsClosed = false
+      let bIsOpen = false
+      const nTimeout = setTimeout(() => {
+        if (bIsClosed || bIsOpen) return
+        fnClose()
+        fnReject(
+          new ActivityError(
+            'TRANSPORT_DISCONNECTED',
+            `${strTransport.toUpperCase()} 首次连接超时。`
+          )
+        )
+      }, nConnectTimeoutMs)
+      const fnClose = () => {
+        if (bIsClosed) return
+        bIsClosed = true
+        clearTimeout(nTimeout)
+        fnCloseStream()
+      }
+      const fnFail = (objError: Error) => {
+        if (bIsClosed || objContext.objSignal.aborted) return
+        if (!bIsOpen) {
+          fnClose()
+          fnReject(objError)
+        } else {
+          fnClose()
+          objContext.fnOnDisconnect(objError)
+        }
+      }
+
+      objContext.objSignal.addEventListener(
+        'abort',
+        () => {
+          const bWasOpen = bIsOpen
+          fnClose()
+          if (!bWasOpen) fnReject(fnCreateAbortError())
+        },
+        { once: true }
+      )
+      fnSetHandlers({
+        fnOnClose: fnFail,
+        fnOnError: () =>
+          fnFail(
+            new ActivityError(
+              'TRANSPORT_DISCONNECTED',
+              `${strTransport.toUpperCase()} 连接发生错误。`
+            )
+          ),
+        fnOnMessage: (strData) => {
+          if (bIsClosed || objContext.objSignal.aborted) return
+          try {
+            if (typeof strData !== 'string') {
+              throw new ActivityError(
+                'INVALID_EVENT',
+                '实时活动传输只接受 UTF-8 文本消息。'
+              )
+            }
+            objContext.fnOnEvent(fnParseMessage(strData))
+          } catch (objCaughtError) {
+            fnFail(
+              objCaughtError instanceof Error
+                ? objCaughtError
+                : new ActivityError(
+                    'INVALID_EVENT',
+                    '实时消息解析器抛出了非标准错误。',
+                    { cause: objCaughtError }
+                  )
+            )
+          }
+        },
+        fnOnOpen: () => {
+          if (bIsClosed || objContext.objSignal.aborted) return
+          bIsOpen = true
+          clearTimeout(nTimeout)
+          fnResolve(Object.freeze({ fnClose }))
+        },
+      })
+    }
+  )
+}
+
+/** 创建由统一控制器接管重连的 SSE Adapter。 */
+export function fnCreateSseActivityTransport({
+  fnCreateEventSource,
+  fnParseMessage,
+  nConnectTimeoutMs: nConnectTimeoutInput = nDefaultConnectTimeoutMs,
+}: ICreateSseActivityTransportOptions): IActivityTransportAdapter {
+  const nConnectTimeoutMs = fnValidatePositiveDuration(
+    nConnectTimeoutInput,
+    'nConnectTimeoutMs'
+  )
+  return Object.freeze({
+    strTransport: 'sse' as const,
+    fnConnect: async (objContext: IActivityTransportConnectContext) => {
+      const objEventSource = await fnCreateEventSource({
+        objScope: objContext.objScope,
+        objSignal: objContext.objSignal,
+        ...(objContext.strLastEventId
+          ? { strLastEventId: objContext.strLastEventId }
+          : {}),
+      })
+      if (objContext.objSignal.aborted) {
+        objEventSource.close()
+        throw fnCreateAbortError()
+      }
+      return fnCreateTextStreamConnection(objContext, {
+        fnCloseStream: () => objEventSource.close(),
+        fnParseMessage,
+        fnSetHandlers: ({ fnOnError, fnOnMessage, fnOnOpen }) => {
+          objEventSource.onerror = fnOnError
+          objEventSource.onmessage = (objEvent) => fnOnMessage(objEvent.data)
+          objEventSource.onopen = fnOnOpen
+        },
+        nConnectTimeoutMs,
+        strTransport: 'sse',
+      })
+    },
+  })
+}
+
+/** 创建由统一控制器接管重连的 WebSocket Adapter。 */
+export function fnCreateWebSocketActivityTransport({
+  fnCreateWebSocket,
+  fnParseMessage,
+  nConnectTimeoutMs: nConnectTimeoutInput = nDefaultConnectTimeoutMs,
+}: ICreateWebSocketActivityTransportOptions): IActivityTransportAdapter {
+  const nConnectTimeoutMs = fnValidatePositiveDuration(
+    nConnectTimeoutInput,
+    'nConnectTimeoutMs'
+  )
+  return Object.freeze({
+    strTransport: 'websocket' as const,
+    fnConnect: async (objContext: IActivityTransportConnectContext) => {
+      const objWebSocket = await fnCreateWebSocket({
+        objScope: objContext.objScope,
+        objSignal: objContext.objSignal,
+        ...(objContext.strLastEventId
+          ? { strLastEventId: objContext.strLastEventId }
+          : {}),
+      })
+      if (objContext.objSignal.aborted) {
+        objWebSocket.close()
+        throw fnCreateAbortError()
+      }
+      return fnCreateTextStreamConnection(objContext, {
+        fnCloseStream: () => objWebSocket.close(),
+        fnParseMessage,
+        fnSetHandlers: ({ fnOnClose, fnOnError, fnOnMessage, fnOnOpen }) => {
+          objWebSocket.onclose = (objEvent) =>
+            fnOnClose(
+              new ActivityError(
+                'TRANSPORT_DISCONNECTED',
+                `WebSocket 连接已关闭（${objEvent.code}）。`
+              )
+            )
+          objWebSocket.onerror = fnOnError
+          objWebSocket.onmessage = (objEvent) => fnOnMessage(objEvent.data)
+          objWebSocket.onopen = fnOnOpen
+        },
+        nConnectTimeoutMs,
+        strTransport: 'websocket',
+      })
+    },
+  })
+}

package/template/src/api/activity/types.ts

@@ -0,0 +1,402 @@
+import type { ReactNode } from 'react'
+import type { IAppQueryScope } from '@/api/query/types'
+import type { ActivityError } from './errors'
+
+/** 脚手架统一支持的后台异步任务状态。 */
+export type TActivityTaskState =
+  | 'queued'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+
+/** 后端活动快照中的任务状态输入。 */
+export interface IActivityTaskStatusInput {
+  /** 后端任务的稳定唯一标识。 */
+  readonly strTaskId: string
+  /** 经项目 Adapter 映射后的通用任务状态。 */
+  readonly strState: TActivityTaskState
+  /** 任务最近一次变化的 ISO 8601 时间。 */
+  readonly strUpdatedAt: string
+  /** 已完成百分比，取值为 0 至 100；后端未知时省略。 */
+  readonly nProgressPercent?: number
+}
+
+/** 经校验、标准化和冻结后可进入 Query 缓存的任务状态。 */
+export interface IActivityTaskStatus {
+  /** 后端任务的稳定唯一标识。 */
+  readonly strTaskId: string
+  /** 经项目 Adapter 映射后的通用任务状态。 */
+  readonly strState: TActivityTaskState
+  /** 标准化后的 ISO 8601 更新时间。 */
+  readonly strUpdatedAt: string
+  /** 已完成百分比，取值为 0 至 100；后端未知时省略。 */
+  readonly nProgressPercent?: number
+}
+
+/** 项目 Adapter 返回的活动快照输入。 */
+export interface IActivitySnapshotInput {
+  /** 当前作用域内尚未读取的通知数量。 */
+  readonly nUnreadCount: number
+  /** 当前用户近期关注的异步任务状态，最多 100 条。 */
+  readonly arrTaskStatuses: readonly IActivityTaskStatusInput[]
+  /** 后端快照版本，用于诊断和刷新确认。 */
+  readonly strVersion: string
+  /** 快照已经包含的最后一个实时事件 ID。 */
+  readonly strLastEventId?: string
+}
+
+/** TanStack Query 持有的完整活动快照。 */
+export interface IActivitySnapshot {
+  /** 当前作用域内尚未读取的通知数量。 */
+  readonly nUnreadCount: number
+  /** 已按更新时间倒序排列的近期异步任务状态。 */
+  readonly arrTaskStatuses: readonly IActivityTaskStatus[]
+  /** 后端快照版本，用于诊断和刷新确认。 */
+  readonly strVersion: string
+  /** 快照或增量更新已经应用的最后一个事件 ID。 */
+  readonly strLastEventId?: string
+}
+
+/** 活动快照数据源的请求上下文。 */
+export interface IActivitySnapshotRequestContext {
+  /** 用户、租户、工作空间、语言和会话组成的缓存作用域。 */
+  readonly objScope: IAppQueryScope
+  /** Query 取消、切换身份或卸载时触发的请求取消信号。 */
+  readonly objSignal: AbortSignal
+}
+
+/** 使用 Swagger 生成客户端加载活动快照的数据源。 */
+export interface IActivitySource {
+  /** 返回当前作用域的完整未读数和近期任务状态。 */
+  readonly fnLoadSnapshot: (
+    objContext: IActivitySnapshotRequestContext
+  ) => Promise<IActivitySnapshot>
+}
+
+/** 项目生成客户端请求函数的最小适配契约。 */
+export type TActivitySnapshotRequest = (
+  objContext: IActivitySnapshotRequestContext
+) => Promise<IActivitySnapshotInput>
+
+/** 所有实时活动事件共有的稳定字段。 */
+export interface IActivityEventBase {
+  /** 后端生成的稳定事件 ID，用于断线续传。 */
+  readonly strEventId: string
+  /** 事件在后端发生的 ISO 8601 时间。 */
+  readonly strOccurredAt: string
+}
+
+/** 用完整服务端快照替换当前缓存。 */
+export interface IActivitySnapshotReplacedEventInput extends IActivityEventBase {
+  /** 可判别的事件类型。 */
+  readonly strType: 'snapshot-replaced'
+  /** 已包含该事件及更早变化的完整快照。 */
+  readonly objSnapshot: IActivitySnapshotInput
+}
+
+/** 当前作用域未读数量发生变化。 */
+export interface IActivityUnreadCountChangedEventInput extends IActivityEventBase {
+  /** 可判别的事件类型。 */
+  readonly strType: 'unread-count-changed'
+  /** 后端确认的最新未读总数，不是增量。 */
+  readonly nUnreadCount: number
+}
+
+/** 一个后台异步任务的状态发生变化。 */
+export interface IActivityTaskStatusChangedEventInput extends IActivityEventBase {
+  /** 可判别的事件类型。 */
+  readonly strType: 'task-status-changed'
+  /** 后端确认的该任务最新状态。 */
+  readonly objTaskStatus: IActivityTaskStatusInput
+}
+
+/** 服务端要求客户端重新获取完整活动快照。 */
+export interface IActivitySnapshotInvalidatedEventInput extends IActivityEventBase {
+  /** 可判别的事件类型。 */
+  readonly strType: 'snapshot-invalidated'
+}
+
+/** 传输 Adapter 可以交给基础设施的活动事件输入。 */
+export type TActivityEventInput =
+  | IActivitySnapshotReplacedEventInput
+  | IActivityUnreadCountChangedEventInput
+  | IActivityTaskStatusChangedEventInput
+  | IActivitySnapshotInvalidatedEventInput
+
+/** 经运行时校验后可以更新 Query 缓存的活动事件。 */
+export type TActivityEvent =
+  | (IActivityEventBase & {
+      readonly strType: 'snapshot-replaced'
+      readonly objSnapshot: IActivitySnapshot
+    })
+  | IActivityUnreadCountChangedEventInput
+  | (IActivityEventBase & {
+      readonly strType: 'task-status-changed'
+      readonly objTaskStatus: IActivityTaskStatus
+    })
+  | IActivitySnapshotInvalidatedEventInput
+
+/** 一次活动传输连接的关闭能力。 */
+export interface IActivityTransportConnection {
+  /** 关闭底层轮询计时器、EventSource 或 WebSocket。 */
+  readonly fnClose: () => void
+}
+
+/** 传输 Adapter 建立连接时获得的作用域和回调。 */
+export interface IActivityTransportConnectContext {
+  /** 当前用户、租户、工作空间、语言和会话作用域。 */
+  readonly objScope: IAppQueryScope
+  /** 关闭 Provider、切换作用域或开始新连接时触发。 */
+  readonly objSignal: AbortSignal
+  /** 断线续传时交给后端的最后事件 ID。 */
+  readonly strLastEventId?: string
+  /** 向快照缓存提交一个或多个事件。 */
+  readonly fnOnEvent: (
+    objEvent: TActivityEventInput | readonly TActivityEventInput[]
+  ) => void
+  /** 非主动关闭导致连接失效时通知重连控制器。 */
+  readonly fnOnDisconnect: (objError: Error) => void
+}
+
+/** 轮询、SSE 和 WebSocket 共用的传输 Adapter。 */
+export interface IActivityTransportAdapter {
+  /** 用于诊断和状态展示的底层传输类型。 */
+  readonly strTransport: TActivityTransport
+  /** 建立一个可关闭连接；首次握手失败时拒绝 Promise。 */
+  readonly fnConnect: (
+    objContext: IActivityTransportConnectContext
+  ) => Promise<IActivityTransportConnection>
+}
+
+/** 脚手架内建的活动传输类型。 */
+export type TActivityTransport = 'polling' | 'sse' | 'websocket'
+
+/** 连接重试的指数退避配置。 */
+export interface IActivityReconnectPolicy {
+  /** 第一次自动重连前的等待毫秒数。 */
+  readonly nInitialDelayMs?: number
+  /** 自动重连等待的毫秒上限。 */
+  readonly nMaxDelayMs?: number
+  /** 每次连续失败后的等待倍数。 */
+  readonly nMultiplier?: number
+  /** 随机抖动比例，取值为 0 至 1。 */
+  readonly nJitterRatio?: number
+  /** 连续连接失败上限；省略表示持续退避重连。 */
+  readonly nMaxAttempts?: number
+}
+
+/** 尚未启动或已经主动停止实时连接。 */
+export interface IActivityIdleConnectionState {
+  /** 可判别的空闲状态。 */
+  readonly strStatus: 'idle'
+}
+
+/** 正在进行首次连接或手动重连。 */
+export interface IActivityConnectingState {
+  /** 可判别的连接中状态。 */
+  readonly strStatus: 'connecting'
+  /** 当前使用的传输类型。 */
+  readonly strTransport: TActivityTransport
+}
+
+/** 实时连接已经建立。 */
+export interface IActivityConnectedState {
+  /** 可判别的已连接状态。 */
+  readonly strStatus: 'connected'
+  /** 当前使用的传输类型。 */
+  readonly strTransport: TActivityTransport
+}
+
+/** 连接中断并等待自动重连。 */
+export interface IActivityReconnectingState {
+  /** 可判别的重连等待状态。 */
+  readonly strStatus: 'reconnecting'
+  /** 当前使用的传输类型。 */
+  readonly strTransport: TActivityTransport
+  /** 当前连续重连轮次，从 1 开始。 */
+  readonly nAttempt: number
+  /** 下一次重连计划执行的毫秒时间戳。 */
+  readonly nRetryAt: number
+  /** 最近一次连接失败的安全错误。 */
+  readonly objError: ActivityError
+}
+
+/** 连续连接失败达到项目配置的上限。 */
+export interface IActivityConnectionErrorState {
+  /** 可判别的最终错误状态。 */
+  readonly strStatus: 'error'
+  /** 当前使用的传输类型。 */
+  readonly strTransport: TActivityTransport
+  /** 已归一化的最终连接错误。 */
+  readonly objError: ActivityError
+}
+
+/** 实时连接的完整可判别状态。 */
+export type TActivityConnectionState =
+  | IActivityIdleConnectionState
+  | IActivityConnectingState
+  | IActivityConnectedState
+  | IActivityReconnectingState
+  | IActivityConnectionErrorState
+
+/** 非 React 订阅控制器的启动参数。 */
+export interface IStartActivitySubscriptionOptions {
+  /** 当前作用域使用的轮询、SSE 或 WebSocket Adapter。 */
+  readonly objAdapter: IActivityTransportAdapter
+  /** 当前用户、租户、工作空间、语言和会话作用域。 */
+  readonly objScope: IAppQueryScope
+  /** 断线恢复时从该事件之后继续。 */
+  readonly strLastEventId?: string
+  /** 项目需要覆盖的重连退避参数。 */
+  readonly objReconnectPolicy?: IActivityReconnectPolicy
+  /** 每个已校验事件的唯一消费者。 */
+  readonly fnOnEvent: (objEvent: TActivityEvent) => void
+  /** 连接状态变化的可选诊断入口。 */
+  readonly fnOnStateChange?: (objState: TActivityConnectionState) => void
+}
+
+/** 一个正在运行或已经停止的活动订阅。 */
+export interface IActivitySubscription {
+  /** 主动停止连接和所有自动重连计时器。 */
+  readonly fnStop: () => void
+  /** 立即关闭旧连接并从零开始手动重连。 */
+  readonly fnReconnect: () => void
+  /** 同步读取当前连接状态。 */
+  readonly fnGetState: () => TActivityConnectionState
+}
+
+/** 轮询 Adapter 调用项目生成客户端的请求参数。 */
+export interface IActivityPollContext {
+  /** 当前完整应用查询作用域。 */
+  readonly objScope: IAppQueryScope
+  /** 停止轮询、切换身份或断线重连时触发。 */
+  readonly objSignal: AbortSignal
+  /** 断线续传时最近应用的事件 ID。 */
+  readonly strLastEventId?: string
+}
+
+/** 创建轮询 Adapter 的参数。 */
+export interface ICreatePollingActivityTransportOptions {
+  /** 通过生成客户端请求一次增量事件。 */
+  readonly fnPoll: (
+    objContext: IActivityPollContext
+  ) => Promise<TActivityEventInput | readonly TActivityEventInput[]>
+  /** 两次成功轮询开始时间之间的最小毫秒数。 */
+  readonly nIntervalMs?: number
+}
+
+/** EventSource 最小能力，允许项目包装 Cookie 或 Fetch 流式认证方案。 */
+export interface IActivityEventSourceLike {
+  /** 底层连接成功回调。 */
+  onopen: ((objEvent: Event) => void) | null
+  /** 收到 UTF-8 文本消息回调。 */
+  onmessage: ((objEvent: MessageEvent<string>) => void) | null
+  /** 连接或协议错误回调。 */
+  onerror: ((objEvent: Event) => void) | null
+  /** 关闭底层流。 */
+  close: () => void
+}
+
+/** SSE/WebSocket 文本消息到活动事件的项目映射函数。 */
+export type TActivityMessageParser = (
+  strData: string
+) => TActivityEventInput | readonly TActivityEventInput[]
+
+/** 创建 SSE Adapter 的参数。 */
+export interface ICreateSseActivityTransportOptions {
+  /** 根据当前作用域和最后事件 ID 创建 EventSource 或兼容包装。 */
+  readonly fnCreateEventSource: (
+    objContext: Pick<
+      IActivityTransportConnectContext,
+      'objScope' | 'objSignal' | 'strLastEventId'
+    >
+  ) => IActivityEventSourceLike | Promise<IActivityEventSourceLike>
+  /** 把后端文本消息校验并映射为通用活动事件输入。 */
+  readonly fnParseMessage: TActivityMessageParser
+  /** 首次 open 事件的等待上限，默认 10 秒。 */
+  readonly nConnectTimeoutMs?: number
+}
+
+/** WebSocket 最小能力，项目可以直接返回浏览器原生 WebSocket。 */
+export interface IActivityWebSocketLike {
+  /** 底层握手成功回调。 */
+  onopen: ((objEvent: Event) => void) | null
+  /** 收到 UTF-8 文本消息回调。 */
+  onmessage: ((objEvent: MessageEvent<string>) => void) | null
+  /** 连接或协议错误回调。 */
+  onerror: ((objEvent: Event) => void) | null
+  /** 连接关闭回调。 */
+  onclose: ((objEvent: CloseEvent) => void) | null
+  /** 主动关闭底层连接。 */
+  close: () => void
+}
+
+/** 创建 WebSocket Adapter 的参数。 */
+export interface ICreateWebSocketActivityTransportOptions {
+  /** 根据当前作用域和最后事件 ID 创建原生或兼容 WebSocket。 */
+  readonly fnCreateWebSocket: (
+    objContext: Pick<
+      IActivityTransportConnectContext,
+      'objScope' | 'objSignal' | 'strLastEventId'
+    >
+  ) => IActivityWebSocketLike | Promise<IActivityWebSocketLike>
+  /** 把后端文本消息校验并映射为通用活动事件输入。 */
+  readonly fnParseMessage: TActivityMessageParser
+  /** 首次 open 事件的等待上限，默认 10 秒。 */
+  readonly nConnectTimeoutMs?: number
+}
+
+/** ActivityProvider 的应用组合参数。 */
+export interface IActivityProviderProps {
+  /** 是否允许加载快照并启动实时连接。 */
+  readonly bIsEnabled?: boolean
+  /** 始终渲染的应用子树；活动接口失败不会阻塞页面。 */
+  readonly children: ReactNode
+  /** 项目使用生成客户端实现的完整活动快照数据源。 */
+  readonly objSource?: IActivitySource
+  /** 可选的轮询、SSE 或 WebSocket 实时传输。 */
+  readonly objTransport?: IActivityTransportAdapter
+  /** 项目需要覆盖的自动重连退避参数。 */
+  readonly objReconnectPolicy?: IActivityReconnectPolicy
+}
+
+/** React 消费者读取的活动快照和连接生命周期。 */
+export interface IUseActivityResult {
+  /** 当前快照中的近期任务状态。 */
+  readonly arrTaskStatuses: readonly IActivityTaskStatus[]
+  /** 是否配置了快照数据源。 */
+  readonly bIsConfigured: boolean
+  /** 当前认证状态是否允许加载。 */
+  readonly bIsEnabled: boolean
+  /** 快照查询是否失败。 */
+  readonly bIsError: boolean
+  /** 快照是否正在请求，包括后台刷新。 */
+  readonly bIsFetching: boolean
+  /** 是否正在进行首次快照加载。 */
+  readonly bIsLoading: boolean
+  /** 是否配置了实时传输 Adapter。 */
+  readonly bIsLiveConfigured: boolean
+  /** 当前未读通知总数；快照未加载时为 0。 */
+  readonly nUnreadCount: number
+  /** 当前完整活动快照。 */
+  readonly objSnapshot?: IActivitySnapshot
+  /** 最近一次快照加载错误。 */
+  readonly objSnapshotError: Error | null
+  /** 当前实时连接状态。 */
+  readonly objConnectionState: TActivityConnectionState
+  /** 手动重新获取完整快照。 */
+  readonly fnRefetch: () => Promise<void>
+  /** 立即重新建立实时连接；未配置或未加载快照时无操作。 */
+  readonly fnReconnect: () => void
+  /** 先恢复失败快照，再重新建立实时连接。 */
+  readonly fnRetry: () => Promise<void>
+}
+
+/** 活动快照和实时连接的稳定错误码。 */
+export type TActivityErrorCode =
+  | 'INVALID_EVENT'
+  | 'INVALID_SNAPSHOT'
+  | 'INVALID_TRANSPORT_CONFIG'
+  | 'RECONNECT_EXHAUSTED'
+  | 'TRANSPORT_DISCONNECTED'