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

package/template/tests/unit/tenantWorkspace/tenantWorkspace.test.tsx

@@ -0,0 +1,261 @@
+import { useState } from 'react'
+import { objAppConfig } from '@/config/appConfig'
+import {
+  fnCancelTenantWorkspaceSwitch,
+  fnGetTenantWorkspaceCurrent,
+  fnGetTenantWorkspaceSnapshot,
+  fnResetTenantWorkspace,
+  fnSwitchTenantWorkspace,
+  TenantWorkspaceError,
+  TenantWorkspaceProvider,
+  useTenantWorkspace,
+  type ITenantWorkspaceAdapter,
+} from '@/tenantWorkspace'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { render } from 'vitest-browser-react'
+import { userEvent } from 'vitest/browser'
+import { useAuthStore, type IAuthSession } from '@/stores/authStore'
+
+function fnCreateSession(
+  strTenantId: string,
+  strUserId = 'user-1'
+): IAuthSession {
+  return {
+    nAccessTokenExpiresAt: Date.now() + 60_000,
+    nRefreshTokenExpiresAt: Date.now() + 120_000,
+    objUser: {
+      arrPermissions: ['workspace:read'],
+      arrRoleCodes: ['member'],
+      strAccount: strUserId,
+      strDisplayName: strUserId,
+      strId: strUserId,
+      strRole: 'admin',
+      strTenantId,
+    },
+    strAccessToken: `access-${strTenantId}`,
+    strRefreshToken: `refresh-${strTenantId}`,
+  }
+}
+
+function SwitchConsumer() {
+  const { fnClearError, fnRetry, fnSwitch, objCurrent, objTransition } =
+    useTenantWorkspace()
+  const [strCommandError, fnSetCommandError] = useState('')
+
+  return (
+    <div>
+      <output data-workspace={objCurrent.strWorkspaceId}>
+        {objTransition.strStatus}
+      </output>
+      <button
+        onClick={() => {
+          void fnSwitch({
+            strTenantId: 'tenant-a',
+            strWorkspaceId: 'workspace-b',
+          }).catch((objError: unknown) =>
+            fnSetCommandError(
+              objError instanceof Error ? objError.message : 'unknown error'
+            )
+          )
+        }}
+        type='button'
+      >
+        switch
+      </button>
+      <button
+        onClick={() => {
+          fnClearError()
+          fnSetCommandError('')
+        }}
+        type='button'
+      >
+        clear
+      </button>
+      <button
+        onClick={() => {
+          void fnRetry().catch((objError: unknown) =>
+            fnSetCommandError(
+              objError instanceof Error ? objError.message : 'unknown error'
+            )
+          )
+        }}
+        type='button'
+      >
+        retry
+      </button>
+      <span>{strCommandError}</span>
+    </div>
+  )
+}
+
+beforeEach(() => {
+  fnCancelTenantWorkspaceSwitch()
+  fnResetTenantWorkspace()
+  localStorage.removeItem(objAppConfig.storage.strTenantWorkspaceKey)
+  useAuthStore.getState().fnClearSession()
+  useAuthStore.getState().fnEstablishSession(fnCreateSession('tenant-a'))
+})
+
+afterEach(() => {
+  fnCancelTenantWorkspaceSwitch()
+  fnResetTenantWorkspace()
+  localStorage.removeItem(objAppConfig.storage.strTenantWorkspaceKey)
+  useAuthStore.getState().fnClearSession()
+})
+
+describe('tenant and workspace context', () => {
+  it('commits a confirmed workspace after cancelling old scoped requests', async () => {
+    const arrOrder: string[] = []
+    const objAdapter: ITenantWorkspaceAdapter = {
+      fnSwitch: async ({ objCurrent, objTarget }) => {
+        arrOrder.push('adapter')
+        expect(objCurrent.strWorkspaceId).toBeUndefined()
+        return objTarget
+      },
+    }
+
+    const objCurrent = await fnSwitchTenantWorkspace(
+      { strTenantId: ' tenant-a ', strWorkspaceId: ' workspace-a ' },
+      {
+        objAdapter,
+        fnBeforeCommit: () => {
+          arrOrder.push('cancel-queries')
+          expect(fnGetTenantWorkspaceCurrent().strWorkspaceId).toBeUndefined()
+        },
+        fnAfterCommit: () => arrOrder.push('invalidate-router'),
+      }
+    )
+
+    expect(arrOrder).toEqual(['adapter', 'cancel-queries', 'invalidate-router'])
+    expect(objCurrent).toMatchObject({
+      strTenantId: 'tenant-a',
+      strWorkspaceId: 'workspace-a',
+    })
+    expect(fnGetTenantWorkspaceSnapshot().objTransition.strStatus).toBe('idle')
+  })
+
+  it('keeps the old context when the adapter rejects the switch', async () => {
+    await fnSwitchTenantWorkspace(
+      { strTenantId: 'tenant-a', strWorkspaceId: 'workspace-a' },
+      { objAdapter: { fnSwitch: async ({ objTarget }) => objTarget } }
+    )
+
+    await expect(
+      fnSwitchTenantWorkspace(
+        { strTenantId: 'tenant-a', strWorkspaceId: 'workspace-b' },
+        {
+          objAdapter: {
+            fnSwitch: async () => {
+              throw new Error('backend unavailable')
+            },
+          },
+        }
+      )
+    ).rejects.toMatchObject({ strCode: 'switch_failed' })
+
+    expect(fnGetTenantWorkspaceCurrent().strWorkspaceId).toBe('workspace-a')
+    expect(fnGetTenantWorkspaceSnapshot().objTransition).toMatchObject({
+      strStatus: 'error',
+      objTarget: { strWorkspaceId: 'workspace-b' },
+    })
+  })
+
+  it('requires and commits a new authenticated session across tenants', async () => {
+    await expect(
+      fnSwitchTenantWorkspace(
+        { strTenantId: 'tenant-b', strWorkspaceId: 'workspace-b' },
+        { objAdapter: { fnSwitch: async ({ objTarget }) => objTarget } }
+      )
+    ).rejects.toMatchObject({ strCode: 'session_required' })
+    expect(fnGetTenantWorkspaceCurrent().strTenantId).toBe('tenant-a')
+
+    const objCurrent = await fnSwitchTenantWorkspace(
+      { strTenantId: 'tenant-b', strWorkspaceId: 'workspace-b' },
+      {
+        objAdapter: {
+          fnSwitch: async ({ objTarget }) => ({
+            ...objTarget,
+            objSession: fnCreateSession('tenant-b'),
+          }),
+        },
+      }
+    )
+
+    expect(objCurrent).toMatchObject({
+      strTenantId: 'tenant-b',
+      strWorkspaceId: 'workspace-b',
+    })
+    expect(useAuthStore.getState().strAccessToken).toBe('access-tenant-b')
+  })
+
+  it('aborts a stale switch and only lets the latest target commit', async () => {
+    const fnFirstAdapter = vi.fn(
+      ({ objSignal }: Parameters<ITenantWorkspaceAdapter['fnSwitch']>[0]) =>
+        new Promise<never>((_fnResolve, fnReject) => {
+          objSignal.addEventListener('abort', () =>
+            fnReject(new DOMException('aborted', 'AbortError'))
+          )
+        })
+    )
+    const objFirstPromise = fnSwitchTenantWorkspace(
+      { strTenantId: 'tenant-a', strWorkspaceId: 'workspace-a' },
+      { objAdapter: { fnSwitch: fnFirstAdapter } }
+    )
+    await expect.poll(() => fnFirstAdapter).toHaveBeenCalledOnce()
+
+    const objSecondPromise = fnSwitchTenantWorkspace(
+      { strTenantId: 'tenant-a', strWorkspaceId: 'workspace-b' },
+      { objAdapter: { fnSwitch: async ({ objTarget }) => objTarget } }
+    )
+
+    await expect(objFirstPromise).rejects.toMatchObject({ name: 'AbortError' })
+    await expect(objSecondPromise).resolves.toMatchObject({
+      strWorkspaceId: 'workspace-b',
+    })
+    expect(fnGetTenantWorkspaceCurrent().strWorkspaceId).toBe('workspace-b')
+  })
+
+  it('exposes failed state and retry through the React provider', async () => {
+    let nAttempts = 0
+    const objAdapter: ITenantWorkspaceAdapter = {
+      fnSwitch: async ({ objTarget }) => {
+        nAttempts += 1
+        if (nAttempts === 1) throw new Error('temporary failure')
+        return objTarget
+      },
+    }
+    const objScreen = await render(
+      <TenantWorkspaceProvider objAdapter={objAdapter}>
+        <SwitchConsumer />
+      </TenantWorkspaceProvider>
+    )
+
+    await userEvent.click(objScreen.getByRole('button', { name: 'switch' }))
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveTextContent('error')
+    expect(fnGetTenantWorkspaceCurrent().strWorkspaceId).toBeUndefined()
+
+    await userEvent.click(objScreen.getByRole('button', { name: 'retry' }))
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveTextContent('idle')
+    await expect
+      .element(objScreen.getByRole('status'))
+      .toHaveAttribute('data-workspace', 'workspace-b')
+    expect(nAttempts).toBe(2)
+  })
+
+  it('uses stable classified errors when no adapter is configured', async () => {
+    await expect(
+      fnSwitchTenantWorkspace({
+        strTenantId: 'tenant-a',
+        strWorkspaceId: 'workspace-a',
+      })
+    ).rejects.toBeInstanceOf(TenantWorkspaceError)
+    expect(fnGetTenantWorkspaceSnapshot().objTransition).toMatchObject({
+      strStatus: 'error',
+      objError: { strCode: 'adapter_missing' },
+    })
+  })
+})

