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

package/template/tests/unit/realtimeCollaboration/useRealtimeCollaboration.test.tsx

@@ -0,0 +1,115 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { LocaleProvider } from '@/locale'
+import {
+  useRealtimeCollaboration,
+  type ICollaborationAdapter,
+} from '@/realtimeCollaboration'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { useAuthStore } from '@/stores/authStore'
+
+interface ITestBinding {
+  readonly strBindingId: string
+}
+
+function fnEstablishSession(arrPermissions: string[]) {
+  useAuthStore.getState().fnEstablishSession({
+    nAccessTokenExpiresAt: Date.now() + 60_000,
+    nRefreshTokenExpiresAt: Date.now() + 120_000,
+    objUser: {
+      arrPermissions,
+      arrRoleCodes: ['editor'],
+      strAccount: 'editor',
+      strDisplayName: 'Editor',
+      strId: 'user-1',
+      strRole: 'admin',
+      strTenantId: 'tenant-a',
+    },
+    strAccessToken: 'access-token',
+    strRefreshToken: 'refresh-token',
+  })
+}
+
+function CollaborationConsumer({
+  objAdapter,
+}: {
+  objAdapter: ICollaborationAdapter<ITestBinding>
+}) {
+  const objSession = useRealtimeCollaboration({
+    objAdapter,
+    strDocumentId: 'document-1',
+    strDocumentType: 'contract',
+    strMode: 'edit',
+  })
+
+  return (
+    <output
+      data-error={'objError' in objSession ? objSession.objError.name : ''}
+    >
+      {objSession.strStatus === 'active'
+        ? objSession.objBinding.strBindingId
+        : objSession.strStatus}
+    </output>
+  )
+}
+
+describe('useRealtimeCollaboration', () => {
+  afterEach(() => {
+    useAuthStore.getState().fnClearSession()
+  })
+
+  it('opens a route-scoped SDK binding for an authorized user', async () => {
+    fnEstablishSession(['document:collaborate'])
+    const fnDisconnect = vi.fn()
+    const fnConnect = vi.fn<ICollaborationAdapter<ITestBinding>['fnConnect']>(
+      async () => ({
+        arrParticipants: [],
+        fnDisconnect,
+        fnSubscribe: () => () => undefined,
+        objBinding: { strBindingId: 'binding-1' },
+        strInitialSyncState: 'synced',
+      })
+    )
+    const objQueryClient = new QueryClient()
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <LocaleProvider strLocale='zh-CN' strTimeZone='Asia/Shanghai'>
+          <CollaborationConsumer objAdapter={{ fnConnect }} />
+        </LocaleProvider>
+      </QueryClientProvider>
+    )
+
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveTextContent('binding-1')
+    expect(fnConnect).toHaveBeenCalledOnce()
+    const objRequest = fnConnect.mock.calls[0]?.[0]
+    expect(objRequest?.objScope).toMatchObject({
+      strTenantId: 'tenant-a',
+      strUserId: 'user-1',
+    })
+    expect(objRequest?.objSignal).toBeInstanceOf(AbortSignal)
+  })
+
+  it('surfaces an authorization failure returned by the project SDK adapter', async () => {
+    fnEstablishSession([])
+    const fnConnect = vi.fn<ICollaborationAdapter<ITestBinding>['fnConnect']>(
+      () => Promise.reject(new Error('backend denied collaboration access'))
+    )
+    const objQueryClient = new QueryClient()
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <LocaleProvider strLocale='zh-CN' strTimeZone='Asia/Shanghai'>
+          <CollaborationConsumer objAdapter={{ fnConnect }} />
+        </LocaleProvider>
+      </QueryClientProvider>
+    )
+    const objOutput = objScreen.getByRole('status')
+
+    await expect.element(objOutput).toHaveTextContent('error')
+    await expect
+      .element(objOutput)
+      .toHaveAttribute('data-error', 'CollaborationError')
+    expect(fnConnect).toHaveBeenCalledOnce()
+  })
+})

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

