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

package/template/tests/unit/api/activity/ActivityProvider.test.tsx

@@ -0,0 +1,131 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { LocaleProvider } from '@/locale'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import {
+  ActivityProvider,
+  fnCreateActivitySource,
+  useActivity,
+  type IActivityTransportAdapter,
+  type IActivityTransportConnectContext,
+} from '@/api/activity'
+import { useAuthStore } from '@/stores/authStore'
+
+function ActivityConsumer() {
+  const objActivity = useActivity()
+  return (
+    <output
+      data-connection={objActivity.objConnectionState.strStatus}
+      data-task={objActivity.arrTaskStatuses[0]?.strState}
+    >
+      {objActivity.nUnreadCount}
+    </output>
+  )
+}
+
+afterEach(() => {
+  useAuthStore.getState().fnClearSession()
+})
+
+describe('ActivityProvider', () => {
+  it('keeps the page available and applies live events after the first snapshot', async () => {
+    useAuthStore.getState().fnEstablishSession({
+      nAccessTokenExpiresAt: Date.now() + 60_000,
+      nRefreshTokenExpiresAt: Date.now() + 120_000,
+      objUser: {
+        arrPermissions: ['activity:read'],
+        arrRoleCodes: ['member'],
+        strAccount: 'member',
+        strDisplayName: 'Member',
+        strId: 'user-1',
+        strRole: 'admin',
+        strTenantId: 'tenant-a',
+      },
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+    })
+    let objTransportContext: IActivityTransportConnectContext | undefined
+    const objTransport: IActivityTransportAdapter = {
+      strTransport: 'sse',
+      fnConnect: async (objContext) => {
+        objTransportContext = objContext
+        return { fnClose: vi.fn() }
+      },
+    }
+    const objSource = fnCreateActivitySource(async ({ objScope }) => {
+      expect(objScope).toMatchObject({
+        strTenantId: 'tenant-a',
+        strUserId: 'user-1',
+      })
+      return {
+        arrTaskStatuses: [
+          {
+            nProgressPercent: 10,
+            strState: 'running',
+            strTaskId: 'task-1',
+            strUpdatedAt: '2026-08-27T01:00:00.000Z',
+          },
+        ],
+        nUnreadCount: 2,
+        strLastEventId: 'event-1',
+        strVersion: 'v1',
+      }
+    })
+    const objQueryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <LocaleProvider strLocale='zh-CN' strTimeZone='Asia/Shanghai'>
+          <ActivityProvider objSource={objSource} objTransport={objTransport}>
+            <p>业务页面始终可用</p>
+            <ActivityConsumer />
+          </ActivityProvider>
+        </LocaleProvider>
+      </QueryClientProvider>
+    )
+    const objStatus = objScreen.getByRole('status')
+
+    await expect.element(objScreen.getByText('业务页面始终可用')).toBeVisible()
+    await expect.element(objStatus).toHaveTextContent('2')
+    await expect
+      .element(objStatus)
+      .toHaveAttribute('data-connection', 'connected')
+    expect(objTransportContext?.strLastEventId).toBe('event-1')
+
+    objTransportContext?.fnOnEvent({
+      nUnreadCount: 4,
+      strEventId: 'event-2',
+      strOccurredAt: '2026-08-27T02:00:00.000Z',
+      strType: 'unread-count-changed',
+    })
+    await expect.element(objStatus).toHaveTextContent('4')
+  })
+
+  it('does not request or connect when disabled', async () => {
+    const fnRequest = vi.fn().mockResolvedValue({
+      arrTaskStatuses: [],
+      nUnreadCount: 0,
+      strVersion: 'v1',
+    })
+    const fnConnect = vi.fn()
+    const objQueryClient = new QueryClient()
+    const objScreen = await render(
+      <QueryClientProvider client={objQueryClient}>
+        <LocaleProvider strLocale='zh-CN' strTimeZone='Asia/Shanghai'>
+          <ActivityProvider
+            bIsEnabled={false}
+            objSource={fnCreateActivitySource(fnRequest)}
+            objTransport={{ strTransport: 'polling', fnConnect }}
+          >
+            <ActivityConsumer />
+          </ActivityProvider>
+        </LocaleProvider>
+      </QueryClientProvider>
+    )
+
+    await expect.element(objScreen.getByRole('status')).toHaveTextContent('0')
+    expect(fnRequest).not.toHaveBeenCalled()
+    expect(fnConnect).not.toHaveBeenCalled()
+  })
+})

package/template/tests/unit/api/activity/modelAndQuery.test.ts

