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

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

@@ -0,0 +1,170 @@
+import { GlobalParameterError } from './errors'
+import type {
+  IGlobalParameter,
+  IGlobalParameterCatalog,
+  IGlobalParameterCatalogPayload,
+  IGlobalParameterPayload,
+  IGlobalParameterRequestContext,
+  IGlobalParameterSource,
+  TGlobalParameterJsonValue,
+  TGlobalParameterLocale,
+  TGlobalParameterRequest,
+  TGlobalParameterType,
+  TGlobalParameterValue,
+} from './types'
+
+function fnIsGlobalParameterLocale(
+  strLocale: string
+): strLocale is TGlobalParameterLocale {
+  return strLocale === 'en-US' || strLocale === 'zh-CN'
+}
+
+function fnIsJsonValue(objValue: TGlobalParameterValue): boolean {
+  if (objValue === null) return true
+  if (typeof objValue === 'number') return Number.isFinite(objValue)
+  if (typeof objValue === 'boolean' || typeof objValue === 'string') return true
+  if (Array.isArray(objValue)) return objValue.every(fnIsJsonValue)
+  if (typeof objValue !== 'object') return false
+  return Object.values(objValue).every(fnIsJsonValue)
+}
+
+function fnFreezeJsonValue(
+  objValue: TGlobalParameterJsonValue
+): TGlobalParameterJsonValue {
+  if (Array.isArray(objValue)) {
+    return Object.freeze(objValue.map(fnFreezeJsonValue))
+  }
+  if (objValue && typeof objValue === 'object') {
+    return Object.freeze(
+      Object.fromEntries(
+        Object.entries(objValue).map(([strKey, objItem]) => [
+          strKey,
+          fnFreezeJsonValue(objItem),
+        ])
+      )
+    )
+  }
+  return objValue
+}
+
+function fnIsGlobalParameterType(
+  strType: string
+): strType is TGlobalParameterType {
+  return (
+    strType === 'boolean' ||
+    strType === 'json' ||
+    strType === 'number' ||
+    strType === 'string'
+  )
+}
+
+function fnDoesValueMatchType(
+  objValue: TGlobalParameterValue,
+  strType: TGlobalParameterType
+) {
+  if (strType === 'boolean') return typeof objValue === 'boolean'
+  if (strType === 'number') {
+    return typeof objValue === 'number' && Number.isFinite(objValue)
+  }
+  if (strType === 'string') return typeof objValue === 'string'
+  return (
+    objValue === null ||
+    Array.isArray(objValue) ||
+    (typeof objValue === 'object' && fnIsJsonValue(objValue))
+  )
+}
+
+function fnNormalizeGlobalParameter(
+  strKey: string,
+  objPayload: IGlobalParameterPayload
+): IGlobalParameter {
+  if (
+    !strKey.trim() ||
+    !objPayload ||
+    typeof objPayload !== 'object' ||
+    typeof objPayload.type !== 'string' ||
+    !fnIsGlobalParameterType(objPayload.type) ||
+    !Object.hasOwn(objPayload, 'value') ||
+    objPayload.value === undefined ||
+    !fnIsJsonValue(objPayload.value) ||
+    !fnDoesValueMatchType(objPayload.value, objPayload.type) ||
+    (objPayload.description !== undefined &&
+      typeof objPayload.description !== 'string')
+  ) {
+    throw new GlobalParameterError(
+      'INVALID_PARAMETER',
+      `全局参数 ${strKey || '<empty>'} 的类型或值无效。`,
+      strKey || undefined
+    )
+  }
+
+  return Object.freeze({
+    description: objPayload.description,
+    strKey,
+    strType: objPayload.type,
+    value: fnFreezeJsonValue(objPayload.value),
+  })
+}
+
+function fnNormalizeGlobalParameterCatalog(
+  objPayload: IGlobalParameterCatalogPayload | undefined
+): IGlobalParameterCatalog {
+  if (
+    !objPayload?.parameters ||
+    typeof objPayload.parameters !== 'object' ||
+    Array.isArray(objPayload.parameters) ||
+    typeof objPayload.locale !== 'string' ||
+    !fnIsGlobalParameterLocale(objPayload.locale) ||
+    typeof objPayload.version !== 'string' ||
+    !objPayload.version.trim()
+  ) {
+    throw new GlobalParameterError(
+      'INVALID_RESPONSE',
+      '全局参数接口未返回有效目录。'
+    )
+  }
+
+  const objParameters = new Map<string, IGlobalParameter>()
+  Object.entries(objPayload.parameters).forEach(([strKey, objParameter]) => {
+    if (!objParameter) {
+      throw new GlobalParameterError(
+        'INVALID_PARAMETER',
+        `全局参数 ${strKey || '<empty>'} 缺少参数内容。`,
+        strKey || undefined
+      )
+    }
+    objParameters.set(strKey, fnNormalizeGlobalParameter(strKey, objParameter))
+  })
+
+  return Object.freeze({
+    locale: objPayload.locale,
+    parameters: objParameters,
+    version: objPayload.version,
+  })
+}
+
+/** 将 Swagger 生成客户端的请求函数适配为全局参数数据源。 */
+export function fnCreateGlobalParameterSource(
+  fnRequest: TGlobalParameterRequest
+): IGlobalParameterSource {
+  return Object.freeze({
+    fnLoadCatalog: async (objContext: IGlobalParameterRequestContext) => {
+      if (objContext.objScope.strLocale !== objContext.strLocale) {
+        throw new GlobalParameterError(
+          'INVALID_SCOPE',
+          `全局参数作用域语言 ${objContext.objScope.strLocale}，与请求语言 ${objContext.strLocale} 不一致。`
+        )
+      }
+      const objCatalog = fnNormalizeGlobalParameterCatalog(
+        await fnRequest(objContext)
+      )
+      if (objCatalog.locale !== objContext.strLocale) {
+        throw new GlobalParameterError(
+          'LOCALE_MISMATCH',
+          `全局参数返回语言 ${objCatalog.locale}，与请求语言 ${objContext.strLocale} 不一致。`
+        )
+      }
+      return objCatalog
+    },
+  })
+}

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