@@ -0,0 +1,195 @@
+import {
+  fnCreateReportTemplateSource,
+  fnNormalizeReportGenerationPollResult,
+  fnNormalizeReportGenerationRequest,
+  fnNormalizeReportOutput,
+  fnNormalizeReportTemplateCatalog,
+  fnReportTemplateQueryKey,
+  ReportingError,
+} from '@/reporting'
+import { describe, expect, it, vi } from 'vitest'
+import type { IAppQueryScope } from '@/api/query'
+
+const objScope: IAppQueryScope = {
+  nSessionGeneration: 1,
+  strLocale: 'zh-CN',
+  strTenantId: 'tenant-a',
+  strUserId: 'user-1',
+  strWorkspaceId: 'workspace-a',
+}
+
+describe('report template catalog', () => {
+  it('normalizes and freezes the authorized template catalog', () => {
+    const objCatalog = fnNormalizeReportTemplateCatalog({
+      arrTemplates: [
+        {
+          arrFormats: ['pdf', 'docx'],
+          strDescription: '  合同归档模板  ',
+          strTemplateId: ' contract-archive ',
+          strTemplateName: ' 合同归档 ',
+          strTemplateVersion: ' 2026.08 ',
+        },
+      ],
+      strCatalogVersion: ' catalog-v1 ',
+    })
+
+    expect(objCatalog).toEqual({
+      arrTemplates: [
+        {
+          arrFormats: ['pdf', 'docx'],
+          strDescription: '合同归档模板',
+          strTemplateId: 'contract-archive',
+          strTemplateName: '合同归档',
+          strTemplateVersion: '2026.08',
+        },
+      ],
+      strCatalogVersion: 'catalog-v1',
+    })
+    expect(Object.isFrozen(objCatalog)).toBe(true)
+    expect(Object.isFrozen(objCatalog.arrTemplates)).toBe(true)
+  })
+
+  it('rejects duplicate template IDs and executable output formats', () => {
+    expect(() =>
+      fnNormalizeReportTemplateCatalog({
+        arrTemplates: [
+          {
+            arrFormats: ['pdf'],
+            strTemplateId: 'duplicate',
+            strTemplateName: '模板一',
+            strTemplateVersion: '1',
+          },
+          {
+            arrFormats: ['pdf'],
+            strTemplateId: 'duplicate',
+            strTemplateName: '模板二',
+            strTemplateVersion: '1',
+          },
+        ],
+        strCatalogVersion: '1',
+      })
+    ).toThrowError(ReportingError)
+
+    expect(() =>
+      fnNormalizeReportTemplateCatalog({
+        arrTemplates: [
+          {
+            arrFormats: ['html'],
+            strTemplateId: 'unsafe-template',
+            strTemplateName: '不安全模板',
+            strTemplateVersion: '1',
+          },
+        ],
+        strCatalogVersion: '1',
+      })
+    ).toThrowError(ReportingError)
+  })
+
+  it('validates Swagger responses before exposing them to Query', async () => {
+    const fnRequest = vi.fn(async () => ({
+      arrTemplates: [],
+      strCatalogVersion: 'catalog-v1',
+    }))
+    const objSource = fnCreateReportTemplateSource(fnRequest)
+    const objSignal = new AbortController().signal
+
+    await expect(
+      objSource.fnListTemplates({ objScope, objSignal })
+    ).resolves.toEqual({
+      arrTemplates: [],
+      strCatalogVersion: 'catalog-v1',
+    })
+    expect(fnRequest).toHaveBeenCalledWith({ objScope, objSignal })
+    expect(fnReportTemplateQueryKey(objScope)).toContain('templates')
+  })
+})
+
+describe('report generation contracts', () => {
+  it('keeps typed parameters and normalizes stable request identity', () => {
+    const objRequest = fnNormalizeReportGenerationRequest({
+      objParameters: { strContractId: 'contract-1' },
+      strFormat: 'pdf',
+      strTemplateId: ' contract ',
+      strTemplateVersion: ' v1 ',
+    })
+
+    expect(objRequest).toEqual({
+      objParameters: { strContractId: 'contract-1' },
+      strFormat: 'pdf',
+      strTemplateId: 'contract',
+      strTemplateVersion: 'v1',
+    })
+  })
+
+  it('cleans file names and rejects format or MIME substitution', () => {
+    expect(
+      fnNormalizeReportOutput(
+        {
+          strFileId: 'file-1',
+          strFileName: '../contract.html',
+          strFormat: 'pdf',
+          strMimeType: 'application/pdf',
+          strReportId: 'report-1',
+        },
+        'pdf'
+      )
+    ).toMatchObject({ strFileName: 'contract.html.pdf' })
+
+    expect(() =>
+      fnNormalizeReportOutput(
+        {
+          strFileId: 'file-1',
+          strFileName: 'contract.pdf',
+          strFormat: 'pdf',
+          strMimeType: 'text/html',
+          strReportId: 'report-1',
+        },
+        'pdf'
+      )
+    ).toThrowError(ReportingError)
+    expect(() =>
+      fnNormalizeReportOutput(
+        {
+          strFileId: 'file-1',
+          strFileName: 'contract.docx',
+          strFormat: 'docx',
+          strMimeType:
+            'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+          strReportId: 'report-1',
+        },
+        'pdf'
+      )
+    ).toThrowError(ReportingError)
+  })
+
+  it('turns safe service failures into a stable reporting error', () => {
+    const objResult = fnNormalizeReportGenerationPollResult(
+      {
+        strReasonCode: 'TEMPLATE_RETIRED',
+        strSafeMessage: '模板版本已停用，请刷新目录。',
+        strStatus: 'error',
+      },
+      'pdf'
+    )
+
+    expect(objResult).toMatchObject({
+      objError: {
+        strCode: 'REPORT_FAILED',
+        strReasonCode: 'TEMPLATE_RETIRED',
+      },
+      strStatus: 'error',
+    })
+  })
+
+  it('rejects invalid service progress before it reaches task state', () => {
+    expect(() =>
+      fnNormalizeReportGenerationPollResult(
+        {
+          objProgress: { nPercent: 101 },
+          strStatus: 'running',
+        },
+        'pdf'
+      )
+    ).toThrowError(ReportingError)
+  })
+})

