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

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

@@ -0,0 +1,227 @@
+import { ActivityError } from './errors'
+import type {
+  IActivitySnapshot,
+  IActivitySnapshotInput,
+  IActivityTaskStatus,
+  IActivityTaskStatusInput,
+  TActivityEvent,
+  TActivityEventInput,
+  TActivityTaskState,
+} from './types'
+
+export const nMaxActivityTaskStatuses = 100
+
+function fnNormalizeRequiredString(
+  strValue: string,
+  strField: string,
+  strErrorCode: 'INVALID_EVENT' | 'INVALID_SNAPSHOT' = 'INVALID_SNAPSHOT'
+) {
+  const strNormalizedValue = typeof strValue === 'string' ? strValue.trim() : ''
+  if (!strNormalizedValue) {
+    throw new ActivityError(
+      strErrorCode,
+      `活动接口字段 ${strField} 必须是非空字符串。`
+    )
+  }
+  return strNormalizedValue
+}
+
+function fnNormalizeEventString(strValue: string, strField: string) {
+  try {
+    return fnNormalizeRequiredString(strValue, strField, 'INVALID_EVENT')
+  } catch (objError) {
+    throw new ActivityError(
+      'INVALID_EVENT',
+      `活动事件字段 ${strField} 必须是非空字符串。`,
+      { cause: objError }
+    )
+  }
+}
+
+function fnNormalizeIsoTimestamp(
+  strValue: string,
+  strField: string,
+  strErrorCode: 'INVALID_EVENT' | 'INVALID_SNAPSHOT'
+) {
+  const bIsIsoTimestamp =
+    typeof strValue === 'string' &&
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      strValue
+    )
+  if (!bIsIsoTimestamp || !Number.isFinite(Date.parse(strValue))) {
+    throw new ActivityError(
+      strErrorCode,
+      `活动接口字段 ${strField} 必须是有效 ISO 8601 时间。`
+    )
+  }
+  return new Date(strValue).toISOString()
+}
+
+function fnNormalizeUnreadCount(
+  nUnreadCount: number,
+  strErrorCode: 'INVALID_EVENT' | 'INVALID_SNAPSHOT'
+) {
+  if (!Number.isSafeInteger(nUnreadCount) || nUnreadCount < 0) {
+    throw new ActivityError(
+      strErrorCode,
+      '活动接口未读数量必须是非负安全整数。'
+    )
+  }
+  return nUnreadCount
+}
+
+function fnIsActivityTaskState(
+  strState: string
+): strState is TActivityTaskState {
+  return (
+    strState === 'queued' ||
+    strState === 'running' ||
+    strState === 'succeeded' ||
+    strState === 'failed' ||
+    strState === 'cancelled'
+  )
+}
+
+function fnNormalizeTaskStatus(
+  objTaskStatus: IActivityTaskStatusInput,
+  strErrorCode: 'INVALID_EVENT' | 'INVALID_SNAPSHOT'
+): IActivityTaskStatus {
+  if (!objTaskStatus || typeof objTaskStatus !== 'object') {
+    throw new ActivityError(strErrorCode, '活动接口包含无效任务状态。')
+  }
+  const strTaskId = fnNormalizeRequiredString(
+    objTaskStatus.strTaskId,
+    'strTaskId',
+    strErrorCode
+  )
+  if (!fnIsActivityTaskState(objTaskStatus.strState)) {
+    throw new ActivityError(
+      strErrorCode,
+      `任务 ${strTaskId} 返回了不支持的状态。`
+    )
+  }
+  if (
+    objTaskStatus.nProgressPercent !== undefined &&
+    (!Number.isFinite(objTaskStatus.nProgressPercent) ||
+      objTaskStatus.nProgressPercent < 0 ||
+      objTaskStatus.nProgressPercent > 100)
+  ) {
+    throw new ActivityError(
+      strErrorCode,
+      `任务 ${strTaskId} 的完成百分比必须在 0 至 100 之间。`
+    )
+  }
+
+  return Object.freeze({
+    ...(objTaskStatus.nProgressPercent === undefined
+      ? {}
+      : { nProgressPercent: objTaskStatus.nProgressPercent }),
+    strState: objTaskStatus.strState,
+    strTaskId,
+    strUpdatedAt: fnNormalizeIsoTimestamp(
+      objTaskStatus.strUpdatedAt,
+      'strUpdatedAt',
+      strErrorCode
+    ),
+  })
+}
+
+/** 校验项目 Adapter 返回的完整快照并建立稳定缓存模型。 */
+export function fnNormalizeActivitySnapshot(
+  objSnapshot: IActivitySnapshotInput
+): IActivitySnapshot {
+  if (
+    !objSnapshot ||
+    typeof objSnapshot !== 'object' ||
+    !Array.isArray(objSnapshot.arrTaskStatuses) ||
+    objSnapshot.arrTaskStatuses.length > nMaxActivityTaskStatuses
+  ) {
+    throw new ActivityError(
+      'INVALID_SNAPSHOT',
+      `活动快照必须包含不超过 ${nMaxActivityTaskStatuses} 条任务状态。`
+    )
+  }
+
+  const objTaskIds = new Set<string>()
+  const arrTaskStatuses = objSnapshot.arrTaskStatuses
+    .map((objTaskStatus) =>
+      fnNormalizeTaskStatus(objTaskStatus, 'INVALID_SNAPSHOT')
+    )
+    .sort((objLeft, objRight) =>
+      objRight.strUpdatedAt.localeCompare(objLeft.strUpdatedAt)
+    )
+  arrTaskStatuses.forEach((objTaskStatus) => {
+    if (objTaskIds.has(objTaskStatus.strTaskId)) {
+      throw new ActivityError(
+        'INVALID_SNAPSHOT',
+        `活动快照包含重复任务 ${objTaskStatus.strTaskId}。`
+      )
+    }
+    objTaskIds.add(objTaskStatus.strTaskId)
+  })
+
+  const strLastEventId =
+    typeof objSnapshot.strLastEventId === 'string'
+      ? objSnapshot.strLastEventId.trim()
+      : undefined
+  return Object.freeze({
+    arrTaskStatuses: Object.freeze(arrTaskStatuses),
+    nUnreadCount: fnNormalizeUnreadCount(
+      objSnapshot.nUnreadCount,
+      'INVALID_SNAPSHOT'
+    ),
+    ...(strLastEventId ? { strLastEventId } : {}),
+    strVersion: fnNormalizeRequiredString(objSnapshot.strVersion, 'strVersion'),
+  })
+}
+
+/** 校验传输 Adapter 产生的一个增量事件。 */
+export function fnNormalizeActivityEvent(
+  objEvent: TActivityEventInput
+): TActivityEvent {
+  if (!objEvent || typeof objEvent !== 'object') {
+    throw new ActivityError('INVALID_EVENT', '活动传输返回了无效事件。')
+  }
+  const objBase = {
+    strEventId: fnNormalizeEventString(objEvent.strEventId, 'strEventId'),
+    strOccurredAt: fnNormalizeIsoTimestamp(
+      objEvent.strOccurredAt,
+      'strOccurredAt',
+      'INVALID_EVENT'
+    ),
+  }
+
+  switch (objEvent.strType) {
+    case 'snapshot-replaced':
+      return Object.freeze({
+        ...objBase,
+        objSnapshot: fnNormalizeActivitySnapshot(objEvent.objSnapshot),
+        strType: objEvent.strType,
+      })
+    case 'unread-count-changed':
+      return Object.freeze({
+        ...objBase,
+        nUnreadCount: fnNormalizeUnreadCount(
+          objEvent.nUnreadCount,
+          'INVALID_EVENT'
+        ),
+        strType: objEvent.strType,
+      })
+    case 'task-status-changed':
+      return Object.freeze({
+        ...objBase,
+        objTaskStatus: fnNormalizeTaskStatus(
+          objEvent.objTaskStatus,
+          'INVALID_EVENT'
+        ),
+        strType: objEvent.strType,
+      })
+    case 'snapshot-invalidated':
+      return Object.freeze({ ...objBase, strType: objEvent.strType })
+    default:
+      throw new ActivityError(
+        'INVALID_EVENT',
+        '活动传输返回了不支持的事件类型。'
+      )
+  }
+}

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

