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

package/template/public/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" class="icon" viewBox="0 0 1024 1024" fill="none"><rect width="1024" height="1024" rx="266.24" fill="#EFEFEF"/><g fill="#007FFC"><path d="M512.004 698.668C573.859 698.668 624.004 748.813 624.004 810.668C624.004 872.523 573.859 922.668 512.004 922.668C450.148 922.668 400.004 872.523 400.004 810.668C400.004 748.813 450.148 698.668 512.004 698.668Z"/><path d="M512.004 101.335C573.859 101.335 624.004 151.479 624.004 213.335C624.004 262.082 592.812 303.42 549.337 318.809V490.418L699.582 577.189C719.293 559.898 745.056 549.335 773.337 549.335C835.192 549.335 885.337 599.48 885.337 661.335C885.337 723.19 835.192 773.335 773.337 773.335C711.482 773.335 661.337 723.19 661.337 661.335C661.337 654.836 661.878 648.464 662.941 642.267L512.004 555.095L361.03 642.267C362.093 648.465 362.67 654.833 362.67 661.335C362.67 723.19 312.525 773.335 250.67 773.335C188.814 773.335 138.67 723.19 138.67 661.335C138.67 599.48 188.814 549.335 250.67 549.335C278.941 549.335 304.68 559.908 324.389 577.189L474.67 490.418V318.809C431.195 303.42 400.004 262.082 400.004 213.335C400.004 151.479 450.149 101.335 512.004 101.335Z"/><path d="M250.67 250.668C312.525 250.668 362.67 300.813 362.67 362.668C362.67 424.523 312.525 474.668 250.67 474.668C188.814 474.668 138.67 424.523 138.67 362.668C138.67 300.813 188.814 250.668 250.67 250.668Z"/><path d="M773.337 250.668C835.192 250.668 885.337 300.813 885.337 362.668C885.337 424.523 835.192 474.668 773.337 474.668C711.482 474.668 661.337 424.523 661.337 362.668C661.337 300.813 711.482 250.668 773.337 250.668Z"/></g></svg>

package/template/public/runtime-config.json

@@ -0,0 +1,49 @@
+{
+  "nSchemaVersion": 1,
+  "app": {
+    "strBrandId": "enterprise-admin",
+    "strTitle": "Enterprise Admin",
+    "strDescription": "企业管理控制台",
+    "strLogoPath": "logo.svg",
+    "strDarkLogoPath": "logo.svg",
+    "strFaviconPath": "favicon.ico",
+    "objTheme": {
+      "objLight": {
+        "strPrimaryColor": "#4068d5",
+        "strPrimaryForegroundColor": "#ffffff",
+        "strSecondaryColor": "#49beff",
+        "strSecondaryForegroundColor": "#102a43",
+        "strBrowserThemeColor": "#ffffff"
+      },
+      "objDark": {
+        "strPrimaryColor": "#8aadff",
+        "strPrimaryForegroundColor": "#0f172a",
+        "strSecondaryColor": "#49beff",
+        "strSecondaryForegroundColor": "#102a43",
+        "strBrowserThemeColor": "#000000"
+      }
+    },
+    "strStorageNamespace": "enterprise-admin",
+    "strMode": "demo"
+  },
+  "api": {
+    "strBaseUrl": ""
+  },
+  "auth": {
+    "strAudience": "admin-api",
+    "strClientId": "react-admin",
+    "strScope": "openid profile offline_access",
+    "strSessionStorage": "session",
+    "strSignInPath": "/api/v1/auth/first-party-login",
+    "strRefreshPath": "/api/v1/auth/refresh-token",
+    "strSignOutPath": "/api/v1/auth/logout"
+  },
+  "locale": {
+    "strLocale": "zh-CN",
+    "strTimeZone": "Asia/Shanghai"
+  },
+  "observability": {
+    "bEnabled": false,
+    "strEnvironment": "local"
+  }
+}

