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

package/template/src/realtimeCollaboration/controller.ts

@@ -0,0 +1,355 @@
+import { CollaborationError } from './errors'
+import {
+  fnCreateInvalidCollaborationIdentity,
+  fnNormalizeCollaborationConnectionState,
+  fnNormalizeCollaborationParticipants,
+  fnNormalizeCollaborationPresenceState,
+  fnNormalizeCollaborationReasonCode,
+  fnNormalizeCollaborationSessionInput,
+  fnNormalizeCollaborationSyncState,
+} from './model'
+import type {
+  ICollaborationActiveSnapshot,
+  ICollaborationAdapter,
+  ICollaborationConnectingSnapshot,
+  ICollaborationConnection,
+  ICollaborationController,
+  ICollaborationErrorSnapshot,
+  ICollaborationIdleSnapshot,
+  ICollaborationSessionInput,
+  TCollaborationPresenceState,
+  TCollaborationSessionEvent,
+  TCollaborationSnapshot,
+} from './types'
+
+type TCollaborationSnapshotInput<TBinding> =
+  | Omit<ICollaborationActiveSnapshot<TBinding>, 'nRevision'>
+  | Omit<ICollaborationConnectingSnapshot, 'nRevision'>
+  | Omit<ICollaborationErrorSnapshot, 'nRevision'>
+  | Omit<ICollaborationIdleSnapshot, 'nRevision'>
+
+function fnCreateSafeCollaborationError(
+  objError: Error | undefined,
+  strCode: 'adapter_failed' | 'invalid_event',
+  strMessage: string
+) {
+  return objError instanceof CollaborationError
+    ? objError
+    : new CollaborationError(strCode, strMessage)
+}
+
+/** 创建拥有取消、竞态、订阅和 SDK 资源释放语义的非 React 协作控制器。 */
+export function fnCreateCollaborationController<TBinding>(
+  objAdapter: ICollaborationAdapter<TBinding>
+): ICollaborationController<TBinding> {
+  const objListeners = new Set<() => void>()
+  let nOperation = 0
+  let objAbortController: AbortController | null = null
+  let objConnection: ICollaborationConnection<TBinding> | null = null
+  let objLastInput: ICollaborationSessionInput | null = null
+  let fnUnsubscribeConnection: (() => void) | null = null
+  let objSnapshot: TCollaborationSnapshot<TBinding> = Object.freeze({
+    nRevision: 0,
+    strStatus: 'idle',
+  })
+
+  const fnPublish = (
+    objNext: TCollaborationSnapshotInput<TBinding>
+  ): TCollaborationSnapshot<TBinding> => {
+    objSnapshot = Object.freeze({
+      ...objNext,
+      nRevision: objSnapshot.nRevision + 1,
+    })
+    objListeners.forEach((fnListener) => fnListener())
+    return objSnapshot
+  }
+
+  const fnReleaseConnection = (
+    objConnectionToRelease: ICollaborationConnection<TBinding> | null
+  ) => {
+    if (!objConnectionToRelease) return
+    try {
+      void Promise.resolve(objConnectionToRelease.fnDisconnect()).catch(
+        () => undefined
+      )
+    } catch {
+      // 本地生命周期已经结束，供应商清理失败不得恢复旧会话。
+    }
+  }
+
+  const fnDisposeActiveSession = () => {
+    objAbortController?.abort()
+    objAbortController = null
+    const fnUnsubscribe = fnUnsubscribeConnection
+    fnUnsubscribeConnection = null
+    try {
+      fnUnsubscribe?.()
+    } catch {
+      // 继续释放连接，不能让供应商取消订阅失败阻塞路由卸载。
+    }
+    const objConnectionToRelease = objConnection
+    objConnection = null
+    fnReleaseConnection(objConnectionToRelease)
+  }
+
+  const fnIsCurrentOperation = (
+    nCurrentOperation: number,
+    objController: AbortController
+  ) =>
+    nCurrentOperation === nOperation &&
+    objAbortController === objController &&
+    !objController.signal.aborted
+
+  const fnPublishActive = (
+    objCurrent: ICollaborationActiveSnapshot<TBinding>,
+    objChanges: Partial<
+      Pick<
+        ICollaborationActiveSnapshot<TBinding>,
+        'arrParticipants' | 'strConnectionState' | 'strSyncState'
+      >
+    >
+  ) =>
+    fnPublish({
+      arrParticipants: objChanges.arrParticipants ?? objCurrent.arrParticipants,
+      objBinding: objCurrent.objBinding,
+      strConnectionState:
+        objChanges.strConnectionState ?? objCurrent.strConnectionState,
+      strDocumentId: objCurrent.strDocumentId,
+      strDocumentType: objCurrent.strDocumentType,
+      strMode: objCurrent.strMode,
+      strStatus: 'active',
+      strSyncState: objChanges.strSyncState ?? objCurrent.strSyncState,
+    })
+
+  const fnFailCurrentSession = (
+    nCurrentOperation: number,
+    objController: AbortController,
+    objInput: ICollaborationSessionInput,
+    objError: CollaborationError
+  ) => {
+    if (!fnIsCurrentOperation(nCurrentOperation, objController)) {
+      return objSnapshot
+    }
+    nOperation += 1
+    fnDisposeActiveSession()
+    return fnPublish({
+      objError,
+      strDocumentId: objInput.strDocumentId,
+      strDocumentType: objInput.strDocumentType,
+      strMode: objInput.strMode,
+      strStatus: 'error',
+    })
+  }
+
+  const fnHandleEvent = (
+    objEvent: TCollaborationSessionEvent,
+    nCurrentOperation: number,
+    objController: AbortController,
+    objInput: ICollaborationSessionInput
+  ) => {
+    if (
+      !fnIsCurrentOperation(nCurrentOperation, objController) ||
+      objSnapshot.strStatus !== 'active'
+    ) {
+      return
+    }
+    try {
+      switch (objEvent.strType) {
+        case 'participantsChanged':
+          fnPublishActive(objSnapshot, {
+            arrParticipants: fnNormalizeCollaborationParticipants(
+              objEvent.arrParticipants,
+              objInput.objScope.strUserId
+            ),
+          })
+          return
+        case 'connectionChanged':
+          fnPublishActive(objSnapshot, {
+            strConnectionState: fnNormalizeCollaborationConnectionState(
+              objEvent.strConnectionState
+            ),
+          })
+          return
+        case 'syncChanged':
+          fnPublishActive(objSnapshot, {
+            strSyncState: fnNormalizeCollaborationSyncState(
+              objEvent.strSyncState
+            ),
+          })
+          return
+        case 'sessionFailed':
+          fnFailCurrentSession(
+            nCurrentOperation,
+            objController,
+            objInput,
+            new CollaborationError(
+              'adapter_failed',
+              '实时协作会话已中断，请重新连接。',
+              fnNormalizeCollaborationReasonCode(objEvent.strReasonCode)
+            )
+          )
+      }
+    } catch (objCaughtError) {
+      fnFailCurrentSession(
+        nCurrentOperation,
+        objController,
+        objInput,
+        fnCreateSafeCollaborationError(
+          objCaughtError instanceof Error ? objCaughtError : undefined,
+          'invalid_event',
+          '协作 SDK 返回了无效状态，当前会话已关闭。'
+        )
+      )
+    }
+  }
+
+  const objController: ICollaborationController<TBinding> = {
+    fnClose() {
+      nOperation += 1
+      fnDisposeActiveSession()
+      return fnPublish({ strStatus: 'idle' })
+    },
+    fnGetSnapshot: () => objSnapshot,
+    async fnOpen(objInput) {
+      let objNormalizedInput: ICollaborationSessionInput
+      try {
+        objNormalizedInput = fnNormalizeCollaborationSessionInput(objInput)
+      } catch (objCaughtError) {
+        nOperation += 1
+        fnDisposeActiveSession()
+        objLastInput = null
+        const objIdentity = fnCreateInvalidCollaborationIdentity(objInput)
+        return fnPublish({
+          ...objIdentity,
+          objError: fnCreateSafeCollaborationError(
+            objCaughtError instanceof Error ? objCaughtError : undefined,
+            'invalid_event',
+            '协作文档输入无效。'
+          ),
+          strStatus: 'error',
+        })
+      }
+
+      nOperation += 1
+      fnDisposeActiveSession()
+      const nCurrentOperation = nOperation
+      const objControllerAbort = new AbortController()
+      objAbortController = objControllerAbort
+      objLastInput = objNormalizedInput
+      fnPublish({
+        strDocumentId: objNormalizedInput.strDocumentId,
+        strDocumentType: objNormalizedInput.strDocumentType,
+        strMode: objNormalizedInput.strMode,
+        strStatus: 'connecting',
+      })
+
+      try {
+        const objNextConnection = await objAdapter.fnConnect({
+          ...objNormalizedInput,
+          objSignal: objControllerAbort.signal,
+        })
+        if (!fnIsCurrentOperation(nCurrentOperation, objControllerAbort)) {
+          fnReleaseConnection(objNextConnection)
+          return objSnapshot
+        }
+        if (
+          typeof objNextConnection.fnDisconnect !== 'function' ||
+          typeof objNextConnection.fnSubscribe !== 'function'
+        ) {
+          fnReleaseConnection(objNextConnection)
+          throw new CollaborationError(
+            'adapter_failed',
+            '协作 Adapter 没有返回完整资源生命周期。'
+          )
+        }
+
+        objConnection = objNextConnection
+        const arrParticipants = fnNormalizeCollaborationParticipants(
+          objNextConnection.arrParticipants,
+          objNormalizedInput.objScope.strUserId
+        )
+        const strSyncState = fnNormalizeCollaborationSyncState(
+          objNextConnection.strInitialSyncState
+        )
+        const fnUnsubscribe = objNextConnection.fnSubscribe((objEvent) => {
+          fnHandleEvent(
+            objEvent,
+            nCurrentOperation,
+            objControllerAbort,
+            objNormalizedInput
+          )
+        })
+        if (typeof fnUnsubscribe !== 'function') {
+          throw new CollaborationError(
+            'adapter_failed',
+            '协作 Adapter 没有返回订阅清理函数。'
+          )
+        }
+        fnUnsubscribeConnection = fnUnsubscribe
+        if (!fnIsCurrentOperation(nCurrentOperation, objControllerAbort)) {
+          fnDisposeActiveSession()
+          return objSnapshot
+        }
+        return fnPublish({
+          arrParticipants,
+          objBinding: objNextConnection.objBinding,
+          strConnectionState: 'connected',
+          strDocumentId: objNormalizedInput.strDocumentId,
+          strDocumentType: objNormalizedInput.strDocumentType,
+          strMode: objNormalizedInput.strMode,
+          strStatus: 'active',
+          strSyncState,
+        })
+      } catch (objCaughtError) {
+        if (!fnIsCurrentOperation(nCurrentOperation, objControllerAbort)) {
+          return objSnapshot
+        }
+        return fnFailCurrentSession(
+          nCurrentOperation,
+          objControllerAbort,
+          objNormalizedInput,
+          fnCreateSafeCollaborationError(
+            objCaughtError instanceof Error ? objCaughtError : undefined,
+            'adapter_failed',
+            '无法建立实时协作文档会话。'
+          )
+        )
+      }
+    },
+    fnReconnect() {
+      return objLastInput
+        ? objController.fnOpen(objLastInput)
+        : Promise.resolve(objSnapshot)
+    },
+    async fnSetPresenceState(strPresenceState: TCollaborationPresenceState) {
+      const objCurrentConnection = objConnection
+      const nCurrentOperation = nOperation
+      if (
+        objSnapshot.strStatus !== 'active' ||
+        !objCurrentConnection?.fnSetPresenceState
+      ) {
+        return false
+      }
+      try {
+        await objCurrentConnection.fnSetPresenceState(
+          fnNormalizeCollaborationPresenceState(strPresenceState)
+        )
+        return (
+          nCurrentOperation === nOperation &&
+          objConnection === objCurrentConnection
+        )
+      } catch {
+        throw new CollaborationError(
+          'presence_update_failed',
+          '无法更新当前协作成员状态。'
+        )
+      }
+    },
+    fnSubscribe(fnListener) {
+      objListeners.add(fnListener)
+      return () => objListeners.delete(fnListener)
+    },
+  }
+
+  return objController
+}