@@ -0,0 +1,163 @@
+import { queryOptions, type QueryClient } from '@tanstack/react-query'
+import type { IAppQueryScope } from '@/api/query/types'
+import { fnNormalizeActivityEvent, nMaxActivityTaskStatuses } from './model'
+import type {
+  IActivitySnapshot,
+  IActivitySource,
+  IActivityTaskStatus,
+  TActivityEvent,
+} from './types'
+
+const arrActivityQueryRoot: readonly ['activity'] = ['activity']
+const nActivityStaleTimeMs = 30_000
+const nActivityGcTimeMs = 10 * 60_000
+
+/** 返回当前用户、租户、工作空间和会话唯一的活动快照 Key。 */
+export function fnActivityQueryKey(
+  objScope: IAppQueryScope
+): readonly ['activity', IAppQueryScope] {
+  return ['activity', objScope]
+}
+
+/** 创建完整活动快照的 QueryClient 查询配置。 */
+export function fnActivityQueryOptions(
+  objSource: IActivitySource,
+  objScope: IAppQueryScope
+) {
+  return queryOptions({
+    queryKey: fnActivityQueryKey(objScope),
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnLoadSnapshot({ objScope, objSignal }),
+    staleTime: nActivityStaleTimeMs,
+    gcTime: nActivityGcTimeMs,
+  })
+}
+
+/** 在路由 Loader 或启动编排中确保当前活动快照已经加载。 */
+export function fnEnsureActivitySnapshot(
+  objQueryClient: QueryClient,
+  objSource: IActivitySource,
+  objScope: IAppQueryScope
+) {
+  return objQueryClient.ensureQueryData(
+    fnActivityQueryOptions(objSource, objScope)
+  )
+}
+
+/** 在 React 外同步读取当前作用域缓存的活动快照。 */
+export function fnGetCachedActivitySnapshot(
+  objQueryClient: QueryClient,
+  objScope: IAppQueryScope
+) {
+  return objQueryClient.getQueryData<IActivitySnapshot>(
+    fnActivityQueryKey(objScope)
+  )
+}
+
+/** 使当前作用域或全部作用域的活动快照重新获取。 */
+export function fnInvalidateActivitySnapshot(
+  objQueryClient: QueryClient,
+  objScope?: IAppQueryScope
+) {
+  return objQueryClient.invalidateQueries({
+    ...(objScope
+      ? { exact: true, queryKey: fnActivityQueryKey(objScope) }
+      : { queryKey: arrActivityQueryRoot }),
+  })
+}
+
+function fnMergeTaskStatus(
+  arrTaskStatuses: readonly IActivityTaskStatus[],
+  objNextTaskStatus: IActivityTaskStatus
+) {
+  const objCurrentTaskStatus = arrTaskStatuses.find(
+    (objTaskStatus) => objTaskStatus.strTaskId === objNextTaskStatus.strTaskId
+  )
+  if (
+    objCurrentTaskStatus &&
+    objCurrentTaskStatus.strUpdatedAt > objNextTaskStatus.strUpdatedAt
+  ) {
+    return arrTaskStatuses
+  }
+
+  return Object.freeze(
+    [
+      objNextTaskStatus,
+      ...arrTaskStatuses.filter(
+        (objTaskStatus) =>
+          objTaskStatus.strTaskId !== objNextTaskStatus.strTaskId
+      ),
+    ]
+      .sort((objLeft, objRight) =>
+        objRight.strUpdatedAt.localeCompare(objLeft.strUpdatedAt)
+      )
+      .slice(0, nMaxActivityTaskStatuses)
+  )
+}
+
+function fnApplyIncrementalActivityEvent(
+  objSnapshot: IActivitySnapshot,
+  objEvent: Exclude<
+    TActivityEvent,
+    { readonly strType: 'snapshot-invalidated' }
+  >
+): IActivitySnapshot {
+  if (objEvent.strType === 'snapshot-replaced') {
+    return Object.freeze({
+      ...objEvent.objSnapshot,
+      strLastEventId: objEvent.strEventId,
+    })
+  }
+  if (objEvent.strType === 'unread-count-changed') {
+    return Object.freeze({
+      ...objSnapshot,
+      nUnreadCount: objEvent.nUnreadCount,
+      strLastEventId: objEvent.strEventId,
+    })
+  }
+  return Object.freeze({
+    ...objSnapshot,
+    arrTaskStatuses: fnMergeTaskStatus(
+      objSnapshot.arrTaskStatuses,
+      objEvent.objTaskStatus
+    ),
+    strLastEventId: objEvent.strEventId,
+  })
+}
+
+/** 将一个实时事件安全合并进唯一的 Query 快照缓存。 */
+export function fnApplyActivityEvent(
+  objQueryClient: QueryClient,
+  objScope: IAppQueryScope,
+  objEventInput: Parameters<typeof fnNormalizeActivityEvent>[0]
+) {
+  const objEvent = fnNormalizeActivityEvent(objEventInput)
+  if (objEvent.strType === 'snapshot-invalidated') {
+    void fnInvalidateActivitySnapshot(objQueryClient, objScope)
+    return objEvent
+  }
+
+  const arrQueryKey = fnActivityQueryKey(objScope)
+  const objCurrentSnapshot =
+    objQueryClient.getQueryData<IActivitySnapshot>(arrQueryKey)
+  if (!objCurrentSnapshot) {
+    if (objEvent.strType !== 'snapshot-replaced') {
+      void fnInvalidateActivitySnapshot(objQueryClient, objScope)
+      return objEvent
+    }
+    objQueryClient.setQueryData<IActivitySnapshot>(
+      arrQueryKey,
+      Object.freeze({
+        ...objEvent.objSnapshot,
+        strLastEventId: objEvent.strEventId,
+      })
+    )
+    return objEvent
+  }
+
+  objQueryClient.setQueryData<IActivitySnapshot>(
+    arrQueryKey,
+    fnApplyIncrementalActivityEvent(objCurrentSnapshot, objEvent)
+  )
+  return objEvent
+}

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

