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

package/template/src/api/hooks/requestId.ts

@@ -0,0 +1,65 @@
+import {
+  AxiosHeaders,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios'
+
+const strRequestIdHeader = 'X-Request-ID'
+const objRequestIdPattern = /^[a-z0-9._:/-]{1,128}$/i
+
+function fnNormalizeRequestId(objValue: unknown) {
+  const strValue =
+    typeof objValue === 'string' || typeof objValue === 'number'
+      ? String(objValue).trim()
+      : ''
+  return objRequestIdPattern.test(strValue) ? strValue : undefined
+}
+
+function fnReadHeader(
+  objHeaders: AxiosResponse['headers'],
+  strHeaderName: string
+) {
+  if (objHeaders instanceof AxiosHeaders) {
+    return fnNormalizeRequestId(objHeaders.get(strHeaderName))
+  }
+  return fnNormalizeRequestId(objHeaders[strHeaderName.toLowerCase()])
+}
+
+/** 请求 ID 不是安全令牌；随机值仅用于跨前后端关联一次请求。 */
+function fnCreateDefaultRequestId() {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID()
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`
+}
+
+/** 保留合法的调用方请求 ID，否则生成一个新的 X-Request-ID。 */
+export function fnEnsureRequestId(
+  objConfig: InternalAxiosRequestConfig,
+  fnCreateRequestId: () => string = fnCreateDefaultRequestId
+) {
+  const strRequestId =
+    fnNormalizeRequestId(objConfig.headers.get(strRequestIdHeader)) ??
+    fnNormalizeRequestId(fnCreateRequestId()) ??
+    fnCreateDefaultRequestId()
+
+  objConfig.strRequestId = strRequestId
+  objConfig.headers.set(strRequestIdHeader, strRequestId)
+  return strRequestId
+}
+
+/** 响应头优先，其次使用响应体 ID，最后回退到客户端请求 ID。 */
+export function fnResolveResponseRequestId(
+  objResponse: AxiosResponse | undefined,
+  objPayloadRequestId?: unknown,
+  objFallbackRequestId?: unknown
+) {
+  return (
+    (objResponse &&
+      (fnReadHeader(objResponse.headers, 'x-request-id') ??
+        fnReadHeader(objResponse.headers, 'x-correlation-id'))) ??
+    fnNormalizeRequestId(objPayloadRequestId) ??
+    fnNormalizeRequestId(objResponse?.config.strRequestId) ??
+    fnNormalizeRequestId(objFallbackRequestId)
+  )
+}

package/template/src/api/hooks/response.ts

@@ -0,0 +1,22 @@
+import type { AxiosResponse } from 'axios'
+import { fnResolveResponseRequestId } from './requestId'
+import type { IApiHookOptions } from './types'
+
+export function fnCreateResponseHook(objOptions: IApiHookOptions = {}) {
+  return async (objResponse: AxiosResponse) => {
+    const objConfig = objResponse.config
+    const strRequestId = fnResolveResponseRequestId(objResponse)
+
+    objResponse.strRequestId = strRequestId
+    objConfig.strRequestId = strRequestId
+
+    objConfig.fnProgress?.(false)
+    objConfig.fnBeforeResponse?.(objResponse)
+
+    if (objConfig.strSuccessMessage) {
+      await objOptions.fnOnSuccess?.(objConfig.strSuccessMessage, objResponse)
+    }
+
+    return objResponse
+  }
+}

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

@@ -0,0 +1,20 @@
+import type { AxiosResponse } from 'axios'
+import type { ApiError } from '@/api/ApiError'
+
+export type TMaybePromise<TValue> = TValue | Promise<TValue>
+
+export interface IApiHookOptions {
+  arrAnonymousPaths?: readonly string[]
+  fnGetAccessToken?: () => TMaybePromise<string | null>
+  fnIsAccessTokenExpired?: () => TMaybePromise<boolean>
+  fnRefreshAccessToken?: () => Promise<string | null>
+  fnOnUnauthorized?: () => TMaybePromise<void>
+  /** 创建新的请求关联 ID；主要用于测试或宿主平台接管 ID 生成。 */
+  fnCreateRequestId?: () => string
+  /** 接收不含 Axios 配置和认证信息的标准 API 错误。 */
+  fnOnError?: (objError: ApiError) => TMaybePromise<void>
+  fnOnSuccess?: (
+    strMessage: string,
+    objResponse: AxiosResponse
+  ) => TMaybePromise<void>
+}

package/template/src/api/idempotency/index.ts

@@ -0,0 +1 @@
+export { fnCreateIdempotencyKey, fnNormalizeIdempotencyKey } from './key'

package/template/src/api/idempotency/key.ts

@@ -0,0 +1,23 @@
+const objIdempotencyKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/
+
+/** 校验并返回可安全写入 HTTP Header 的幂等键。 */
+export function fnNormalizeIdempotencyKey(strIdempotencyKey: string) {
+  const strNormalizedKey = strIdempotencyKey.trim()
+  if (
+    strNormalizedKey !== strIdempotencyKey ||
+    !objIdempotencyKeyPattern.test(strNormalizedKey)
+  ) {
+    throw new TypeError(
+      '幂等键必须为 8 到 128 位，只能包含字母、数字、点、下划线、冒号和连字符。'
+    )
+  }
+  return strNormalizedKey
+}
+
+/** 使用浏览器密码学随机源创建新的幂等键。 */
+export function fnCreateIdempotencyKey() {
+  if (typeof globalThis.crypto?.randomUUID !== 'function') {
+    throw new Error('当前运行环境不支持安全的幂等键生成。')
+  }
+  return fnNormalizeIdempotencyKey(globalThis.crypto.randomUUID())
+}

package/template/src/api/index.ts

@@ -0,0 +1,14 @@
+import './types'
+
+export { ApiError, fnIsApiError } from './ApiError'
+export {
+  fnConfigureApiClient,
+  fnShowApiError,
+} from './clients/configureApiClient'
+export type {
+  IApiErrorOptions,
+  IAuthApiClient,
+  IGeneratedApiClient,
+  TApiEnvelope,
+  TApiErrorKind,
+} from './types'

package/template/src/api/metadata/MetadataProvider.tsx

@@ -0,0 +1,37 @@
+import { EnumCatalogProvider } from '@/api/enums'
+import { GlobalParameterProvider } from '@/api/parameters'
+import type { IMetadataProviderProps } from './types'
+
+/**
+ * 并行装配应用级枚举和参数目录。
+ *
+ * Provider 不渲染全局加载或错误占位，避免无关页面被单个元数据资源阻塞。
+ */
+export function MetadataProvider({
+  bIsEnumCatalogEnabled = true,
+  bIsGlobalParameterEnabled = true,
+  children: objChildren,
+  objEnumCatalogScope,
+  objEnumCatalogSource,
+  objGlobalParameterScope,
+  objGlobalParameterSource,
+  strLocale = 'zh-CN',
+}: IMetadataProviderProps) {
+  return (
+    <EnumCatalogProvider
+      bIsEnabled={bIsEnumCatalogEnabled}
+      objScope={objEnumCatalogScope}
+      objSource={objEnumCatalogSource}
+      strLocale={strLocale}
+    >
+      <GlobalParameterProvider
+        bIsEnabled={bIsGlobalParameterEnabled}
+        objScope={objGlobalParameterScope}
+        objSource={objGlobalParameterSource}
+        strLocale={strLocale}
+      >
+        {objChildren}
+      </GlobalParameterProvider>
+    </EnumCatalogProvider>
+  )
+}

package/template/src/api/metadata/index.ts

@@ -0,0 +1,2 @@
+export { MetadataProvider } from './MetadataProvider'
+export type { IMetadataProviderProps } from './types'

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

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react'
+import type {
+  IEnumCatalogScopeContext,
+  IEnumCatalogSource,
+  TEnumLocale,
+} from '@/api/enums/types'
+import type {
+  IGlobalParameterScopeContext,
+  IGlobalParameterSource,
+} from '@/api/parameters/types'
+
+/** 应用级元数据 Provider 的公共参数。 */
+export interface IMetadataProviderProps {
+  /** 是否允许加载枚举目录。 */
+  bIsEnumCatalogEnabled?: boolean
+  /** 是否允许加载全局参数目录。 */
+  bIsGlobalParameterEnabled?: boolean
+  /** 始终渲染的应用子树；元数据失败不会阻塞它。 */
+  children: ReactNode
+  /** 枚举目录的业务缓存作用域。 */
+  objEnumCatalogScope?: IEnumCatalogScopeContext
+  /** 枚举目录后端数据源。 */
+  objEnumCatalogSource?: IEnumCatalogSource
+  /** 全局参数目录的业务缓存作用域。 */
+  objGlobalParameterScope?: IGlobalParameterScopeContext
+  /** 全局参数目录后端数据源。 */
+  objGlobalParameterSource?: IGlobalParameterSource
+  /** 当前元数据语言，默认 `zh-CN`。 */
+  strLocale?: TEnumLocale
+}

package/template/src/api/parameters/GlobalParameterProvider.tsx

@@ -0,0 +1,210 @@
+import { createContext, useContext, useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import {
+  fnGetBooleanGlobalParameter,
+  fnGetGlobalParameter,
+  fnGetGlobalParameterKeys,
+  fnGetGlobalParameters,
+  fnGetGlobalParameterValue,
+  fnGetJsonGlobalParameter,
+  fnGetNumberGlobalParameter,
+  fnGetStringGlobalParameter,
+  fnHasGlobalParameterKey,
+} from './access'
+import { fnGlobalParameterQueryOptions } from './query'
+import { fnCreateGlobalParameterScope } from './scope'
+import type {
+  IGlobalParameter,
+  IGlobalParameterProviderProps,
+  IGlobalParameterSource,
+  IUseGlobalParameterCatalogResult,
+  IUseGlobalParameterResult,
+  TGlobalParameterLocale,
+} from './types'
+
+interface IGlobalParameterContextValue {
+  bIsEnabled: boolean
+  objScope: IGlobalParameterProviderProps['objScope']
+  objSource?: IGlobalParameterSource
+  strLocale: TGlobalParameterLocale
+}
+
+interface IGlobalParameterState {
+  objCatalogResult: IUseGlobalParameterCatalogResult
+  objParameter: IGlobalParameter | null
+}
+
+const objUnavailableSource: IGlobalParameterSource = {
+  fnLoadCatalog: () =>
+    Promise.reject(new Error('尚未配置全局参数后端数据源。')),
+}
+const fnGlobalParameterContext =
+  createContext<IGlobalParameterContextValue | null>(null)
+
+export function GlobalParameterProvider({
+  bIsEnabled = true,
+  children: objChildren,
+  objScope,
+  objSource,
+  strLocale = 'zh-CN',
+}: IGlobalParameterProviderProps) {
+  const objContextValue = useMemo(
+    () => ({ bIsEnabled, objScope, objSource, strLocale }),
+    [bIsEnabled, objScope, objSource, strLocale]
+  )
+
+  return (
+    <fnGlobalParameterContext.Provider value={objContextValue}>
+      <GlobalParameterPreload />
+      {objChildren}
+    </fnGlobalParameterContext.Provider>
+  )
+}
+
+function useGlobalParameterContext() {
+  const objContext = useContext(fnGlobalParameterContext)
+  if (!objContext) {
+    throw new Error(
+      'useGlobalParameter 必须在 GlobalParameterProvider 内使用。'
+    )
+  }
+  return objContext
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useGlobalParameterCatalog(): IUseGlobalParameterCatalogResult {
+  const {
+    bIsEnabled,
+    objScope: objScopeContext,
+    objSource,
+    strLocale,
+  } = useGlobalParameterContext()
+  const bIsConfigured = objSource !== undefined
+  const objScope = useMemo(
+    () => fnCreateGlobalParameterScope(strLocale, objScopeContext),
+    [objScopeContext, strLocale]
+  )
+  const objQuery = useQuery({
+    ...fnGlobalParameterQueryOptions(
+      objSource ?? objUnavailableSource,
+      objScope
+    ),
+    enabled: bIsConfigured && bIsEnabled,
+  })
+  const arrKeys = useMemo(
+    () => fnGetGlobalParameterKeys(objQuery.data),
+    [objQuery.data]
+  )
+  const arrParameters = useMemo(
+    () => fnGetGlobalParameters(objQuery.data),
+    [objQuery.data]
+  )
+
+  async function fnRefetch() {
+    if (!bIsConfigured || !bIsEnabled) return
+    await objQuery.refetch()
+  }
+
+  return {
+    arrKeys,
+    arrParameters,
+    bIsConfigured,
+    bIsEnabled,
+    bIsError: objQuery.isError,
+    bIsFetching: objQuery.isFetching,
+    bIsLoading: bIsConfigured && bIsEnabled && objQuery.isPending,
+    bIsRefetching: objQuery.isRefetching,
+    nUpdatedAt: objQuery.dataUpdatedAt,
+    objCatalog: objQuery.data,
+    objError: objQuery.error,
+    objScope,
+    strLocale,
+    strVersion: objQuery.data?.version ?? null,
+    fnGetBoolean: (strKey) =>
+      fnGetBooleanGlobalParameter(objQuery.data, strKey),
+    fnGetJson: (strKey) => fnGetJsonGlobalParameter(objQuery.data, strKey),
+    fnGetNumber: (strKey) => fnGetNumberGlobalParameter(objQuery.data, strKey),
+    fnGetParameter: (strKey) => fnGetGlobalParameter(objQuery.data, strKey),
+    fnGetString: (strKey) => fnGetStringGlobalParameter(objQuery.data, strKey),
+    fnGetValue: (strKey) => fnGetGlobalParameterValue(objQuery.data, strKey),
+    fnHasKey: (strKey) => fnHasGlobalParameterKey(objQuery.data, strKey),
+    fnRefetch,
+  }
+}
+
+function GlobalParameterPreload() {
+  useGlobalParameterCatalog()
+  return null
+}
+
+function useGlobalParameterState(strKey: string): IGlobalParameterState {
+  const objCatalogResult = useGlobalParameterCatalog()
+  return {
+    objCatalogResult,
+    objParameter: fnGetGlobalParameter(objCatalogResult.objCatalog, strKey),
+  }
+}
+
+function fnCreateGlobalParameterResult<TValue>(
+  { objCatalogResult, objParameter }: IGlobalParameterState,
+  objValue: TValue | undefined
+): IUseGlobalParameterResult<TValue> {
+  return {
+    bIsConfigured: objCatalogResult.bIsConfigured,
+    bIsEnabled: objCatalogResult.bIsEnabled,
+    bIsError: objCatalogResult.bIsError,
+    bIsFetching: objCatalogResult.bIsFetching,
+    bIsLoading: objCatalogResult.bIsLoading,
+    bIsMissing:
+      objCatalogResult.objCatalog !== undefined && objParameter === null,
+    objError: objCatalogResult.objError,
+    objParameter,
+    objScope: objCatalogResult.objScope,
+    strType: objParameter?.strType ?? null,
+    strVersion: objCatalogResult.strVersion,
+    value: objValue,
+    fnRefetch: objCatalogResult.fnRefetch,
+  }
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useGlobalParameter(strKey: string) {
+  const objState = useGlobalParameterState(strKey)
+  return fnCreateGlobalParameterResult(objState, objState.objParameter?.value)
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useBooleanGlobalParameter(strKey: string) {
+  const objState = useGlobalParameterState(strKey)
+  return fnCreateGlobalParameterResult(
+    objState,
+    fnGetBooleanGlobalParameter(objState.objCatalogResult.objCatalog, strKey)
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useJsonGlobalParameter(strKey: string) {
+  const objState = useGlobalParameterState(strKey)
+  return fnCreateGlobalParameterResult(
+    objState,
+    fnGetJsonGlobalParameter(objState.objCatalogResult.objCatalog, strKey)
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useNumberGlobalParameter(strKey: string) {
+  const objState = useGlobalParameterState(strKey)
+  return fnCreateGlobalParameterResult(
+    objState,
+    fnGetNumberGlobalParameter(objState.objCatalogResult.objCatalog, strKey)
+  )
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useStringGlobalParameter(strKey: string) {
+  const objState = useGlobalParameterState(strKey)
+  return fnCreateGlobalParameterResult(
+    objState,
+    fnGetStringGlobalParameter(objState.objCatalogResult.objCatalog, strKey)
+  )
+}

package/template/src/api/parameters/access.ts

@@ -0,0 +1,117 @@
+import { GlobalParameterError } from './errors'
+import type {
+  IGlobalParameter,
+  IGlobalParameterCatalog,
+  TGlobalParameterJsonValue,
+  TGlobalParameterType,
+  TGlobalParameterValue,
+} from './types'
+
+const arrEmptyKeys: readonly string[] = Object.freeze([])
+const arrEmptyParameters: readonly IGlobalParameter[] = Object.freeze([])
+
+/** 获取完整目录中按字典序排列的所有参数 Key。 */
+export function fnGetGlobalParameterKeys(
+  objCatalog: IGlobalParameterCatalog | undefined
+): readonly string[] {
+  if (!objCatalog) return arrEmptyKeys
+  return Object.freeze([...objCatalog.parameters.keys()].sort())
+}
+
+/** 获取完整目录中按 Key 排列的所有参数。 */
+export function fnGetGlobalParameters(
+  objCatalog: IGlobalParameterCatalog | undefined
+): readonly IGlobalParameter[] {
+  if (!objCatalog) return arrEmptyParameters
+  return Object.freeze(
+    fnGetGlobalParameterKeys(objCatalog).flatMap((strKey) => {
+      const objParameter = objCatalog.parameters.get(strKey)
+      return objParameter ? [objParameter] : []
+    })
+  )
+}
+
+/** 判断完整目录中是否存在指定参数 Key。 */
+export function fnHasGlobalParameterKey(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+) {
+  return objCatalog?.parameters.has(strKey) ?? false
+}
+
+/** 根据 Key 读取完整参数，不存在时返回 `null`。 */
+export function fnGetGlobalParameter(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+) {
+  return objCatalog?.parameters.get(strKey) ?? null
+}
+
+/** 根据 Key 读取全局参数值。 */
+export function fnGetGlobalParameterValue(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+): TGlobalParameterValue | undefined {
+  return fnGetGlobalParameter(objCatalog, strKey)?.value
+}
+
+function fnRequireGlobalParameterType(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string,
+  strExpectedType: TGlobalParameterType
+) {
+  const objParameter = fnGetGlobalParameter(objCatalog, strKey)
+  if (!objParameter) return undefined
+  if (objParameter.strType !== strExpectedType) {
+    throw new GlobalParameterError(
+      'TYPE_MISMATCH',
+      `全局参数 ${strKey} 声明为 ${objParameter.strType}，调用方要求 ${strExpectedType}。`,
+      strKey
+    )
+  }
+  return objParameter.value
+}
+
+/** 根据 Key 读取布尔值；声明类型不一致时立即失败。 */
+export function fnGetBooleanGlobalParameter(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+) {
+  const objValue = fnRequireGlobalParameterType(objCatalog, strKey, 'boolean')
+  return typeof objValue === 'boolean' ? objValue : undefined
+}
+
+/** 根据 Key 读取有限数值；声明类型不一致时立即失败。 */
+export function fnGetNumberGlobalParameter(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+) {
+  const objValue = fnRequireGlobalParameterType(objCatalog, strKey, 'number')
+  return typeof objValue === 'number' ? objValue : undefined
+}
+
+/** 根据 Key 读取文本值；声明类型不一致时立即失败。 */
+export function fnGetStringGlobalParameter(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+) {
+  const objValue = fnRequireGlobalParameterType(objCatalog, strKey, 'string')
+  return typeof objValue === 'string' ? objValue : undefined
+}
+
+/** 根据 Key 读取 JSON 值；声明类型不一致时立即失败。 */
+export function fnGetJsonGlobalParameter(
+  objCatalog: IGlobalParameterCatalog | undefined,
+  strKey: string
+):
+  | null
+  | readonly TGlobalParameterJsonValue[]
+  | { readonly [strKey: string]: TGlobalParameterJsonValue }
+  | undefined {
+  const objValue = fnRequireGlobalParameterType(objCatalog, strKey, 'json')
+  return objValue === null ||
+    Array.isArray(objValue) ||
+    typeof objValue === 'object'
+    ? objValue
+    : undefined
+}