package/template/tests/unit/reporting/reportingHooks.test.tsx

@@ -0,0 +1,203 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ApiError } from '@/api'
+import { LocaleProvider } from '@/locale'
+import {
+  fnCreateReportTemplateSource,
+  fnPrintCurrentDocument,
+  useReportGeneration,
+  useReportTemplates,
+  type IReportGenerationSource,
+  type IReportTemplateSource,
+} from '@/reporting'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { useAuthStore } from '@/stores/authStore'
+
+interface IContractReportParameters {
+  readonly strContractId: string
+}
+
+function fnEstablishSession(arrPermissions: string[]) {
+  useAuthStore.getState().fnEstablishSession({
+    nAccessTokenExpiresAt: Date.now() + 60_000,
+    nRefreshTokenExpiresAt: Date.now() + 120_000,
+    objUser: {
+      arrPermissions,
+      arrRoleCodes: ['reporter'],
+      strAccount: 'reporter',
+      strDisplayName: 'Reporter',
+      strId: 'user-1',
+      strRole: 'admin',
+      strTenantId: 'tenant-a',
+    },
+    strAccessToken: 'access-token',
+    strRefreshToken: 'refresh-token',
+  })
+}
+
+function ReportTemplateConsumer({
+  objSource,
+}: {
+  objSource: IReportTemplateSource
+}) {
+  const objQuery = useReportTemplates({
+    objSource,
+  })
+  return (
+    <output>
+      {objQuery.data?.arrTemplates[0]?.strTemplateName ?? objQuery.status}
+    </output>
+  )
+}
+
+function ReportGenerationConsumer({
+  objSource,
+}: {
+  objSource: IReportGenerationSource<IContractReportParameters>
+}) {
+  const { fnRun, objState } = useReportGeneration({
+    objSource,
+  })
+  return (
+    <section>
+      <button
+        type='button'
+        onClick={() =>
+          void fnRun({
+            objParameters: { strContractId: 'contract-1' },
+            strFormat: 'pdf',
+            strTemplateId: 'contract',
+            strTemplateVersion: 'v1',
+          })
+        }
+      >
+        生成
+      </button>
+      <output>
+        {objState.strStatus === 'success'
+          ? objState.objResult.strFileName
+          : objState.strStatus}
+      </output>
+    </section>
+  )
+}
+
+function fnCreateTestRoot(objChildren: React.ReactNode) {
+  const objQueryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return (
+    <QueryClientProvider client={objQueryClient}>
+      <LocaleProvider strLocale='zh-CN' strTimeZone='Asia/Shanghai'>
+        {objChildren}
+      </LocaleProvider>
+    </QueryClientProvider>
+  )
+}
+
+describe('reporting hooks', () => {
+  afterEach(() => {
+    useAuthStore.getState().fnClearSession()
+    vi.restoreAllMocks()
+  })
+
+  it('loads the authorized server template catalog', async () => {
+    fnEstablishSession(['report:template:read'])
+    const fnRequest = vi.fn(async () => ({
+      arrTemplates: [
+        {
+          arrFormats: ['pdf'],
+          strTemplateId: 'contract',
+          strTemplateName: '合同模板',
+          strTemplateVersion: 'v1',
+        },
+      ],
+      strCatalogVersion: 'catalog-v1',
+    }))
+    const objSource = fnCreateReportTemplateSource(fnRequest)
+    const objScreen = await render(
+      fnCreateTestRoot(<ReportTemplateConsumer objSource={objSource} />)
+    )
+
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveTextContent('合同模板')
+    expect(fnRequest).toHaveBeenCalledOnce()
+  })
+
+  it('generates a protected file identity through the shared file task', async () => {
+    fnEstablishSession(['report:generate'])
+    const fnStartReport = vi.fn<
+      IReportGenerationSource<IContractReportParameters>['fnStartReport']
+    >(async () => ({
+      objResult: {
+        strFileId: 'file-1',
+        strFileName: '../contract.pdf',
+        strFormat: 'pdf',
+        strMimeType: 'application/pdf',
+        strReportId: 'report-1',
+      },
+      strMode: 'completed',
+    }))
+    const objScreen = await render(
+      fnCreateTestRoot(
+        <ReportGenerationConsumer objSource={{ fnStartReport }} />
+      )
+    )
+
+    await objScreen.getByRole('button', { name: '生成' }).click()
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveTextContent('contract.pdf')
+    expect(fnStartReport).toHaveBeenCalledOnce()
+    expect(fnStartReport.mock.calls[0]?.[0].objScope).toMatchObject({
+      strTenantId: 'tenant-a',
+      strUserId: 'user-1',
+    })
+  })
+
+  it('surfaces a backend authorization error from report generation', async () => {
+    fnEstablishSession([])
+    const fnStartReport = vi.fn<
+      IReportGenerationSource<IContractReportParameters>['fnStartReport']
+    >(() =>
+      Promise.reject(
+        new ApiError({
+          bRetriable: false,
+          nStatus: 403,
+          strCode: 'FORBIDDEN',
+          strKind: 'http',
+          strMessage: '无权生成报表。',
+        })
+      )
+    )
+    const objScreen = await render(
+      fnCreateTestRoot(
+        <ReportGenerationConsumer objSource={{ fnStartReport }} />
+      )
+    )
+
+    await objScreen.getByRole('button', { name: '生成' }).click()
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveTextContent('error')
+    expect(fnStartReport).toHaveBeenCalledOnce()
+  })
+})
+
+describe('current document printing', () => {
+  afterEach(() => {
+    useAuthStore.getState().fnClearSession()
+    vi.restoreAllMocks()
+  })
+
+  it('prints the current controlled route', () => {
+    const fnPrint = vi
+      .spyOn(window, 'print')
+      .mockImplementation(() => undefined)
+
+    fnPrintCurrentDocument()
+
+    expect(fnPrint).toHaveBeenCalledOnce()
+  })
+})

