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

package/template/tests/unit/api/authSession.test.ts

@@ -0,0 +1,289 @@
+import type { IAuthApiClient } from '@/api'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  AuthIdentityError,
+  fnEstablishAuthSessionFromToken,
+  fnRefreshAuthSession,
+  fnSignInWithCredentials,
+  fnSignOutAuthSession,
+} from '@/api/authSession'
+import { useAuthStore } from '@/stores/authStore'
+
+function fnCreateAuthApi(strRole?: string) {
+  const fnLogin = vi.fn().mockResolvedValue({
+    strAccessToken: 'access-token',
+    strRefreshToken: 'refresh-token',
+    nExpiresIn: 600,
+    nRefreshIdleExpiresIn: 86_400,
+    ...(strRole
+      ? {
+          objUser: {
+            strId: 'user-1',
+            strMaskedPhone: '138****0000',
+            strNickname: '后台管理员',
+            strRole,
+          },
+        }
+      : {}),
+  })
+  const fnLogout = vi.fn().mockResolvedValue(undefined)
+  const fnRefresh = vi.fn().mockResolvedValue({
+    strAccessToken: 'refreshed-access-token',
+    strRefreshToken: 'refreshed-refresh-token',
+    nExpiresIn: 600,
+    nRefreshIdleExpiresIn: 86_400,
+  })
+  const objApiClient = {
+    fnFirstPartyLogin: fnLogin,
+    fnSignOut: fnLogout,
+    fnRefreshToken: fnRefresh,
+  } satisfies IAuthApiClient
+
+  return { objApiClient, fnLogin, fnLogout, fnRefresh }
+}
+
+describe('application authentication', () => {
+  beforeEach(() => {
+    useAuthStore.getState().fnClearSession()
+  })
+
+  it('creates a session from the generated login response', async () => {
+    const { objApiClient, fnLogin } = fnCreateAuthApi('admin')
+
+    await fnSignInWithCredentials(
+      { strPhone: '13800000000', strPassword: 'password' },
+      objApiClient
+    )
+
+    expect(fnLogin).toHaveBeenCalledWith(
+      expect.objectContaining({
+        strAudience: 'admin-api',
+        strClientId: 'react-admin',
+        strPassword: 'password',
+        strPhone: '13800000000',
+      })
+    )
+    expect(useAuthStore.getState()).toMatchObject({
+      bIsAuthenticated: true,
+      strAccessToken: 'access-token',
+      objUser: {
+        arrPermissions: [],
+        strDisplayName: '后台管理员',
+        strRole: 'admin',
+      },
+    })
+  })
+
+  it('establishes the same session from an SSO or MFA completion result', async () => {
+    const { objApiClient } = fnCreateAuthApi('admin')
+
+    const objUser = await fnEstablishAuthSessionFromToken(
+      {
+        nExpiresIn: 600,
+        objUser: {
+          arrPermissions: ['dashboard:read'],
+          arrRoleCodes: ['admin'],
+          strId: 'sso-user',
+          strMaskedPhone: '139****0000',
+          strNickname: '企业管理员',
+          strRole: 'admin',
+        },
+        strAccessToken: 'sso-access-token',
+        strRefreshToken: 'sso-refresh-token',
+      },
+      '',
+      objApiClient
+    )
+
+    expect(objUser).toMatchObject({
+      arrPermissions: ['dashboard:read'],
+      strAccount: '139****0000',
+      strId: 'sso-user',
+    })
+    expect(useAuthStore.getState()).toMatchObject({
+      bIsAuthenticated: true,
+      strAccessToken: 'sso-access-token',
+      strRefreshToken: 'sso-refresh-token',
+    })
+  })
+
+  it('accepts a server-authenticated identity without hardcoded role policy', async () => {
+    const { objApiClient, fnLogout } = fnCreateAuthApi('member')
+
+    await fnSignInWithCredentials(
+      { strPhone: '13800000000', strPassword: 'password' },
+      objApiClient
+    )
+
+    expect(fnLogout).not.toHaveBeenCalled()
+    expect(useAuthStore.getState()).toMatchObject({
+      bIsAuthenticated: true,
+      objUser: { strRole: 'member' },
+    })
+  })
+
+  it('rejects and revokes a login response without an identity', async () => {
+    const { objApiClient, fnLogout } = fnCreateAuthApi()
+
+    await expect(
+      fnSignInWithCredentials(
+        { strPhone: '13800000000', strPassword: 'password' },
+        objApiClient
+      )
+    ).rejects.toBeInstanceOf(AuthIdentityError)
+
+    expect(fnLogout).toHaveBeenCalledWith({ strRefreshToken: 'refresh-token' })
+    expect(useAuthStore.getState().bIsAuthenticated).toBe(false)
+  })
+
+  it('clears the local session before revoking the refresh token', async () => {
+    const { objApiClient, fnLogout } = fnCreateAuthApi('admin')
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['admin'],
+        strId: 'user-1',
+        strAccount: '138****0000',
+        strDisplayName: '管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+      nAccessTokenExpiresAt: Date.now() + 60_000,
+      nRefreshTokenExpiresAt: Date.now() + 60_000,
+    })
+
+    await fnSignOutAuthSession(objApiClient)
+
+    expect(useAuthStore.getState().bIsAuthenticated).toBe(false)
+    expect(fnLogout).toHaveBeenCalledWith({ strRefreshToken: 'refresh-token' })
+  })
+
+  it('ignores a refresh response after the active account changes', async () => {
+    let fnResolveRefresh: (objValue: unknown) => void = () => undefined
+    const { objApiClient, fnRefresh } = fnCreateAuthApi('admin')
+    const objRefreshGate = new Promise<unknown>((fnResolve) => {
+      fnResolveRefresh = fnResolve
+    })
+    fnRefresh.mockReturnValueOnce(
+      objRefreshGate as ReturnType<typeof fnRefresh>
+    )
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['admin'],
+        strId: 'old-user',
+        strAccount: 'old-account',
+        strDisplayName: '旧管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'old-access-token',
+      strRefreshToken: 'old-refresh-token',
+      nAccessTokenExpiresAt: Date.now() - 1,
+      nRefreshTokenExpiresAt: Date.now() + 60_000,
+    })
+
+    const objRefreshRequest = fnRefreshAuthSession(objApiClient)
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['admin'],
+        strId: 'new-user',
+        strAccount: 'new-account',
+        strDisplayName: '新管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'new-access-token',
+      strRefreshToken: 'new-refresh-token',
+      nAccessTokenExpiresAt: Date.now() + 60_000,
+      nRefreshTokenExpiresAt: Date.now() + 60_000,
+    })
+    fnResolveRefresh({
+      strAccessToken: 'stale-access-token',
+      strRefreshToken: 'stale-refresh-token',
+      nExpiresIn: 600,
+    })
+
+    await expect(objRefreshRequest).rejects.toMatchObject({
+      code: 'ERR_CANCELED',
+    })
+    expect(useAuthStore.getState()).toMatchObject({
+      objUser: { strId: 'new-user' },
+      strAccessToken: 'new-access-token',
+      strRefreshToken: 'new-refresh-token',
+    })
+  })
+
+  it('refreshes the permission identity and its session generation', async () => {
+    const { objApiClient, fnRefresh } = fnCreateAuthApi('admin')
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['feature:item:read'],
+        arrRoleCodes: ['admin'],
+        strId: 'user-1',
+        strAccount: '138****0000',
+        strDisplayName: '管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+      nAccessTokenExpiresAt: Date.now() - 1,
+      nRefreshTokenExpiresAt: Date.now() + 60_000,
+    })
+    const nPreviousGeneration = useAuthStore.getState().nSessionGeneration
+    fnRefresh.mockResolvedValueOnce({
+      strAccessToken: 'refreshed-access-token',
+      strRefreshToken: 'refreshed-refresh-token',
+      nExpiresIn: 600,
+      objUser: {
+        arrPermissions: ['feature:item:write', 'feature:item:write'],
+        arrRoleCodes: ['admin'],
+        strRole: 'ADMIN',
+      },
+    })
+
+    await fnRefreshAuthSession(objApiClient)
+
+    expect(useAuthStore.getState()).toMatchObject({
+      nSessionGeneration: nPreviousGeneration + 1,
+      objUser: {
+        arrPermissions: ['feature:item:write'],
+        strAccount: '138****0000',
+        strId: 'user-1',
+        strRole: 'admin',
+      },
+      strAccessToken: 'refreshed-access-token',
+    })
+  })
+
+  it('applies a refreshed role without treating it as a frontend access boundary', async () => {
+    const { objApiClient, fnRefresh } = fnCreateAuthApi('admin')
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['admin'],
+        strId: 'user-1',
+        strAccount: '138****0000',
+        strDisplayName: '管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+      nAccessTokenExpiresAt: Date.now() - 1,
+      nRefreshTokenExpiresAt: Date.now() + 60_000,
+    })
+    fnRefresh.mockResolvedValueOnce({
+      strAccessToken: 'refreshed-access-token',
+      strRefreshToken: 'refreshed-refresh-token',
+      objUser: { strRole: 'member' },
+    })
+
+    await expect(fnRefreshAuthSession(objApiClient)).resolves.toBe(
+      'refreshed-access-token'
+    )
+    expect(useAuthStore.getState()).toMatchObject({
+      bIsAuthenticated: true,
+      objUser: { strRole: 'member' },
+    })
+  })
+})

