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

package/template/tests/unit/dataMasking/dataMasking.test.ts

@@ -0,0 +1,95 @@
+import {
+  fnMaskSensitiveText,
+  fnResolveSensitiveDataMaskedText,
+  objDataMaskingPresets,
+} from '@/dataMasking'
+import { describe, expect, it } from 'vitest'
+
+describe('data masking policies', () => {
+  it('exposes immutable defaults for project-level policy composition', () => {
+    expect(objDataMaskingPresets.phone).toEqual({
+      nMaskLength: 4,
+      nVisibleEnd: 4,
+      nVisibleStart: 3,
+      strMaskCharacter: '*',
+    })
+    expect(Object.isFrozen(objDataMaskingPresets.phone)).toBe(true)
+  })
+
+  it('provides predictable presets for common enterprise fields', () => {
+    expect(fnMaskSensitiveText('13800138000', { strPreset: 'phone' })).toBe(
+      '138****8000'
+    )
+    expect(
+      fnMaskSensitiveText('110101199001011234', {
+        strPreset: 'identity',
+      })
+    ).toBe('110********1234')
+    expect(
+      fnMaskSensitiveText('6222021234561234', {
+        strPreset: 'bankCard',
+      })
+    ).toBe('************1234')
+    expect(fnMaskSensitiveText('张三丰', { strPreset: 'name' })).toBe('张**')
+    expect(
+      fnMaskSensitiveText('admin@example.com', { strPreset: 'email' })
+    ).toBe('a***@example.com')
+  })
+
+  it('handles Unicode and never exposes a short value unchanged', () => {
+    expect(
+      fnMaskSensitiveText('😀测试', {
+        nVisibleEnd: 1,
+        nVisibleStart: 1,
+        strPreset: 'segment',
+      })
+    ).toBe('😀*试')
+    expect(
+      fnMaskSensitiveText('A', {
+        nVisibleEnd: 99,
+        nVisibleStart: 99,
+        strPreset: 'segment',
+      })
+    ).toBe('*')
+  })
+
+  it('supports fixed mask length and safe empty-value output', () => {
+    expect(
+      fnMaskSensitiveText('123456789', {
+        nMaskLength: 3,
+        nVisibleEnd: 2,
+        nVisibleStart: 2,
+        strMaskCharacter: '•',
+        strPreset: 'segment',
+      })
+    ).toBe('12•••89')
+    expect(
+      fnMaskSensitiveText('', {
+        strEmptyText: '暂无',
+        strPreset: 'phone',
+      })
+    ).toBe('暂无')
+  })
+
+  it('prefers the backend masked result and does not require a raw value', () => {
+    expect(
+      fnResolveSensitiveDataMaskedText(
+        {
+          strMaskedValue: '后端脱敏结果',
+          strState: 'masked',
+        },
+        { strPreset: 'phone' }
+      )
+    ).toBe('后端脱敏结果')
+    expect(
+      fnResolveSensitiveDataMaskedText(
+        {
+          strMaskedValue: '138####8000',
+          strState: 'available',
+          strValue: '13800138000',
+        },
+        { strPreset: 'phone' }
+      )
+    ).toBe('138####8000')
+  })
+})

package/template/tests/unit/featureFlags/featureFlags.test.ts