package/template/tests/unit/router/authLifecycle.test.ts

@@ -0,0 +1,55 @@
+import { fnHandleAuthSessionTransition } from '@/router/authLifecycle'
+import { describe, expect, it, vi } from 'vitest'
+
+describe('authentication lifecycle', () => {
+  it('clears request cache and redirects when a signed-in session ends', () => {
+    const fnClearQueryCache = vi.fn()
+    const fnInvalidateRouter = vi.fn()
+    const fnNavigateToSignIn = vi.fn()
+
+    const bHandled = fnHandleAuthSessionTransition(
+      { bIsAuthenticated: false, nSessionGeneration: 2 },
+      { bIsAuthenticated: true, nSessionGeneration: 1 },
+      { fnClearQueryCache, fnInvalidateRouter, fnNavigateToSignIn }
+    )
+
+    expect(bHandled).toBe(true)
+    expect(fnClearQueryCache).toHaveBeenCalledOnce()
+    expect(fnInvalidateRouter).toHaveBeenCalledOnce()
+    expect(fnNavigateToSignIn).toHaveBeenCalledOnce()
+  })
+
+  it('ignores unrelated authentication state updates', () => {
+    const fnClearQueryCache = vi.fn()
+    const fnInvalidateRouter = vi.fn()
+    const fnNavigateToSignIn = vi.fn()
+
+    const bHandled = fnHandleAuthSessionTransition(
+      { bIsAuthenticated: true, nSessionGeneration: 1 },
+      { bIsAuthenticated: true, nSessionGeneration: 1 },
+      { fnClearQueryCache, fnInvalidateRouter, fnNavigateToSignIn }
+    )
+
+    expect(bHandled).toBe(false)
+    expect(fnClearQueryCache).not.toHaveBeenCalled()
+    expect(fnInvalidateRouter).not.toHaveBeenCalled()
+    expect(fnNavigateToSignIn).not.toHaveBeenCalled()
+  })
+
+  it('clears request cache when one signed-in account replaces another', () => {
+    const fnClearQueryCache = vi.fn()
+    const fnInvalidateRouter = vi.fn()
+    const fnNavigateToSignIn = vi.fn()
+
+    const bHandled = fnHandleAuthSessionTransition(
+      { bIsAuthenticated: true, nSessionGeneration: 2 },
+      { bIsAuthenticated: true, nSessionGeneration: 1 },
+      { fnClearQueryCache, fnInvalidateRouter, fnNavigateToSignIn }
+    )
+
+    expect(bHandled).toBe(true)
+    expect(fnClearQueryCache).toHaveBeenCalledOnce()
+    expect(fnInvalidateRouter).toHaveBeenCalledOnce()
+    expect(fnNavigateToSignIn).not.toHaveBeenCalled()
+  })
+})