package/template/src/realtimeCollaboration/errors.ts

@@ -0,0 +1,20 @@
+import type { TCollaborationErrorCode } from './types'
+
+/** 可由 UI 和测试稳定分类、不会泄漏供应商响应的协作错误。 */
+export class CollaborationError extends Error {
+  /** 稳定错误码。 */
+  readonly strCode: TCollaborationErrorCode
+  /** Adapter 提供的非敏感原因码。 */
+  readonly strReasonCode?: string
+
+  constructor(
+    strCode: TCollaborationErrorCode,
+    strMessage: string,
+    strReasonCode?: string
+  ) {
+    super(strMessage)
+    this.name = 'CollaborationError'
+    this.strCode = strCode
+    this.strReasonCode = strReasonCode
+  }
+}

package/template/src/realtimeCollaboration/index.ts

@@ -0,0 +1,39 @@
+export { fnCreateCollaborationController } from './controller'
+export { CollaborationError } from './errors'
+export {
+  fnCreateInvalidCollaborationIdentity,
+  fnNormalizeCollaborationConnectionState,
+  fnNormalizeCollaborationParticipants,
+  fnNormalizeCollaborationPresenceState,
+  fnNormalizeCollaborationReasonCode,
+  fnNormalizeCollaborationSessionInput,
+  fnNormalizeCollaborationSyncState,
+  nMaxCollaborationParticipants,
+} from './model'
+export { useRealtimeCollaboration } from './react'
+export type {
+  ICollaborationActiveSnapshot,
+  ICollaborationAdapter,
+  ICollaborationConnectingSnapshot,
+  ICollaborationConnection,
+  ICollaborationConnectionChangedEvent,
+  ICollaborationController,
+  ICollaborationErrorSnapshot,
+  ICollaborationIdleSnapshot,
+  ICollaborationParticipant,
+  ICollaborationParticipantInput,
+  ICollaborationParticipantsChangedEvent,
+  ICollaborationSessionFailedEvent,
+  ICollaborationSessionInput,
+  ICollaborationSessionRequest,
+  ICollaborationSyncChangedEvent,
+  IUseRealtimeCollaborationOptions,
+  TCollaborationConnectionState,
+  TCollaborationDocumentMode,
+  TCollaborationErrorCode,
+  TCollaborationPresenceState,
+  TCollaborationSessionEvent,
+  TCollaborationSnapshot,
+  TCollaborationSyncState,
+  TUseRealtimeCollaborationResult,
+} from './types'