package/template/scaffold.template.json

@@ -0,0 +1,5 @@
+{
+  "nSchemaVersion": 1,
+  "strTemplateId": "enterprise-react-admin",
+  "strAppliedVersion": "0.1.0"
+}

package/template/src/Application.tsx

@@ -0,0 +1,114 @@
+import { useMemo } from 'react'
+import { QueryClientProvider } from '@tanstack/react-query'
+import { RouterProvider } from '@tanstack/react-router'
+import type {
+  IApplicationMetadataOptions,
+  IApplicationOptions,
+} from '@/application/types'
+import {
+  LocaleProvider,
+  type TAppLocale,
+  type TSharedMessageOverrides,
+} from '@/locale'
+import { objQueryClient, objRouter } from '@/router/router'
+import { MetadataProvider } from '@/api/metadata'
+import { useAuthStore } from '@/stores/authStore'
+import { ThemeProvider } from '@/context/ThemeProvider'
+import {
+  fnCreateApplicationScope,
+  fnResolveApplicationMetadataScope,
+} from '@/context/applicationScope'
+
+interface IApplicationContentProps {
+  /** 全局枚举和参数能力。 */
+  readonly objMetadata: IApplicationMetadataOptions
+  /** 项目对共享文案的覆盖。 */
+  readonly objSharedMessages?: TSharedMessageOverrides
+  /** 已解析的统一应用语言。 */
+  readonly strLocale: TAppLocale
+  /** 统一 IANA 时区。 */
+  readonly strTimeZone: string
+}
+
+function ApplicationContent({
+  objMetadata,
+  objSharedMessages,
+  strLocale,
+  strTimeZone,
+}: IApplicationContentProps) {
+  const bIsAuthenticated = useAuthStore((objState) => objState.bIsAuthenticated)
+  const nSessionGeneration = useAuthStore(
+    (objState) => objState.nSessionGeneration
+  )
+  const strTenantId = useAuthStore((objState) => objState.objUser?.strTenantId)
+  const objApplicationScope = useMemo(
+    () =>
+      fnCreateApplicationScope({
+        nSessionGeneration,
+        strLocale,
+        strTenantId,
+      }),
+    [nSessionGeneration, strLocale, strTenantId]
+  )
+  const objResolvedEnumScope = useMemo(
+    () =>
+      fnResolveApplicationMetadataScope(
+        objApplicationScope,
+        objMetadata.objEnumCatalog?.objScope
+      ),
+    [objApplicationScope, objMetadata.objEnumCatalog?.objScope]
+  )
+  const objResolvedGlobalParameterScope = useMemo(
+    () =>
+      fnResolveApplicationMetadataScope(
+        objApplicationScope,
+        objMetadata.objGlobalParameters?.objScope
+      ),
+    [objApplicationScope, objMetadata.objGlobalParameters?.objScope]
+  )
+  const bShouldLoadEnumCatalog =
+    objMetadata.objEnumCatalog?.bIsEnabled ?? bIsAuthenticated
+  const bShouldLoadGlobalParameters =
+    objMetadata.objGlobalParameters?.bIsEnabled ?? bIsAuthenticated
+
+  return (
+    <LocaleProvider
+      objSharedMessages={objSharedMessages}
+      strLocale={strLocale}
+      strTimeZone={strTimeZone}
+    >
+      <MetadataProvider
+        bIsEnumCatalogEnabled={bShouldLoadEnumCatalog}
+        bIsGlobalParameterEnabled={bShouldLoadGlobalParameters}
+        objEnumCatalogScope={objResolvedEnumScope}
+        objEnumCatalogSource={objMetadata.objEnumCatalog?.objSource}
+        objGlobalParameterScope={objResolvedGlobalParameterScope}
+        objGlobalParameterSource={objMetadata.objGlobalParameters?.objSource}
+        strLocale={strLocale}
+      >
+        <ThemeProvider>
+          <RouterProvider router={objRouter} />
+        </ThemeProvider>
+      </MetadataProvider>
+    </LocaleProvider>
+  )
+}
+
+export function Application({
+  objLocale = {},
+  objMetadata = {},
+}: IApplicationOptions = {}) {
+  const strResolvedLocale = objLocale.strLocale ?? 'zh-CN'
+  const strTimeZone = objLocale.strTimeZone ?? 'Asia/Shanghai'
+
+  return (
+    <QueryClientProvider client={objQueryClient}>
+      <ApplicationContent
+        objMetadata={objMetadata}
+        objSharedMessages={objLocale.objSharedMessages}
+        strLocale={strResolvedLocale}
+        strTimeZone={strTimeZone}
+      />
+    </QueryClientProvider>
+  )
+}