package/template/tools/bundle/budgets.json

@@ -0,0 +1,48 @@
+{
+  "nSchemaVersion": 1,
+  "arrBudgets": [
+    {
+      "strId": "bootstrap-js",
+      "strLabel": "应用启动 JavaScript",
+      "strOwner": "应用入口与运行时配置",
+      "strKind": "javascript",
+      "arrEntries": ["index.html"],
+      "nMaxGzipBytes": 86016
+    },
+    {
+      "strId": "sign-in-js",
+      "strLabel": "登录旅程 JavaScript",
+      "strOwner": "认证 Feature 与访客路由",
+      "strKind": "javascript",
+      "arrEntries": [
+        "index.html",
+        "src/Application.tsx",
+        "src/router/router.ts",
+        "src/features/auth/index.ts"
+      ],
+      "nMaxGzipBytes": 209920
+    },
+    {
+      "strId": "dashboard-js",
+      "strLabel": "中性首页旅程 JavaScript",
+      "strOwner": "认证后壳层与首页 Feature",
+      "strKind": "javascript",
+      "arrEntries": [
+        "index.html",
+        "src/Application.tsx",
+        "src/router/router.ts",
+        "src/layouts/AppLayout.tsx",
+        "src/features/home/index.tsx"
+      ],
+      "nMaxGzipBytes": 243712
+    },
+    {
+      "strId": "bootstrap-css",
+      "strLabel": "应用启动 CSS",
+      "strOwner": "全局样式与主题",
+      "strKind": "stylesheet",
+      "arrEntries": ["index.html"],
+      "nMaxGzipBytes": 18432
+    }
+  ]
+}