@@ -0,0 +1,169 @@
+import {
+  FeatureFlagError,
+  fnCreateFeatureFlagScope,
+  fnCreateFeatureFlagRegistry,
+  fnCreateFeatureFlagSource,
+  fnEvaluateFeatureFlag,
+  fnGetFeatureFlagDefinition,
+  type IFeatureFlagDefinition,
+} from '@/featureFlags'
+import { describe, expect, it } from 'vitest'
+
+const objKillSwitchDefinition: IFeatureFlagDefinition = {
+  bSafeDefault: false,
+  strKey: 'orders.bulkExport',
+  strKind: 'killSwitch',
+}
+
+describe('Feature Flag source', () => {
+  it('uses the session generation as the authorization cache version', () => {
+    expect(fnCreateFeatureFlagScope({ nSessionGeneration: 3 })).toMatchObject({
+      nSessionGeneration: 3,
+    })
+    expect(() => fnCreateFeatureFlagScope({ nSessionGeneration: -1 })).toThrow(
+      '会话版本必须是非负整数'
+    )
+  })
+
+  it('validates and freezes a backend-evaluated catalog', async () => {
+    const nNow = Date.now()
+    const objSource = fnCreateFeatureFlagSource(async () => ({
+      nEvaluatedAt: nNow,
+      nExpiresAt: nNow + 60_000,
+      objFlags: {
+        'orders.bulkExport': {
+          bEnabled: true,
+          objPayload: { strFormat: 'xlsx' },
+          strReason: 'tenant_allowlist',
+          strVariant: 'enabled-v2',
+        },
+      },
+      version: 'rules-v3',
+    }))
+
+    const objCatalog = await objSource.fnLoadCatalog({
+      arrFlagKeys: ['orders.bulkExport'],
+      objScope: { strTenantId: 'tenant-a' },
+      objSignal: new AbortController().signal,
+    })
+
+    expect(objCatalog.version).toBe('rules-v3')
+    expect(objCatalog.objFlags.get('orders.bulkExport')).toMatchObject({
+      bEnabled: true,
+      strReason: 'tenant_allowlist',
+      strVariant: 'enabled-v2',
+    })
+    expect(
+      Object.isFrozen(objCatalog.objFlags.get('orders.bulkExport')?.objPayload)
+    ).toBe(true)
+  })
+
+  it('rejects malformed timestamps and flag results at the adapter boundary', async () => {
+    const objSource = fnCreateFeatureFlagSource(async () => ({
+      nEvaluatedAt: 2_000,
+      nExpiresAt: 1_000,
+      objFlags: {
+        'orders.bulkExport': { bEnabled: true },
+      },
+      version: 'rules-v3',
+    }))
+
+    await expect(
+      objSource.fnLoadCatalog({
+        arrFlagKeys: ['orders.bulkExport'],
+        objScope: {},
+        objSignal: new AbortController().signal,
+      })
+    ).rejects.toMatchObject({ strCode: 'INVALID_CATALOG' })
+  })
+})
+
+describe('Feature Flag local safety policy', () => {
+  it('forces Kill Switch definitions to default off without stale use', () => {
+    expect(() =>
+      fnCreateFeatureFlagRegistry([
+        {
+          bAllowStale: true,
+          bSafeDefault: true,
+          nMaxStaleMs: 60_000,
+          strKey: 'orders.bulkExport',
+          strKind: 'killSwitch',
+        },
+      ])
+    ).toThrowError(FeatureFlagError)
+  })
+
+  it('uses a fresh remote result but closes a Kill Switch after expiry', async () => {
+    const nNow = Date.now()
+    const objSource = fnCreateFeatureFlagSource(async () => ({
+      nEvaluatedAt: nNow,
+      nExpiresAt: nNow + 10_000,
+      objFlags: {
+        'orders.bulkExport': { bEnabled: true },
+      },
+      version: 'rules-v3',
+    }))
+    const objCatalog = await objSource.fnLoadCatalog({
+      arrFlagKeys: ['orders.bulkExport'],
+      objScope: {},
+      objSignal: new AbortController().signal,
+    })
+
+    expect(
+      fnEvaluateFeatureFlag(objKillSwitchDefinition, objCatalog, nNow + 1)
+    ).toMatchObject({
+      bEnabled: true,
+      bIsFallback: false,
+      strEvaluationSource: 'remote',
+    })
+    expect(
+      fnEvaluateFeatureFlag(objKillSwitchDefinition, objCatalog, nNow + 10_001)
+    ).toMatchObject({
+      bEnabled: false,
+      bIsFallback: true,
+      strEvaluationReason: 'catalogExpired',
+      strEvaluationSource: 'safeDefault',
+    })
+  })
+
+  it('allows an explicitly bounded stale window for non-critical releases', async () => {
+    const nNow = Date.now()
+    const objDefinition: IFeatureFlagDefinition = {
+      bAllowStale: true,
+      bSafeDefault: false,
+      nMaxStaleMs: 30_000,
+      strKey: 'navigation.newShell',
+      strKind: 'release',
+    }
+    const objSource = fnCreateFeatureFlagSource(async () => ({
+      nEvaluatedAt: nNow,
+      nExpiresAt: nNow + 10_000,
+      objFlags: {
+        'navigation.newShell': { bEnabled: true },
+      },
+      version: 'rules-v4',
+    }))
+    const objCatalog = await objSource.fnLoadCatalog({
+      arrFlagKeys: ['navigation.newShell'],
+      objScope: {},
+      objSignal: new AbortController().signal,
+    })
+
+    expect(
+      fnEvaluateFeatureFlag(objDefinition, objCatalog, nNow + 20_000)
+    ).toMatchObject({
+      bEnabled: true,
+      bIsFallback: false,
+      strEvaluationReason: 'catalogExpired',
+      strEvaluationSource: 'stale',
+    })
+  })
+
+  it('rejects unknown keys instead of silently returning false', () => {
+    const objRegistry = fnCreateFeatureFlagRegistry([objKillSwitchDefinition])
+
+    expect(() =>
+      fnGetFeatureFlagDefinition(objRegistry, 'orders.unknown')
+    ).toThrowError(FeatureFlagError)
+  })
+})

