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

package/template/src/api/enums/EnumCatalogProvider.tsx

@@ -0,0 +1,169 @@
+import { createContext, useContext, useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { EnumDictionary } from './EnumDictionary'
+import {
+  fnGetEnumEntries,
+  fnGetEnumKeys,
+  fnGetEnumLabel,
+  fnGetEnumLabels,
+  fnGetEnumOptions,
+  fnGetEnumOptionsByValues,
+  fnGetEnumValue,
+  fnGetEnumValues,
+  fnHasEnumKey,
+} from './access'
+import { fnEnumCatalogQueryOptions } from './query'
+import { fnCreateEnumCatalogScope } from './scope'
+import type {
+  IEnumCatalogProviderProps,
+  IEnumCatalogSource,
+  IUseEnumCatalogResult,
+  IUseEnumResult,
+  TEnumLocale,
+} from './types'
+
+interface IEnumCatalogContextValue {
+  bIsEnabled: boolean
+  objScope: IEnumCatalogProviderProps['objScope']
+  objSource?: IEnumCatalogSource
+  strLocale: TEnumLocale
+}
+
+const objEmptyDictionary = new EnumDictionary([])
+const objUnavailableSource: IEnumCatalogSource = {
+  fnLoadCatalog: () =>
+    Promise.reject(new Error('尚未配置全局枚举后端数据源。')),
+}
+const fnEnumCatalogContext = createContext<IEnumCatalogContextValue | null>(
+  null
+)
+
+export function EnumCatalogProvider({
+  bIsEnabled = true,
+  children: objChildren,
+  objScope,
+  objSource,
+  strLocale = 'zh-CN',
+}: IEnumCatalogProviderProps) {
+  const objContextValue = useMemo(
+    () => ({ bIsEnabled, objScope, objSource, strLocale }),
+    [bIsEnabled, objScope, objSource, strLocale]
+  )
+
+  return (
+    <fnEnumCatalogContext.Provider value={objContextValue}>
+      <EnumCatalogPreload />
+      {objChildren}
+    </fnEnumCatalogContext.Provider>
+  )
+}
+
+function useEnumCatalogContext() {
+  const objContext = useContext(fnEnumCatalogContext)
+  if (!objContext) {
+    throw new Error('useEnum 必须在 EnumCatalogProvider 内使用。')
+  }
+  return objContext
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useEnumCatalog(): IUseEnumCatalogResult {
+  const {
+    bIsEnabled,
+    objScope: objScopeContext,
+    objSource,
+    strLocale,
+  } = useEnumCatalogContext()
+  const bIsConfigured = objSource !== undefined
+  const objScope = useMemo(
+    () => fnCreateEnumCatalogScope(strLocale, objScopeContext),
+    [objScopeContext, strLocale]
+  )
+  const objQuery = useQuery({
+    ...fnEnumCatalogQueryOptions(objSource ?? objUnavailableSource, objScope),
+    enabled: bIsConfigured && bIsEnabled,
+  })
+  const arrKeys = useMemo(() => fnGetEnumKeys(objQuery.data), [objQuery.data])
+  const arrEntries = useMemo(
+    () => fnGetEnumEntries(objQuery.data),
+    [objQuery.data]
+  )
+
+  async function fnRefetch() {
+    if (!bIsConfigured || !bIsEnabled) return
+    await objQuery.refetch()
+  }
+
+  return {
+    arrEntries,
+    arrKeys,
+    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,
+    fnGetLabel: (strEnumKey, objValue) =>
+      fnGetEnumLabel(objQuery.data, strEnumKey, objValue),
+    fnGetLabels: (strEnumKey, arrValues) =>
+      fnGetEnumLabels(objQuery.data, strEnumKey, arrValues),
+    fnGetOptions: (strEnumKey) => fnGetEnumOptions(objQuery.data, strEnumKey),
+    fnGetOptionsByValues: (strEnumKey, arrValues) =>
+      fnGetEnumOptionsByValues(objQuery.data, strEnumKey, arrValues),
+    fnGetValue: (strEnumKey, strLabel) =>
+      fnGetEnumValue(objQuery.data, strEnumKey, strLabel),
+    fnGetValues: (strEnumKey) => fnGetEnumValues(objQuery.data, strEnumKey),
+    fnHasKey: (strEnumKey) => fnHasEnumKey(objQuery.data, strEnumKey),
+    fnRefetch,
+  }
+}
+
+function EnumCatalogPreload() {
+  useEnumCatalog()
+  return null
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useEnum(strEnumKey: string): IUseEnumResult {
+  const objCatalogResult = useEnumCatalog()
+  const arrOptions =
+    objCatalogResult.objCatalog?.enums.get(strEnumKey) ??
+    objEmptyDictionary.arrOptions
+  const objDictionary = useMemo(
+    () =>
+      arrOptions.length ? new EnumDictionary(arrOptions) : objEmptyDictionary,
+    [arrOptions]
+  )
+
+  return {
+    arrOptions: objDictionary.arrOptions,
+    bIsConfigured: objCatalogResult.bIsConfigured,
+    bIsEnabled: objCatalogResult.bIsEnabled,
+    bIsError: objCatalogResult.bIsError,
+    bIsFetching: objCatalogResult.bIsFetching,
+    bIsLoading: objCatalogResult.bIsLoading,
+    bIsRefetching: objCatalogResult.bIsRefetching,
+    bIsMissing:
+      objCatalogResult.objCatalog !== undefined &&
+      !objCatalogResult.objCatalog.enums.has(strEnumKey),
+    nUpdatedAt: objCatalogResult.nUpdatedAt,
+    objError: objCatalogResult.objError,
+    objScope: objCatalogResult.objScope,
+    strLocale: objCatalogResult.strLocale,
+    strVersion: objCatalogResult.objCatalog?.version ?? null,
+    fnGetLabel: (objValue) => objDictionary.fnGetLabel(objValue),
+    fnGetLabels: (arrValues) => objDictionary.fnGetLabels(arrValues),
+    fnGetOption: (objValue) => objDictionary.fnGetOption(objValue),
+    fnGetOptionsByValues: (arrValues) =>
+      objDictionary.fnGetOptionsByValues(arrValues),
+    fnGetValue: (strLabel) => objDictionary.fnGetValue(strLabel),
+    fnHasValue: (objValue) => objDictionary.fnHasValue(objValue),
+    fnRefetch: objCatalogResult.fnRefetch,
+  }
+}

package/template/src/api/enums/EnumDictionary.ts

@@ -0,0 +1,55 @@
+import type { IEnumOption, TEnumValue } from './types'
+
+/** 为单个枚举提供排序、值查找和显示文本回退。 */
+export class EnumDictionary {
+  /** 已按后端顺序排序的只读选项。 */
+  readonly arrOptions: readonly IEnumOption[]
+
+  private readonly objOptionsByValue: ReadonlyMap<TEnumValue, IEnumOption>
+
+  constructor(arrOptions: readonly IEnumOption[]) {
+    this.arrOptions = Object.freeze(
+      arrOptions
+        .map((objOption) => Object.freeze({ ...objOption }))
+        .sort(
+          (objLeftOption, objRightOption) =>
+            objLeftOption.sortOrder - objRightOption.sortOrder
+        )
+    )
+    this.objOptionsByValue = new Map(
+      this.arrOptions.map((objOption) => [objOption.value, objOption])
+    )
+  }
+
+  fnGetOption(objValue: TEnumValue | null | undefined) {
+    if (objValue === null || objValue === undefined) return null
+    return this.objOptionsByValue.get(objValue) ?? null
+  }
+
+  fnGetLabel(objValue: TEnumValue | null | undefined) {
+    if (objValue === null || objValue === undefined) return '-'
+    return this.fnGetOption(objValue)?.label ?? String(objValue)
+  }
+
+  fnGetValue(strLabel: string) {
+    return this.arrOptions.find((objOption) => objOption.label === strLabel)
+      ?.value
+  }
+
+  fnGetLabels(arrValues: readonly TEnumValue[]) {
+    return Object.freeze(arrValues.map((objValue) => this.fnGetLabel(objValue)))
+  }
+
+  fnGetOptionsByValues(arrValues: readonly TEnumValue[]) {
+    return Object.freeze(
+      arrValues.flatMap((objValue) => {
+        const objOption = this.fnGetOption(objValue)
+        return objOption ? [objOption] : []
+      })
+    )
+  }
+
+  fnHasValue(objValue: TEnumValue | null | undefined) {
+    return this.fnGetOption(objValue) !== null
+  }
+}

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

@@ -0,0 +1,130 @@
+import type {
+  IEnumCatalog,
+  IEnumCatalogEntry,
+  IEnumOption,
+  TEnumValue,
+} from './types'
+
+const arrEmptyEntries: readonly IEnumCatalogEntry[] = Object.freeze([])
+const arrEmptyKeys: readonly string[] = Object.freeze([])
+const arrEmptyOptions: readonly IEnumOption[] = Object.freeze([])
+const arrEmptyValues: readonly TEnumValue[] = Object.freeze([])
+
+/** 获取完整目录中按字典序排列的所有枚举 Key。 */
+export function fnGetEnumKeys(
+  objCatalog: IEnumCatalog | undefined
+): readonly string[] {
+  if (!objCatalog) return arrEmptyKeys
+  return Object.freeze([...objCatalog.enums.keys()].sort())
+}
+
+/** 将完整目录按 Key 排序并展开为便于遍历的条目列表。 */
+export function fnGetEnumEntries(
+  objCatalog: IEnumCatalog | undefined
+): readonly IEnumCatalogEntry[] {
+  if (!objCatalog) return arrEmptyEntries
+  return Object.freeze(
+    fnGetEnumKeys(objCatalog).map((strKey) =>
+      Object.freeze({
+        arrOptions: objCatalog.enums.get(strKey) ?? arrEmptyOptions,
+        strKey,
+      })
+    )
+  )
+}
+
+/** 判断完整目录中是否存在指定枚举 Key。 */
+export function fnHasEnumKey(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string
+): boolean {
+  return objCatalog?.enums.has(strEnumKey) ?? false
+}
+
+/** 根据枚举 Key 获取已排序的完整选项。 */
+export function fnGetEnumOptions(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string
+): readonly IEnumOption[] {
+  return objCatalog?.enums.get(strEnumKey) ?? arrEmptyOptions
+}
+
+/** 根据枚举 Key 获取所有稳定值。 */
+export function fnGetEnumValues(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string
+): readonly TEnumValue[] {
+  const arrOptions = fnGetEnumOptions(objCatalog, strEnumKey)
+  if (!arrOptions.length) return arrEmptyValues
+  return Object.freeze(arrOptions.map((objOption) => objOption.value))
+}
+
+/** 根据枚举 Key 和稳定值读取完整选项。 */
+export function fnGetEnumOption(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string,
+  objValue: TEnumValue | null | undefined
+): IEnumOption | null {
+  if (objValue === null || objValue === undefined) return null
+  return (
+    fnGetEnumOptions(objCatalog, strEnumKey).find(
+      (objOption) => objOption.value === objValue
+    ) ?? null
+  )
+}
+
+/** 根据枚举 Key 和稳定值读取显示文本，未知值回退为原始字符串。 */
+export function fnGetEnumLabel(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string,
+  objValue: TEnumValue | null | undefined
+): string {
+  if (objValue === null || objValue === undefined) return '-'
+  return (
+    fnGetEnumOption(objCatalog, strEnumKey, objValue)?.label ?? String(objValue)
+  )
+}
+
+/** 根据枚举 Key 和显示文本反查稳定值。 */
+export function fnGetEnumValue(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string,
+  strLabel: string
+): TEnumValue | undefined {
+  return fnGetEnumOptions(objCatalog, strEnumKey).find(
+    (objOption) => objOption.label === strLabel
+  )?.value
+}
+
+/** 批量读取显示文本，保持输入顺序和重复项。 */
+export function fnGetEnumLabels(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string,
+  arrValues: readonly TEnumValue[]
+): readonly string[] {
+  return Object.freeze(
+    arrValues.map((objValue) =>
+      fnGetEnumLabel(objCatalog, strEnumKey, objValue)
+    )
+  )
+}
+
+/** 批量读取已存在的选项，保持输入顺序并忽略未知值。 */
+export function fnGetEnumOptionsByValues(
+  objCatalog: IEnumCatalog | undefined,
+  strEnumKey: string,
+  arrValues: readonly TEnumValue[]
+): readonly IEnumOption[] {
+  const objOptions = new Map(
+    fnGetEnumOptions(objCatalog, strEnumKey).map((objOption) => [
+      objOption.value,
+      objOption,
+    ])
+  )
+  return Object.freeze(
+    arrValues.flatMap((objValue) => {
+      const objOption = objOptions.get(objValue)
+      return objOption ? [objOption] : []
+    })
+  )
+}

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

@@ -0,0 +1,216 @@
+import { EnumCatalogError } from './errors'
+import type {
+  IEnumCatalog,
+  IEnumCatalogPayload,
+  IEnumCatalogRequestContext,
+  IEnumCatalogSource,
+  IEnumOption,
+  IEnumOptionPayload,
+  TEnumCatalogRequest,
+  TEnumLocale,
+  TEnumMetadataValue,
+  TEnumValue,
+} from './types'
+
+function fnIsEnumMetadataValue(objValue: TEnumMetadataValue): 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((objItem) => fnIsEnumMetadataValue(objItem))
+  }
+  if (typeof objValue !== 'object') return false
+  return Object.values(objValue).every((objItem) =>
+    fnIsEnumMetadataValue(objItem)
+  )
+}
+
+function fnFreezeEnumMetadataValue(
+  objValue: TEnumMetadataValue
+): TEnumMetadataValue {
+  if (Array.isArray(objValue)) {
+    return Object.freeze(
+      objValue.map((objItem) => fnFreezeEnumMetadataValue(objItem))
+    )
+  }
+  if (objValue && typeof objValue === 'object') {
+    return Object.freeze(
+      Object.fromEntries(
+        Object.entries(objValue).map(([strKey, objItem]) => [
+          strKey,
+          fnFreezeEnumMetadataValue(objItem),
+        ])
+      )
+    )
+  }
+  return objValue
+}
+
+function fnFreezeEnumMetadata(
+  objMetadata: Readonly<Record<string, TEnumMetadataValue>>
+): Readonly<Record<string, TEnumMetadataValue>> {
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(objMetadata).map(([strKey, objValue]) => [
+        strKey,
+        fnFreezeEnumMetadataValue(objValue),
+      ])
+    )
+  )
+}
+
+function fnIsEnumValue(
+  objValue: TEnumValue | undefined
+): objValue is TEnumValue {
+  return (
+    typeof objValue === 'boolean' ||
+    typeof objValue === 'string' ||
+    (typeof objValue === 'number' && Number.isFinite(objValue))
+  )
+}
+
+function fnNormalizeEnumOption(
+  objOption: IEnumOptionPayload,
+  strEnumKey: string
+): IEnumOption {
+  if (
+    !objOption ||
+    typeof objOption !== 'object' ||
+    !fnIsEnumValue(objOption.value) ||
+    typeof objOption.label !== 'string' ||
+    typeof objOption.sortOrder !== 'number' ||
+    !Number.isFinite(objOption.sortOrder) ||
+    (objOption.color !== undefined && typeof objOption.color !== 'string') ||
+    (objOption.description !== undefined &&
+      typeof objOption.description !== 'string') ||
+    (objOption.disabled !== undefined &&
+      typeof objOption.disabled !== 'boolean') ||
+    (objOption.metadata !== undefined &&
+      (typeof objOption.metadata !== 'object' ||
+        objOption.metadata === null ||
+        Array.isArray(objOption.metadata) ||
+        !Object.values(objOption.metadata).every((objValue) =>
+          fnIsEnumMetadataValue(objValue)
+        )))
+  ) {
+    throw new EnumCatalogError(
+      'INVALID_OPTION',
+      `枚举目录 ${strEnumKey} 包含无效选项。`,
+      strEnumKey
+    )
+  }
+
+  return Object.freeze({
+    color: objOption.color,
+    description: objOption.description,
+    disabled: objOption.disabled ?? false,
+    label: objOption.label,
+    metadata:
+      objOption.metadata === undefined
+        ? undefined
+        : fnFreezeEnumMetadata(objOption.metadata),
+    sortOrder: objOption.sortOrder,
+    value: objOption.value,
+  })
+}
+
+function fnNormalizeEnumOptions(
+  arrOptions: readonly IEnumOptionPayload[],
+  strEnumKey: string
+) {
+  const objLabels = new Set<string>()
+  const objValues = new Set<TEnumValue>()
+
+  return Object.freeze(
+    arrOptions
+      .map((objOption) => {
+        const objNormalizedOption = fnNormalizeEnumOption(objOption, strEnumKey)
+        if (objValues.has(objNormalizedOption.value)) {
+          throw new EnumCatalogError(
+            'DUPLICATE_VALUE',
+            `枚举目录 ${strEnumKey} 包含重复值 ${String(objNormalizedOption.value)}。`,
+            strEnumKey
+          )
+        }
+        if (objLabels.has(objNormalizedOption.label)) {
+          throw new EnumCatalogError(
+            'DUPLICATE_LABEL',
+            `枚举目录 ${strEnumKey} 包含重复显示文本 ${objNormalizedOption.label}。`,
+            strEnumKey
+          )
+        }
+        objValues.add(objNormalizedOption.value)
+        objLabels.add(objNormalizedOption.label)
+        return objNormalizedOption
+      })
+      .sort(
+        (objLeftOption, objRightOption) =>
+          objLeftOption.sortOrder - objRightOption.sortOrder
+      )
+  )
+}
+
+function fnIsEnumLocale(strLocale: string): strLocale is TEnumLocale {
+  return strLocale === 'en-US' || strLocale === 'zh-CN'
+}
+
+function fnNormalizeEnumCatalog(
+  objCatalog: IEnumCatalogPayload | undefined
+): IEnumCatalog {
+  if (
+    !objCatalog?.enums ||
+    typeof objCatalog.enums !== 'object' ||
+    Array.isArray(objCatalog.enums) ||
+    typeof objCatalog.locale !== 'string' ||
+    !fnIsEnumLocale(objCatalog.locale) ||
+    typeof objCatalog.version !== 'string' ||
+    !objCatalog.version.trim()
+  ) {
+    throw new EnumCatalogError(
+      'INVALID_RESPONSE',
+      '枚举目录接口未返回有效数据。'
+    )
+  }
+
+  const objEnums = new Map<string, readonly IEnumOption[]>()
+  Object.entries(objCatalog.enums).forEach(([strEnumKey, arrOptions]) => {
+    if (!strEnumKey.trim() || !Array.isArray(arrOptions)) {
+      throw new EnumCatalogError(
+        'INVALID_RESPONSE',
+        `枚举目录 ${strEnumKey || '<empty>'} 的选项不是数组。`,
+        strEnumKey || undefined
+      )
+    }
+    objEnums.set(strEnumKey, fnNormalizeEnumOptions(arrOptions, strEnumKey))
+  })
+
+  return Object.freeze({
+    enums: objEnums,
+    locale: objCatalog.locale,
+    version: objCatalog.version,
+  })
+}
+
+/** 将 Swagger 生成客户端的请求函数适配为全局枚举数据源。 */
+export function fnCreateEnumCatalogSource(
+  fnRequest: TEnumCatalogRequest
+): IEnumCatalogSource {
+  return Object.freeze({
+    fnLoadCatalog: async (objContext: IEnumCatalogRequestContext) => {
+      if (objContext.objScope.strLocale !== objContext.strLocale) {
+        throw new EnumCatalogError(
+          'INVALID_SCOPE',
+          `枚举目录作用域语言 ${objContext.objScope.strLocale}，与请求语言 ${objContext.strLocale} 不一致。`
+        )
+      }
+      const objCatalog = fnNormalizeEnumCatalog(await fnRequest(objContext))
+      if (objCatalog.locale !== objContext.strLocale) {
+        throw new EnumCatalogError(
+          'LOCALE_MISMATCH',
+          `枚举目录返回语言 ${objCatalog.locale}，与请求语言 ${objContext.strLocale} 不一致。`
+        )
+      }
+      return objCatalog
+    },
+  })
+}

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