@@ -0,0 +1,21 @@
+import type { TGlobalParameterErrorCode } from './types'
+
+/** 全局参数目录校验、作用域和消费契约错误。 */
+export class GlobalParameterError extends Error {
+  /** 可供日志、监控和调用方分支处理的稳定错误码。 */
+  readonly strCode: TGlobalParameterErrorCode
+
+  /** 错误对应的参数 Key；目录级错误时为空。 */
+  readonly strParameterKey?: string
+
+  constructor(
+    strCode: TGlobalParameterErrorCode,
+    strMessage: string,
+    strParameterKey?: string
+  ) {
+    super(strMessage)
+    this.name = 'GlobalParameterError'
+    this.strCode = strCode
+    this.strParameterKey = strParameterKey
+  }
+}

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

@@ -0,0 +1,53 @@
+export {
+  GlobalParameterProvider,
+  useBooleanGlobalParameter,
+  useGlobalParameter,
+  useGlobalParameterCatalog,
+  useJsonGlobalParameter,
+  useNumberGlobalParameter,
+  useStringGlobalParameter,
+} from './GlobalParameterProvider'
+export {
+  fnGetBooleanGlobalParameter,
+  fnGetGlobalParameter,
+  fnGetGlobalParameterKeys,
+  fnGetGlobalParameters,
+  fnGetGlobalParameterValue,
+  fnGetJsonGlobalParameter,
+  fnGetNumberGlobalParameter,
+  fnGetStringGlobalParameter,
+  fnHasGlobalParameterKey,
+} from './access'
+export { fnCreateGlobalParameterSource } from './catalog'
+export { GlobalParameterError } from './errors'
+export {
+  fnEnsureGlobalParameters,
+  fnGetCachedGlobalParameters,
+  fnGlobalParameterQueryKey,
+  fnGlobalParameterQueryOptions,
+  fnInvalidateGlobalParameters,
+} from './query'
+export {
+  fnCreateGlobalParameterScope,
+  fnResolveGlobalParameterScope,
+} from './scope'
+export type {
+  IGlobalParameter,
+  IGlobalParameterCatalog,
+  IGlobalParameterCatalogPayload,
+  IGlobalParameterPayload,
+  IGlobalParameterProviderProps,
+  IGlobalParameterRequestContext,
+  IGlobalParameterScope,
+  IGlobalParameterScopeContext,
+  IGlobalParameterSource,
+  IUseGlobalParameterCatalogResult,
+  IUseGlobalParameterResult,
+  TGlobalParameterErrorCode,
+  TGlobalParameterJsonValue,
+  TGlobalParameterLocale,
+  TGlobalParameterRequest,
+  TGlobalParameterScopeInput,
+  TGlobalParameterType,
+  TGlobalParameterValue,
+} from './types'

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