@@ -0,0 +1,16 @@
+import { fnNormalizeActivitySnapshot } from './model'
+import type {
+  IActivitySnapshotRequestContext,
+  IActivitySource,
+  TActivitySnapshotRequest,
+} from './types'
+
+/** 将 Swagger 生成客户端请求适配为活动快照数据源。 */
+export function fnCreateActivitySource(
+  fnRequest: TActivitySnapshotRequest
+): IActivitySource {
+  return Object.freeze({
+    fnLoadSnapshot: async (objContext: IActivitySnapshotRequestContext) =>
+      fnNormalizeActivitySnapshot(await fnRequest(objContext)),
+  })
+}

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

@@ -0,0 +1,292 @@
+import { ActivityError } from './errors'
+import { fnNormalizeActivityEvent } from './model'
+import type {
+  IActivityReconnectPolicy,
+  IActivitySubscription,
+  IActivityTransportConnection,
+  IStartActivitySubscriptionOptions,
+  TActivityConnectionState,
+  TActivityEventInput,
+} from './types'
+
+interface IResolvedReconnectPolicy {
+  readonly nInitialDelayMs: number
+  readonly nJitterRatio: number
+  readonly nMaxAttempts?: number
+  readonly nMaxDelayMs: number
+  readonly nMultiplier: number
+}
+
+const objIdleConnectionState = Object.freeze({ strStatus: 'idle' as const })
+
+function fnResolveNonNegativeNumber(
+  nValue: number | undefined,
+  nFallback: number,
+  strField: string
+) {
+  const nResolvedValue = nValue ?? nFallback
+  if (!Number.isFinite(nResolvedValue) || nResolvedValue < 0) {
+    throw new ActivityError(
+      'INVALID_TRANSPORT_CONFIG',
+      `${strField} 必须是非负有限数字。`
+    )
+  }
+  return nResolvedValue
+}
+
+function fnResolveReconnectPolicy(
+  objPolicy: IActivityReconnectPolicy | undefined
+): IResolvedReconnectPolicy {
+  const nInitialDelayMs = fnResolveNonNegativeNumber(
+    objPolicy?.nInitialDelayMs,
+    1_000,
+    'nInitialDelayMs'
+  )
+  const nMaxDelayMs = fnResolveNonNegativeNumber(
+    objPolicy?.nMaxDelayMs,
+    30_000,
+    'nMaxDelayMs'
+  )
+  const nMultiplier = fnResolveNonNegativeNumber(
+    objPolicy?.nMultiplier,
+    2,
+    'nMultiplier'
+  )
+  const nJitterRatio = fnResolveNonNegativeNumber(
+    objPolicy?.nJitterRatio,
+    0.2,
+    'nJitterRatio'
+  )
+  if (nMultiplier < 1 || nJitterRatio > 1 || nMaxDelayMs < nInitialDelayMs) {
+    throw new ActivityError(
+      'INVALID_TRANSPORT_CONFIG',
+      '重连倍数不得小于 1，抖动比例不得大于 1，最大延迟不得小于初始延迟。'
+    )
+  }
+  if (
+    objPolicy?.nMaxAttempts !== undefined &&
+    (!Number.isSafeInteger(objPolicy.nMaxAttempts) ||
+      objPolicy.nMaxAttempts < 0)
+  ) {
+    throw new ActivityError(
+      'INVALID_TRANSPORT_CONFIG',
+      'nMaxAttempts 必须是非负安全整数。'
+    )
+  }
+  return Object.freeze({
+    nInitialDelayMs,
+    nJitterRatio,
+    nMaxDelayMs,
+    nMultiplier,
+    ...(objPolicy?.nMaxAttempts === undefined
+      ? {}
+      : { nMaxAttempts: objPolicy.nMaxAttempts }),
+  })
+}
+
+function fnNormalizeConnectionError(objError: Error) {
+  if (objError instanceof ActivityError) return objError
+  return new ActivityError(
+    'TRANSPORT_DISCONNECTED',
+    '通知与任务状态连接已中断。',
+    { cause: objError }
+  )
+}
+
+function fnResolveReconnectDelay(
+  nAttempt: number,
+  objPolicy: IResolvedReconnectPolicy
+) {
+  const nBaseDelay = Math.min(
+    objPolicy.nMaxDelayMs,
+    objPolicy.nInitialDelayMs * objPolicy.nMultiplier ** (nAttempt - 1)
+  )
+  const nJitter = nBaseDelay * objPolicy.nJitterRatio * (Math.random() * 2 - 1)
+  return Math.max(0, Math.round(nBaseDelay + nJitter))
+}
+
+/**
+ * 启动一个与 React 无关的活动订阅，统一拥有连接关闭、事件校验、指数退避、
+ * 最后事件 ID 和“最后一次连接生效”语义。
+ */
+export function fnStartActivitySubscription({
+  fnOnEvent,
+  fnOnStateChange,
+  objAdapter,
+  objReconnectPolicy,
+  objScope,
+  strLastEventId: strInitialLastEventId,
+}: IStartActivitySubscriptionOptions): IActivitySubscription {
+  const objPolicy = fnResolveReconnectPolicy(objReconnectPolicy)
+  let bIsStopped = false
+  let nActiveSequence = 0
+  let nAttempt = 0
+  let objAbortController: AbortController | undefined
+  let objConnection: IActivityTransportConnection | undefined
+  let nReconnectTimer: ReturnType<typeof setTimeout> | undefined
+  let objState: TActivityConnectionState = objIdleConnectionState
+  let strLastEventId = strInitialLastEventId?.trim() || undefined
+
+  const fnSetState = (objNextState: TActivityConnectionState) => {
+    objState = objNextState
+    fnOnStateChange?.(objNextState)
+  }
+
+  const fnDisposeActiveConnection = () => {
+    nActiveSequence += 1
+    objAbortController?.abort()
+    objAbortController = undefined
+    objConnection?.fnClose()
+    objConnection = undefined
+    if (nReconnectTimer !== undefined) clearTimeout(nReconnectTimer)
+    nReconnectTimer = undefined
+  }
+
+  const fnEmitEvents = (
+    objInput: TActivityEventInput | readonly TActivityEventInput[]
+  ) => {
+    const arrEvents = Array.isArray(objInput) ? objInput : [objInput]
+    arrEvents.forEach((objEventInput) => {
+      const objEvent = fnNormalizeActivityEvent(objEventInput)
+      strLastEventId = objEvent.strEventId
+      fnOnEvent(objEvent)
+    })
+  }
+
+  const fnScheduleReconnect = (objConnectionError: Error) => {
+    if (bIsStopped) return
+    fnDisposeActiveConnection()
+    nAttempt += 1
+    const objError = fnNormalizeConnectionError(objConnectionError)
+    if (
+      objPolicy.nMaxAttempts !== undefined &&
+      nAttempt > objPolicy.nMaxAttempts
+    ) {
+      fnSetState({
+        strStatus: 'error',
+        strTransport: objAdapter.strTransport,
+        objError: new ActivityError(
+          'RECONNECT_EXHAUSTED',
+          '通知与任务状态连接连续恢复失败，请手动重试。',
+          { cause: objError }
+        ),
+      })
+      return
+    }
+    const nDelayMs = fnResolveReconnectDelay(nAttempt, objPolicy)
+    fnSetState({
+      nAttempt,
+      nRetryAt: Date.now() + nDelayMs,
+      objError,
+      strStatus: 'reconnecting',
+      strTransport: objAdapter.strTransport,
+    })
+    nReconnectTimer = setTimeout(() => {
+      nReconnectTimer = undefined
+      void fnConnect(false)
+    }, nDelayMs)
+  }
+
+  const fnConnect = async (bIsManual: boolean) => {
+    if (bIsStopped) return
+    fnDisposeActiveConnection()
+    if (bIsManual) nAttempt = 0
+    const nConnectionSequence = ++nActiveSequence
+    const objController = new AbortController()
+    objAbortController = objController
+    if (bIsManual || nAttempt === 0) {
+      fnSetState({
+        strStatus: 'connecting',
+        strTransport: objAdapter.strTransport,
+      })
+    }
+
+    try {
+      const objNextConnection = await objAdapter.fnConnect({
+        fnOnDisconnect: (objError) => {
+          if (
+            bIsStopped ||
+            nConnectionSequence !== nActiveSequence ||
+            objController.signal.aborted
+          ) {
+            return
+          }
+          fnScheduleReconnect(objError)
+        },
+        fnOnEvent: (objInput) => {
+          if (
+            bIsStopped ||
+            nConnectionSequence !== nActiveSequence ||
+            objController.signal.aborted
+          ) {
+            return
+          }
+          try {
+            fnEmitEvents(objInput)
+          } catch (objCaughtError) {
+            const objError =
+              objCaughtError instanceof Error
+                ? objCaughtError
+                : new ActivityError(
+                    'INVALID_EVENT',
+                    '活动事件处理器抛出了非标准错误。',
+                    { cause: objCaughtError }
+                  )
+            fnScheduleReconnect(objError)
+          }
+        },
+        objScope,
+        objSignal: objController.signal,
+        ...(strLastEventId ? { strLastEventId } : {}),
+      })
+      if (
+        bIsStopped ||
+        nConnectionSequence !== nActiveSequence ||
+        objController.signal.aborted
+      ) {
+        objNextConnection.fnClose()
+        return
+      }
+      objConnection = objNextConnection
+      nAttempt = 0
+      fnSetState({
+        strStatus: 'connected',
+        strTransport: objAdapter.strTransport,
+      })
+    } catch (objCaughtError) {
+      if (
+        bIsStopped ||
+        nConnectionSequence !== nActiveSequence ||
+        objController.signal.aborted
+      ) {
+        return
+      }
+      fnScheduleReconnect(
+        objCaughtError instanceof Error
+          ? objCaughtError
+          : new Error('活动传输抛出了非标准连接错误。', {
+              cause: objCaughtError,
+            })
+      )
+    }
+  }
+
+  const fnStop = () => {
+    if (bIsStopped) return
+    bIsStopped = true
+    fnDisposeActiveConnection()
+    fnSetState(objIdleConnectionState)
+  }
+
+  const fnReconnect = () => {
+    bIsStopped = false
+    void fnConnect(true)
+  }
+
+  void fnConnect(true)
+  return Object.freeze({
+    fnGetState: () => objState,
+    fnReconnect,
+    fnStop,
+  })
+}