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

package/template/src/files/useFileTask.ts

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { FileCapabilityError } from './errors'
+import type {
+  IFileTaskContext,
+  IUseFileTaskOptions,
+  IUseFileTaskResult,
+  TFileTaskState,
+} from './types'
+
+function fnIsAbortError(objError: Error) {
+  return objError.name === 'AbortError' || objError.name === 'CanceledError'
+}
+
+function fnWaitForPoll(nDelayMs: number, objSignal: AbortSignal) {
+  return new Promise<void>((fnResolve, fnReject) => {
+    if (objSignal.aborted) {
+      fnReject(new DOMException('任务已取消', 'AbortError'))
+      return
+    }
+    const fnHandleAbort = () => {
+      window.clearTimeout(nTimeoutId)
+      fnReject(new DOMException('任务已取消', 'AbortError'))
+    }
+    const nTimeoutId = window.setTimeout(() => {
+      objSignal.removeEventListener('abort', fnHandleAbort)
+      fnResolve()
+    }, nDelayMs)
+    objSignal.addEventListener('abort', fnHandleAbort, { once: true })
+  })
+}
+
+/** 统一协调立即完成和服务端后台轮询两类导入/导出任务。 */
+export function useFileTask<TInput, TResult>(
+  objOptions: IUseFileTaskOptions<TInput, TResult>
+): IUseFileTaskResult<TInput, TResult> {
+  const { nPollIntervalMs, objAdapter } = objOptions
+  const [objState, fnSetState] = useState<TFileTaskState<TResult>>({
+    strStatus: 'idle',
+  })
+  const objControllerRef = useRef<AbortController | null>(null)
+  const objLastInputRef = useRef<TInput | null>(null)
+  const objRequestIdRef = useRef(0)
+
+  const fnCancel = useCallback(() => {
+    objControllerRef.current?.abort()
+  }, [])
+
+  const fnRun = useCallback(
+    async (objInput: TInput) => {
+      objLastInputRef.current = objInput
+      objControllerRef.current?.abort()
+      const objController = new AbortController()
+      objControllerRef.current = objController
+      const nRequestId = ++objRequestIdRef.current
+      const fnOnProgress: IFileTaskContext['fnOnProgress'] = (objProgress) => {
+        if (nRequestId !== objRequestIdRef.current) return
+        fnSetState((objCurrentState) => ({
+          objProgress,
+          strStatus:
+            objCurrentState.strStatus === 'queued' ? 'queued' : 'running',
+          strTaskId:
+            'strTaskId' in objCurrentState
+              ? objCurrentState.strTaskId
+              : undefined,
+        }))
+      }
+      const objContext = {
+        fnOnProgress,
+        objSignal: objController.signal,
+      }
+      fnSetState({ objProgress: {}, strStatus: 'starting' })
+
+      try {
+        const objStartResult = await objAdapter.fnStart(objInput, objContext)
+        if (nRequestId !== objRequestIdRef.current) return undefined
+        if (objStartResult.strMode === 'completed') {
+          fnSetState({
+            objResult: objStartResult.objResult,
+            strStatus: 'success',
+          })
+          return objStartResult.objResult
+        }
+
+        const fnPoll = objAdapter.fnPoll
+        if (!fnPoll) {
+          throw new FileCapabilityError({
+            strCode: 'TASK_POLLING_NOT_CONFIGURED',
+            strMessage: '后台文件任务没有配置状态查询适配器',
+          })
+        }
+        fnSetState({
+          objProgress: {},
+          strStatus: 'queued',
+          strTaskId: objStartResult.strTaskId,
+        })
+
+        const nEffectivePollIntervalMs = Math.max(250, nPollIntervalMs ?? 1500)
+        while (!objController.signal.aborted) {
+          await fnWaitForPoll(nEffectivePollIntervalMs, objController.signal)
+          const objPollResult = await fnPoll(
+            objStartResult.strTaskId,
+            objContext
+          )
+          if (nRequestId !== objRequestIdRef.current) return undefined
+          if (objPollResult.strStatus === 'success') {
+            fnSetState({
+              objResult: objPollResult.objResult,
+              strStatus: 'success',
+            })
+            return objPollResult.objResult
+          }
+          if (objPollResult.strStatus === 'error') {
+            throw objPollResult.objError
+          }
+          fnSetState({
+            objProgress: objPollResult.objProgress ?? {},
+            strStatus: objPollResult.strStatus,
+            strTaskId: objStartResult.strTaskId,
+          })
+        }
+        return undefined
+      } catch (objCaughtError) {
+        if (nRequestId !== objRequestIdRef.current) return undefined
+        const objError =
+          objCaughtError instanceof Error
+            ? objCaughtError
+            : new Error('文件任务执行失败')
+        fnSetState(
+          fnIsAbortError(objError) || objController.signal.aborted
+            ? { strStatus: 'canceled' }
+            : { objError, strStatus: 'error' }
+        )
+        return undefined
+      }
+    },
+    [nPollIntervalMs, objAdapter]
+  )
+
+  const fnRetry = useCallback(() => {
+    const objInput = objLastInputRef.current
+    return objInput === null ? Promise.resolve(undefined) : fnRun(objInput)
+  }, [fnRun])
+
+  useEffect(
+    () => () => {
+      objRequestIdRef.current += 1
+      objControllerRef.current?.abort()
+    },
+    []
+  )
+
+  return { fnCancel, fnRetry, fnRun, objState }
+}