@@ -0,0 +1,84 @@
+import { queryOptions, type QueryClient } from '@tanstack/react-query'
+import { fnResolveGlobalParameterScope } from './scope'
+import type {
+  IGlobalParameterCatalog,
+  IGlobalParameterScope,
+  IGlobalParameterSource,
+  TGlobalParameterScopeInput,
+} from './types'
+
+const arrGlobalParameterQueryRoot: readonly ['globalParameters'] = [
+  'globalParameters',
+]
+const nGlobalParameterStaleTimeMs = 5 * 60_000
+const nGlobalParameterGcTimeMs = 30 * 60_000
+
+/** 返回一个作用域对应的稳定全局参数查询 Key。 */
+export function fnGlobalParameterQueryKey(
+  objScopeInput: TGlobalParameterScopeInput
+): readonly ['globalParameters', IGlobalParameterScope] {
+  return ['globalParameters', fnResolveGlobalParameterScope(objScopeInput)]
+}
+
+/** 创建完整全局参数目录的 QueryClient 查询配置。 */
+export function fnGlobalParameterQueryOptions(
+  objSource: IGlobalParameterSource,
+  objScopeInput: TGlobalParameterScopeInput
+) {
+  const objScope = fnResolveGlobalParameterScope(objScopeInput)
+  return queryOptions({
+    queryKey: fnGlobalParameterQueryKey(objScope),
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnLoadCatalog({
+        objScope,
+        objSignal,
+        strLocale: objScope.strLocale,
+      }),
+    staleTime: nGlobalParameterStaleTimeMs,
+    gcTime: nGlobalParameterGcTimeMs,
+  })
+}
+
+/** 在路由 Loader 或应用启动阶段确保指定作用域参数已加载。 */
+export function fnEnsureGlobalParameters(
+  objQueryClient: QueryClient,
+  objSource: IGlobalParameterSource,
+  objScopeInput: TGlobalParameterScopeInput = 'zh-CN'
+) {
+  return objQueryClient.ensureQueryData(
+    fnGlobalParameterQueryOptions(objSource, objScopeInput)
+  )
+}
+
+/** 从 QueryClient 同步读取指定作用域已缓存的完整参数目录。 */
+export function fnGetCachedGlobalParameters(
+  objQueryClient: QueryClient,
+  objScopeInput: TGlobalParameterScopeInput = 'zh-CN'
+): IGlobalParameterCatalog | undefined {
+  return objQueryClient.getQueryData<IGlobalParameterCatalog>(
+    fnGlobalParameterQueryKey(objScopeInput)
+  )
+}
+
+/** 参数维护完成后统一失效一个语言、精确作用域或全部参数缓存。 */
+export function fnInvalidateGlobalParameters(
+  objQueryClient: QueryClient,
+  objScopeInput?: TGlobalParameterScopeInput
+) {
+  if (!objScopeInput) {
+    return objQueryClient.invalidateQueries({
+      queryKey: arrGlobalParameterQueryRoot,
+    })
+  }
+
+  if (typeof objScopeInput === 'string') {
+    return objQueryClient.invalidateQueries({
+      queryKey: [arrGlobalParameterQueryRoot[0], { strLocale: objScopeInput }],
+    })
+  }
+
+  return objQueryClient.invalidateQueries({
+    exact: true,
+    queryKey: fnGlobalParameterQueryKey(objScopeInput),
+  })
+}

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

