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

package/template/src/observability/types.ts

@@ -0,0 +1,119 @@
+/** 可观测事件的严重级别。 */
+export type TObservabilityLevel = 'error' | 'info' | 'warning'
+
+/** 脚手架内置的稳定事件来源。 */
+export type TObservabilitySource =
+  | 'api'
+  | 'bootstrap'
+  | 'global'
+  | 'performance'
+  | 'route'
+
+/** Adapter 最终允许接收的标量属性。 */
+export type TObservabilityAttributeValue = boolean | null | number | string
+
+/** 调用方可提交的属性结构；嵌套值会被默认拒绝，不会传给 Adapter。 */
+export type TObservabilityAttributeInput =
+  | TObservabilityAttributeValue
+  | readonly TObservabilityAttributeInput[]
+  | { readonly [strKey: string]: TObservabilityAttributeInput }
+
+/** 可由错误采集入口安全接收的值。 */
+export type TObservabilityErrorInput =
+  | Error
+  | object
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+
+/** 一次构建及其部署环境的公开发布信息。 */
+export interface IReleaseInfo {
+  /** `package.json` 中的应用版本。 */
+  strVersion: string
+  /** 构建对应的 Git Commit；本地无法解析时为 `unknown`。 */
+  strCommit: string
+  /** 产生前端静态产物的 ISO 时间。 */
+  strBuildTime: string
+  /** 部署时通过运行时配置提供的环境名称。 */
+  strEnvironment: string
+}
+
+/** 构建阶段即可获得且不包含部署环境的公开信息。 */
+export interface IBuildInfo {
+  /** `package.json` 中的应用版本。 */
+  strVersion: string
+  /** 构建对应的 Git Commit。 */
+  strCommit: string
+  /** 产生前端静态产物的 ISO 时间。 */
+  strBuildTime: string
+}
+
+/** 已脱敏的异常摘要；不包含原始 Error、请求或响应对象。 */
+export interface IObservabilityException {
+  /** 异常类名。 */
+  strName: string
+  /** 截断并脱敏后的异常消息。 */
+  strMessage: string
+  /** 截断并逐行脱敏后的调用栈，原始 Error 对象不会离开基础层。 */
+  strStack?: string
+}
+
+/** 发送给外部监控供应商的稳定、安全事件。 */
+export interface IObservabilityEvent {
+  /** 客户端生成的事件 ID。 */
+  strEventId: string
+  /** 供检索和告警使用的稳定事件名。 */
+  strName: string
+  /** 事件严重级别。 */
+  strLevel: TObservabilityLevel
+  /** 事件产生的技术边界。 */
+  strSource: TObservabilitySource
+  /** 浏览器产生事件时的 ISO 时间。 */
+  strTimestamp: string
+  /** 自动附加的版本、Commit、构建时间和部署环境。 */
+  objRelease: Readonly<IReleaseInfo>
+  /** 经过白名单过滤的标量上下文。 */
+  objAttributes: Readonly<Record<string, TObservabilityAttributeValue>>
+  /** 错误事件才包含的安全异常摘要。 */
+  objException?: Readonly<IObservabilityException>
+}
+
+/** Sentry、OpenTelemetry 或企业日志 SDK 需要实现的最小 Adapter。 */
+export interface IObservabilityAdapter {
+  /** 接收已经完成脱敏和版本补全的事件。Adapter 失败不得影响应用。 */
+  fnCaptureEvent: (objEvent: IObservabilityEvent) => Promise<void> | void
+}
+
+/** 初始化可观测性运行时的公开配置。 */
+export interface IObservabilityConfig {
+  /** 是否允许产生并发送可观测事件。 */
+  bEnabled: boolean
+  /** 当前应用发布信息。 */
+  objRelease: Readonly<IReleaseInfo>
+  /** 项目选择的供应商 Adapter；未提供时安全地丢弃事件。 */
+  objAdapter?: IObservabilityAdapter
+}
+
+/** 捕获普通结构化事件时允许提供的字段。 */
+export interface ICaptureEventOptions {
+  /** 稳定事件名，不应包含用户输入。 */
+  strName: string
+  /** 事件来源。 */
+  strSource: TObservabilitySource
+  /** 默认是 `info`。 */
+  strLevel?: TObservabilityLevel
+  /** 进入 Adapter 前执行白名单过滤和脱敏。 */
+  objAttributes?: Readonly<Record<string, TObservabilityAttributeInput>>
+}
+
+/** 捕获异常时允许提供的安全上下文。 */
+export interface ICaptureErrorOptions {
+  /** 稳定事件名，不应使用原始错误消息。 */
+  strName: string
+  /** 异常来源。 */
+  strSource: TObservabilitySource
+  /** 进入 Adapter 前执行白名单过滤和脱敏。 */
+  objAttributes?: Readonly<Record<string, TObservabilityAttributeInput>>
+}