package/template/tests/unit/api/clients/configureApiClient.test.ts

@@ -0,0 +1,198 @@
+import axios, { AxiosError, type InternalAxiosRequestConfig } from 'axios'
+import { toast } from 'sonner'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiError } from '@/api/ApiError'
+import {
+  fnConfigureApiClient,
+  fnShowApiError,
+} from '@/api/clients/configureApiClient'
+import { useAuthStore } from '@/stores/authStore'
+
+vi.mock('sonner', () => ({
+  toast: { error: vi.fn() },
+}))
+
+describe('generated API client configuration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    useAuthStore.getState().fnClearSession()
+  })
+
+  it('installs the token request hook on generated clients', async () => {
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['admin'],
+        strId: 'user-1',
+        strAccount: '138****0000',
+        strDisplayName: '管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+      nAccessTokenExpiresAt: Date.now() + 10 * 60_000,
+      nRefreshTokenExpiresAt: Date.now() + 7 * 24 * 60 * 60_000,
+    })
+    const arrCapturedConfigs: InternalAxiosRequestConfig[] = []
+    const objClient = fnConfigureApiClient({
+      instance: axios.create({
+        adapter: async (objConfig) => {
+          arrCapturedConfigs.push(objConfig)
+          return {
+            config: objConfig,
+            data: null,
+            headers: {},
+            status: 200,
+            statusText: 'OK',
+          }
+        },
+      }),
+    })
+
+    await objClient.instance.get('/protected')
+
+    expect(arrCapturedConfigs[0]?.headers.get('Authorization')).toBe(
+      'Bearer access-token'
+    )
+    expect(arrCapturedConfigs[0]?.validateStatus?.(200)).toBe(true)
+    expect(arrCapturedConfigs[0]?.validateStatus?.(204)).toBe(true)
+    expect(arrCapturedConfigs[0]?.validateStatus?.(299)).toBe(true)
+    expect(arrCapturedConfigs[0]?.validateStatus?.(199)).toBe(false)
+    expect(arrCapturedConfigs[0]?.validateStatus?.(300)).toBe(false)
+    expect(arrCapturedConfigs[0]?.validateStatus?.(401)).toBe(false)
+    expect(arrCapturedConfigs[0]?.validateStatus?.(500)).toBe(false)
+  })
+
+  it('clears the Zustand session after an unauthorized response', async () => {
+    useAuthStore.getState().fnEstablishSession({
+      objUser: {
+        arrPermissions: ['*'],
+        arrRoleCodes: ['admin'],
+        strId: 'user-1',
+        strAccount: '138****0000',
+        strDisplayName: '管理员',
+        strRole: 'admin',
+      },
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+      nAccessTokenExpiresAt: Date.now() + 10 * 60_000,
+      nRefreshTokenExpiresAt: Date.now() + 7 * 24 * 60 * 60_000,
+    })
+    const objClient = fnConfigureApiClient(
+      {
+        instance: axios.create({
+          adapter: async (objConfig) => {
+            throw new AxiosError(
+              'Unauthorized',
+              'ERR_BAD_REQUEST',
+              objConfig,
+              undefined,
+              {
+                config: objConfig,
+                data: { message: '会话已失效' },
+                headers: {},
+                status: 401,
+                statusText: 'Unauthorized',
+              }
+            )
+          },
+        }),
+      },
+      { fnCreateRequestId: () => 'unauthorized-request-1' }
+    )
+
+    await expect(objClient.instance.get('/protected')).rejects.toThrow(
+      '会话已失效'
+    )
+    expect(useAuthStore.getState().bIsAuthenticated).toBe(false)
+    expect(toast.error).toHaveBeenCalledWith('会话已失效', {
+      description: '请求 ID：unauthorized-request-1',
+    })
+  })
+
+  it('shows normalized API errors through the global message handler', async () => {
+    const objClient = fnConfigureApiClient(
+      {
+        instance: axios.create({
+          adapter: async (objConfig) => {
+            throw new AxiosError(
+              'Request failed',
+              'ERR_BAD_RESPONSE',
+              objConfig,
+              undefined,
+              {
+                config: objConfig,
+                data: { message: '接口未返回数据' },
+                headers: {},
+                status: 500,
+                statusText: 'Internal Server Error',
+              }
+            )
+          },
+        }),
+      },
+      {
+        fnCreateRequestId: () => 'failed-request-1',
+        fnIsAccessTokenExpired: () => false,
+      }
+    )
+
+    await expect(objClient.instance.get('/example')).rejects.toMatchObject({
+      message: '接口未返回数据',
+      strCode: 'HTTP_500',
+      strKind: 'http',
+      strRequestId: 'failed-request-1',
+    })
+    expect(toast.error).toHaveBeenCalledWith('接口未返回数据', {
+      description: '请求 ID：failed-request-1',
+    })
+  })
+
+  it('allows requests to suppress the global error message', async () => {
+    const objClient = fnConfigureApiClient(
+      {
+        instance: axios.create({
+          adapter: async (objConfig) => {
+            throw new AxiosError('Request failed', 'ERR_NETWORK', objConfig)
+          },
+        }),
+      },
+      { fnIsAccessTokenExpired: () => false }
+    )
+
+    await expect(
+      objClient.instance.get('/silent', { bShowError: false })
+    ).rejects.toMatchObject({
+      message: '网络连接异常，请稍后重试',
+      strCode: 'ERR_NETWORK',
+      strKind: 'network',
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+  })
+
+  it('deduplicates errors reported by the interceptor and business layer', () => {
+    const objError = new Error('业务响应结构异常')
+
+    fnShowApiError(objError)
+    fnShowApiError(objError)
+
+    expect(toast.error).toHaveBeenCalledTimes(1)
+    expect(toast.error).toHaveBeenCalledWith('业务响应结构异常')
+  })
+
+  it('shows the request ID without exposing transport data', () => {
+    const objError = new ApiError({
+      bRetriable: false,
+      strCode: 'FAILED',
+      strKind: 'http',
+      strMessage: '保存失败',
+      strRequestId: 'visible-request-1',
+    })
+
+    fnShowApiError(objError)
+
+    expect(toast.error).toHaveBeenCalledWith('保存失败', {
+      description: '请求 ID：visible-request-1',
+    })
+  })
+})