@@ -0,0 +1,144 @@
+import { QueryClient } from '@tanstack/react-query'
+import { describe, expect, it } from 'vitest'
+import {
+  ActivityError,
+  fnActivityQueryKey,
+  fnApplyActivityEvent,
+  fnNormalizeActivityEvent,
+  fnNormalizeActivitySnapshot,
+} from '@/api/activity'
+import { fnCreateAppQueryScope } from '@/api/query'
+
+const objScope = fnCreateAppQueryScope({
+  nSessionGeneration: 2,
+  strLocale: 'zh-CN',
+  strTenantId: 'tenant-a',
+  strUserId: 'user-1',
+  strWorkspaceId: 'workspace-a',
+})
+
+const objSnapshot = fnNormalizeActivitySnapshot({
+  arrTaskStatuses: [
+    {
+      nProgressPercent: 20,
+      strState: 'running',
+      strTaskId: 'task-1',
+      strUpdatedAt: '2026-08-27T01:00:00.000Z',
+    },
+  ],
+  nUnreadCount: 2,
+  strLastEventId: 'event-1',
+  strVersion: 'v1',
+})
+
+describe('activity snapshot and events', () => {
+  it('normalizes and freezes the server snapshot', () => {
+    expect(objSnapshot).toMatchObject({
+      nUnreadCount: 2,
+      strLastEventId: 'event-1',
+      strVersion: 'v1',
+    })
+    expect(Object.isFrozen(objSnapshot)).toBe(true)
+    expect(Object.isFrozen(objSnapshot.arrTaskStatuses)).toBe(true)
+    expect(Object.isFrozen(objSnapshot.arrTaskStatuses[0])).toBe(true)
+  })
+
+  it('rejects duplicate tasks, invalid counts and invalid task progress', () => {
+    expect(() =>
+      fnNormalizeActivitySnapshot({
+        arrTaskStatuses: [
+          ...objSnapshot.arrTaskStatuses,
+          ...objSnapshot.arrTaskStatuses,
+        ],
+        nUnreadCount: 0,
+        strVersion: 'v1',
+      })
+    ).toThrow('重复任务')
+    expect(() =>
+      fnNormalizeActivitySnapshot({
+        arrTaskStatuses: [],
+        nUnreadCount: -1,
+        strVersion: 'v1',
+      })
+    ).toThrow('非负安全整数')
+    expect(() =>
+      fnNormalizeActivityEvent({
+        objTaskStatus: {
+          nProgressPercent: -1,
+          strState: 'running',
+          strTaskId: 'task-1',
+          strUpdatedAt: '2026-08-27T01:00:00.000Z',
+        },
+        strEventId: 'event-2',
+        strOccurredAt: '2026-08-27T01:00:00.000Z',
+        strType: 'task-status-changed',
+      })
+    ).toThrow(ActivityError)
+  })
+
+  it('merges unread and task updates into the scoped Query cache', () => {
+    const objQueryClient = new QueryClient()
+    const arrQueryKey = fnActivityQueryKey(objScope)
+    objQueryClient.setQueryData(arrQueryKey, objSnapshot)
+
+    fnApplyActivityEvent(objQueryClient, objScope, {
+      nUnreadCount: 5,
+      strEventId: 'event-2',
+      strOccurredAt: '2026-08-27T02:00:00.000Z',
+      strType: 'unread-count-changed',
+    })
+    fnApplyActivityEvent(objQueryClient, objScope, {
+      objTaskStatus: {
+        nProgressPercent: 100,
+        strState: 'succeeded',
+        strTaskId: 'task-1',
+        strUpdatedAt: '2026-08-27T02:00:00.000Z',
+      },
+      strEventId: 'event-3',
+      strOccurredAt: '2026-08-27T02:00:00.000Z',
+      strType: 'task-status-changed',
+    })
+
+    expect(objQueryClient.getQueryData(arrQueryKey)).toMatchObject({
+      arrTaskStatuses: [
+        {
+          nProgressPercent: 100,
+          strState: 'succeeded',
+          strTaskId: 'task-1',
+        },
+      ],
+      nUnreadCount: 5,
+      strLastEventId: 'event-3',
+    })
+  })
+
+  it('ignores an older task projection and invalidates on a server signal', async () => {
+    const objQueryClient = new QueryClient()
+    const arrQueryKey = fnActivityQueryKey(objScope)
+    objQueryClient.setQueryData(arrQueryKey, objSnapshot)
+    fnApplyActivityEvent(objQueryClient, objScope, {
+      objTaskStatus: {
+        nProgressPercent: 10,
+        strState: 'running',
+        strTaskId: 'task-1',
+        strUpdatedAt: '2026-08-27T00:00:00.000Z',
+      },
+      strEventId: 'event-2',
+      strOccurredAt: '2026-08-27T02:00:00.000Z',
+      strType: 'task-status-changed',
+    })
+    expect(
+      objQueryClient.getQueryData<typeof objSnapshot>(arrQueryKey)
+        ?.arrTaskStatuses[0]?.nProgressPercent
+    ).toBe(20)
+
+    fnApplyActivityEvent(objQueryClient, objScope, {
+      strEventId: 'event-3',
+      strOccurredAt: '2026-08-27T03:00:00.000Z',
+      strType: 'snapshot-invalidated',
+    })
+    await expect
+      .poll(() => objQueryClient.getQueryState(arrQueryKey)?.isInvalidated)
+      .toBe(true)
+  })
+})