package/template/src/optionalEditors/controller.ts

@@ -0,0 +1,327 @@
+import { OptionalEditorError } from './errors'
+import {
+  fnNormalizeOptionalEditorMountRequest,
+  fnNormalizeOptionalEditorReasonCode,
+} from './model'
+import type {
+  IOptionalEditorActiveSnapshot,
+  IOptionalEditorAdapter,
+  IOptionalEditorController,
+  IOptionalEditorDocument,
+  IOptionalEditorMountInput,
+  IOptionalEditorSession,
+  TOptionalEditorSessionEvent,
+  TOptionalEditorSnapshot,
+} from './types'
+
+type TOptionalEditorSnapshotInput<TBinding> =
+  | Omit<IOptionalEditorActiveSnapshot<TBinding>, 'nRevision'>
+  | {
+      readonly objError: OptionalEditorError
+      readonly strStatus: 'error'
+    }
+  | { readonly strStatus: 'idle' }
+  | {
+      readonly strContentRevision?: string
+      readonly strDocumentId: string
+      readonly strEditorKind: IOptionalEditorActiveSnapshot<TBinding>['strEditorKind']
+      readonly strMode: IOptionalEditorActiveSnapshot<TBinding>['strMode']
+      readonly strSchemaVersion: string
+      readonly strStatus: 'loading'
+    }
+
+function fnCreateSafeOptionalEditorError(
+  objError: Error | undefined,
+  strCode: 'ADAPTER_FAILED' | 'EXPORT_FAILED' | 'INVALID_EVENT',
+  strMessage: string
+) {
+  return objError instanceof OptionalEditorError
+    ? objError
+    : new OptionalEditorError(strCode, strMessage)
+}
+
+/** 创建拥有取消、竞态、dirty、导出和 SDK 资源释放语义的编辑器控制器。 */
+export function fnCreateOptionalEditorController<
+  TDocument extends object,
+  TBinding,
+>(
+  objAdapter: IOptionalEditorAdapter<TDocument, TBinding>
+): IOptionalEditorController<TDocument, TBinding> {
+  const objListeners = new Set<() => void>()
+  let nOperation = 0
+  let objAbortController: AbortController | null = null
+  let objSession: IOptionalEditorSession<TDocument, TBinding> | null = null
+  let objActiveDocument: IOptionalEditorDocument<TDocument> | null = null
+  let fnUnsubscribeSession: (() => void) | null = null
+  let objSnapshot: TOptionalEditorSnapshot<TBinding> = Object.freeze({
+    nRevision: 0,
+    strStatus: 'idle',
+  })
+
+  const fnPublish = (
+    objNext: TOptionalEditorSnapshotInput<TBinding>
+  ): TOptionalEditorSnapshot<TBinding> => {
+    objSnapshot = Object.freeze({
+      ...objNext,
+      nRevision: objSnapshot.nRevision + 1,
+    })
+    objListeners.forEach((fnListener) => fnListener())
+    return objSnapshot
+  }
+
+  const fnReleaseSession = (
+    objSessionToRelease: IOptionalEditorSession<TDocument, TBinding> | null
+  ) => {
+    if (!objSessionToRelease) return
+    try {
+      void Promise.resolve(objSessionToRelease.fnDestroy()).catch(
+        () => undefined
+      )
+    } catch {
+      // 当前路由生命周期已经结束，供应商销毁异常不得恢复旧编辑器。
+    }
+  }
+
+  const fnDisposeActiveSession = () => {
+    objAbortController?.abort()
+    objAbortController = null
+    const fnUnsubscribe = fnUnsubscribeSession
+    fnUnsubscribeSession = null
+    try {
+      fnUnsubscribe?.()
+    } catch {
+      // 继续释放 SDK，不能让取消订阅异常阻塞路由卸载。
+    }
+    const objSessionToRelease = objSession
+    objSession = null
+    objActiveDocument = null
+    fnReleaseSession(objSessionToRelease)
+  }
+
+  const fnIsCurrentOperation = (
+    nCurrentOperation: number,
+    objController: AbortController
+  ) =>
+    nCurrentOperation === nOperation &&
+    objAbortController === objController &&
+    !objController.signal.aborted
+
+  const fnFailCurrentSession = (
+    nCurrentOperation: number,
+    objController: AbortController,
+    objError: OptionalEditorError
+  ) => {
+    if (!fnIsCurrentOperation(nCurrentOperation, objController)) {
+      return objSnapshot
+    }
+    nOperation += 1
+    fnDisposeActiveSession()
+    return fnPublish({ objError, strStatus: 'error' })
+  }
+
+  const fnHandleEvent = (
+    objEvent: TOptionalEditorSessionEvent,
+    nCurrentOperation: number,
+    objController: AbortController
+  ) => {
+    if (
+      !fnIsCurrentOperation(nCurrentOperation, objController) ||
+      objSnapshot.strStatus !== 'active'
+    ) {
+      return
+    }
+    try {
+      if (objEvent.strType === 'dirtyChanged') {
+        if (typeof objEvent.bIsDirty !== 'boolean') {
+          throw new OptionalEditorError(
+            'INVALID_EVENT',
+            '编辑器 SDK 返回了无效 dirty 状态。'
+          )
+        }
+        fnPublish({
+          ...objSnapshot,
+          bIsDirty: objEvent.bIsDirty,
+          strStatus: 'active',
+        })
+        return
+      }
+      if (objEvent.strType === 'sessionFailed') {
+        fnFailCurrentSession(
+          nCurrentOperation,
+          objController,
+          new OptionalEditorError(
+            'ADAPTER_FAILED',
+            '可选编辑器会话已中断，请重新打开文档。',
+            fnNormalizeOptionalEditorReasonCode(objEvent.strReasonCode)
+          )
+        )
+        return
+      }
+      throw new OptionalEditorError(
+        'INVALID_EVENT',
+        '编辑器 SDK 返回了未知事件。'
+      )
+    } catch (objCaughtError) {
+      fnFailCurrentSession(
+        nCurrentOperation,
+        objController,
+        fnCreateSafeOptionalEditorError(
+          objCaughtError instanceof Error ? objCaughtError : undefined,
+          'INVALID_EVENT',
+          '编辑器 SDK 返回了无效状态，当前会话已关闭。'
+        )
+      )
+    }
+  }
+
+  const objController: IOptionalEditorController<TDocument, TBinding> = {
+    fnClose() {
+      nOperation += 1
+      fnDisposeActiveSession()
+      return fnPublish({ strStatus: 'idle' })
+    },
+    async fnExportDocument() {
+      const objCurrentSession = objSession
+      const objCurrentDocument = objActiveDocument
+      const nCurrentOperation = nOperation
+      if (
+        objSnapshot.strStatus !== 'active' ||
+        !objCurrentSession ||
+        !objCurrentDocument
+      ) {
+        throw new OptionalEditorError(
+          'SESSION_INACTIVE',
+          '当前没有可导出的活动编辑器会话。'
+        )
+      }
+      try {
+        const objDocument = objAdapter.fnValidateDocument(
+          await objCurrentSession.fnReadDocument()
+        )
+        if (
+          nCurrentOperation !== nOperation ||
+          objCurrentSession !== objSession
+        ) {
+          throw new OptionalEditorError(
+            'SESSION_INACTIVE',
+            '编辑器会话已被替换，请重新导出。'
+          )
+        }
+        return Object.freeze({
+          ...objCurrentDocument,
+          objDocument,
+        })
+      } catch (objCaughtError) {
+        throw fnCreateSafeOptionalEditorError(
+          objCaughtError instanceof Error ? objCaughtError : undefined,
+          'EXPORT_FAILED',
+          '无法导出当前结构化文档。'
+        )
+      }
+    },
+    fnGetSnapshot: () => objSnapshot,
+    fnMarkSaved() {
+      return objSnapshot.strStatus === 'active'
+        ? fnPublish({ ...objSnapshot, bIsDirty: false, strStatus: 'active' })
+        : objSnapshot
+    },
+    async fnMount(objInput: IOptionalEditorMountInput<TDocument>) {
+      nOperation += 1
+      fnDisposeActiveSession()
+      const nCurrentOperation = nOperation
+      const objControllerAbort = new AbortController()
+      objAbortController = objControllerAbort
+      let objRequest
+      try {
+        objRequest = fnNormalizeOptionalEditorMountRequest(
+          objInput,
+          objAdapter.strEditorKind,
+          objAdapter.fnValidateDocument,
+          objControllerAbort.signal
+        )
+      } catch (objCaughtError) {
+        objAbortController = null
+        return fnPublish({
+          objError: fnCreateSafeOptionalEditorError(
+            objCaughtError instanceof Error ? objCaughtError : undefined,
+            'ADAPTER_FAILED',
+            '可选编辑器挂载请求无效。'
+          ),
+          strStatus: 'error',
+        })
+      }
+      fnPublish({
+        strContentRevision: objRequest.objDocument.strContentRevision,
+        strDocumentId: objRequest.objDocument.strDocumentId,
+        strEditorKind: objRequest.objDocument.strEditorKind,
+        strMode: objRequest.strMode,
+        strSchemaVersion: objRequest.objDocument.strSchemaVersion,
+        strStatus: 'loading',
+      })
+
+      try {
+        const objNextSession = await objAdapter.fnMount(objRequest)
+        if (!fnIsCurrentOperation(nCurrentOperation, objControllerAbort)) {
+          fnReleaseSession(objNextSession)
+          return objSnapshot
+        }
+        if (
+          typeof objNextSession.fnDestroy !== 'function' ||
+          typeof objNextSession.fnReadDocument !== 'function' ||
+          typeof objNextSession.fnSubscribe !== 'function'
+        ) {
+          fnReleaseSession(objNextSession)
+          throw new OptionalEditorError(
+            'ADAPTER_FAILED',
+            '编辑器 Adapter 没有返回完整资源生命周期。'
+          )
+        }
+        objSession = objNextSession
+        objActiveDocument = objRequest.objDocument
+        const fnUnsubscribe = objNextSession.fnSubscribe((objEvent) => {
+          fnHandleEvent(objEvent, nCurrentOperation, objControllerAbort)
+        })
+        if (typeof fnUnsubscribe !== 'function') {
+          throw new OptionalEditorError(
+            'ADAPTER_FAILED',
+            '编辑器 Adapter 没有返回订阅清理函数。'
+          )
+        }
+        fnUnsubscribeSession = fnUnsubscribe
+        if (!fnIsCurrentOperation(nCurrentOperation, objControllerAbort)) {
+          fnDisposeActiveSession()
+          return objSnapshot
+        }
+        return fnPublish({
+          bIsDirty: false,
+          objBinding: objNextSession.objBinding,
+          strContentRevision: objRequest.objDocument.strContentRevision,
+          strDocumentId: objRequest.objDocument.strDocumentId,
+          strEditorKind: objRequest.objDocument.strEditorKind,
+          strMode: objRequest.strMode,
+          strSchemaVersion: objRequest.objDocument.strSchemaVersion,
+          strStatus: 'active',
+        })
+      } catch (objCaughtError) {
+        if (!fnIsCurrentOperation(nCurrentOperation, objControllerAbort)) {
+          return objSnapshot
+        }
+        return fnFailCurrentSession(
+          nCurrentOperation,
+          objControllerAbort,
+          fnCreateSafeOptionalEditorError(
+            objCaughtError instanceof Error ? objCaughtError : undefined,
+            'ADAPTER_FAILED',
+            '无法加载或挂载可选编辑器。'
+          )
+        )
+      }
+    },
+    fnSubscribe(fnListener) {
+      objListeners.add(fnListener)
+      return () => objListeners.delete(fnListener)
+    },
+  }
+
+  return objController
+}