@@ -0,0 +1,58 @@
+import { GlobalParameterError } from './errors'
+import type {
+  IGlobalParameterScope,
+  IGlobalParameterScopeContext,
+  TGlobalParameterLocale,
+  TGlobalParameterScopeInput,
+} from './types'
+
+function fnNormalizeScopeValue(strValue: string | undefined) {
+  const strNormalizedValue = strValue?.trim()
+  return strNormalizedValue || undefined
+}
+
+/** 创建不含凭据、可安全用于 Query Key 的全局参数作用域。 */
+export function fnCreateGlobalParameterScope(
+  strLocale: TGlobalParameterLocale,
+  objContext: IGlobalParameterScopeContext = {}
+): IGlobalParameterScope {
+  if (!strLocale) {
+    throw new GlobalParameterError(
+      'INVALID_SCOPE',
+      '全局参数作用域必须包含语言。'
+    )
+  }
+  if (
+    objContext.nSessionGeneration !== undefined &&
+    (!Number.isInteger(objContext.nSessionGeneration) ||
+      objContext.nSessionGeneration < 0)
+  ) {
+    throw new GlobalParameterError(
+      'INVALID_SCOPE',
+      '全局参数作用域的会话版本必须是非负整数。'
+    )
+  }
+
+  const strNamespace = fnNormalizeScopeValue(objContext.strNamespace)
+  const strTenantId = fnNormalizeScopeValue(objContext.strTenantId)
+  const strWorkspaceId = fnNormalizeScopeValue(objContext.strWorkspaceId)
+
+  return Object.freeze({
+    ...(objContext.nSessionGeneration !== undefined
+      ? { nSessionGeneration: objContext.nSessionGeneration }
+      : {}),
+    ...(strNamespace ? { strNamespace } : {}),
+    ...(strTenantId ? { strTenantId } : {}),
+    ...(strWorkspaceId ? { strWorkspaceId } : {}),
+    strLocale,
+  })
+}
+
+/** 将兼容的语言或完整作用域输入标准化为稳定作用域。 */
+export function fnResolveGlobalParameterScope(
+  objScope: TGlobalParameterScopeInput
+): IGlobalParameterScope {
+  return typeof objScope === 'string'
+    ? fnCreateGlobalParameterScope(objScope)
+    : fnCreateGlobalParameterScope(objScope.strLocale, objScope)
+}

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