package/template/tests/unit/api/activity/subscription.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  fnStartActivitySubscription,
+  type IActivityTransportAdapter,
+  type IActivityTransportConnectContext,
+  type TActivityConnectionState,
+  type TActivityEvent,
+} from '@/api/activity'
+import { fnCreateAppQueryScope } from '@/api/query'
+
+const objScope = fnCreateAppQueryScope({
+  nSessionGeneration: 1,
+  strLocale: 'zh-CN',
+  strTenantId: 'tenant-a',
+  strUserId: 'user-1',
+})
+
+describe('activity subscription lifecycle', () => {
+  it('reconnects with the last event ID and ignores disposed connections', async () => {
+    const arrContexts: IActivityTransportConnectContext[] = []
+    const arrEvents: TActivityEvent[] = []
+    const arrStates: TActivityConnectionState[] = []
+    const fnClose = vi.fn()
+    const objAdapter: IActivityTransportAdapter = {
+      strTransport: 'sse',
+      fnConnect: async (objContext) => {
+        arrContexts.push(objContext)
+        return { fnClose }
+      },
+    }
+    const objSubscription = fnStartActivitySubscription({
+      fnOnEvent: (objEvent) => arrEvents.push(objEvent),
+      fnOnStateChange: (objState) => arrStates.push(objState),
+      objAdapter,
+      objReconnectPolicy: {
+        nInitialDelayMs: 0,
+        nJitterRatio: 0,
+        nMaxDelayMs: 0,
+      },
+      objScope,
+    })
+    await expect.poll(() => arrContexts.length).toBe(1)
+    await expect
+      .poll(() => objSubscription.fnGetState().strStatus)
+      .toBe('connected')
+
+    arrContexts[0]?.fnOnEvent({
+      nUnreadCount: 3,
+      strEventId: 'event-1',
+      strOccurredAt: '2026-08-27T01:00:00.000Z',
+      strType: 'unread-count-changed',
+    })
+    arrContexts[0]?.fnOnDisconnect(new Error('network lost'))
+
+    await expect.poll(() => arrContexts.length).toBe(2)
+    expect(arrContexts[1]?.strLastEventId).toBe('event-1')
+    expect(arrEvents).toHaveLength(1)
+    expect(arrStates.map((objState) => objState.strStatus)).toContain(
+      'reconnecting'
+    )
+    arrContexts[0]?.fnOnEvent({
+      nUnreadCount: 99,
+      strEventId: 'stale-event',
+      strOccurredAt: '2026-08-27T02:00:00.000Z',
+      strType: 'unread-count-changed',
+    })
+    expect(arrEvents).toHaveLength(1)
+
+    objSubscription.fnStop()
+    expect(objSubscription.fnGetState().strStatus).toBe('idle')
+    expect(fnClose).toHaveBeenCalled()
+  })
+
+  it('enters a classified error and supports manual recovery', async () => {
+    let bShouldFail = true
+    const objAdapter: IActivityTransportAdapter = {
+      strTransport: 'websocket',
+      fnConnect: async () => {
+        if (bShouldFail) throw new Error('handshake failed')
+        return { fnClose: vi.fn() }
+      },
+    }
+    const objSubscription = fnStartActivitySubscription({
+      fnOnEvent: vi.fn(),
+      objAdapter,
+      objReconnectPolicy: { nMaxAttempts: 0 },
+      objScope,
+    })
+    await expect
+      .poll(() => objSubscription.fnGetState().strStatus)
+      .toBe('error')
+    expect(objSubscription.fnGetState()).toMatchObject({
+      objError: { strCode: 'RECONNECT_EXHAUSTED' },
+    })
+
+    bShouldFail = false
+    objSubscription.fnReconnect()
+    await expect
+      .poll(() => objSubscription.fnGetState().strStatus)
+      .toBe('connected')
+    objSubscription.fnStop()
+  })
+})

