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

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

@@ -0,0 +1,170 @@
+import {
+  AxiosHeaders,
+  CanceledError,
+  type InternalAxiosRequestConfig,
+} from 'axios'
+import { describe, expect, it, vi } from 'vitest'
+import { fnCreateRequestHook } from '@/api/hooks/request'
+
+function fnCreateRequestConfig(strUrl = '/api/profile') {
+  return {
+    headers: new AxiosHeaders(),
+    method: 'get',
+    url: strUrl,
+  } as InternalAxiosRequestConfig
+}
+
+describe('API request hook', () => {
+  it('adds a bearer token to authenticated requests', async () => {
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'access-token',
+    })
+
+    const objConfig = await fnRequestHook(fnCreateRequestConfig())
+
+    expect(objConfig.headers.get('Authorization')).toBe('Bearer access-token')
+  })
+
+  it('adds a stable request ID before sending the request', async () => {
+    const fnRequestHook = fnCreateRequestHook({
+      fnCreateRequestId: () => 'client-request-1',
+    })
+
+    const objConfig = await fnRequestHook(fnCreateRequestConfig())
+
+    expect(objConfig.strRequestId).toBe('client-request-1')
+    expect(objConfig.headers.get('X-Request-ID')).toBe('client-request-1')
+  })
+
+  it('preserves an existing valid request ID', async () => {
+    const objRequestConfig = fnCreateRequestConfig()
+    objRequestConfig.headers.set('X-Request-ID', 'upstream-request-1')
+    const fnRequestHook = fnCreateRequestHook({
+      fnCreateRequestId: () => 'replacement-request-1',
+    })
+
+    const objConfig = await fnRequestHook(objRequestConfig)
+
+    expect(objConfig.strRequestId).toBe('upstream-request-1')
+    expect(objConfig.headers.get('X-Request-ID')).toBe('upstream-request-1')
+  })
+
+  it('maps an idempotency key from generated-client config to the header', async () => {
+    const objRequestConfig = fnCreateRequestConfig()
+    objRequestConfig.strIdempotencyKey = 'write-intent-0001'
+    const fnRequestHook = fnCreateRequestHook()
+
+    const objConfig = await fnRequestHook(objRequestConfig)
+
+    expect(objConfig.headers.get('Idempotency-Key')).toBe('write-intent-0001')
+  })
+
+  it('rejects an unsafe idempotency key before sending the request', async () => {
+    const objRequestConfig = fnCreateRequestConfig()
+    objRequestConfig.strIdempotencyKey = 'unsafe key\nvalue'
+    const fnRequestHook = fnCreateRequestHook()
+
+    await expect(fnRequestHook(objRequestConfig)).rejects.toThrow('幂等键必须')
+  })
+
+  it('does not add a token to anonymous requests', async () => {
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'access-token',
+    })
+
+    const objConfig = await fnRequestHook(fnCreateRequestConfig('/api/login'))
+
+    expect(objConfig.headers.has('Authorization')).toBe(false)
+  })
+
+  it('recognizes anonymous requests with query parameters', async () => {
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'access-token',
+    })
+
+    const objConfig = await fnRequestHook(
+      fnCreateRequestConfig('/api/login?redirect=%2Fdashboard')
+    )
+
+    expect(objConfig.headers.has('Authorization')).toBe(false)
+  })
+
+  it('merges concurrent token refresh requests', async () => {
+    let nRefreshCount = 0
+    let fnResolveRefresh: (strToken: string) => void = () => undefined
+    const objRefreshGate = new Promise<string>((fnResolve) => {
+      fnResolveRefresh = fnResolve
+    })
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'expired-token',
+      fnIsAccessTokenExpired: () => true,
+      fnRefreshAccessToken: () => {
+        nRefreshCount += 1
+        return objRefreshGate
+      },
+    })
+
+    const objFirstRequest = fnRequestHook(fnCreateRequestConfig('/api/one'))
+    const objSecondRequest = fnRequestHook(fnCreateRequestConfig('/api/two'))
+    fnResolveRefresh('refreshed-token')
+
+    const [objFirstConfig, objSecondConfig] = await Promise.all([
+      objFirstRequest,
+      objSecondRequest,
+    ])
+
+    expect(nRefreshCount).toBe(1)
+    expect(objFirstConfig.headers.get('Authorization')).toBe(
+      'Bearer refreshed-token'
+    )
+    expect(objSecondConfig.headers.get('Authorization')).toBe(
+      'Bearer refreshed-token'
+    )
+  })
+
+  it('stops protected requests when token refresh returns no token', async () => {
+    const fnOnUnauthorized = vi.fn()
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'expired-token',
+      fnIsAccessTokenExpired: () => true,
+      fnRefreshAccessToken: async () => null,
+      fnOnUnauthorized,
+    })
+
+    await expect(
+      fnRequestHook(fnCreateRequestConfig('/api/profile'))
+    ).rejects.toMatchObject({ code: 'ERR_UNAUTHORIZED' })
+    expect(fnOnUnauthorized).toHaveBeenCalledOnce()
+  })
+
+  it('stops expired protected requests when no refresh handler exists', async () => {
+    const fnOnUnauthorized = vi.fn()
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'expired-token',
+      fnIsAccessTokenExpired: () => true,
+      fnOnUnauthorized,
+    })
+
+    await expect(
+      fnRequestHook(fnCreateRequestConfig('/api/profile'))
+    ).rejects.toMatchObject({ code: 'ERR_UNAUTHORIZED' })
+    expect(fnOnUnauthorized).toHaveBeenCalledOnce()
+  })
+
+  it('does not sign out a newer session when an old refresh is canceled', async () => {
+    const fnOnUnauthorized = vi.fn()
+    const fnRequestHook = fnCreateRequestHook({
+      fnGetAccessToken: () => 'expired-token',
+      fnIsAccessTokenExpired: () => true,
+      fnRefreshAccessToken: async () => {
+        throw new CanceledError('session changed')
+      },
+      fnOnUnauthorized,
+    })
+
+    await expect(
+      fnRequestHook(fnCreateRequestConfig('/api/profile'))
+    ).rejects.toMatchObject({ code: 'ERR_CANCELED' })
+    expect(fnOnUnauthorized).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,46 @@
+import {
+  AxiosHeaders,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios'
+import { describe, expect, it } from 'vitest'
+import { fnCreateResponseHook } from '@/api/hooks/response'
+
+function fnCreateResponse(
+  objHeaders: AxiosHeaders,
+  strClientRequestId: string
+): AxiosResponse {
+  const objConfig = {
+    headers: new AxiosHeaders(),
+    strRequestId: strClientRequestId,
+  } as InternalAxiosRequestConfig
+  return {
+    config: objConfig,
+    data: null,
+    headers: objHeaders,
+    status: 200,
+    statusText: 'OK',
+  }
+}
+
+describe('API response hook', () => {
+  it('prefers the server request ID and exposes it on the response', async () => {
+    const objResponse = fnCreateResponse(
+      new AxiosHeaders({ 'x-request-id': 'server-request-1' }),
+      'client-request-1'
+    )
+
+    const objResult = await fnCreateResponseHook()(objResponse)
+
+    expect(objResult.strRequestId).toBe('server-request-1')
+    expect(objResult.config.strRequestId).toBe('server-request-1')
+  })
+
+  it('falls back to the client request ID', async () => {
+    const objResponse = fnCreateResponse(new AxiosHeaders(), 'client-request-1')
+
+    const objResult = await fnCreateResponseHook()(objResponse)
+
+    expect(objResult.strRequestId).toBe('client-request-1')
+  })
+})

package/template/tests/unit/api/metadata/MetadataProvider.test.tsx

@@ -0,0 +1,102 @@
+import { useState } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { userEvent } from 'vitest/browser'
+import {
+  fnCreateEnumCatalogSource,
+  type IEnumCatalogRequestContext,
+} from '@/api/enums'
+import { MetadataProvider } from '@/api/metadata'
+import {
+  fnCreateGlobalParameterSource,
+  type IGlobalParameterRequestContext,
+} from '@/api/parameters'
+
+describe('metadata initialization orchestration', () => {
+  it('keeps children available when one independent resource fails', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const fnEnumRequest = vi.fn().mockResolvedValue({
+      enums: {},
+      locale: 'zh-CN',
+      version: 'v1',
+    })
+    const fnParameterRequest = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('参数服务暂不可用'))
+      .mockResolvedValue({
+        locale: 'zh-CN',
+        parameters: {},
+        version: 'v2',
+      })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <MetadataProvider
+          objEnumCatalogSource={fnCreateEnumCatalogSource(fnEnumRequest)}
+          objGlobalParameterSource={fnCreateGlobalParameterSource(
+            fnParameterRequest
+          )}
+        >
+          <p>业务页面始终可用</p>
+        </MetadataProvider>
+      </QueryClientProvider>
+    )
+
+    await expect.element(objScreen.getByText('业务页面始终可用')).toBeVisible()
+    await expect.poll(() => fnEnumRequest).toHaveBeenCalledTimes(1)
+    await expect.poll(() => fnParameterRequest).toHaveBeenCalledTimes(1)
+  })
+
+  it('reloads both independent resources when the language changes', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const fnEnumRequest = vi.fn(
+      async (objContext: IEnumCatalogRequestContext) => ({
+        enums: {},
+        locale: objContext.strLocale,
+        version: objContext.strLocale,
+      })
+    )
+    const fnParameterRequest = vi.fn(
+      async (objContext: IGlobalParameterRequestContext) => ({
+        locale: objContext.strLocale,
+        parameters: {},
+        version: objContext.strLocale,
+      })
+    )
+
+    function LocaleHarness() {
+      const [strLocale, fnSetLocale] = useState<'en-US' | 'zh-CN'>('zh-CN')
+      return (
+        <MetadataProvider
+          objEnumCatalogSource={fnCreateEnumCatalogSource(fnEnumRequest)}
+          objGlobalParameterSource={fnCreateGlobalParameterSource(
+            fnParameterRequest
+          )}
+          strLocale={strLocale}
+        >
+          <p>业务页面始终可用</p>
+          <button onClick={() => fnSetLocale('en-US')}>切换语言</button>
+        </MetadataProvider>
+      )
+    }
+
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <LocaleHarness />
+      </QueryClientProvider>
+    )
+    await expect.poll(() => fnEnumRequest).toHaveBeenCalledTimes(1)
+    await expect.poll(() => fnParameterRequest).toHaveBeenCalledTimes(1)
+
+    await userEvent.click(objScreen.getByRole('button', { name: '切换语言' }))
+
+    await expect.poll(() => fnEnumRequest).toHaveBeenCalledTimes(2)
+    await expect.poll(() => fnParameterRequest).toHaveBeenCalledTimes(2)
+    expect(fnEnumRequest.mock.calls[1]?.[0].strLocale).toBe('en-US')
+    expect(fnParameterRequest.mock.calls[1]?.[0].strLocale).toBe('en-US')
+  })
+})

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