package/template/tools/bundle/check.mjs

@@ -0,0 +1,307 @@
+import { z } from 'zod'
+import { lstat, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { gzipSync } from 'node:zlib'
+
+const strCurrentDirectory = path.dirname(fileURLToPath(import.meta.url))
+const strDefaultProjectRoot = path.resolve(strCurrentDirectory, '../..')
+const strDefaultBudgetsPath = path.resolve(strCurrentDirectory, 'budgets.json')
+
+const objBudgetSchema = z
+  .object({
+    strId: z
+      .string()
+      .trim()
+      .regex(/^[a-z][a-z0-9-]*$/),
+    strLabel: z.string().trim().min(1),
+    strOwner: z.string().trim().min(1),
+    strKind: z.enum(['javascript', 'stylesheet']),
+    arrEntries: z.array(z.string().trim().min(1)).min(1),
+    nMaxGzipBytes: z.number().int().positive(),
+  })
+  .strict()
+
+const objBudgetsSchema = z
+  .object({
+    nSchemaVersion: z.literal(1),
+    arrBudgets: z.array(objBudgetSchema).min(1),
+  })
+  .strict()
+  .superRefine((objConfig, objContext) => {
+    const objIds = new Set()
+    objConfig.arrBudgets.forEach((objBudget, nIndex) => {
+      if (objIds.has(objBudget.strId)) {
+        objContext.addIssue({
+          code: 'custom',
+          message: `预算标识重复：${objBudget.strId}`,
+          path: ['arrBudgets', nIndex, 'strId'],
+        })
+      }
+      objIds.add(objBudget.strId)
+      if (new Set(objBudget.arrEntries).size !== objBudget.arrEntries.length) {
+        objContext.addIssue({
+          code: 'custom',
+          message: '入口列表不能包含重复项。',
+          path: ['arrBudgets', nIndex, 'arrEntries'],
+        })
+      }
+    })
+  })
+
+const objManifestEntrySchema = z
+  .object({
+    file: z.string().trim().min(1),
+    name: z.string().trim().min(1).optional(),
+    src: z.string().trim().min(1).optional(),
+    imports: z.array(z.string().trim().min(1)).default([]),
+    css: z.array(z.string().trim().min(1)).default([]),
+  })
+  .passthrough()
+const objManifestSchema = z.record(z.string(), objManifestEntrySchema)
+
+class BundleBudgetError extends Error {
+  constructor(strCode, strMessage) {
+    super(strMessage)
+    this.name = 'BundleBudgetError'
+    this.strCode = strCode
+  }
+}
+
+const fnFormatIssues = (arrIssues) =>
+  arrIssues
+    .map(
+      (objIssue) => `${objIssue.path.join('.') || 'root'}: ${objIssue.message}`
+    )
+    .join('; ')
+
+const fnReadJson = async (strFilePath, strCode) => {
+  try {
+    return JSON.parse(await readFile(strFilePath, 'utf8'))
+  } catch (objError) {
+    const strReason =
+      objError instanceof Error ? ` 原因：${objError.message}` : ''
+    throw new BundleBudgetError(
+      strCode,
+      `无法读取有效 JSON：${strFilePath}。${strReason}`
+    )
+  }
+}
+
+const fnAssertSafeAssetPath = (strAssetPath) => {
+  if (
+    path.posix.isAbsolute(strAssetPath) ||
+    strAssetPath.includes('\\') ||
+    strAssetPath.split('/').includes('..')
+  ) {
+    throw new BundleBudgetError(
+      'BUNDLE_MANIFEST_INVALID',
+      `Manifest 包含不安全的产物路径：${strAssetPath}。`
+    )
+  }
+}
+
+const fnValidateBudgets = (objInput) => {
+  const objResult = objBudgetsSchema.safeParse(objInput)
+  if (!objResult.success) {
+    throw new BundleBudgetError(
+      'BUNDLE_BUDGET_CONFIG_INVALID',
+      `体积预算配置不符合契约：${fnFormatIssues(objResult.error.issues)}`
+    )
+  }
+  return objResult.data
+}
+
+const fnValidateManifest = (objInput) => {
+  const objResult = objManifestSchema.safeParse(objInput)
+  if (!objResult.success || Object.keys(objResult.data ?? {}).length === 0) {
+    throw new BundleBudgetError(
+      'BUNDLE_MANIFEST_INVALID',
+      objResult.success
+        ? 'Vite Manifest 不能为空。'
+        : `Vite Manifest 不符合契约：${fnFormatIssues(objResult.error.issues)}`
+    )
+  }
+  for (const objEntry of Object.values(objResult.data)) {
+    fnAssertSafeAssetPath(objEntry.file)
+    objEntry.css.forEach(fnAssertSafeAssetPath)
+  }
+  return objResult.data
+}
+
+const fnCollectStaticEntries = (objManifest, arrEntryKeys) => {
+  const arrPendingKeys = [...arrEntryKeys]
+  const objEntryKeys = new Set()
+  while (arrPendingKeys.length > 0) {
+    const strEntryKey = arrPendingKeys.pop()
+    if (!strEntryKey || objEntryKeys.has(strEntryKey)) continue
+    const objEntry = objManifest[strEntryKey]
+    if (!objEntry) {
+      throw new BundleBudgetError(
+        'BUNDLE_MANIFEST_ENTRY_MISSING',
+        `Vite Manifest 缺少预算入口或静态依赖：${strEntryKey}。`
+      )
+    }
+    objEntryKeys.add(strEntryKey)
+    arrPendingKeys.push(...objEntry.imports)
+  }
+  return [...objEntryKeys]
+}
+
+const fnResolveAssetOwner = (strEntryKey, objEntry) =>
+  objEntry.src ?? objEntry.name ?? strEntryKey.replace(/^_/, '')
+
+const fnCollectBudgetAssets = (objManifest, objBudget) => {
+  const arrEntryKeys = fnCollectStaticEntries(objManifest, objBudget.arrEntries)
+  const objAssets = new Map()
+  for (const strEntryKey of arrEntryKeys) {
+    const objEntry = objManifest[strEntryKey]
+    const strOwner = fnResolveAssetOwner(strEntryKey, objEntry)
+    if (
+      objBudget.strKind === 'javascript' &&
+      objEntry.file.endsWith('.js') &&
+      !objAssets.has(objEntry.file)
+    ) {
+      objAssets.set(objEntry.file, strOwner)
+    }
+    if (objBudget.strKind === 'stylesheet') {
+      for (const strCssFile of objEntry.css) {
+        if (!objAssets.has(strCssFile)) objAssets.set(strCssFile, strOwner)
+      }
+    }
+  }
+  if (objAssets.size === 0) {
+    throw new BundleBudgetError(
+      'BUNDLE_MANIFEST_INVALID',
+      `预算 ${objBudget.strId} 没有匹配到 ${objBudget.strKind} 产物。`
+    )
+  }
+  return objAssets
+}
+
+const fnReadGzipSize = async (strDistRoot, strAssetPath) => {
+  fnAssertSafeAssetPath(strAssetPath)
+  const strFilePath = path.resolve(strDistRoot, strAssetPath)
+  let objStats
+  try {
+    objStats = await lstat(strFilePath)
+  } catch (objError) {
+    const strReason =
+      objError instanceof Error ? ` 原因：${objError.message}` : ''
+    throw new BundleBudgetError(
+      'BUNDLE_ASSET_INVALID',
+      `Manifest 产物不存在：${strAssetPath}。${strReason}`
+    )
+  }
+  if (!objStats.isFile() || objStats.isSymbolicLink()) {
+    throw new BundleBudgetError(
+      'BUNDLE_ASSET_INVALID',
+      `Manifest 产物必须是普通文件且不能是符号链接：${strAssetPath}。`
+    )
+  }
+  return gzipSync(await readFile(strFilePath), { level: 9 }).length
+}
+
+/** 基于 Vite 静态依赖图计算关键用户旅程的 gzip 传输体积。 */
+export async function fnCheckBundleBudgets({
+  strBudgetsPath = strDefaultBudgetsPath,
+  strDistRoot = path.resolve(strDefaultProjectRoot, 'dist'),
+} = {}) {
+  const strResolvedDistRoot = path.resolve(strDistRoot)
+  const [objBudgetInput, objManifestInput] = await Promise.all([
+    fnReadJson(path.resolve(strBudgetsPath), 'BUNDLE_BUDGET_CONFIG_INVALID'),
+    fnReadJson(
+      path.resolve(strResolvedDistRoot, '.vite/manifest.json'),
+      'BUNDLE_MANIFEST_INVALID'
+    ),
+  ])
+  const objConfig = fnValidateBudgets(objBudgetInput)
+  const objManifest = fnValidateManifest(objManifestInput)
+  const objGzipSizeCache = new Map()
+  const arrResults = []
+
+  for (const objBudget of objConfig.arrBudgets) {
+    const objAssets = fnCollectBudgetAssets(objManifest, objBudget)
+    const arrAssets = []
+    for (const [strAssetPath, strOwner] of objAssets) {
+      let nGzipBytes = objGzipSizeCache.get(strAssetPath)
+      if (nGzipBytes === undefined) {
+        nGzipBytes = await fnReadGzipSize(strResolvedDistRoot, strAssetPath)
+        objGzipSizeCache.set(strAssetPath, nGzipBytes)
+      }
+      arrAssets.push({ nGzipBytes, strAssetPath, strOwner })
+    }
+    arrAssets.sort(
+      (objLeft, objRight) => objRight.nGzipBytes - objLeft.nGzipBytes
+    )
+    const nGzipBytes = arrAssets.reduce(
+      (nTotal, objAsset) => nTotal + objAsset.nGzipBytes,
+      0
+    )
+    arrResults.push({
+      ...objBudget,
+      arrAssets,
+      bPassed: nGzipBytes <= objBudget.nMaxGzipBytes,
+      nGzipBytes,
+    })
+  }
+
+  return {
+    arrResults,
+    bPassed: arrResults.every((objResult) => objResult.bPassed),
+  }
+}
+
+const fnFormatKiB = (nBytes) => `${(nBytes / 1024).toFixed(2)} KiB`
+
+const fnPrintReport = (objReport) => {
+  for (const objResult of objReport.arrResults) {
+    const strLevel = objResult.bPassed ? 'PASS' : 'ERROR'
+    const strCode = objResult.bPassed
+      ? 'BUNDLE_BUDGET_OK'
+      : 'BUNDLE_BUDGET_EXCEEDED'
+    process.stdout.write(
+      `[${strLevel}] ${strCode} ${objResult.strId} ${objResult.strLabel}：` +
+        `${fnFormatKiB(objResult.nGzipBytes)} / ${fnFormatKiB(objResult.nMaxGzipBytes)}；` +
+        `Owner：${objResult.strOwner}。\n`
+    )
+    if (!objResult.bPassed) {
+      process.stdout.write('        主要 Chunk：\n')
+      for (const objAsset of objResult.arrAssets.slice(0, 5)) {
+        process.stdout.write(
+          `        - ${objAsset.strOwner} / ${objAsset.strAssetPath} / ` +
+            `${fnFormatKiB(objAsset.nGzipBytes)}\n`
+        )
+      }
+      process.stdout.write(
+        '        修复：检查上述入口最近新增的静态依赖，按路由或可选能力拆分后重新构建。\n'
+      )
+    }
+  }
+  if (!objReport.bPassed) process.exitCode = 1
+}
+
+const fnRunCli = async () => {
+  try {
+    if (process.argv.length > 2) {
+      throw new BundleBudgetError(
+        'BUNDLE_BUDGET_ARGUMENT_INVALID',
+        'bundle:check 不接受参数；预算由 tools/bundle/budgets.json 统一维护。'
+      )
+    }
+    fnPrintReport(await fnCheckBundleBudgets())
+  } catch (objError) {
+    const strCode =
+      objError instanceof BundleBudgetError
+        ? objError.strCode
+        : 'BUNDLE_BUDGET_CHECK_FAILED'
+    const strMessage =
+      objError instanceof Error ? objError.message : '构建体积检查失败。'
+    process.stderr.write(`[ERROR] ${strCode} ${strMessage}\n`)
+    process.exitCode = 1
+  }
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  await fnRunCli()
+}