package/template/src/files/useFileUpload.ts

@@ -0,0 +1,117 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type {
+  IFileValidationIssue,
+  IUseFileUploadOptions,
+  IUseFileUploadResult,
+  TFileUploadState,
+} from './types'
+import { fnValidateFiles } from './validation'
+
+function fnCreateValidationError(arrIssues: readonly IFileValidationIssue[]) {
+  return new Error(arrIssues[0]?.strMessage ?? '文件校验未通过')
+}
+
+function fnIsAbortError(objError: Error) {
+  return objError.name === 'AbortError' || objError.name === 'CanceledError'
+}
+
+/** 管理文件校验、上传进度、取消、失败和重试的互斥状态机。 */
+export function useFileUpload<TResult>(
+  objOptions: IUseFileUploadOptions<TResult>
+): IUseFileUploadResult<TResult> {
+  const { fnUpload: fnRequest, objValidation } = objOptions
+  const [objState, fnSetState] = useState<TFileUploadState<TResult>>({
+    strStatus: 'idle',
+  })
+  const objControllerRef = useRef<AbortController | null>(null)
+  const objLastFilesRef = useRef<readonly File[]>([])
+  const objRequestIdRef = useRef(0)
+
+  const fnCancel = useCallback(() => {
+    objControllerRef.current?.abort()
+  }, [])
+
+  const fnUpload = useCallback(
+    async (arrFiles: readonly File[]) => {
+      const objValidationResult = fnValidateFiles(arrFiles, objValidation)
+      objLastFilesRef.current = arrFiles
+      if (objValidationResult.arrIssues.length > 0) {
+        fnSetState({
+          arrFiles,
+          arrIssues: objValidationResult.arrIssues,
+          objError: fnCreateValidationError(objValidationResult.arrIssues),
+          strStatus: 'error',
+        })
+        return undefined
+      }
+
+      objControllerRef.current?.abort()
+      const objController = new AbortController()
+      objControllerRef.current = objController
+      const nRequestId = ++objRequestIdRef.current
+      fnSetState({
+        arrFiles: objValidationResult.arrAcceptedFiles,
+        objProgress: {},
+        strStatus: 'uploading',
+      })
+
+      try {
+        const objResult = await fnRequest({
+          arrFiles: objValidationResult.arrAcceptedFiles,
+          objSignal: objController.signal,
+          fnOnProgress: (objProgress) => {
+            if (nRequestId !== objRequestIdRef.current) return
+            fnSetState({
+              arrFiles: objValidationResult.arrAcceptedFiles,
+              objProgress,
+              strStatus: 'uploading',
+            })
+          },
+        })
+        if (nRequestId !== objRequestIdRef.current) return undefined
+        fnSetState({
+          arrFiles: objValidationResult.arrAcceptedFiles,
+          objResult,
+          strStatus: 'success',
+        })
+        return objResult
+      } catch (objCaughtError) {
+        if (nRequestId !== objRequestIdRef.current) return undefined
+        const objError =
+          objCaughtError instanceof Error
+            ? objCaughtError
+            : new Error('文件上传失败')
+        fnSetState(
+          fnIsAbortError(objError) || objController.signal.aborted
+            ? {
+                arrFiles: objValidationResult.arrAcceptedFiles,
+                strStatus: 'canceled',
+              }
+            : {
+                arrFiles: objValidationResult.arrAcceptedFiles,
+                arrIssues: [],
+                objError,
+                strStatus: 'error',
+              }
+        )
+        return undefined
+      }
+    },
+    [fnRequest, objValidation]
+  )
+
+  const fnRetry = useCallback(
+    () => fnUpload(objLastFilesRef.current),
+    [fnUpload]
+  )
+
+  useEffect(
+    () => () => {
+      objRequestIdRef.current += 1
+      objControllerRef.current?.abort()
+    },
+    []
+  )
+
+  return { fnCancel, fnRetry, fnUpload, objState }
+}