package/template/src/api/ApiError.ts

@@ -0,0 +1,33 @@
+import type { IApiErrorOptions } from '@/api/types'
+
+/** 不依赖具体 HTTP 客户端的应用级 API 错误。 */
+export class ApiError extends Error {
+  /** 后端业务码或前端稳定错误码。 */
+  readonly strCode: string
+  /** 失败类别。 */
+  readonly strKind: IApiErrorOptions['strKind']
+  /** HTTP 状态码。 */
+  readonly nStatus?: number
+  /** 请求关联 ID。 */
+  readonly strRequestId?: string
+  /** 后端明确提供的字段校验明细。 */
+  readonly objDetails?: unknown
+  /** 是否适合再次尝试；不会自动触发重试。 */
+  readonly bRetriable: boolean
+
+  constructor(objOptions: IApiErrorOptions) {
+    super(objOptions.strMessage)
+    this.name = 'ApiError'
+    this.strCode = objOptions.strCode
+    this.strKind = objOptions.strKind
+    this.nStatus = objOptions.nStatus
+    this.strRequestId = objOptions.strRequestId
+    this.objDetails = objOptions.objDetails
+    this.bRetriable = objOptions.bRetriable
+  }
+}
+
+/** 在业务代码和错误边界中识别标准 API 错误。 */
+export function fnIsApiError(objError: unknown): objError is ApiError {
+  return objError instanceof ApiError
+}

package/template/src/api/activity/ActivityProvider.tsx