package/template/tests/unit/featureFlags/useFeatureFlag.test.tsx

@@ -0,0 +1,108 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  FeatureFlagProvider,
+  FeatureGate,
+  fnCreateFeatureFlagSource,
+  useFeatureFlag,
+  useFeatureFlagCatalog,
+  type IFeatureFlagDefinition,
+  type TFeatureFlagRequest,
+} from '@/featureFlags'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+
+const arrDefinitions: readonly IFeatureFlagDefinition[] = [
+  {
+    bSafeDefault: false,
+    strKey: 'orders.bulkExport',
+    strKind: 'killSwitch',
+  },
+]
+
+function FeatureFlagConsumer() {
+  const objCatalog = useFeatureFlagCatalog()
+  const objFlag = useFeatureFlag('orders.bulkExport')
+
+  return (
+    <output
+      data-configured={String(objCatalog.bIsConfigured)}
+      data-enabled={String(objFlag.bEnabled)}
+      data-fallback={String(objFlag.bIsFallback)}
+      data-keys={objCatalog.arrKeys.join(',')}
+      data-scope={objCatalog.objScope.strTenantId}
+      data-source={objFlag.strEvaluationSource}
+    >
+      <FeatureGate
+        objFallback={<span>export-disabled</span>}
+        strFlagKey='orders.bulkExport'
+      >
+        <span>export-enabled</span>
+      </FeatureGate>
+    </output>
+  )
+}
+
+describe('Feature Flag React access', () => {
+  it('shares one scoped request and exposes the remote evaluation', async () => {
+    const nNow = Date.now()
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const fnRequest = vi.fn<TFeatureFlagRequest>().mockResolvedValue({
+      nEvaluatedAt: nNow,
+      nExpiresAt: nNow + 60_000,
+      objFlags: {
+        'orders.bulkExport': { bEnabled: true },
+      },
+      version: 'rules-v1',
+    })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <FeatureFlagProvider
+          arrDefinitions={arrDefinitions}
+          objScope={{ strTenantId: 'tenant-a', strUserId: 'user-a' }}
+          objSource={fnCreateFeatureFlagSource(fnRequest)}
+        >
+          <FeatureFlagConsumer />
+        </FeatureFlagProvider>
+      </QueryClientProvider>
+    )
+    const objOutput = objScreen.getByRole('status')
+
+    await expect.element(objOutput).toHaveTextContent('export-enabled')
+    await expect.element(objOutput).toHaveAttribute('data-enabled', 'true')
+    await expect.element(objOutput).toHaveAttribute('data-fallback', 'false')
+    await expect.element(objOutput).toHaveAttribute('data-source', 'remote')
+    await expect.element(objOutput).toHaveAttribute('data-scope', 'tenant-a')
+    expect(fnRequest).toHaveBeenCalledTimes(1)
+    const objRequest = fnRequest.mock.calls[0]?.[0]
+    expect(objRequest?.arrFlagKeys).toEqual(['orders.bulkExport'])
+    expect(objRequest?.objScope).toMatchObject({
+      strTenantId: 'tenant-a',
+      strUserId: 'user-a',
+    })
+    expect(objRequest?.objSignal).toBeInstanceOf(AbortSignal)
+  })
+
+  it('renders the safe fallback immediately when no source is configured', async () => {
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <FeatureFlagProvider arrDefinitions={arrDefinitions}>
+          <FeatureFlagConsumer />
+        </FeatureFlagProvider>
+      </QueryClientProvider>
+    )
+    const objOutput = objScreen.getByRole('status')
+
+    await expect.element(objOutput).toHaveTextContent('export-disabled')
+    await expect.element(objOutput).toHaveAttribute('data-enabled', 'false')
+    await expect.element(objOutput).toHaveAttribute('data-fallback', 'true')
+    await expect
+      .element(objOutput)
+      .toHaveAttribute('data-source', 'safeDefault')
+    await expect.element(objOutput).toHaveAttribute('data-configured', 'false')
+  })
+})