package/template/src/files/validation.ts

@@ -0,0 +1,109 @@
+import type {
+  IFileValidationIssue,
+  IFileValidationOptions,
+  IFileValidationResult,
+} from './types'
+
+function fnNormalizeExtension(strExtension: string) {
+  const strValue = strExtension.trim().toLowerCase()
+  if (!strValue) return ''
+  return strValue.startsWith('.') ? strValue : `.${strValue}`
+}
+
+function fnGetFileExtension(strFileName: string) {
+  const nIndex = strFileName.lastIndexOf('.')
+  return nIndex <= 0 ? '' : strFileName.slice(nIndex).toLowerCase()
+}
+
+function fnMatchesMimeType(strMimeType: string, strAcceptedMimeType: string) {
+  const strExpected = strAcceptedMimeType.trim().toLowerCase()
+  const strActual = strMimeType.trim().toLowerCase()
+  if (strExpected.endsWith('/*')) {
+    return strActual.startsWith(strExpected.slice(0, -1))
+  }
+  return strActual === strExpected
+}
+
+function fnIsAcceptedType(objFile: File, objOptions: IFileValidationOptions) {
+  const arrExtensions = (objOptions.arrAcceptedExtensions ?? [])
+    .map(fnNormalizeExtension)
+    .filter(Boolean)
+  const arrMimeTypes = (objOptions.arrAcceptedMimeTypes ?? [])
+    .map((strMimeType) => strMimeType.trim().toLowerCase())
+    .filter(Boolean)
+  if (arrExtensions.length === 0 && arrMimeTypes.length === 0) return true
+
+  const bExtensionMatches = arrExtensions.includes(
+    fnGetFileExtension(objFile.name)
+  )
+  const bMimeMatches = arrMimeTypes.some((strMimeType) =>
+    fnMatchesMimeType(objFile.type, strMimeType)
+  )
+  return bExtensionMatches || bMimeMatches
+}
+
+/**
+ * 校验一次文件选择。
+ *
+ * 扩展名和 MIME 采用 OR 语义，便于兼容浏览器缺失 MIME 的情况；后端仍需按
+ * 文件签名、权限、病毒扫描和业务规则完成最终校验。
+ */
+export function fnValidateFiles(
+  arrFiles: readonly File[],
+  objOptions: IFileValidationOptions = {}
+): IFileValidationResult {
+  const arrIssues: IFileValidationIssue[] = []
+  const arrAcceptedFiles: File[] = []
+  const nMaxFiles = objOptions.nMaxFiles
+
+  if (nMaxFiles !== undefined && arrFiles.length > nMaxFiles) {
+    arrIssues.push({
+      strCode: 'TOO_MANY_FILES',
+      strMessage: `一次最多选择 ${nMaxFiles} 个文件`,
+    })
+    return { arrAcceptedFiles, arrIssues }
+  }
+
+  arrFiles.forEach((objFile) => {
+    if (!objOptions.bAllowEmptyFile && objFile.size === 0) {
+      arrIssues.push({
+        strCode: 'EMPTY_FILE',
+        strFileName: objFile.name,
+        strMessage: `${objFile.name} 是空文件`,
+      })
+      return
+    }
+    if (
+      objOptions.nMaxBytes !== undefined &&
+      objFile.size > objOptions.nMaxBytes
+    ) {
+      arrIssues.push({
+        strCode: 'FILE_TOO_LARGE',
+        strFileName: objFile.name,
+        strMessage: `${objFile.name} 超过允许的文件大小`,
+      })
+      return
+    }
+    if (!fnIsAcceptedType(objFile, objOptions)) {
+      arrIssues.push({
+        strCode: 'FILE_TYPE_NOT_ALLOWED',
+        strFileName: objFile.name,
+        strMessage: `${objFile.name} 的文件类型不被允许`,
+      })
+      return
+    }
+    arrAcceptedFiles.push(objFile)
+  })
+
+  return { arrAcceptedFiles, arrIssues }
+}
+
+/** 将校验规则转换为原生文件输入框 accept 提示。 */
+export function fnCreateFileAccept(objOptions: IFileValidationOptions = {}) {
+  return [
+    ...(objOptions.arrAcceptedMimeTypes ?? []),
+    ...(objOptions.arrAcceptedExtensions ?? []).map(fnNormalizeExtension),
+  ]
+    .filter(Boolean)
+    .join(',')
+}