@@ -0,0 +1,167 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { useAppQueryScope } from '@/api/query'
+import { fnGetActivityTaskStatus } from './access'
+import { fnApplyActivityEvent, fnActivityQueryOptions } from './query'
+import { fnStartActivitySubscription } from './subscription'
+import type {
+  IActivityProviderProps,
+  IActivitySource,
+  IActivitySubscription,
+  IUseActivityResult,
+  TActivityConnectionState,
+} from './types'
+
+const objIdleConnectionState = Object.freeze({ strStatus: 'idle' as const })
+const objUnavailableActivitySource: IActivitySource = {
+  fnLoadSnapshot: () =>
+    Promise.reject(new Error('尚未配置通知与任务状态快照数据源。')),
+}
+const fnActivityContext = createContext<IUseActivityResult | null>(null)
+
+/**
+ * 组合活动快照 Query 与可选实时传输。首次快照完成前不连接实时通道，快照失败也
+ * 不阻塞应用子树。
+ */
+export function ActivityProvider({
+  bIsEnabled = true,
+  children: objChildren,
+  objReconnectPolicy,
+  objSource,
+  objTransport,
+}: IActivityProviderProps) {
+  const objQueryClient = useQueryClient()
+  const objScope = useAppQueryScope()
+  const bIsConfigured = objSource !== undefined
+  const bIsLiveConfigured = objTransport !== undefined
+  const objQuery = useQuery({
+    ...fnActivityQueryOptions(
+      objSource ?? objUnavailableActivitySource,
+      objScope
+    ),
+    enabled: bIsConfigured && bIsEnabled,
+  })
+  const { refetch: fnRefetchQuery } = objQuery
+  const [objConnectionState, fnSetConnectionState] =
+    useState<TActivityConnectionState>(objIdleConnectionState)
+  const objSubscriptionRef = useRef<IActivitySubscription | null>(null)
+  const bCanStartLiveConnection = Boolean(
+    bIsConfigured &&
+    bIsEnabled &&
+    bIsLiveConfigured &&
+    objQuery.data !== undefined &&
+    !objQuery.isFetching
+  )
+
+  useEffect(() => {
+    if (!bCanStartLiveConnection || !objSource || !objTransport) return
+
+    const objSubscription = fnStartActivitySubscription({
+      fnOnEvent: (objEvent) => {
+        fnApplyActivityEvent(objQueryClient, objScope, objEvent)
+      },
+      fnOnStateChange: fnSetConnectionState,
+      objAdapter: objTransport,
+      objReconnectPolicy,
+      objScope,
+      strLastEventId: objQueryClient.getQueryData<{
+        readonly strLastEventId?: string
+      }>(fnActivityQueryOptions(objSource, objScope).queryKey)?.strLastEventId,
+    })
+    objSubscriptionRef.current = objSubscription
+    return () => {
+      objSubscription.fnStop()
+      if (objSubscriptionRef.current === objSubscription) {
+        objSubscriptionRef.current = null
+      }
+    }
+  }, [
+    bCanStartLiveConnection,
+    objQueryClient,
+    objReconnectPolicy,
+    objScope,
+    objSource,
+    objTransport,
+  ])
+
+  const fnRefetch = useCallback(async () => {
+    if (!bIsConfigured || !bIsEnabled) return
+    await fnRefetchQuery()
+  }, [bIsConfigured, bIsEnabled, fnRefetchQuery])
+
+  const fnReconnect = useCallback(() => {
+    objSubscriptionRef.current?.fnReconnect()
+  }, [])
+
+  const fnRetry = useCallback(async () => {
+    if (objQuery.isError || objQuery.data === undefined) await fnRefetch()
+    objSubscriptionRef.current?.fnReconnect()
+  }, [fnRefetch, objQuery.data, objQuery.isError])
+
+  const objContextValue = useMemo<IUseActivityResult>(
+    () => ({
+      arrTaskStatuses: objQuery.data?.arrTaskStatuses ?? [],
+      bIsConfigured,
+      bIsEnabled,
+      bIsError: objQuery.isError,
+      bIsFetching: objQuery.isFetching,
+      bIsLiveConfigured,
+      bIsLoading: bIsConfigured && bIsEnabled && objQuery.isPending,
+      nUnreadCount: objQuery.data?.nUnreadCount ?? 0,
+      objConnectionState,
+      objSnapshot: objQuery.data,
+      objSnapshotError: objQuery.error,
+      fnReconnect,
+      fnRefetch,
+      fnRetry,
+    }),
+    [
+      bIsConfigured,
+      bIsEnabled,
+      bIsLiveConfigured,
+      objConnectionState,
+      objQuery.data,
+      objQuery.error,
+      objQuery.isError,
+      objQuery.isFetching,
+      objQuery.isPending,
+      fnReconnect,
+      fnRefetch,
+      fnRetry,
+    ]
+  )
+
+  return (
+    <fnActivityContext.Provider value={objContextValue}>
+      {objChildren}
+    </fnActivityContext.Provider>
+  )
+}
+
+/** 读取未读数、任务状态、快照请求和实时连接生命周期。 */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useActivity() {
+  const objContext = useContext(fnActivityContext)
+  if (!objContext) {
+    throw new Error('useActivity 必须在 ActivityProvider 内使用。')
+  }
+  return objContext
+}
+
+/** 按稳定任务 ID 订阅当前快照中的一个异步任务状态。 */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useActivityTaskStatus(strTaskId: string) {
+  const { objSnapshot } = useActivity()
+  return useMemo(
+    () => fnGetActivityTaskStatus(objSnapshot, strTaskId),
+    [objSnapshot, strTaskId]
+  )
+}

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