package/template/src/realtimeCollaboration/model.ts

@@ -0,0 +1,212 @@
+import { fnCreateAppQueryScope } from '@/api/query'
+import { CollaborationError } from './errors'
+import type {
+  ICollaborationParticipant,
+  ICollaborationParticipantInput,
+  ICollaborationSessionInput,
+  TCollaborationConnectionState,
+  TCollaborationDocumentMode,
+  TCollaborationPresenceState,
+  TCollaborationSyncState,
+} from './types'
+
+export const nMaxCollaborationParticipants = 200
+const nMaxCollaborationIdentifierLength = 200
+const nMaxCollaborationDisplayNameLength = 300
+const nMaxCollaborationReasonCodeLength = 100
+
+function fnNormalizeRequiredText(
+  strValue: string,
+  strField: string,
+  nMaxLength = nMaxCollaborationIdentifierLength,
+  strCode: 'invalid_event' | 'invalid_request' = 'invalid_request'
+) {
+  const strNormalizedValue = typeof strValue === 'string' ? strValue.trim() : ''
+  if (!strNormalizedValue || strNormalizedValue.length > nMaxLength) {
+    throw new CollaborationError(
+      strCode,
+      `协作字段 ${strField} 必须是长度不超过 ${nMaxLength} 的非空字符串。`
+    )
+  }
+  return strNormalizedValue
+}
+
+function fnNormalizeOptionalText(
+  strValue: string | undefined,
+  strField: string,
+  nMaxLength = nMaxCollaborationIdentifierLength
+) {
+  if (strValue === undefined) return undefined
+  return fnNormalizeRequiredText(
+    strValue,
+    strField,
+    nMaxLength,
+    'invalid_event'
+  )
+}
+
+/** 校验文档身份与模式，并规范化用于会话隔离的应用作用域。 */
+export function fnNormalizeCollaborationSessionInput(
+  objInput: ICollaborationSessionInput
+): ICollaborationSessionInput {
+  if (objInput.strMode !== 'edit' && objInput.strMode !== 'view') {
+    throw new CollaborationError(
+      'invalid_request',
+      '协作文档模式只支持 edit 或 view。'
+    )
+  }
+  return Object.freeze({
+    objScope: fnCreateAppQueryScope(objInput.objScope),
+    strDocumentId: fnNormalizeRequiredText(
+      objInput.strDocumentId,
+      'strDocumentId'
+    ),
+    strDocumentType: fnNormalizeRequiredText(
+      objInput.strDocumentType,
+      'strDocumentType'
+    ),
+    strMode: objInput.strMode,
+  })
+}
+
+function fnIsPresenceState(
+  strPresenceState: string
+): strPresenceState is TCollaborationPresenceState {
+  return strPresenceState === 'active' || strPresenceState === 'idle'
+}
+
+function fnIsParticipantInputArray(
+  arrInputs: readonly ICollaborationParticipantInput[]
+): boolean {
+  return Array.isArray(arrInputs)
+}
+
+/** 校验 SDK 成员快照、拒绝重复连接身份，并标记当前应用用户。 */
+export function fnNormalizeCollaborationParticipants(
+  arrInputs: readonly ICollaborationParticipantInput[],
+  strCurrentUserId: string
+): readonly ICollaborationParticipant[] {
+  if (
+    !fnIsParticipantInputArray(arrInputs) ||
+    arrInputs.length > nMaxCollaborationParticipants
+  ) {
+    throw new CollaborationError(
+      'invalid_event',
+      `协作成员列表不能超过 ${nMaxCollaborationParticipants} 项。`
+    )
+  }
+
+  const objParticipantIds = new Set<string>()
+  const arrParticipants = arrInputs.map((objInput) => {
+    if (!objInput || typeof objInput !== 'object') {
+      throw new CollaborationError('invalid_event', '协作 SDK 返回了无效成员。')
+    }
+    const strParticipantId = fnNormalizeRequiredText(
+      objInput.strParticipantId ?? '',
+      'strParticipantId',
+      nMaxCollaborationIdentifierLength,
+      'invalid_event'
+    )
+    const strPresenceState = objInput.strPresenceState ?? ''
+    if (!fnIsPresenceState(strPresenceState)) {
+      throw new CollaborationError(
+        'invalid_event',
+        `协作成员 ${strParticipantId} 返回了无效活跃状态。`
+      )
+    }
+    if (objParticipantIds.has(strParticipantId)) {
+      throw new CollaborationError(
+        'invalid_event',
+        `协作成员列表包含重复身份 ${strParticipantId}。`
+      )
+    }
+    objParticipantIds.add(strParticipantId)
+    const strUserId = fnNormalizeOptionalText(objInput.strUserId, 'strUserId')
+
+    return Object.freeze({
+      bIsCurrentUser: strUserId === strCurrentUserId,
+      strDisplayName: fnNormalizeRequiredText(
+        objInput.strDisplayName ?? '',
+        'strDisplayName',
+        nMaxCollaborationDisplayNameLength,
+        'invalid_event'
+      ),
+      strParticipantId,
+      strPresenceState,
+      strUserId,
+    })
+  })
+  return Object.freeze(arrParticipants)
+}
+
+/** 校验 Adapter 提供的非敏感失败原因码。 */
+export function fnNormalizeCollaborationReasonCode(
+  strReasonCode: string | undefined
+) {
+  return fnNormalizeOptionalText(
+    strReasonCode,
+    'strReasonCode',
+    nMaxCollaborationReasonCodeLength
+  )
+}
+
+/** 校验 SDK 连接状态。 */
+export function fnNormalizeCollaborationConnectionState(
+  strConnectionState: string
+): TCollaborationConnectionState {
+  if (
+    strConnectionState !== 'connected' &&
+    strConnectionState !== 'reconnecting'
+  ) {
+    throw new CollaborationError(
+      'invalid_event',
+      '协作 SDK 返回了无效连接状态。'
+    )
+  }
+  return strConnectionState
+}
+
+/** 校验 SDK 文档同步状态。 */
+export function fnNormalizeCollaborationSyncState(
+  strSyncState: string
+): TCollaborationSyncState {
+  if (strSyncState !== 'synced' && strSyncState !== 'syncing') {
+    throw new CollaborationError(
+      'invalid_event',
+      '协作 SDK 返回了无效同步状态。'
+    )
+  }
+  return strSyncState
+}
+
+/** 校验当前成员活跃状态命令。 */
+export function fnNormalizeCollaborationPresenceState(
+  strPresenceState: string
+): TCollaborationPresenceState {
+  if (!fnIsPresenceState(strPresenceState)) {
+    throw new CollaborationError(
+      'invalid_request',
+      '协作成员状态只支持 active 或 idle。'
+    )
+  }
+  return strPresenceState
+}
+
+/** 为无效运行时输入创建不泄漏原值的安全文档身份。 */
+export function fnCreateInvalidCollaborationIdentity(
+  objInput: ICollaborationSessionInput
+): {
+  readonly strDocumentId: string
+  readonly strDocumentType: string
+  readonly strMode: TCollaborationDocumentMode
+} {
+  const fnSafeIdentity = (strValue: string) =>
+    typeof strValue === 'string' && strValue.trim()
+      ? strValue.trim().slice(0, nMaxCollaborationIdentifierLength)
+      : 'invalid'
+  return Object.freeze({
+    strDocumentId: fnSafeIdentity(objInput.strDocumentId),
+    strDocumentType: fnSafeIdentity(objInput.strDocumentType),
+    strMode: objInput.strMode === 'edit' ? 'edit' : 'view',
+  })
+}