package/template/src/layouts/AppLayout.tsx

@@ -0,0 +1,37 @@
+import { Outlet } from '@tanstack/react-router'
+import { useUiPreferenceStore } from '@/stores/uiPreferenceStore'
+import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar'
+import { Toaster } from '@/components/ui/sonner'
+import { AppHeader } from '@/components/layout/AppHeader'
+import { AppSidebar } from '@/components/layout/AppSidebar'
+
+export function AppLayout() {
+  const bIsSidebarOpen = useUiPreferenceStore(
+    (objState) => objState.bIsSidebarOpen
+  )
+  const nSidebarWidth = useUiPreferenceStore(
+    (objState) => objState.nSidebarWidth
+  )
+  const fnSetSidebarOpen = useUiPreferenceStore(
+    (objState) => objState.fnSetSidebarOpen
+  )
+  const fnSetSidebarWidth = useUiPreferenceStore(
+    (objState) => objState.fnSetSidebarWidth
+  )
+
+  return (
+    <SidebarProvider
+      open={bIsSidebarOpen}
+      onOpenChange={fnSetSidebarOpen}
+      width={nSidebarWidth}
+      onWidthChange={fnSetSidebarWidth}
+    >
+      <AppSidebar />
+      <SidebarInset className='@container/content overflow-x-hidden overflow-y-auto'>
+        <AppHeader />
+        <Outlet />
+      </SidebarInset>
+      <Toaster position='top-center' richColors />
+    </SidebarProvider>
+  )
+}

package/template/src/lib/accessControl.ts

@@ -0,0 +1,42 @@
+import type {
+  TPermissionMatchMode,
+  TPermissionRequirement,
+} from '@/permissions/types'
+import type { IAuthUser } from '@/stores/types'
+
+export function fnHasPermission(
+  objUser: IAuthUser | null,
+  strPermission?: string
+) {
+  if (!strPermission) return true
+  if (!objUser) return false
+
+  return (
+    objUser.arrPermissions.includes('*') ||
+    objUser.arrPermissions.includes(strPermission)
+  )
+}
+
+/**
+ * 判断当前用户是否满足一组权限要求。
+ *
+ * 空权限要求表示当前操作不设前端权限门槛；通配符仅来自后端身份中的 `*`。
+ */
+export function fnHasPermissions(
+  objUser: IAuthUser | null,
+  objRequirement?: TPermissionRequirement,
+  strMatchMode: TPermissionMatchMode = 'all'
+) {
+  if (!objRequirement) return true
+
+  const arrPermissions =
+    typeof objRequirement === 'string' ? [objRequirement] : objRequirement
+  if (arrPermissions.length === 0) return true
+
+  const fnMatch = (strPermission: string) =>
+    fnHasPermission(objUser, strPermission)
+
+  return strMatchMode === 'any'
+    ? arrPermissions.some(fnMatch)
+    : arrPermissions.every(fnMatch)
+}

