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

package/template/tests/unit/api/enums/catalog.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  EnumCatalogError,
+  EnumDictionary,
+  fnCreateEnumCatalogScope,
+  fnCreateEnumCatalogSource,
+} from '@/api/enums'
+
+const objChineseScope = fnCreateEnumCatalogScope('zh-CN')
+
+describe('global enum catalog source', () => {
+  it('validates the backend catalog and exposes sorted dictionary lookups', async () => {
+    const objAbortController = new AbortController()
+    const fnRequest = vi.fn().mockResolvedValue({
+      enums: {
+        'activity.status': [
+          { disabled: true, label: '已停用', sortOrder: 20, value: 0 },
+          { label: '已启用', sortOrder: 10, value: 1 },
+        ],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    })
+    const objSource = fnCreateEnumCatalogSource(fnRequest)
+
+    const objCatalog = await objSource.fnLoadCatalog({
+      objScope: objChineseScope,
+      objSignal: objAbortController.signal,
+      strLocale: 'zh-CN',
+    })
+    const objDictionary = new EnumDictionary(
+      objCatalog.enums.get('activity.status') ?? []
+    )
+
+    expect(fnRequest).toHaveBeenCalledWith({
+      objScope: objChineseScope,
+      objSignal: objAbortController.signal,
+      strLocale: 'zh-CN',
+    })
+    expect(
+      objDictionary.arrOptions.map((objOption) => objOption.value)
+    ).toEqual([1, 0])
+    expect(objDictionary.arrOptions[1]?.disabled).toBe(true)
+    expect(objDictionary.fnGetLabel(1)).toBe('已启用')
+    expect(objDictionary.fnGetLabel('1')).toBe('1')
+    expect(objDictionary.fnGetLabel('missing')).toBe('missing')
+    expect(objDictionary.fnGetLabel(null)).toBe('-')
+    expect(objDictionary.fnGetValue('已停用')).toBe(0)
+    expect(objDictionary.fnHasValue(0)).toBe(true)
+    expect(objDictionary.fnHasValue(false)).toBe(false)
+  })
+
+  it('rejects duplicate labels so reverse lookup is deterministic', async () => {
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {
+        status: [
+          { label: '处理中', sortOrder: 1, value: 'pending' },
+          { label: '处理中', sortOrder: 2, value: 'running' },
+        ],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+
+    let objCaughtError: unknown
+    try {
+      await objSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    } catch (objError) {
+      objCaughtError = objError
+    }
+
+    expect(objCaughtError).toBeInstanceOf(EnumCatalogError)
+    if (!(objCaughtError instanceof EnumCatalogError)) return
+    expect(objCaughtError.strCode).toBe('DUPLICATE_LABEL')
+    expect(objCaughtError.strEnumKey).toBe('status')
+  })
+
+  it('deeply freezes validated metadata shared by every consumer', async () => {
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {
+        status: [
+          {
+            label: '启用',
+            metadata: { arrTags: ['stable'], objPolicy: { bVisible: true } },
+            sortOrder: 1,
+            value: true,
+          },
+        ],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+    const objCatalog = await objSource.fnLoadCatalog({
+      objScope: objChineseScope,
+      objSignal: new AbortController().signal,
+      strLocale: 'zh-CN',
+    })
+    const objMetadata = objCatalog.enums.get('status')?.[0]?.metadata
+
+    expect(Object.isFrozen(objMetadata)).toBe(true)
+    expect(Object.isFrozen(objMetadata?.arrTags)).toBe(true)
+    expect(Object.isFrozen(objMetadata?.objPolicy)).toBe(true)
+  })
+
+  it('rejects duplicate values instead of silently choosing one label', async () => {
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {
+        status: [
+          { label: '启用', sortOrder: 1, value: 'active' },
+          { label: '重复启用', sortOrder: 2, value: 'active' },
+        ],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+
+    await expect(
+      objSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toThrow('枚举目录 status 包含重复值 active。')
+  })
+
+  it('rejects an invalid backend catalog envelope', async () => {
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {},
+      locale: 'fr-FR',
+      version: '',
+    }))
+
+    await expect(
+      objSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toThrow('枚举目录接口未返回有效数据。')
+  })
+
+  it('rejects metadata that is not valid JSON data', async () => {
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {
+        status: [
+          {
+            label: '启用',
+            metadata: { nInvalidValue: Number.NaN },
+            sortOrder: 1,
+            value: 'active',
+          },
+        ],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+
+    await expect(
+      objSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toThrow('枚举目录 status 包含无效选项。')
+  })
+
+  it('rejects a catalog returned in a different locale', async () => {
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {},
+      locale: 'en-US',
+      version: 'v1',
+    }))
+
+    await expect(
+      objSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toThrow('枚举目录返回语言 en-US，与请求语言 zh-CN 不一致。')
+  })
+
+  it('rejects inconsistent scope and request locales before transport', async () => {
+    const fnRequest = vi.fn()
+    const objSource = fnCreateEnumCatalogSource(fnRequest)
+
+    await expect(
+      objSource.fnLoadCatalog({
+        objScope: fnCreateEnumCatalogScope('en-US'),
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toThrow('枚举目录作用域语言 en-US，与请求语言 zh-CN 不一致。')
+    expect(fnRequest).not.toHaveBeenCalled()
+  })
+})

package/template/tests/unit/api/enums/query.test.ts

@@ -0,0 +1,110 @@
+import { QueryClient } from '@tanstack/react-query'
+import { describe, expect, it } from 'vitest'
+import {
+  fnCreateEnumCatalogScope,
+  fnEnumCatalogQueryKey,
+  fnInvalidateEnumCatalog,
+  type IEnumCatalog,
+  type IEnumCatalogScope,
+} from '@/api/enums'
+
+function fnCreateCatalog(strLocale: IEnumCatalog['locale']): IEnumCatalog {
+  return {
+    enums: new Map(),
+    locale: strLocale,
+    version: 'v1',
+  }
+}
+
+describe('enum catalog query cache', () => {
+  it('uses the session generation as the authorization cache version', () => {
+    expect(
+      fnCreateEnumCatalogScope('zh-CN', { nSessionGeneration: 3 })
+    ).toEqual({ nSessionGeneration: 3, strLocale: 'zh-CN' })
+    expect(() =>
+      fnCreateEnumCatalogScope('zh-CN', { nSessionGeneration: -1 })
+    ).toThrow('会话版本必须是非负整数')
+  })
+
+  it('invalidates only the requested locale when one is provided', async () => {
+    const objQueryClient = new QueryClient()
+    const arrChineseKey = fnEnumCatalogQueryKey('zh-CN')
+    const arrEnglishKey = fnEnumCatalogQueryKey('en-US')
+    objQueryClient.setQueryData(arrChineseKey, fnCreateCatalog('zh-CN'))
+    objQueryClient.setQueryData(arrEnglishKey, fnCreateCatalog('en-US'))
+
+    await fnInvalidateEnumCatalog(objQueryClient, 'zh-CN')
+
+    expect(objQueryClient.getQueryState(arrChineseKey)?.isInvalidated).toBe(
+      true
+    )
+    expect(objQueryClient.getQueryState(arrEnglishKey)?.isInvalidated).toBe(
+      false
+    )
+  })
+
+  it('invalidates every locale when no locale is provided', async () => {
+    const objQueryClient = new QueryClient()
+    const arrChineseKey = fnEnumCatalogQueryKey('zh-CN')
+    const arrEnglishKey = fnEnumCatalogQueryKey('en-US')
+    objQueryClient.setQueryData(arrChineseKey, fnCreateCatalog('zh-CN'))
+    objQueryClient.setQueryData(arrEnglishKey, fnCreateCatalog('en-US'))
+
+    await fnInvalidateEnumCatalog(objQueryClient)
+
+    expect(objQueryClient.getQueryState(arrChineseKey)?.isInvalidated).toBe(
+      true
+    )
+    expect(objQueryClient.getQueryState(arrEnglishKey)?.isInvalidated).toBe(
+      true
+    )
+  })
+
+  it('isolates tenants and can invalidate one exact business scope', async () => {
+    const objQueryClient = new QueryClient()
+    const objTenantAScope: IEnumCatalogScope = {
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-a',
+    }
+    const objTenantBScope: IEnumCatalogScope = {
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-b',
+    }
+    const arrTenantAKey = fnEnumCatalogQueryKey(objTenantAScope)
+    const arrTenantBKey = fnEnumCatalogQueryKey(objTenantBScope)
+    objQueryClient.setQueryData(arrTenantAKey, fnCreateCatalog('zh-CN'))
+    objQueryClient.setQueryData(arrTenantBKey, fnCreateCatalog('zh-CN'))
+
+    await fnInvalidateEnumCatalog(objQueryClient, objTenantAScope)
+
+    expect(objQueryClient.getQueryState(arrTenantAKey)?.isInvalidated).toBe(
+      true
+    )
+    expect(objQueryClient.getQueryState(arrTenantBKey)?.isInvalidated).toBe(
+      false
+    )
+  })
+
+  it('invalidates every scope under a requested locale', async () => {
+    const objQueryClient = new QueryClient()
+    const arrTenantAKey = fnEnumCatalogQueryKey({
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-a',
+    })
+    const arrTenantBKey = fnEnumCatalogQueryKey({
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-b',
+    })
+    objQueryClient.setQueryData(arrTenantAKey, fnCreateCatalog('zh-CN'))
+    objQueryClient.setQueryData(arrTenantBKey, fnCreateCatalog('zh-CN'))
+
+    await fnInvalidateEnumCatalog(objQueryClient, 'zh-CN')
+
+    expect(objQueryClient.getQueryState(arrTenantAKey)?.isInvalidated).toBe(
+      true
+    )
+    expect(objQueryClient.getQueryState(arrTenantBKey)?.isInvalidated).toBe(
+      true
+    )
+  })
+})

package/template/tests/unit/api/enums/useEnum.test.tsx

@@ -0,0 +1,98 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import {
+  EnumCatalogProvider,
+  fnCreateEnumCatalogSource,
+  useEnum,
+} from '@/api/enums'
+
+function EnumConsumer({ strTestId }: { strTestId: string }) {
+  const objStatusEnum = useEnum('activity.status')
+  const strContent = objStatusEnum.bIsLoading
+    ? 'loading'
+    : objStatusEnum.fnGetLabel('active')
+
+  return (
+    <output
+      data-testid={strTestId}
+      data-configured={objStatusEnum.bIsConfigured}
+      data-error={objStatusEnum.bIsError}
+      data-missing={objStatusEnum.bIsMissing}
+    >
+      {strContent}
+    </output>
+  )
+}
+
+describe('useEnum', () => {
+  it('shares one backend catalog request across all enum consumers', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const fnRequest = vi.fn().mockResolvedValue({
+      enums: {
+        'activity.status': [{ label: '启用', sortOrder: 1, value: 'active' }],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    })
+    const objSource = fnCreateEnumCatalogSource(fnRequest)
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <EnumCatalogProvider objSource={objSource}>
+          <EnumConsumer strTestId='first-consumer' />
+          <EnumConsumer strTestId='second-consumer' />
+        </EnumCatalogProvider>
+      </QueryClientProvider>
+    )
+
+    await expect
+      .element(objScreen.getByTestId('first-consumer'))
+      .toHaveTextContent('启用')
+    await expect
+      .element(objScreen.getByTestId('second-consumer'))
+      .toHaveTextContent('启用')
+    expect(fnRequest).toHaveBeenCalledTimes(1)
+  })
+
+  it('stays idle and reports unconfigured when no backend source is wired', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <EnumCatalogProvider>
+          <EnumConsumer strTestId='consumer' />
+        </EnumCatalogProvider>
+      </QueryClientProvider>
+    )
+    const objConsumer = objScreen.getByTestId('consumer')
+
+    await expect.element(objConsumer).toHaveTextContent('active')
+    await expect
+      .element(objConsumer)
+      .toHaveAttribute('data-configured', 'false')
+    await expect.element(objConsumer).toHaveAttribute('data-missing', 'false')
+  })
+
+  it('exposes backend failures without creating a second local cache', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objSource = fnCreateEnumCatalogSource(async () => {
+      throw new Error('枚举服务暂不可用')
+    })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <EnumCatalogProvider objSource={objSource}>
+          <EnumConsumer strTestId='consumer' />
+        </EnumCatalogProvider>
+      </QueryClientProvider>
+    )
+
+    await expect
+      .element(objScreen.getByTestId('consumer'))
+      .toHaveAttribute('data-error', 'true')
+  })
+})

package/template/tests/unit/api/enums/useEnumCatalog.test.tsx

@@ -0,0 +1,68 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { describe, expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import {
+  EnumCatalogProvider,
+  fnCreateEnumCatalogSource,
+  useEnumCatalog,
+} from '@/api/enums'
+
+function EnumCatalogConsumer() {
+  const objCatalog = useEnumCatalog()
+  if (objCatalog.bIsLoading) return <output>loading</output>
+
+  return (
+    <output
+      data-has-key={objCatalog.fnHasKey('activity.status')}
+      data-keys={objCatalog.arrKeys.join(',')}
+      data-label={objCatalog.fnGetLabel('activity.status', 'active')}
+      data-labels={objCatalog
+        .fnGetLabels('activity.status', ['disabled', 'active'])
+        .join(',')}
+      data-scope={objCatalog.objScope.strTenantId}
+      data-value={objCatalog.fnGetValue('activity.status', '启用')}
+      data-values={objCatalog.fnGetValues('activity.status').join(',')}
+    >
+      {objCatalog.arrEntries.length}
+    </output>
+  )
+}
+
+describe('useEnumCatalog', () => {
+  it('exposes the complete catalog and common lookup helpers', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objSource = fnCreateEnumCatalogSource(async () => ({
+      enums: {
+        'activity.status': [{ label: '启用', sortOrder: 1, value: 'active' }],
+      },
+      locale: 'zh-CN',
+      version: 'v1',
+    }))
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <EnumCatalogProvider
+          objScope={{ strTenantId: 'tenant-a' }}
+          objSource={objSource}
+        >
+          <EnumCatalogConsumer />
+        </EnumCatalogProvider>
+      </QueryClientProvider>
+    )
+    const objOutput = objScreen.getByRole('status')
+
+    await expect.element(objOutput).toHaveTextContent('1')
+    await expect
+      .element(objOutput)
+      .toHaveAttribute('data-keys', 'activity.status')
+    await expect.element(objOutput).toHaveAttribute('data-has-key', 'true')
+    await expect.element(objOutput).toHaveAttribute('data-label', '启用')
+    await expect
+      .element(objOutput)
+      .toHaveAttribute('data-labels', 'disabled,启用')
+    await expect.element(objOutput).toHaveAttribute('data-scope', 'tenant-a')
+    await expect.element(objOutput).toHaveAttribute('data-value', 'active')
+    await expect.element(objOutput).toHaveAttribute('data-values', 'active')
+  })
+})