package/template/tests/unit/api/demoAuthClient.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { objDemoAuthApiClient, objDemoCredentials } from '@/api/demoAuthClient'
+
+const objSignInInput = {
+  strAudience: 'admin-api',
+  strClientId: 'react-admin',
+  strPassword: objDemoCredentials.strPassword,
+  strPhone: objDemoCredentials.strPhone,
+  strScope: 'openid profile offline_access',
+}
+
+describe('objDemoAuthApiClient', () => {
+  it('creates a complete enterprise demo identity', async () => {
+    const objSession =
+      await objDemoAuthApiClient.fnFirstPartyLogin(objSignInInput)
+
+    expect(objSession.strAccessToken).toMatch(/^demo-access-/)
+    expect(objSession.objUser).toMatchObject({
+      arrPermissions: ['*'],
+      arrRoleCodes: ['platform-admin'],
+      strOrganizationName: '示例企业',
+      strTenantId: 'demo-tenant',
+    })
+  })
+
+  it('rejects credentials that are not part of the demo contract', async () => {
+    await expect(
+      objDemoAuthApiClient.fnFirstPartyLogin({
+        ...objSignInInput,
+        strPassword: 'wrong-password',
+      })
+    ).rejects.toThrow('演示账号或密码不正确。')
+  })
+
+  it('refreshes demo tokens without a backend', async () => {
+    const objSession = await objDemoAuthApiClient.fnRefreshToken(
+      {
+        strClientId: 'react-admin',
+        strRefreshToken: 'demo-refresh-existing',
+      },
+      AbortSignal.timeout(1_000)
+    )
+
+    expect(objSession.strAccessToken).toMatch(/^demo-access-/)
+    expect(objSession.strRefreshToken).toMatch(/^demo-refresh-/)
+  })
+})

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