package/template/src/optionalEditors/errors.ts

@@ -0,0 +1,21 @@
+import type { TOptionalEditorErrorCode } from './types'
+
+/** 可选编辑器边界抛出的安全稳定错误。 */
+export class OptionalEditorError extends Error {
+  /** 供界面分支和测试使用的稳定错误码。 */
+  readonly strCode: TOptionalEditorErrorCode
+
+  /** 可选的非敏感供应商原因码。 */
+  readonly strReasonCode?: string
+
+  constructor(
+    strCode: TOptionalEditorErrorCode,
+    strMessage: string,
+    strReasonCode?: string
+  ) {
+    super(strMessage)
+    this.name = 'OptionalEditorError'
+    this.strCode = strCode
+    this.strReasonCode = strReasonCode
+  }
+}

package/template/src/optionalEditors/index.ts

@@ -0,0 +1,35 @@
+export { fnCreateOptionalEditorController } from './controller'
+export { OptionalEditorError } from './errors'
+export {
+  fnMigrateOptionalEditorDocument,
+  fnNormalizeOptionalEditorDocument,
+  fnNormalizeOptionalEditorKind,
+  fnNormalizeOptionalEditorMode,
+  fnNormalizeOptionalEditorMountRequest,
+  fnNormalizeOptionalEditorReasonCode,
+} from './model'
+export { useOptionalEditor } from './react'
+export type {
+  IMigrateOptionalEditorDocumentOptions,
+  IOptionalEditorActiveSnapshot,
+  IOptionalEditorAdapter,
+  IOptionalEditorController,
+  IOptionalEditorDirtyChangedEvent,
+  IOptionalEditorDocument,
+  IOptionalEditorDocumentInput,
+  IOptionalEditorErrorSnapshot,
+  IOptionalEditorIdleSnapshot,
+  IOptionalEditorLoadingSnapshot,
+  IOptionalEditorMigration,
+  IOptionalEditorMountInput,
+  IOptionalEditorMountRequest,
+  IOptionalEditorSession,
+  IOptionalEditorSessionFailedEvent,
+  IUseOptionalEditorOptions,
+  TOptionalEditorErrorCode,
+  TOptionalEditorKind,
+  TOptionalEditorMode,
+  TOptionalEditorSessionEvent,
+  TOptionalEditorSnapshot,
+  TUseOptionalEditorResult,
+} from './types'