package/template/tests/unit/api/hooks/error.test.ts

@@ -0,0 +1,168 @@
+import {
+  fnConfigureObservability,
+  type IObservabilityAdapter,
+} from '@/observability'
+import {
+  AxiosError,
+  AxiosHeaders,
+  CanceledError,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios'
+import { describe, expect, it, vi } from 'vitest'
+import { ApiError } from '@/api/ApiError'
+import { fnCreateErrorHook } from '@/api/hooks/error'
+
+function fnCreateRequestConfig(strRequestId = 'client-request-1') {
+  return {
+    headers: new AxiosHeaders(),
+    strRequestId,
+    url: '/api/example',
+  } as InternalAxiosRequestConfig
+}
+
+function fnCreateHttpError({
+  nStatus = 422,
+  objData,
+  objHeaders = new AxiosHeaders(),
+}: {
+  nStatus?: number
+  objData: object
+  objHeaders?: AxiosHeaders
+}) {
+  const objConfig = fnCreateRequestConfig()
+  const objResponse: AxiosResponse = {
+    config: objConfig,
+    data: objData,
+    headers: objHeaders,
+    status: nStatus,
+    statusText: 'Request Failed',
+  }
+  return new AxiosError(
+    'Request failed',
+    'ERR_BAD_REQUEST',
+    objConfig,
+    undefined,
+    objResponse
+  )
+}
+
+describe('API error hook', () => {
+  it('normalizes HTTP failures without exposing the Axios request config', async () => {
+    const fnOnError = vi.fn()
+    const objTransportError = fnCreateHttpError({
+      objData: {
+        code: 'VALIDATION_FAILED',
+        details: { phone: 'invalid' },
+        message: '请检查表单字段',
+      },
+      objHeaders: new AxiosHeaders({
+        'x-request-id': 'server-request-1',
+      }),
+    })
+
+    try {
+      await fnCreateErrorHook({ fnOnError })(objTransportError)
+      throw new Error('Expected API request to fail')
+    } catch (objError) {
+      expect(objError).toBeInstanceOf(ApiError)
+      if (objError instanceof ApiError) {
+        expect(objError).toMatchObject({
+          bRetriable: false,
+          message: '请检查表单字段',
+          nStatus: 422,
+          objDetails: { phone: 'invalid' },
+          strCode: 'VALIDATION_FAILED',
+          strKind: 'http',
+          strRequestId: 'server-request-1',
+        })
+        expect('config' in objError).toBe(false)
+        expect('response' in objError).toBe(false)
+      }
+    }
+
+    expect(fnOnError).toHaveBeenCalledOnce()
+  })
+
+  it('marks network and server failures as retriable', async () => {
+    const objConfig = fnCreateRequestConfig('network-request-1')
+    const objNetworkError = new AxiosError(
+      'Network Error',
+      'ERR_NETWORK',
+      objConfig
+    )
+    const objServerError = fnCreateHttpError({
+      nStatus: 503,
+      objData: { message: '服务暂不可用' },
+    })
+
+    await expect(fnCreateErrorHook()(objNetworkError)).rejects.toMatchObject({
+      bRetriable: true,
+      message: '网络连接异常，请稍后重试',
+      strCode: 'ERR_NETWORK',
+      strKind: 'network',
+      strRequestId: 'network-request-1',
+    })
+    await expect(fnCreateErrorHook()(objServerError)).rejects.toMatchObject({
+      bRetriable: true,
+      nStatus: 503,
+    })
+  })
+
+  it('preserves cancellation semantics and does not report it as an error', async () => {
+    const fnOnError = vi.fn()
+    const objCanceledError = new CanceledError('request canceled')
+
+    await expect(
+      fnCreateErrorHook({ fnOnError })(objCanceledError)
+    ).rejects.toBe(objCanceledError)
+    expect(fnOnError).not.toHaveBeenCalled()
+  })
+
+  it('uses a valid request ID from the response payload as a fallback', async () => {
+    const objTransportError = fnCreateHttpError({
+      objData: {
+        code: 'FAILED',
+        message: '请求失败',
+        requestId: 'payload-request-1',
+      },
+    })
+
+    await expect(fnCreateErrorHook()(objTransportError)).rejects.toMatchObject({
+      strRequestId: 'payload-request-1',
+    })
+  })
+
+  it('reports API errors independently from the user notification setting', async () => {
+    const fnCaptureEvent = vi.fn<IObservabilityAdapter['fnCaptureEvent']>()
+    fnConfigureObservability({
+      bEnabled: true,
+      objAdapter: { fnCaptureEvent },
+      objRelease: {
+        strVersion: '1.2.3',
+        strCommit: 'abc123',
+        strBuildTime: '2026-08-26T08:00:00.000Z',
+        strEnvironment: 'test',
+      },
+    })
+    const objTransportError = fnCreateHttpError({
+      objData: { code: 'FAILED', message: '请求失败' },
+    })
+    if (!objTransportError.config) throw new Error('Expected Axios config')
+    objTransportError.config.bShowError = false
+
+    await expect(fnCreateErrorHook()(objTransportError)).rejects.toBeInstanceOf(
+      ApiError
+    )
+    expect(fnCaptureEvent).toHaveBeenCalledOnce()
+    expect(fnCaptureEvent.mock.calls[0]?.[0]).toMatchObject({
+      strName: 'api.request_failed',
+      strSource: 'api',
+      objAttributes: {
+        nStatus: 422,
+        strCode: 'FAILED',
+        strRequestId: 'client-request-1',
+      },
+    })
+  })
+})