package/template/tests/unit/features/FeatureLocalization.test.tsx

@@ -0,0 +1,54 @@
+import { QueryClient } from '@tanstack/react-query'
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRouteWithContext,
+  createRoute,
+  createRouter,
+} from '@tanstack/react-router'
+import { LocaleProvider } from '@/locale'
+import { expect, it } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { Home } from '@/features/home'
+
+function fnCreateHomeRouter() {
+  const objRootRoute = createRootRouteWithContext<{
+    objQueryClient: QueryClient
+    objAuth: {
+      fnHasPermission: () => boolean
+      fnIsAuthenticated: () => boolean
+    }
+  }>()({ component: Outlet })
+  const objHomeRoute = createRoute({
+    getParentRoute: () => objRootRoute,
+    path: '/',
+    component: Home,
+  })
+
+  return createRouter({
+    routeTree: objRootRoute.addChildren([objHomeRoute]),
+    history: createMemoryHistory({ initialEntries: ['/'] }),
+    context: {
+      objQueryClient: new QueryClient(),
+      objAuth: {
+        fnHasPermission: () => true,
+        fnIsAuthenticated: () => true,
+      },
+    },
+  })
+}
+
+it('renders the scaffold home Feature in the active locale', async () => {
+  const objScreen = await render(
+    <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+      <RouterProvider router={fnCreateHomeRouter()} />
+    </LocaleProvider>
+  )
+
+  await expect.element(objScreen.getByText('Table scenarios')).toBeVisible()
+  await expect.element(objScreen.getByText('Upload and preview')).toBeVisible()
+  await expect
+    .element(objScreen.getByRole('region', { name: 'Live scaffold demos' }))
+    .toBeVisible()
+})

package/template/tests/unit/features/RouteError.test.tsx