@@ -0,0 +1,214 @@
+import type { ReactNode } from 'react'
+import type { TAppLocale } from '@/locale/types'
+
+/** 全局参数目录支持的语言。 */
+export type TGlobalParameterLocale = TAppLocale
+
+/** 全局参数允许声明的稳定值类型。 */
+export type TGlobalParameterType = 'boolean' | 'json' | 'number' | 'string'
+
+/** JSON 参数允许携带的递归只读值。 */
+export type TGlobalParameterJsonValue =
+  | boolean
+  | number
+  | string
+  | null
+  | readonly TGlobalParameterJsonValue[]
+  | { readonly [strKey: string]: TGlobalParameterJsonValue }
+
+/** 全局参数经过校验后允许交给 Feature 的值。 */
+export type TGlobalParameterValue = TGlobalParameterJsonValue
+
+/** 全局参数校验和作用域错误的稳定分类。 */
+export type TGlobalParameterErrorCode =
+  | 'INVALID_PARAMETER'
+  | 'INVALID_RESPONSE'
+  | 'INVALID_SCOPE'
+  | 'LOCALE_MISMATCH'
+  | 'TYPE_MISMATCH'
+
+/** 除语言外用于隔离全局参数缓存的业务作用域。 */
+export interface IGlobalParameterScopeContext {
+  /** 登录、退出或授权上下文变化时递增的会话版本。 */
+  readonly nSessionGeneration?: number
+  /** 后端参数命名空间。 */
+  readonly strNamespace?: string
+  /** 当前租户标识。 */
+  readonly strTenantId?: string
+  /** 当前组织、项目或工作空间标识。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 一个全局参数请求与缓存的完整身份。 */
+export interface IGlobalParameterScope extends IGlobalParameterScopeContext {
+  /** 参数目录使用的语言。 */
+  readonly strLocale: TGlobalParameterLocale
+}
+
+/** 查询 API 接受完整作用域，也兼容仅传语言。 */
+export type TGlobalParameterScopeInput =
+  | IGlobalParameterScope
+  | TGlobalParameterLocale
+
+/** 后端全局参数目录中的单个原始参数。 */
+export interface IGlobalParameterPayload {
+  /** 可选的参数用途说明。 */
+  description?: string
+  /** 后端声明的值类型。 */
+  type?: string
+  /** 参数值；必须与 `type` 一致。 */
+  value?: TGlobalParameterValue
+}
+
+/** 后端统一全局参数接口的原始目录。 */
+export interface IGlobalParameterCatalogPayload {
+  /** 本次响应的语言。 */
+  locale?: string
+  /** 以稳定参数 Key 为索引的参数集合。 */
+  parameters?: Readonly<Record<string, IGlobalParameterPayload | undefined>>
+  /** 后端目录版本，用于诊断与刷新确认。 */
+  version?: string
+}
+
+/** 经过运行时校验、可安全交给 Feature 使用的全局参数。 */
+export interface IGlobalParameter {
+  /** 可选的参数用途说明。 */
+  readonly description?: string
+  /** 跨环境稳定的参数 Key。 */
+  readonly strKey: string
+  /** 参数声明类型。 */
+  readonly strType: TGlobalParameterType
+  /** 已校验并深度冻结的参数值。 */
+  readonly value: TGlobalParameterValue
+}
+
+/** 单个作用域下已标准化的完整全局参数目录。 */
+export interface IGlobalParameterCatalog {
+  /** 已加载目录的语言。 */
+  readonly locale: TGlobalParameterLocale
+  /** 以稳定参数 Key 为索引的只读参数集合。 */
+  readonly parameters: ReadonlyMap<string, IGlobalParameter>
+  /** 后端返回的目录版本。 */
+  readonly version: string
+}
+
+/** 后端全局参数请求所需的运行时上下文。 */
+export interface IGlobalParameterRequestContext {
+  /** 本次请求与缓存使用的完整业务作用域。 */
+  readonly objScope: IGlobalParameterScope
+  /** QueryClient 取消或替换请求时触发的取消信号。 */
+  readonly objSignal: AbortSignal
+  /** 请求使用的语言。 */
+  readonly strLocale: TGlobalParameterLocale
+}
+
+/** 由 Swagger 生成客户端实现的后端全局参数请求函数。 */
+export type TGlobalParameterRequest = (
+  objContext: IGlobalParameterRequestContext
+) => Promise<IGlobalParameterCatalogPayload | undefined>
+
+/** 全局参数系统依赖的后端数据源契约。 */
+export interface IGlobalParameterSource {
+  /** 加载并返回一个作用域下的完整、已校验目录。 */
+  fnLoadCatalog: (
+    objContext: IGlobalParameterRequestContext
+  ) => Promise<IGlobalParameterCatalog>
+}
+
+/** 全局参数 Provider 的公共参数。 */
+export interface IGlobalParameterProviderProps {
+  /** 是否允许发起目录请求，默认启用。 */
+  bIsEnabled?: boolean
+  /** 使用全局参数能力的应用子树。 */
+  children: ReactNode
+  /** 租户、工作空间等非语言缓存作用域。 */
+  objScope?: IGlobalParameterScopeContext
+  /** 由 Swagger 生成客户端适配的后端数据源；未配置时不会发起请求。 */
+  objSource?: IGlobalParameterSource
+  /** 当前参数目录语言，默认 `zh-CN`。 */
+  strLocale?: TGlobalParameterLocale
+}
+
+/** 完整参数目录查询暴露给预加载与诊断界面的状态。 */
+export interface IUseGlobalParameterCatalogResult {
+  /** 完整目录中按 Key 排列的参数。 */
+  arrParameters: readonly IGlobalParameter[]
+  /** 完整目录中按字典序排列的参数 Key。 */
+  arrKeys: readonly string[]
+  /** 是否已经配置后端参数数据源。 */
+  bIsConfigured: boolean
+  /** 当前是否允许发起目录请求。 */
+  bIsEnabled: boolean
+  /** 请求是否失败。 */
+  bIsError: boolean
+  /** 包含首次请求和后台刷新的所有请求状态。 */
+  bIsFetching: boolean
+  /** 首次目录请求是否仍在进行。 */
+  bIsLoading: boolean
+  /** 已有数据时是否正在后台刷新。 */
+  bIsRefetching: boolean
+  /** 最近一次成功更新的时间戳，尚未成功时为 `0`。 */
+  nUpdatedAt: number
+  /** 已加载目录；尚未成功时为空。 */
+  objCatalog: IGlobalParameterCatalog | undefined
+  /** 请求失败时的标准 Error。 */
+  objError: Error | null
+  /** 当前请求与缓存使用的完整业务作用域。 */
+  objScope: IGlobalParameterScope
+  /** 当前请求语言。 */
+  strLocale: TGlobalParameterLocale
+  /** 后端目录版本；尚未加载时为空。 */
+  strVersion: string | null
+  /** 根据 Key 读取完整参数。 */
+  fnGetParameter: (strKey: string) => IGlobalParameter | null
+  /** 根据 Key 读取已校验值。 */
+  fnGetValue: (strKey: string) => TGlobalParameterValue | undefined
+  /** 根据 Key 读取布尔值；声明类型不一致时立即失败。 */
+  fnGetBoolean: (strKey: string) => boolean | undefined
+  /** 根据 Key 读取 JSON 值；声明类型不一致时立即失败。 */
+  fnGetJson: (
+    strKey: string
+  ) =>
+    | null
+    | readonly TGlobalParameterJsonValue[]
+    | { readonly [strKey: string]: TGlobalParameterJsonValue }
+    | undefined
+  /** 根据 Key 读取有限数值；声明类型不一致时立即失败。 */
+  fnGetNumber: (strKey: string) => number | undefined
+  /** 判断完整目录中是否存在指定参数 Key。 */
+  fnHasKey: (strKey: string) => boolean
+  /** 根据 Key 读取文本值；声明类型不一致时立即失败。 */
+  fnGetString: (strKey: string) => string | undefined
+  /** 重新请求当前作用域的参数目录。 */
+  fnRefetch: () => Promise<void>
+}
+
+/** Feature 按参数 Key 消费时获得的标准结果。 */
+export interface IUseGlobalParameterResult<TValue = TGlobalParameterValue> {
+  /** 是否已经配置后端参数数据源。 */
+  bIsConfigured: boolean
+  /** 当前是否允许发起目录请求。 */
+  bIsEnabled: boolean
+  /** 目录请求是否失败。 */
+  bIsError: boolean
+  /** 包含首次请求和后台刷新的所有请求状态。 */
+  bIsFetching: boolean
+  /** 目录已加载但没有找到当前参数 Key。 */
+  bIsMissing: boolean
+  /** 首次目录请求是否仍在进行。 */
+  bIsLoading: boolean
+  /** 请求失败时的标准 Error。 */
+  objError: Error | null
+  /** 当前 Key 对应的完整参数，不存在时为空。 */
+  objParameter: IGlobalParameter | null
+  /** 当前请求与缓存使用的完整业务作用域。 */
+  objScope: IGlobalParameterScope
+  /** 参数声明类型；尚未加载或不存在时为空。 */
+  strType: TGlobalParameterType | null
+  /** 后端目录版本；尚未加载时为空。 */
+  strVersion: string | null
+  /** 当前 Key 对应的已校验值。 */
+  value: TValue | undefined
+  /** 重新请求当前作用域的参数目录。 */
+  fnRefetch: () => Promise<void>
+}

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

@@ -0,0 +1,13 @@
+export { fnCreateAppQueryKeys } from './keys'
+export {
+  fnApplyOptimisticQueryUpdate,
+  fnCreateAppMutationScope,
+  fnRollbackOptimisticQueryUpdate,
+} from './mutation'
+export { useAppQueryScope } from './react'
+export { fnCreateAppQueryScope } from './scope'
+export type {
+  IAppQueryRollbackSnapshot,
+  IAppQueryScope,
+  TAppQueryParameters,
+} from './types'