@@ -0,0 +1,21 @@
+import type { TEnumCatalogErrorCode } from './types'
+
+/** 枚举目录校验和作用域错误的稳定公共类型。 */
+export class EnumCatalogError extends Error {
+  /** 可供日志、监控和调用方分支处理的稳定错误码。 */
+  readonly strCode: TEnumCatalogErrorCode
+
+  /** 错误对应的枚举 Key；目录级错误时为空。 */
+  readonly strEnumKey?: string
+
+  constructor(
+    strCode: TEnumCatalogErrorCode,
+    strMessage: string,
+    strEnumKey?: string
+  ) {
+    super(strMessage)
+    this.name = 'EnumCatalogError'
+    this.strCode = strCode
+    this.strEnumKey = strEnumKey
+  }
+}

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

@@ -0,0 +1,48 @@
+export {
+  EnumCatalogProvider,
+  useEnum,
+  useEnumCatalog,
+} from './EnumCatalogProvider'
+export { EnumDictionary } from './EnumDictionary'
+export { EnumCatalogError } from './errors'
+export {
+  fnGetEnumEntries,
+  fnGetEnumKeys,
+  fnGetEnumLabel,
+  fnGetEnumLabels,
+  fnGetEnumOption,
+  fnGetEnumOptions,
+  fnGetEnumOptionsByValues,
+  fnGetEnumValue,
+  fnGetEnumValues,
+  fnHasEnumKey,
+} from './access'
+export { fnCreateEnumCatalogSource } from './catalog'
+export {
+  fnEnsureEnumCatalog,
+  fnEnumCatalogQueryKey,
+  fnEnumCatalogQueryOptions,
+  fnGetCachedEnumCatalog,
+  fnInvalidateEnumCatalog,
+} from './query'
+export { fnCreateEnumCatalogScope, fnResolveEnumCatalogScope } from './scope'
+export type {
+  IEnumCatalog,
+  IEnumCatalogEntry,
+  IEnumCatalogPayload,
+  IEnumCatalogProviderProps,
+  IEnumCatalogRequestContext,
+  IEnumCatalogScope,
+  IEnumCatalogScopeContext,
+  IEnumCatalogSource,
+  IEnumOption,
+  IEnumOptionPayload,
+  IUseEnumCatalogResult,
+  IUseEnumResult,
+  TEnumCatalogRequest,
+  TEnumCatalogErrorCode,
+  TEnumCatalogScopeInput,
+  TEnumLocale,
+  TEnumMetadataValue,
+  TEnumValue,
+} from './types'