package/template/tests/unit/router/navigation.test.ts

@@ -0,0 +1,55 @@
+import { QueryClient } from '@tanstack/react-query'
+import { createMemoryHistory, createRouter } from '@tanstack/react-router'
+import { objRouteTree } from '@/router/config'
+import { fnCreateNavigationCatalog } from '@/router/navigation'
+import { describe, expect, it } from 'vitest'
+
+function fnCreateNavigationTestRouter(
+  fnHasPermission: (strPermission?: string) => boolean
+) {
+  const objQueryClient = new QueryClient()
+  return createRouter({
+    context: {
+      objAuth: {
+        fnHasPermission,
+        fnIsAuthenticated: () => true,
+      },
+      objQueryClient,
+    },
+    history: createMemoryHistory({ initialEntries: ['/dashboard'] }),
+    routeTree: objRouteTree,
+  })
+}
+
+describe('navigation catalog', () => {
+  it('creates one frozen catalog for every navigation consumer', () => {
+    const objRouter = fnCreateNavigationTestRouter(() => true)
+    const arrCatalog = fnCreateNavigationCatalog(
+      objRouter,
+      () => true,
+      (strLeft, strRight) => strLeft.localeCompare(strRight, 'en-US'),
+      (strKey) => strKey
+    )
+
+    expect(Object.isFrozen(arrCatalog)).toBe(true)
+    const objWorkspaceGroup = arrCatalog.find(
+      (objGroup) => objGroup.strKey === 'route.group.workspace'
+    )
+    expect(
+      objWorkspaceGroup?.arrEntries.map(({ strTitle }) => strTitle)
+    ).toContain('route.home.title')
+  })
+
+  it('removes denied routes before building search or sidebar projections', () => {
+    const objRouter = fnCreateNavigationTestRouter(() => false)
+
+    expect(
+      fnCreateNavigationCatalog(
+        objRouter,
+        () => false,
+        (strLeft, strRight) => strLeft.localeCompare(strRight),
+        (strKey) => strKey
+      )
+    ).toEqual([])
+  })
+})