@@ -0,0 +1,40 @@
+import { fnConfigureObservability } from '@/observability'
+import { expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { RouteError } from '@/features/errors/RouteError'
+
+vi.mock('@tanstack/react-router', () => ({
+  useNavigate: () => vi.fn(),
+  useRouter: () => ({ invalidate: vi.fn() }),
+  useRouterState: () => '/broken-route',
+}))
+
+it('reports route rendering failures with release information', async () => {
+  const fnCaptureEvent = vi.fn()
+  fnConfigureObservability({
+    bEnabled: true,
+    objAdapter: { fnCaptureEvent },
+    objRelease: {
+      strVersion: '1.2.3',
+      strCommit: 'abc123',
+      strBuildTime: '2026-08-26T08:00:00.000Z',
+      strEnvironment: 'test',
+    },
+  })
+
+  const objScreen = await render(
+    <RouteError error={new Error('route failed')} reset={vi.fn()} />
+  )
+
+  await expect.element(objScreen.getByText('页面运行异常')).toBeInTheDocument()
+  await expect
+    .poll(() => fnCaptureEvent)
+    .toHaveBeenCalledWith(
+      expect.objectContaining({
+        strName: 'route.render_failed',
+        strSource: 'route',
+        objAttributes: { strRouteId: '/broken-route' },
+      })
+    )
+  await expect.element(objScreen.getByText(/版本 v0\.1\.0/)).toBeInTheDocument()
+})

package/template/tests/unit/features/auth/signIn/UserAuthForm.test.tsx

@@ -0,0 +1,79 @@
+import { LocaleProvider } from '@/locale'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { render, type RenderResult } from 'vitest-browser-react'
+import { type Locator, userEvent } from 'vitest/browser'
+import { UserAuthForm } from '@/features/auth/signIn/components/UserAuthForm'
+import type { TSignInValues } from '@/features/auth/signIn/types'
+
+const objFormMessages = {
+  strPhoneEmpty: '请输入手机号。',
+  strPasswordEmpty: '请输入密码。',
+} as const
+
+describe('UserAuthForm', () => {
+  let objScreen: RenderResult
+  let objPhoneInput: Locator
+  let objPasswordInput: Locator
+  let objSubmitButton: Locator
+  let fnOnSubmit: (objValues: TSignInValues) => void
+
+  beforeEach(async () => {
+    fnOnSubmit = vi.fn()
+    objScreen = await render(<UserAuthForm fnOnSubmit={fnOnSubmit} />)
+    objPhoneInput = objScreen.getByRole('textbox', { name: /^手机号$/ })
+    objPasswordInput = objScreen.getByLabelText(/^密码$/)
+    objSubmitButton = objScreen.getByRole('button', { name: /^登录$/ })
+  })
+
+  it('renders fields and submit button', async () => {
+    await expect.element(objPhoneInput).toBeInTheDocument()
+    await expect.element(objPasswordInput).toBeInTheDocument()
+    await expect.element(objSubmitButton).toBeInTheDocument()
+  })
+
+  it('shows validation messages when submitting an empty form', async () => {
+    await userEvent.click(objSubmitButton)
+
+    await expect
+      .element(objScreen.getByText(objFormMessages.strPhoneEmpty))
+      .toBeInTheDocument()
+    await expect
+      .element(objScreen.getByText(objFormMessages.strPasswordEmpty))
+      .toBeInTheDocument()
+    await expect.element(objPhoneInput).toHaveFocus()
+  })
+
+  it('passes validated values to onSubmit', async () => {
+    await userEvent.fill(objPhoneInput, '13800000000')
+    await userEvent.fill(objPasswordInput, '1234567')
+    await userEvent.click(objSubmitButton)
+
+    await vi.waitFor(() =>
+      expect(fnOnSubmit).toHaveBeenCalledWith({
+        phone: '13800000000',
+        password: '1234567',
+      })
+    )
+  })
+
+  it('renders validation and controls in the active locale', async () => {
+    const objEnglishScreen = await render(
+      <LocaleProvider strLocale='en-US' strTimeZone='UTC'>
+        <UserAuthForm fnOnSubmit={vi.fn()} />
+      </LocaleProvider>
+    )
+
+    const objEnglishSubmit = objEnglishScreen.getByRole('button', {
+      name: /^Sign in$/,
+    })
+    await expect
+      .element(
+        objEnglishScreen.getByRole('textbox', { name: /^Phone number$/ })
+      )
+      .toBeVisible()
+    await userEvent.click(objEnglishSubmit)
+    await expect
+      .element(objEnglishScreen.getByText('Enter your phone number.'))
+      .toBeVisible()
+  })
+})

package/template/tests/unit/files/fileHooks.test.tsx

@@ -0,0 +1,130 @@
+import { useState } from 'react'
+import { useFileTask, useFileUpload, type TFileUploadRequest } from '@/files'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+
+function UploadHarness({
+  fnRequest,
+  nMaxBytes,
+}: {
+  fnRequest: TFileUploadRequest<string>
+  nMaxBytes?: number
+}) {
+  const { fnCancel, fnUpload, objState } = useFileUpload({
+    fnUpload: fnRequest,
+    objValidation: { nMaxBytes },
+  })
+  const objFile = new File(['content'], 'report.csv', { type: 'text/csv' })
+
+  return (
+    <div>
+      <button type='button' onClick={() => void fnUpload([objFile])}>
+        上传
+      </button>
+      <button type='button' onClick={fnCancel}>
+        取消
+      </button>
+      <span>{objState.strStatus}</span>
+      {objState.strStatus === 'uploading' ? (
+        <span>{objState.objProgress.nPercent ?? 0}</span>
+      ) : null}
+    </div>
+  )
+}
+
+function TaskHarness({ bBackground = false }: { bBackground?: boolean }) {
+  const [nPollCount, fnSetPollCount] = useState(0)
+  const { fnRun, objState } = useFileTask({
+    nPollIntervalMs: 250,
+    objAdapter: {
+      fnStart: async (strInput: string) =>
+        bBackground
+          ? { strMode: 'background' as const, strTaskId: strInput }
+          : { strMode: 'completed' as const, objResult: `${strInput}-done` },
+      fnPoll: async () => {
+        fnSetPollCount((nCurrent) => nCurrent + 1)
+        return {
+          strStatus: 'success' as const,
+          objResult: 'background-done',
+        }
+      },
+    },
+  })
+
+  return (
+    <div>
+      <button type='button' onClick={() => void fnRun('task-1')}>
+        执行
+      </button>
+      <span>{objState.strStatus}</span>
+      <span>轮询 {nPollCount}</span>
+      {objState.strStatus === 'success' ? (
+        <span>{objState.objResult}</span>
+      ) : null}
+    </div>
+  )
+}
+
+describe('file upload state machine', () => {
+  it('reports progress and success from the injected generated-client adapter', async () => {
+    const fnRequest = vi.fn<TFileUploadRequest<string>>(async (objContext) => {
+      objContext.fnOnProgress({ nPercent: 60 })
+      return 'uploaded'
+    })
+    const objScreen = await render(<UploadHarness fnRequest={fnRequest} />)
+
+    await objScreen.getByRole('button', { name: '上传' }).click()
+
+    await expect.element(objScreen.getByText('success')).toBeVisible()
+    expect(fnRequest).toHaveBeenCalledOnce()
+  })
+
+  it('stops before the request when browser validation fails', async () => {
+    const fnRequest = vi.fn<TFileUploadRequest<string>>()
+    const objScreen = await render(
+      <UploadHarness fnRequest={fnRequest} nMaxBytes={1} />
+    )
+
+    await objScreen.getByRole('button', { name: '上传' }).click()
+
+    await expect.element(objScreen.getByText('error')).toBeVisible()
+    expect(fnRequest).not.toHaveBeenCalled()
+  })
+
+  it('propagates cancellation to the request signal', async () => {
+    const fnRequest: TFileUploadRequest<string> = (objContext) =>
+      new Promise((_fnResolve, fnReject) => {
+        objContext.objSignal.addEventListener(
+          'abort',
+          () => fnReject(new DOMException('canceled', 'AbortError')),
+          { once: true }
+        )
+      })
+    const objScreen = await render(<UploadHarness fnRequest={fnRequest} />)
+
+    await objScreen.getByRole('button', { name: '上传' }).click()
+    await expect.element(objScreen.getByText('uploading')).toBeVisible()
+    await objScreen.getByRole('button', { name: '取消' }).click()
+
+    await expect.element(objScreen.getByText('canceled')).toBeVisible()
+  })
+})
+
+describe('file task coordinator', () => {
+  it('supports an immediately completed import/export task', async () => {
+    const objScreen = await render(<TaskHarness />)
+
+    await objScreen.getByRole('button', { name: '执行' }).click()
+
+    await expect.element(objScreen.getByText('task-1-done')).toBeVisible()
+  })
+
+  it('polls a background import/export task until success', async () => {
+    const objScreen = await render(<TaskHarness bBackground />)
+
+    await objScreen.getByRole('button', { name: '执行' }).click()
+
+    await expect.element(objScreen.getByText('background-done')).toBeVisible()
+    await expect.element(objScreen.getByText('轮询 1')).toBeVisible()
+  })
+})