@@ -0,0 +1,107 @@
+import { QueryClient } from '@tanstack/react-query'
+import { describe, expect, it } from 'vitest'
+import {
+  fnCreateEnumCatalogSource,
+  fnCreateEnumCatalogScope,
+  fnEnumCatalogQueryKey,
+  fnGetCachedEnumCatalog,
+  fnGetEnumEntries,
+  fnGetEnumKeys,
+  fnGetEnumLabel,
+  fnGetEnumLabels,
+  fnGetEnumOption,
+  fnGetEnumOptions,
+  fnGetEnumOptionsByValues,
+  fnGetEnumValue,
+  fnGetEnumValues,
+  fnHasEnumKey,
+} from '@/api/enums'
+
+async function fnCreateCatalog() {
+  const objSource = fnCreateEnumCatalogSource(async () => ({
+    enums: {
+      'user.gender': [
+        { label: '女', sortOrder: 2, value: 'female' },
+        { label: '男', sortOrder: 1, value: 'male' },
+      ],
+      'user.status': [{ label: '启用', sortOrder: 1, value: 'enabled' }],
+      'value.identity': [
+        { label: '数字零', sortOrder: 1, value: 0 },
+        { label: '字符串零', sortOrder: 2, value: '0' },
+        { label: '布尔否', sortOrder: 3, value: false },
+      ],
+    },
+    locale: 'zh-CN',
+    version: 'v1',
+  }))
+
+  return objSource.fnLoadCatalog({
+    objScope: fnCreateEnumCatalogScope('zh-CN'),
+    objSignal: new AbortController().signal,
+    strLocale: 'zh-CN',
+  })
+}
+
+describe('enum catalog access', () => {
+  it('provides complete keys, entries, options and values', async () => {
+    const objCatalog = await fnCreateCatalog()
+
+    expect(fnGetEnumKeys(objCatalog)).toEqual([
+      'user.gender',
+      'user.status',
+      'value.identity',
+    ])
+    expect(fnGetEnumEntries(objCatalog).map(({ strKey }) => strKey)).toEqual([
+      'user.gender',
+      'user.status',
+      'value.identity',
+    ])
+    expect(fnGetEnumOptions(objCatalog, 'user.gender')).toMatchObject([
+      { label: '男', value: 'male' },
+      { label: '女', value: 'female' },
+    ])
+    expect(fnGetEnumValues(objCatalog, 'user.gender')).toEqual([
+      'male',
+      'female',
+    ])
+    expect(fnHasEnumKey(objCatalog, 'user.status')).toBe(true)
+  })
+
+  it('preserves primitive identity and supports ordered batch lookup', async () => {
+    const objCatalog = await fnCreateCatalog()
+
+    expect(fnGetEnumLabel(objCatalog, 'value.identity', 0)).toBe('数字零')
+    expect(fnGetEnumLabel(objCatalog, 'value.identity', '0')).toBe('字符串零')
+    expect(fnGetEnumLabel(objCatalog, 'value.identity', false)).toBe('布尔否')
+    expect(
+      fnGetEnumLabels(objCatalog, 'value.identity', [false, 0, false])
+    ).toEqual(['布尔否', '数字零', '布尔否'])
+    expect(
+      fnGetEnumOptionsByValues(objCatalog, 'value.identity', [
+        'missing',
+        '0',
+        0,
+      ]).map((objOption) => objOption.value)
+    ).toEqual(['0', 0])
+  })
+
+  it('supports value and label lookup with safe missing fallbacks', async () => {
+    const objCatalog = await fnCreateCatalog()
+
+    expect(fnGetEnumOption(objCatalog, 'user.gender', 'male')?.label).toBe('男')
+    expect(fnGetEnumLabel(objCatalog, 'user.gender', 'female')).toBe('女')
+    expect(fnGetEnumValue(objCatalog, 'user.gender', '男')).toBe('male')
+    expect(fnGetEnumLabel(objCatalog, 'missing.key', 'unknown')).toBe('unknown')
+    expect(fnGetEnumOptions(undefined, 'missing.key')).toEqual([])
+    expect(fnGetEnumValues(undefined, 'missing.key')).toEqual([])
+  })
+
+  it('reads a locale catalog synchronously from the QueryClient cache', async () => {
+    const objQueryClient = new QueryClient()
+    const objCatalog = await fnCreateCatalog()
+    objQueryClient.setQueryData(fnEnumCatalogQueryKey('zh-CN'), objCatalog)
+
+    expect(fnGetCachedEnumCatalog(objQueryClient)).toBe(objCatalog)
+    expect(fnGetCachedEnumCatalog(objQueryClient, 'en-US')).toBeUndefined()
+  })
+})