package/template/src/realtimeCollaboration/react.ts

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react'
+import { useAppQueryScope } from '@/api/query'
+import { fnCreateCollaborationController } from './controller'
+import type {
+  ICollaborationSessionInput,
+  IUseRealtimeCollaborationOptions,
+  TCollaborationPresenceState,
+  TUseRealtimeCollaborationResult,
+} from './types'
+
+/**
+ * 在当前路由拥有一个实时协作文档会话，并在身份、文档或路由变化时释放 SDK。
+ */
+export function useRealtimeCollaboration<TBinding>({
+  bIsEnabled = true,
+  objAdapter,
+  strDocumentId,
+  strDocumentType,
+  strMode,
+  strWorkspaceId,
+}: IUseRealtimeCollaborationOptions<TBinding>): TUseRealtimeCollaborationResult<TBinding> {
+  const objScope = useAppQueryScope({ strWorkspaceId })
+  const objController = useMemo(
+    () => fnCreateCollaborationController(objAdapter),
+    [objAdapter]
+  )
+  const objInput = useMemo<ICollaborationSessionInput>(
+    () => ({ objScope, strDocumentId, strDocumentType, strMode }),
+    [objScope, strDocumentId, strDocumentType, strMode]
+  )
+  const objSnapshot = useSyncExternalStore(
+    objController.fnSubscribe,
+    objController.fnGetSnapshot,
+    objController.fnGetSnapshot
+  )
+
+  useEffect(() => {
+    if (!bIsEnabled) {
+      objController.fnClose()
+      return
+    }
+    void objController.fnOpen(objInput)
+    return () => {
+      objController.fnClose()
+    }
+  }, [bIsEnabled, objController, objInput])
+
+  const fnClose = useCallback(() => {
+    objController.fnClose()
+  }, [objController])
+  const fnReconnect = useCallback(async () => {
+    if (!bIsEnabled) return
+    await objController.fnReconnect()
+  }, [bIsEnabled, objController])
+  const fnSetPresenceState = useCallback(
+    (strPresenceState: TCollaborationPresenceState) =>
+      bIsEnabled
+        ? objController.fnSetPresenceState(strPresenceState)
+        : Promise.resolve(false),
+    [bIsEnabled, objController]
+  )
+
+  return useMemo(
+    () => ({
+      ...objSnapshot,
+      fnClose,
+      fnReconnect,
+      fnSetPresenceState,
+    }),
+    [fnClose, fnReconnect, fnSetPresenceState, objSnapshot]
+  )
+}