package/template/tests/unit/api/activity/transports.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  fnCreatePollingActivityTransport,
+  fnCreateSseActivityTransport,
+  fnCreateWebSocketActivityTransport,
+  type IActivityEventSourceLike,
+  type IActivityWebSocketLike,
+  type TActivityEventInput,
+} from '@/api/activity'
+import { fnCreateAppQueryScope } from '@/api/query'
+
+const objScope = fnCreateAppQueryScope({
+  nSessionGeneration: 1,
+  strLocale: 'zh-CN',
+  strUserId: 'user-1',
+})
+
+function fnCreateEvent(strEventId: string): TActivityEventInput {
+  return {
+    nUnreadCount: Number(strEventId.replace(/\D/g, '')),
+    strEventId,
+    strOccurredAt: '2026-08-27T01:00:00.000Z',
+    strType: 'unread-count-changed',
+  }
+}
+
+describe('activity transport adapters', () => {
+  it('polls sequentially and advances the last event ID', async () => {
+    const arrLastEventIds: Array<string | undefined> = []
+    const objController = new AbortController()
+    const fnOnEvent = vi.fn(() => {
+      if (fnOnEvent.mock.calls.length === 2) objController.abort()
+    })
+    const objAdapter = fnCreatePollingActivityTransport({
+      fnPoll: async ({ strLastEventId }) => {
+        arrLastEventIds.push(strLastEventId)
+        return fnCreateEvent(`event-${arrLastEventIds.length}`)
+      },
+      nIntervalMs: 5,
+    })
+    const objConnection = await objAdapter.fnConnect({
+      fnOnDisconnect: vi.fn(),
+      fnOnEvent,
+      objScope,
+      objSignal: objController.signal,
+    })
+    await expect.poll(() => fnOnEvent).toHaveBeenCalledTimes(2)
+    expect(arrLastEventIds).toEqual([undefined, 'event-1'])
+    objConnection.fnClose()
+    const nCallsAfterClose = fnOnEvent.mock.calls.length
+    await new Promise((fnResolve) => setTimeout(fnResolve, 15))
+    expect(fnOnEvent).toHaveBeenCalledTimes(nCallsAfterClose)
+  })
+
+  it('maps SSE text messages and reports a disconnect', async () => {
+    const fnClose = vi.fn()
+    const objEventSource: IActivityEventSourceLike = {
+      close: fnClose,
+      onerror: null,
+      onmessage: null,
+      onopen: null,
+    }
+    const fnOnEvent = vi.fn()
+    const fnOnDisconnect = vi.fn()
+    const objAdapter = fnCreateSseActivityTransport({
+      fnCreateEventSource: () => objEventSource,
+      fnParseMessage: (strData) => fnCreateEvent(strData),
+    })
+    const objConnectionPromise = objAdapter.fnConnect({
+      fnOnDisconnect,
+      fnOnEvent,
+      objScope,
+      objSignal: new AbortController().signal,
+    })
+    await expect.poll(() => typeof objEventSource.onopen).toBe('function')
+    objEventSource.onopen?.(new Event('open'))
+    const objConnection = await objConnectionPromise
+    objEventSource.onmessage?.(new MessageEvent('message', { data: 'event-2' }))
+    expect(fnOnEvent).toHaveBeenCalledWith(fnCreateEvent('event-2'))
+    objEventSource.onerror?.(new Event('error'))
+    expect(fnOnDisconnect).toHaveBeenCalledOnce()
+    objConnection.fnClose()
+    expect(fnClose).toHaveBeenCalled()
+  })
+
+  it('rejects an SSE handshake that is cancelled before open', async () => {
+    const fnClose = vi.fn()
+    const objEventSource: IActivityEventSourceLike = {
+      close: fnClose,
+      onerror: null,
+      onmessage: null,
+      onopen: null,
+    }
+    const objController = new AbortController()
+    const objAdapter = fnCreateSseActivityTransport({
+      fnCreateEventSource: () => objEventSource,
+      fnParseMessage: (strData) => fnCreateEvent(strData),
+    })
+    const objConnectionPromise = objAdapter.fnConnect({
+      fnOnDisconnect: vi.fn(),
+      fnOnEvent: vi.fn(),
+      objScope,
+      objSignal: objController.signal,
+    })
+
+    objController.abort()
+
+    await expect(objConnectionPromise).rejects.toMatchObject({
+      name: 'AbortError',
+    })
+    expect(fnClose).toHaveBeenCalledOnce()
+  })
+
+  it('maps WebSocket messages and classifies close events', async () => {
+    const objWebSocket: IActivityWebSocketLike = {
+      close: vi.fn(),
+      onclose: null,
+      onerror: null,
+      onmessage: null,
+      onopen: null,
+    }
+    const fnOnEvent = vi.fn()
+    const fnOnDisconnect = vi.fn()
+    const objAdapter = fnCreateWebSocketActivityTransport({
+      fnCreateWebSocket: () => objWebSocket,
+      fnParseMessage: (strData) => fnCreateEvent(strData),
+    })
+    const objConnectionPromise = objAdapter.fnConnect({
+      fnOnDisconnect,
+      fnOnEvent,
+      objScope,
+      objSignal: new AbortController().signal,
+    })
+    await expect.poll(() => typeof objWebSocket.onopen).toBe('function')
+    objWebSocket.onopen?.(new Event('open'))
+    await objConnectionPromise
+    objWebSocket.onmessage?.(new MessageEvent('message', { data: 'event-3' }))
+    objWebSocket.onclose?.(new CloseEvent('close', { code: 1006 }))
+
+    expect(fnOnEvent).toHaveBeenCalledWith(fnCreateEvent('event-3'))
+    expect(fnOnDisconnect).toHaveBeenCalledWith(
+      expect.objectContaining({ strCode: 'TRANSPORT_DISCONNECTED' })
+    )
+  })
+})

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

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { fnPost, fnRequestUse, fnResponseUse } = vi.hoisted(() => ({
+  fnPost: vi.fn(),
+  fnRequestUse: vi.fn(),
+  fnResponseUse: vi.fn(),
+}))
+
+vi.mock('axios', async (fnImportOriginal) => {
+  const objAxios = await fnImportOriginal<typeof import('axios')>()
+  return {
+    ...objAxios,
+    default: {
+      ...objAxios.default,
+      create: () => ({
+        interceptors: {
+          request: { use: fnRequestUse },
+          response: { use: fnResponseUse },
+        },
+        post: fnPost,
+      }),
+    },
+  }
+})
+
+const { objAuthApiClient } = await import('@/api/authClient')
+
+describe('authentication HTTP adapter', () => {
+  beforeEach(() => {
+    fnPost.mockReset()
+  })
+
+  it('installs the shared request ID and error lifecycle', () => {
+    expect(fnRequestUse).toHaveBeenCalledOnce()
+    expect(fnResponseUse).toHaveBeenCalledOnce()
+    expect(fnResponseUse).toHaveBeenCalledWith(
+      expect.any(Function),
+      expect.any(Function)
+    )
+  })
+
+  it('maps the external login envelope into the stable session contract', async () => {
+    fnPost.mockResolvedValue({
+      data: {
+        data: {
+          accessToken: 'access-token',
+          refreshToken: 'refresh-token',
+          expiresIn: 600,
+          user: {
+            id: 'user-1',
+            maskedPhone: '138****0000',
+            nickname: '管理员',
+            role: 'admin',
+          },
+        },
+      },
+    })
+
+    const objResult = await objAuthApiClient.fnFirstPartyLogin({
+      strAudience: 'admin-api',
+      strClientId: 'react-admin',
+      strPassword: 'password',
+      strPhone: '13800000000',
+      strScope: 'openid profile offline_access',
+    })
+
+    expect(fnPost).toHaveBeenCalledWith(
+      '/api/v1/auth/first-party-login',
+      {
+        audience: 'admin-api',
+        clientId: 'react-admin',
+        password: 'password',
+        phone: '13800000000',
+        scope: 'openid profile offline_access',
+      },
+      { signal: undefined }
+    )
+    expect(objResult).toMatchObject({
+      strAccessToken: 'access-token',
+      strRefreshToken: 'refresh-token',
+      nExpiresIn: 600,
+      objUser: {
+        strId: 'user-1',
+        strMaskedPhone: '138****0000',
+        strRole: 'admin',
+      },
+    })
+  })
+
+  it('rejects malformed successful responses at the transport boundary', async () => {
+    fnPost.mockResolvedValue({ data: { data: { accessToken: 'incomplete' } } })
+
+    await expect(
+      objAuthApiClient.fnRefreshToken(
+        { strClientId: 'react-admin', strRefreshToken: 'refresh-token' },
+        new AbortController().signal
+      )
+    ).rejects.toThrow('刷新接口未返回有效响应。')
+  })
+
+  it('uses the narrow logout endpoint', async () => {
+    fnPost.mockResolvedValue({ data: {} })
+
+    await objAuthApiClient.fnSignOut({ strRefreshToken: 'refresh-token' })
+
+    expect(fnPost).toHaveBeenCalledWith('/api/v1/auth/logout', {
+      refreshToken: 'refresh-token',
+    })
+  })
+})