@@ -0,0 +1,13 @@
+import type { IActivitySnapshot } from './types'
+
+/** 按稳定任务 ID 读取当前活动快照中的任务状态。 */
+export function fnGetActivityTaskStatus(
+  objSnapshot: IActivitySnapshot | undefined,
+  strTaskId: string
+) {
+  const strNormalizedTaskId = strTaskId.trim()
+  if (!strNormalizedTaskId) return undefined
+  return objSnapshot?.arrTaskStatuses.find(
+    (objTaskStatus) => objTaskStatus.strTaskId === strNormalizedTaskId
+  )
+}

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

@@ -0,0 +1,17 @@
+import type { TActivityErrorCode } from './types'
+
+/** 活动快照、事件或传输生命周期的可分类错误。 */
+export class ActivityError extends Error {
+  /** 供页面、日志和测试稳定分类的错误码。 */
+  readonly strCode: TActivityErrorCode
+
+  constructor(
+    strCode: TActivityErrorCode,
+    strMessage: string,
+    objOptions?: ErrorOptions
+  ) {
+    super(strMessage, objOptions)
+    this.name = 'ActivityError'
+    this.strCode = strCode
+  }
+}

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

@@ -0,0 +1,67 @@
+export {
+  ActivityProvider,
+  useActivity,
+  useActivityTaskStatus,
+} from './ActivityProvider'
+export { fnGetActivityTaskStatus } from './access'
+export { ActivityError } from './errors'
+export {
+  fnNormalizeActivityEvent,
+  fnNormalizeActivitySnapshot,
+  nMaxActivityTaskStatuses,
+} from './model'
+export {
+  fnActivityQueryKey,
+  fnActivityQueryOptions,
+  fnApplyActivityEvent,
+  fnEnsureActivitySnapshot,
+  fnGetCachedActivitySnapshot,
+  fnInvalidateActivitySnapshot,
+} from './query'
+export { fnCreateActivitySource } from './source'
+export { fnStartActivitySubscription } from './subscription'
+export {
+  fnCreatePollingActivityTransport,
+  fnCreateSseActivityTransport,
+  fnCreateWebSocketActivityTransport,
+} from './transports'
+export type {
+  IActivityConnectedState,
+  IActivityConnectionErrorState,
+  IActivityConnectingState,
+  IActivityEventBase,
+  IActivityEventSourceLike,
+  IActivityIdleConnectionState,
+  IActivityPollContext,
+  IActivityProviderProps,
+  IActivityReconnectPolicy,
+  IActivityReconnectingState,
+  IActivitySnapshot,
+  IActivitySnapshotInput,
+  IActivitySnapshotInvalidatedEventInput,
+  IActivitySnapshotReplacedEventInput,
+  IActivitySnapshotRequestContext,
+  IActivitySource,
+  IActivitySubscription,
+  IActivityTaskStatus,
+  IActivityTaskStatusChangedEventInput,
+  IActivityTaskStatusInput,
+  IActivityTransportAdapter,
+  IActivityTransportConnectContext,
+  IActivityTransportConnection,
+  IActivityUnreadCountChangedEventInput,
+  IActivityWebSocketLike,
+  ICreatePollingActivityTransportOptions,
+  ICreateSseActivityTransportOptions,
+  ICreateWebSocketActivityTransportOptions,
+  IStartActivitySubscriptionOptions,
+  IUseActivityResult,
+  TActivityConnectionState,
+  TActivityErrorCode,
+  TActivityEvent,
+  TActivityEventInput,
+  TActivityMessageParser,
+  TActivitySnapshotRequest,
+  TActivityTaskState,
+  TActivityTransport,
+} from './types'