package/template/tests/unit/router/redirects.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import {
+  fnGetPostSignInPath,
+  fnParseInternalRedirect,
+  strDefaultAuthenticatedPath,
+} from '@/lib/navigationRedirect'
+
+describe('router redirects', () => {
+  it('preserves internal redirect paths', () => {
+    expect(fnParseInternalRedirect('/users?page=2#results')).toBe(
+      '/users?page=2#results'
+    )
+  })
+
+  it.each(['https://example.com', '//example.com', '/\\example.com', 'users'])(
+    'rejects unsafe redirect target %s',
+    (strTarget) => {
+      expect(fnParseInternalRedirect(strTarget)).toBeUndefined()
+      expect(fnGetPostSignInPath(strTarget)).toBe(strDefaultAuthenticatedPath)
+    }
+  )
+})

package/template/tests/unit/scaffoldFeatureTemplate/featureTemplate.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { fnCreateTemplateRecordFeature } from '../../../tools/scaffold/templates/feature'
+
+describe('Feature template composition', () => {
+  it('creates an opaque Demo Feature from one composition point', () => {
+    const objFeature = fnCreateTemplateRecordFeature({
+      arrDemoRecords: [
+        {
+          bIsEnabled: true,
+          nRevision: 0,
+          strId: 'record-a',
+          strName: 'Alpha',
+        },
+      ],
+      strMode: 'demo',
+      strReadPermission: 'template:record:read',
+      strWritePermission: 'template:record:write',
+    })
+
+    expect(Object.isFrozen(objFeature)).toBe(true)
+  })
+
+  it('never falls back to Demo data when Connected wiring is missing', () => {
+    expect(() =>
+      fnCreateTemplateRecordFeature({
+        strMode: 'connected',
+        strReadPermission: 'template:record:read',
+        strWritePermission: 'template:record:write',
+      })
+    ).toThrow('Connected 模式必须配置 Swagger 生成客户端数据源')
+  })
+
+  it('rejects blank permission contracts at the composition point', () => {
+    expect(() =>
+      fnCreateTemplateRecordFeature({
+        strMode: 'demo',
+        strReadPermission: '  ',
+        strWritePermission: 'template:record:write',
+      })
+    ).toThrow('strReadPermission 不能为空')
+  })
+})