package/template/src/lib/navigationRedirect.ts

@@ -0,0 +1,26 @@
+import { objAppConfig } from '@/config/appConfig'
+
+/** 登录成功或错误页返回时使用的默认受保护路径。 */
+export const strDefaultAuthenticatedPath =
+  objAppConfig.navigation.strDefaultAuthenticatedPath
+
+/**
+ * 将外部输入收窄为站内绝对路径，拒绝协议相对 URL 和反斜杠绕过。
+ */
+export function fnParseInternalRedirect(objValue: unknown) {
+  if (
+    typeof objValue !== 'string' ||
+    !objValue.startsWith('/') ||
+    objValue.startsWith('//') ||
+    objValue.includes('\\')
+  ) {
+    return undefined
+  }
+
+  return objValue
+}
+
+/** 返回安全的登录后回跳路径，无效输入回退到默认受保护路径。 */
+export function fnGetPostSignInPath(objValue: unknown) {
+  return fnParseInternalRedirect(objValue) ?? strDefaultAuthenticatedPath
+}

package/template/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...arrInputs: ClassValue[]) {
+  return twMerge(clsx(arrInputs))
+}

package/template/src/locale/LocaleProvider.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useMemo } from 'react'
+import { LocaleContext } from './context'
+import { fnCreateLocaleFormatter } from './formatters'
+import { objSharedLocaleMessages } from './messages'
+import type { ILocaleContextValue, ILocaleProviderProps } from './types'
+
+/** 为应用提供唯一 Locale、时区、Intl 格式化器和共享文案目录。 */
+export function LocaleProvider({
+  children: objChildren,
+  objSharedMessages,
+  strLocale,
+  strTimeZone,
+}: ILocaleProviderProps) {
+  const objValue = useMemo<ILocaleContextValue>(() => {
+    const objFormatter = fnCreateLocaleFormatter({ strLocale, strTimeZone })
+    const objOverrides = objSharedMessages?.[strLocale]
+    return {
+      ...objFormatter,
+      fnTranslateShared: (strKey) =>
+        objOverrides?.[strKey] ?? objSharedLocaleMessages[strLocale][strKey],
+    }
+  }, [objSharedMessages, strLocale, strTimeZone])
+
+  useEffect(() => {
+    const strPreviousLanguage = document.documentElement.lang
+    document.documentElement.lang = strLocale
+    return () => {
+      document.documentElement.lang = strPreviousLanguage
+    }
+  }, [strLocale])
+
+  return (
+    <LocaleContext.Provider value={objValue}>
+      {objChildren}
+    </LocaleContext.Provider>
+  )
+}

package/template/src/locale/context.ts

@@ -0,0 +1,15 @@
+import { createContext } from 'react'
+import { fnCreateLocaleFormatter } from './formatters'
+import { objSharedLocaleMessages } from './messages'
+import type { ILocaleContextValue } from './types'
+
+const objDefaultFormatter = fnCreateLocaleFormatter({
+  strLocale: 'zh-CN',
+  strTimeZone: 'Asia/Shanghai',
+})
+
+/** 独立组件测试和 Provider 外工具的兼容回退；应用运行时必须由 Provider 覆盖。 */
+export const LocaleContext = createContext<ILocaleContextValue>({
+  ...objDefaultFormatter,
+  fnTranslateShared: (strKey) => objSharedLocaleMessages['zh-CN'][strKey],
+})

package/template/src/locale/formatters.ts