@@ -0,0 +1,147 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  fnCreateGlobalParameterScope,
+  fnCreateGlobalParameterSource,
+  fnGetBooleanGlobalParameter,
+  fnGetGlobalParameterKeys,
+  fnGetGlobalParameterValue,
+  fnGetJsonGlobalParameter,
+  fnGetNumberGlobalParameter,
+  fnGetStringGlobalParameter,
+  GlobalParameterError,
+} from '@/api/parameters'
+
+const objChineseScope = fnCreateGlobalParameterScope('zh-CN')
+
+describe('global parameter catalog source', () => {
+  it('validates every supported type and exposes common lookup helpers', async () => {
+    const fnRequest = vi.fn().mockResolvedValue({
+      locale: 'zh-CN',
+      parameters: {
+        'application.allowExport': { type: 'boolean', value: true },
+        'application.maxExportRows': { type: 'number', value: 5_000 },
+        'application.policy': {
+          type: 'json',
+          value: { arrFormats: ['csv', 'xlsx'] },
+        },
+        'application.supportName': { type: 'string', value: '平台支持' },
+      },
+      version: 'v1',
+    })
+    const objSource = fnCreateGlobalParameterSource(fnRequest)
+    const objSignal = new AbortController().signal
+
+    const objCatalog = await objSource.fnLoadCatalog({
+      objScope: objChineseScope,
+      objSignal,
+      strLocale: 'zh-CN',
+    })
+
+    expect(fnRequest).toHaveBeenCalledWith({
+      objScope: objChineseScope,
+      objSignal,
+      strLocale: 'zh-CN',
+    })
+    expect(fnGetGlobalParameterKeys(objCatalog)).toEqual([
+      'application.allowExport',
+      'application.maxExportRows',
+      'application.policy',
+      'application.supportName',
+    ])
+    expect(
+      fnGetBooleanGlobalParameter(objCatalog, 'application.allowExport')
+    ).toBe(true)
+    expect(
+      fnGetNumberGlobalParameter(objCatalog, 'application.maxExportRows')
+    ).toBe(5_000)
+    expect(
+      fnGetStringGlobalParameter(objCatalog, 'application.supportName')
+    ).toBe('平台支持')
+    expect(fnGetGlobalParameterValue(objCatalog, 'missing')).toBeUndefined()
+    const objPolicy = fnGetJsonGlobalParameter(objCatalog, 'application.policy')
+    expect(objPolicy).toEqual({ arrFormats: ['csv', 'xlsx'] })
+    expect(Object.isFrozen(objPolicy)).toBe(true)
+    const arrPolicyValues =
+      objPolicy && typeof objPolicy === 'object' ? Object.values(objPolicy) : []
+    expect(Object.isFrozen(arrPolicyValues[0])).toBe(true)
+  })
+
+  it('rejects values that do not match the backend declared type', async () => {
+    const objSource = fnCreateGlobalParameterSource(async () => ({
+      locale: 'zh-CN',
+      parameters: {
+        'application.maxExportRows': { type: 'number', value: '5000' },
+      },
+      version: 'v1',
+    }))
+
+    await expect(
+      objSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toMatchObject({
+      strCode: 'INVALID_PARAMETER',
+      strParameterKey: 'application.maxExportRows',
+    })
+  })
+
+  it('fails loudly when a consumer expects the wrong parameter type', async () => {
+    const objSource = fnCreateGlobalParameterSource(async () => ({
+      locale: 'zh-CN',
+      parameters: {
+        'application.maxExportRows': { type: 'number', value: 5_000 },
+      },
+      version: 'v1',
+    }))
+    const objCatalog = await objSource.fnLoadCatalog({
+      objScope: objChineseScope,
+      objSignal: new AbortController().signal,
+      strLocale: 'zh-CN',
+    })
+
+    expect(() =>
+      fnGetStringGlobalParameter(objCatalog, 'application.maxExportRows')
+    ).toThrowError(
+      expect.objectContaining({
+        strCode: 'TYPE_MISMATCH',
+        strParameterKey: 'application.maxExportRows',
+      })
+    )
+  })
+
+  it('rejects invalid JSON and locale mismatches', async () => {
+    const objInvalidJsonSource = fnCreateGlobalParameterSource(async () => ({
+      locale: 'zh-CN',
+      parameters: {
+        'application.policy': {
+          type: 'json',
+          value: { nInvalid: Number.NaN },
+        },
+      },
+      version: 'v1',
+    }))
+
+    await expect(
+      objInvalidJsonSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toBeInstanceOf(GlobalParameterError)
+
+    const objEnglishSource = fnCreateGlobalParameterSource(async () => ({
+      locale: 'en-US',
+      parameters: {},
+      version: 'v1',
+    }))
+    await expect(
+      objEnglishSource.fnLoadCatalog({
+        objScope: objChineseScope,
+        objSignal: new AbortController().signal,
+        strLocale: 'zh-CN',
+      })
+    ).rejects.toMatchObject({ strCode: 'LOCALE_MISMATCH' })
+  })
+})

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

@@ -0,0 +1,78 @@
+import { QueryClient } from '@tanstack/react-query'
+import { describe, expect, it } from 'vitest'
+import {
+  fnCreateGlobalParameterScope,
+  fnGlobalParameterQueryKey,
+  fnInvalidateGlobalParameters,
+  type IGlobalParameterCatalog,
+  type IGlobalParameterScope,
+} from '@/api/parameters'
+
+function fnCreateCatalog(
+  strLocale: IGlobalParameterCatalog['locale']
+): IGlobalParameterCatalog {
+  return {
+    locale: strLocale,
+    parameters: new Map(),
+    version: 'v1',
+  }
+}
+
+describe('global parameter query cache', () => {
+  it('uses the session generation as the authorization cache version', () => {
+    expect(
+      fnCreateGlobalParameterScope('zh-CN', { nSessionGeneration: 3 })
+    ).toEqual({ nSessionGeneration: 3, strLocale: 'zh-CN' })
+    expect(() =>
+      fnCreateGlobalParameterScope('zh-CN', { nSessionGeneration: -1 })
+    ).toThrow('会话版本必须是非负整数')
+  })
+
+  it('isolates tenant scopes and invalidates one exact scope', async () => {
+    const objQueryClient = new QueryClient()
+    const objTenantAScope: IGlobalParameterScope = {
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-a',
+    }
+    const objTenantBScope: IGlobalParameterScope = {
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-b',
+    }
+    const arrTenantAKey = fnGlobalParameterQueryKey(objTenantAScope)
+    const arrTenantBKey = fnGlobalParameterQueryKey(objTenantBScope)
+    objQueryClient.setQueryData(arrTenantAKey, fnCreateCatalog('zh-CN'))
+    objQueryClient.setQueryData(arrTenantBKey, fnCreateCatalog('zh-CN'))
+
+    await fnInvalidateGlobalParameters(objQueryClient, objTenantAScope)
+
+    expect(objQueryClient.getQueryState(arrTenantAKey)?.isInvalidated).toBe(
+      true
+    )
+    expect(objQueryClient.getQueryState(arrTenantBKey)?.isInvalidated).toBe(
+      false
+    )
+  })
+
+  it('invalidates every scope under one locale without touching others', async () => {
+    const objQueryClient = new QueryClient()
+    const arrChineseKey = fnGlobalParameterQueryKey({
+      strLocale: 'zh-CN',
+      strTenantId: 'tenant-a',
+    })
+    const arrEnglishKey = fnGlobalParameterQueryKey({
+      strLocale: 'en-US',
+      strTenantId: 'tenant-a',
+    })
+    objQueryClient.setQueryData(arrChineseKey, fnCreateCatalog('zh-CN'))
+    objQueryClient.setQueryData(arrEnglishKey, fnCreateCatalog('en-US'))
+
+    await fnInvalidateGlobalParameters(objQueryClient, 'zh-CN')
+
+    expect(objQueryClient.getQueryState(arrChineseKey)?.isInvalidated).toBe(
+      true
+    )
+    expect(objQueryClient.getQueryState(arrEnglishKey)?.isInvalidated).toBe(
+      false
+    )
+  })
+})

package/template/tests/unit/api/parameters/useGlobalParameter.test.tsx

@@ -0,0 +1,89 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import {
+  fnCreateGlobalParameterSource,
+  GlobalParameterProvider,
+  useBooleanGlobalParameter,
+  useGlobalParameterCatalog,
+  useNumberGlobalParameter,
+} from '@/api/parameters'
+
+function GlobalParameterConsumer() {
+  const objCatalog = useGlobalParameterCatalog()
+  const objAllowExport = useBooleanGlobalParameter('application.allowExport')
+  const objMaxExportRows = useNumberGlobalParameter('application.maxExportRows')
+
+  return (
+    <output
+      data-allow-export={String(objAllowExport.value)}
+      data-configured={String(objCatalog.bIsConfigured)}
+      data-has-key={String(objCatalog.fnHasKey('application.allowExport'))}
+      data-keys={objCatalog.arrKeys.join(',')}
+      data-max-export-rows={String(objMaxExportRows.value)}
+      data-missing={String(objMaxExportRows.bIsMissing)}
+      data-scope={objCatalog.objScope.strTenantId}
+    >
+      {objCatalog.bIsLoading ? 'loading' : objCatalog.strVersion}
+    </output>
+  )
+}
+
+describe('global parameter React access', () => {
+  it('shares one request and exposes typed values to every consumer', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const fnRequest = vi.fn().mockResolvedValue({
+      locale: 'zh-CN',
+      parameters: {
+        'application.allowExport': { type: 'boolean', value: true },
+        'application.maxExportRows': { type: 'number', value: 5_000 },
+      },
+      version: 'v1',
+    })
+    const objSource = fnCreateGlobalParameterSource(fnRequest)
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <GlobalParameterProvider
+          objScope={{ strTenantId: 'tenant-a' }}
+          objSource={objSource}
+        >
+          <GlobalParameterConsumer />
+        </GlobalParameterProvider>
+      </QueryClientProvider>
+    )
+    const objOutput = objScreen.getByRole('status')
+
+    await expect.element(objOutput).toHaveTextContent('v1')
+    await expect.element(objOutput).toHaveAttribute('data-allow-export', 'true')
+    await expect
+      .element(objOutput)
+      .toHaveAttribute('data-max-export-rows', '5000')
+    await expect.element(objOutput).toHaveAttribute('data-has-key', 'true')
+    await expect.element(objOutput).toHaveAttribute('data-missing', 'false')
+    await expect.element(objOutput).toHaveAttribute('data-scope', 'tenant-a')
+    expect(fnRequest).toHaveBeenCalledTimes(1)
+  })
+
+  it('stays idle and reports unconfigured when no source is wired', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <GlobalParameterProvider>
+          <GlobalParameterConsumer />
+        </GlobalParameterProvider>
+      </QueryClientProvider>
+    )
+    const objOutput = objScreen.getByRole('status')
+
+    await expect.element(objOutput).toHaveTextContent('')
+    await expect
+      .element(objOutput)
+      .toHaveAttribute('data-allow-export', 'undefined')
+    await expect.element(objOutput).toHaveAttribute('data-configured', 'false')
+    await expect.element(objOutput).toHaveAttribute('data-missing', 'false')
+  })
+})