@@ -0,0 +1,123 @@
+import type {
+  ILocaleFormatter,
+  ILocaleFormatterConfig,
+  TCurrencyFormatOptions,
+  TLocaleDateValue,
+} from './types'
+
+const strInvalidFormattedValue = '-'
+
+function fnCreateDateValue(objValue: TLocaleDateValue) {
+  const objDate = objValue instanceof Date ? objValue : new Date(objValue)
+  return Number.isFinite(objDate.getTime()) ? objDate : null
+}
+
+/** 创建可在 React 外使用的 Locale 格式化器，并复用已构造的 Intl 实例。 */
+export function fnCreateLocaleFormatter(
+  objConfig: ILocaleFormatterConfig
+): ILocaleFormatter {
+  const objDateFormatters = new Map<string, Intl.DateTimeFormat>()
+  const objNumberFormatters = new Map<string, Intl.NumberFormat>()
+  const objCollator = new Intl.Collator(objConfig.strLocale, {
+    numeric: true,
+    sensitivity: 'base',
+  })
+
+  const fnGetDateFormatter = (objOptions: Intl.DateTimeFormatOptions) => {
+    const objResolvedOptions: Intl.DateTimeFormatOptions = {
+      ...objOptions,
+      timeZone: objConfig.strTimeZone,
+    }
+    const strKey = JSON.stringify(objResolvedOptions)
+    const objCachedFormatter = objDateFormatters.get(strKey)
+    if (objCachedFormatter) return objCachedFormatter
+    const objFormatter = new Intl.DateTimeFormat(
+      objConfig.strLocale,
+      objResolvedOptions
+    )
+    objDateFormatters.set(strKey, objFormatter)
+    return objFormatter
+  }
+
+  const fnGetNumberFormatter = (objOptions: Intl.NumberFormatOptions) => {
+    const strKey = JSON.stringify(objOptions)
+    const objCachedFormatter = objNumberFormatters.get(strKey)
+    if (objCachedFormatter) return objCachedFormatter
+    const objFormatter = new Intl.NumberFormat(objConfig.strLocale, objOptions)
+    objNumberFormatters.set(strKey, objFormatter)
+    return objFormatter
+  }
+
+  const fnFormatDateValue = (
+    objValue: TLocaleDateValue,
+    objOptions: Intl.DateTimeFormatOptions
+  ) => {
+    const objDate = fnCreateDateValue(objValue)
+    return objDate
+      ? fnGetDateFormatter(objOptions).format(objDate)
+      : strInvalidFormattedValue
+  }
+
+  const fnFormatNumberValue = (
+    nValue: number,
+    objOptions: Intl.NumberFormatOptions
+  ) =>
+    Number.isFinite(nValue)
+      ? fnGetNumberFormatter(objOptions).format(nValue)
+      : strInvalidFormattedValue
+
+  const fnResolveDateOptions = (
+    objOptions: Intl.DateTimeFormatOptions,
+    objDefaults: Intl.DateTimeFormatOptions
+  ) => (Object.keys(objOptions).length > 0 ? objOptions : objDefaults)
+
+  return {
+    strLocale: objConfig.strLocale,
+    strTimeZone: objConfig.strTimeZone,
+    fnCompare: (strLeft, strRight) => objCollator.compare(strLeft, strRight),
+    fnFormatCurrency: (
+      nValue: number,
+      strCurrency: string,
+      objOptions: TCurrencyFormatOptions = {}
+    ) =>
+      fnFormatNumberValue(nValue, {
+        ...objOptions,
+        currency: strCurrency,
+        style: 'currency',
+      }),
+    fnFormatDate: (objValue, objOptions = {}) =>
+      fnFormatDateValue(
+        objValue,
+        fnResolveDateOptions(objOptions, {
+          day: '2-digit',
+          month: '2-digit',
+          year: 'numeric',
+        })
+      ),
+    fnFormatDateTime: (objValue, objOptions = {}) =>
+      fnFormatDateValue(
+        objValue,
+        fnResolveDateOptions(objOptions, {
+          day: '2-digit',
+          hour: '2-digit',
+          minute: '2-digit',
+          month: '2-digit',
+          second: '2-digit',
+          year: 'numeric',
+        })
+      ),
+    fnFormatNumber: (nValue, objOptions = {}) =>
+      fnFormatNumberValue(nValue, objOptions),
+    fnFormatPercent: (nValue, objOptions = {}) =>
+      fnFormatNumberValue(nValue, { ...objOptions, style: 'percent' }),
+    fnFormatTime: (objValue, objOptions = {}) =>
+      fnFormatDateValue(
+        objValue,
+        fnResolveDateOptions(objOptions, {
+          hour: '2-digit',
+          minute: '2-digit',
+          second: '2-digit',
+        })
+      ),
+  }
+}