create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/apps/web/test/workspace-navigation-boundary.spec.tsx

@@ -0,0 +1,169 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+const antdMocks = vi.hoisted(() => ({ destroyAll: vi.fn() }))
+vi.mock('antd', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('antd')>()
+  return { ...actual, Modal: { ...actual.Modal, destroyAll: antdMocks.destroyAll } }
+})
+
+import { ConfigProvider } from 'antd'
+import WorkspaceNavigationBoundary from '../src/layouts/WorkspaceLayout/components/WorkspaceNavigationBoundary'
+
+let host: HTMLDivElement
+let root: ReturnType<typeof createRoot>
+
+/** 读取内层 ConfigProvider 的宿主并模拟 Ant Design 页面级 portal。 */
+function PortalDialog({ onSave }: { onSave: () => void }) {
+  const { getPopupContainer } = useContext(ConfigProvider.ConfigContext)
+  return createPortal(
+    <button type="button" data-testid="portal-save" onClick={onSave}>
+      保存企业 A
+    </button>,
+    getPopupContainer?.() ?? document.body,
+  )
+}
+
+/** 模拟带未保存本地状态及打开弹窗的工作空间页面。 */
+function WorkspacePage({ onSave, onUnmount }: { onSave: () => void; onUnmount: () => void }) {
+  const [count, setCount] = useState(0)
+  const [open, setOpen] = useState(false)
+
+  useEffect(() => onUnmount, [onUnmount])
+
+  return (
+    <section data-testid="workspace-page">
+      <span data-testid="draft-count">{count}</span>
+      <button
+        type="button"
+        data-testid="change-draft"
+        onClick={() => setCount((value) => value + 1)}
+      >
+        修改草稿
+      </button>
+      <button type="button" data-testid="open-portal" onClick={() => setOpen(true)}>
+        编辑企业 A
+      </button>
+      {open && <PortalDialog onSave={onSave} />}
+    </section>
+  )
+}
+
+interface RenderBoundaryOptions {
+  navigating?: boolean
+  refreshing?: boolean
+  pageKey?: string
+  onSave: () => void
+  onUnmount: () => void
+}
+
+/** 同步提交导航或重校验状态，便于断言页面状态和 portal 宿主。 */
+function renderBoundary({
+  navigating = false,
+  refreshing = false,
+  pageKey = 'current-page',
+  onSave,
+  onUnmount,
+}: RenderBoundaryOptions) {
+  flushSync(() => {
+    root.render(
+      <WorkspaceNavigationBoundary
+        navigating={navigating}
+        refreshing={refreshing}
+        fallback={<div data-testid="workspace-loading">加载中</div>}
+      >
+        <div key={pageKey}>
+          <WorkspacePage onSave={onSave} onUnmount={onUnmount} />
+        </div>
+      </WorkspaceNavigationBoundary>,
+    )
+  })
+}
+
+/** 点击指定测试元素并同步提交由事件触发的状态更新。 */
+function click(testId: string) {
+  flushSync(() => {
+    ;(document.querySelector(`[data-testid="${testId}"]`) as HTMLButtonElement).click()
+  })
+}
+
+beforeEach(() => {
+  document.body.replaceChildren()
+  host = document.createElement('div')
+  document.body.append(host)
+  root = createRoot(host)
+  antdMocks.destroyAll.mockClear()
+})
+
+afterEach(() => {
+  flushSync(() => root.unmount())
+  document.body.replaceChildren()
+})
+
+describe('工作空间等待交互边界', () => {
+  it('权限重校验保留页面和弹窗状态，同时隐藏并禁用页面与 portal 宿主', () => {
+    const save = vi.fn()
+    const unmount = vi.fn()
+    renderBoundary({ onSave: save, onUnmount: unmount })
+    click('change-draft')
+    click('open-portal')
+
+    const portalButton = document.querySelector('[data-testid="portal-save"]')
+    const portalHost = portalButton?.closest('.workspace-portal-host') as HTMLDivElement
+    expect(portalButton).not.toBeNull()
+    expect(portalHost).not.toBeNull()
+
+    renderBoundary({ refreshing: true, onSave: save, onUnmount: unmount })
+
+    const pageSurface = document.querySelector('.workspace-page-surface') as HTMLDivElement
+    expect(document.querySelector('[data-testid="workspace-page"]')).not.toBeNull()
+    expect(document.querySelector('[data-testid="draft-count"]')?.textContent).toBe('1')
+    expect(document.querySelector('[data-testid="portal-save"]')).toBe(portalButton)
+    expect(pageSurface.hidden).toBe(true)
+    expect(pageSurface.hasAttribute('inert')).toBe(true)
+    expect(portalHost.hidden).toBe(true)
+    expect(portalHost.hasAttribute('inert')).toBe(true)
+    expect(document.querySelector('[data-testid="workspace-loading"]')).not.toBeNull()
+    expect(unmount).not.toHaveBeenCalled()
+    expect(antdMocks.destroyAll).toHaveBeenCalledOnce()
+
+    renderBoundary({ onSave: save, onUnmount: unmount })
+    expect(document.querySelector('[data-testid="draft-count"]')?.textContent).toBe('1')
+    expect(document.querySelector('[data-testid="portal-save"]')).toBe(portalButton)
+    expect(portalHost.hidden).toBe(false)
+    expect(unmount).not.toHaveBeenCalled()
+  })
+
+  it('跨路由导航保留旧页面快照并隔离交互，提交新路由后创建全新页面状态', () => {
+    const save = vi.fn()
+    const unmount = vi.fn()
+    renderBoundary({ onSave: save, onUnmount: unmount })
+    click('change-draft')
+    click('open-portal')
+    const oldPortalButton = document.querySelector(
+      '[data-testid="portal-save"]',
+    ) as HTMLButtonElement
+
+    renderBoundary({ navigating: true, onSave: save, onUnmount: unmount })
+
+    const pageSurface = document.querySelector('.workspace-page-surface') as HTMLDivElement
+    const portalHost = document.querySelector('.workspace-portal-host') as HTMLDivElement
+    expect(document.querySelector('[data-testid="workspace-page"]')).not.toBeNull()
+    expect(document.querySelector('[data-testid="draft-count"]')?.textContent).toBe('1')
+    expect(document.querySelector('[data-testid="portal-save"]')).toBe(oldPortalButton)
+    expect(document.querySelector('[data-testid="workspace-loading"]')).not.toBeNull()
+    expect(pageSurface.hidden).toBe(false)
+    expect(pageSurface.hasAttribute('inert')).toBe(true)
+    expect(portalHost.hidden).toBe(true)
+    expect(portalHost.hasAttribute('inert')).toBe(true)
+    expect(unmount).not.toHaveBeenCalled()
+    expect(antdMocks.destroyAll).toHaveBeenCalledOnce()
+
+    renderBoundary({ pageKey: 'next-page', onSave: save, onUnmount: unmount })
+    expect(unmount).toHaveBeenCalledOnce()
+    expect(document.querySelector('[data-testid="draft-count"]')?.textContent).toBe('0')
+    expect(document.querySelector('[data-testid="portal-save"]')).toBeNull()
+    expect(save).not.toHaveBeenCalled()
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/web/test/workspace-navigation.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vite-plus/test'
+import type { AccessContext, MenuNode } from 'shared/types'
+import { ACCESS_PAGE_CATALOG } from 'shared/utils'
+import { resolveSvgAsset, svgAssets } from '../src/components/Icon/SvgAsset'
+import {
+  firstAccessiblePagePath,
+  navigationTree,
+  pagePath,
+} from '../src/router/page-registry'
+
+/** 构造可覆盖字段的菜单节点，供导航和权限筛选用例复用。 */
+function node(input: Partial<MenuNode>): MenuNode {
+  return {
+    id: 'node',
+    scopeType: 'company',
+    parentId: null,
+    type: 'page',
+    name: '页面',
+    icon: '',
+    sort: 0,
+    hidden: false,
+    status: 'active',
+    routeKey: 'company.home',
+    permissionKey: 'company.home.read',
+    protected: false,
+    children: [],
+    ...input,
+  }
+}
+
+describe('前端静态页面注册与菜单', () => {
+  it('未知页面及其按钮和空目录不会进入菜单，来源数据不被修改', () => {
+    const menus = [
+      node({ id: 'known' }),
+      node({
+        id: 'directory',
+        type: 'directory',
+        routeKey: null,
+        children: [
+          node({
+            id: 'future',
+            routeKey: 'company.future',
+            children: [node({ type: 'operation', routeKey: 'company.future' })],
+          }),
+        ],
+      }),
+    ]
+    const before = JSON.stringify(menus)
+    expect(
+      navigationTree(menus, { type: 'company', companyId: 'a' }).map((item) => item.key),
+    ).toEqual(['/companies/a'])
+    expect(JSON.stringify(menus)).toBe(before)
+  })
+
+  it('隐藏或停用菜单不显示；隐藏页面已注册路径仍能被 loader 单独鉴权', () => {
+    const scope = { type: 'company', companyId: 'a' } as const
+    expect(
+      navigationTree([node({ hidden: true }), node({ id: 'disabled', status: 'disabled' })], scope),
+    ).toEqual([])
+    expect(pagePath(scope, 'company.home')).toBe('/companies/a')
+  })
+
+  it('不为未知或跨作用域页面生成路径', () => {
+    expect(pagePath({ type: 'platform' }, 'company.members')).toBeNull()
+    expect(pagePath({ type: 'platform' }, 'platform.future')).toBeNull()
+  })
+
+  it('菜单目录图标均能解析为本地 SVG 资源', () => {
+    for (const page of ACCESS_PAGE_CATALOG) {
+      expect(resolveSvgAsset(page.icon).key).toBe(page.icon)
+    }
+    expect(svgAssets.map((asset) => asset.key)).toContain('menu-item')
+    expect(resolveSvgAsset('').key).toBe('menu-item')
+    expect(resolveSvgAsset('missing-icon').key).toBe('menu-item')
+  })
+
+  it('进入空间优先落在已授权的可见菜单，排除未知及跨作用域页面', () => {
+    const context = {
+      scope: { type: 'company', companyId: 'a' },
+      permissionKeys: [
+        'platform.menus.read',
+        'company.future.read',
+        'company.roles.read',
+        'company.members.read',
+      ],
+      menus: [
+        node({ routeKey: 'company.future' }),
+        node({ routeKey: 'company.members', hidden: true }),
+        node({ routeKey: 'company.roles' }),
+      ],
+    } as AccessContext
+    expect(firstAccessiblePagePath(context)).toBe('/companies/a/roles')
+    expect(firstAccessiblePagePath({ ...context, menus: [] })).toBe('/companies/a/members')
+  })
+
+  it('没有已授权静态页面时不生成工作空间落点', () => {
+    expect(
+      firstAccessiblePagePath({
+        scope: { type: 'platform' },
+        permissionKeys: ['platform.future.read', 'company.members.read'],
+        menus: [],
+      } as unknown as AccessContext),
+    ).toBeNull()
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/web/test/workspace-requests.spec.ts

@@ -0,0 +1,174 @@
+import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+
+vi.mock('../src/utils/request/index', () => ({ default: () => ({}) }))
+const cookieMocks = vi.hoisted(() => ({ get: vi.fn(() => 'session-one'), remove: vi.fn() }))
+vi.mock('../src/utils/storage/cookie', () => ({ cookie: cookieMocks }))
+
+import {
+  clearWorkspaceRequests,
+  enterWorkspace,
+  runWorkspaceRequest,
+} from '../src/utils/request/workspace'
+
+const dispatchEvent = vi.fn()
+const assign = vi.fn()
+
+/** 创建可手动完成或拒绝的请求替身，用于验证取消与迟到响应。 */
+function deferredMethod<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason: unknown) => void
+  const promise = new Promise<T>((onResolve, onReject) => {
+    resolve = onResolve
+    reject = onReject
+  })
+  return { method: { send: () => promise, abort: vi.fn() }, resolve, reject }
+}
+
+beforeEach(() => {
+  clearWorkspaceRequests()
+  vi.clearAllMocks()
+  cookieMocks.get.mockReturnValue('session-one')
+  vi.stubGlobal('window', { dispatchEvent, location: { assign } })
+})
+
+describe('工作空间请求隔离', () => {
+  it('切换空间取消旧请求，即使服务端迟到成功也不返回旧数据', async () => {
+    enterWorkspace('company:a')
+    const pending = deferredMethod<string>()
+    const result = runWorkspaceRequest({ method: pending.method, workspaceKey: 'company:a' })
+    const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' })
+    enterWorkspace('company:b')
+    pending.resolve('企业 A 的数据')
+    await rejected
+    expect(pending.method.abort).toHaveBeenCalledOnce()
+  })
+
+  it('重复进入同一空间不会中止该空间的在途请求', async () => {
+    enterWorkspace('company:a')
+    const pending = deferredMethod<string>()
+    const result = runWorkspaceRequest({ method: pending.method, workspaceKey: 'company:a' })
+
+    enterWorkspace('company:a')
+    expect(pending.method.abort).not.toHaveBeenCalled()
+
+    pending.resolve('企业 A 的数据')
+    await expect(result).resolves.toBe('企业 A 的数据')
+  })
+
+  it('连续切换 A、B、C 时前两个空间失效，当前空间仍可正常完成', async () => {
+    enterWorkspace('company:a')
+    const companyA = deferredMethod<string>()
+    const resultA = runWorkspaceRequest({ method: companyA.method, workspaceKey: 'company:a' })
+    const rejectedA = expect(resultA).rejects.toMatchObject({ name: 'AbortError' })
+
+    enterWorkspace('company:b')
+    const companyB = deferredMethod<string>()
+    const resultB = runWorkspaceRequest({ method: companyB.method, workspaceKey: 'company:b' })
+    const rejectedB = expect(resultB).rejects.toMatchObject({ name: 'AbortError' })
+
+    enterWorkspace('company:c')
+    const currentMethod = {
+      send: vi.fn(() => Promise.resolve('企业 C 的数据')),
+      abort: vi.fn(),
+    }
+    await expect(
+      runWorkspaceRequest({ method: currentMethod, workspaceKey: 'company:c' }),
+    ).resolves.toBe('企业 C 的数据')
+
+    companyA.resolve('企业 A 的迟到数据')
+    companyB.resolve('企业 B 的迟到数据')
+    await Promise.all([rejectedA, rejectedB])
+    expect(companyA.method.abort).toHaveBeenCalledOnce()
+    expect(companyB.method.abort).toHaveBeenCalledOnce()
+    expect(currentMethod.abort).not.toHaveBeenCalled()
+  })
+
+  it('旧账号迟到的 401 不能删除新账号 Cookie 或触发跳转', async () => {
+    enterWorkspace('company:a')
+    const pending = deferredMethod<string>()
+    const result = runWorkspaceRequest({ method: pending.method, workspaceKey: 'company:a' })
+    const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' })
+    cookieMocks.get.mockReturnValue('session-two')
+    enterWorkspace('company:a')
+    pending.reject(Object.assign(new Error('旧会话失效'), { status: 401 }))
+    await rejected
+    expect(cookieMocks.remove).not.toHaveBeenCalled()
+    expect(assign).not.toHaveBeenCalled()
+  })
+
+  it('旧作用域迟到的 403 不刷新新空间权限', async () => {
+    enterWorkspace('company:a')
+    const pending = deferredMethod<string>()
+    const result = runWorkspaceRequest({ method: pending.method, workspaceKey: 'company:a' })
+    const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' })
+    enterWorkspace('company:b')
+    pending.reject(Object.assign(new Error('无权限'), { status: 403 }))
+    await rejected
+    expect(dispatchEvent).not.toHaveBeenCalled()
+  })
+
+  it('当前业务请求 403 触发权限刷新，access 请求失败不递归刷新', async () => {
+    enterWorkspace('platform')
+    const error = Object.assign(new Error('无权限'), { status: 403 })
+    await expect(
+      runWorkspaceRequest({
+        method: { send: () => Promise.reject(error), abort: vi.fn() },
+        workspaceKey: 'platform',
+      }),
+    ).rejects.toBe(error)
+    expect(dispatchEvent).toHaveBeenCalledOnce()
+    dispatchEvent.mockClear()
+    await expect(
+      runWorkspaceRequest({
+        method: { send: () => Promise.reject(error), abort: vi.fn() },
+        workspaceKey: 'platform',
+        accessRequest: true,
+      }),
+    ).rejects.toBe(error)
+    expect(dispatchEvent).not.toHaveBeenCalled()
+  })
+
+  it('当前空间的 401 会清理登录令牌并跳转登录页', async () => {
+    enterWorkspace('platform')
+    const error = Object.assign(new Error('登录已失效'), { status: 401 })
+
+    await expect(
+      runWorkspaceRequest({
+        method: { send: () => Promise.reject(error), abort: vi.fn() },
+        workspaceKey: 'platform',
+      }),
+    ).rejects.toBe(error)
+
+    expect(cookieMocks.remove).toHaveBeenCalledWith('token')
+    expect(assign).toHaveBeenCalledWith('/login')
+  })
+
+  it('Router AbortSignal 取消后拒绝迟到结果', async () => {
+    enterWorkspace('project:a:p')
+    const controller = new AbortController()
+    const pending = deferredMethod<string>()
+    const result = runWorkspaceRequest({
+      method: pending.method,
+      workspaceKey: 'project:a:p',
+      signal: controller.signal,
+    })
+    const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' })
+    controller.abort()
+    pending.resolve('迟到结果')
+    await rejected
+    expect(pending.method.abort).toHaveBeenCalledOnce()
+  })
+
+  it('绑定旧空间的请求不能在新空间代次中借用 generation 发出', async () => {
+    enterWorkspace('company:a')
+    enterWorkspace('company:b')
+    const method = { send: vi.fn(() => Promise.resolve('不应发送')), abort: vi.fn() }
+
+    await expect(runWorkspaceRequest({ method, workspaceKey: 'company:a' })).rejects.toMatchObject({
+      name: 'AbortError',
+    })
+
+    expect(method.send).not.toHaveBeenCalled()
+    expect(method.abort).not.toHaveBeenCalled()
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/web/vite.config.ts

@@ -5,48 +5,97 @@ import AutoImport from 'unplugin-auto-import/vite'
 import svgr from 'vite-plugin-svgr'
 import { defineConfig, loadEnv } from 'vite-plus'
 
-export default defineConfig(({ mode }) => {
-  const root = process.cwd()
-  const env = loadEnv(mode, root)
-  const { VITE_PORT, VITE_API_AFFIX, VITE_API_URL } = env
+export default defineConfig(
+  /** 按运行模式配置 Web 开发代理、自动导入和构建插件。 */ ({ mode }) => {
+    const root = process.cwd()
+    const env = loadEnv(mode, root)
+    const { VITE_PORT, VITE_API_AFFIX, VITE_API_URL } = env
 
-  console.log(`
+    console.log(`
     mode: ${mode}
     VITE_PORT: ${VITE_PORT}
     VITE_API_AFFIX: ${VITE_API_AFFIX}
     VITE_API_URL: ${VITE_API_URL}
     `)
 
-  return {
-    test: {
-      environment: 'node',
-      include: ['test/**/*.spec.ts'],
-      restoreMocks: true,
-    },
-    resolve: {
-      alias: {
-        '@': path.resolve(__dirname, 'src'),
+    return {
+      test: {
+        environment: 'node',
+        include: ['test/**/*.spec.{ts,tsx}'],
+        restoreMocks: true,
       },
-    },
-    server: {
-      port: Number(VITE_PORT),
-      host: '0.0.0.0',
-      proxy: {
-        [VITE_API_AFFIX]: {
-          target: VITE_API_URL,
-          changeOrigin: true,
-          rewrite: (path) => path.replace(new RegExp('^' + VITE_API_AFFIX), ''),
+      resolve: {
+        alias: {
+          '@': path.resolve(__dirname, 'src'),
         },
       },
-    },
-    plugins: [
-      react(),
-      svgr({ svgrOptions: { icon: true, ref: true } }),
-      AutoImport({
-        imports: ['react', 'react-router', 'react-dom'],
-        dts: './src/types/auto-imports.d.ts',
-      }),
-      tailwindcss(),
-    ],
-  }
-})
+      server: {
+        port: Number(VITE_PORT),
+        host: '0.0.0.0',
+        proxy: {
+          [VITE_API_AFFIX]: {
+            target: VITE_API_URL,
+            changeOrigin: true,
+            rewrite: (path) => path.replace(new RegExp('^' + VITE_API_AFFIX), ''),
+          },
+        },
+      },
+      plugins: [
+        react(),
+        svgr({ svgrOptions: { icon: true, ref: true } }),
+        AutoImport({
+          imports: [
+            'react',
+            'react-router',
+            'react-dom',
+            {
+              react: [['ViewTransition', 'ReactViewTransition']],
+            },
+            {
+              'react-router': [
+                'RouterProvider',
+                'Link',
+                'Outlet',
+                'useNavigation',
+                'useMatches',
+                'useRevalidator',
+                'useSearchParams',
+                'createBrowserRouter',
+                'redirect',
+                ['createContext', 'createRouterContext'],
+                'isRouteErrorResponse',
+                'useRouteError',
+                'createMemoryRouter',
+              ],
+            },
+            {
+              'react-dom/client': ['createRoot'],
+            },
+            {
+              from: 'react',
+              type: true,
+              imports: [
+                'ReactNode',
+                'ComponentType',
+                'SVGProps',
+                'PropsWithChildren',
+                'Key',
+                'Ref',
+                'LazyExoticComponent',
+                'ReactElement',
+              ],
+            },
+            {
+              from: 'react-router',
+              type: true,
+              imports: ['MiddlewareFunction', 'DataRouter', 'RouterState', 'RouteObject'],
+            },
+          ],
+          dts: path.resolve(__dirname, 'src/types/auto-imports.d.ts'),
+          dtsMode: 'overwrite',
+        }),
+        tailwindcss(),
+      ],
+    }
+  },
+)

package/template-vp-monorepo-react-nestjs/apps/web-vue/package.json

@@ -13,6 +13,8 @@
   "dependencies": {
     "@alova/adapter-axios": "catalog:",
     "@antdv-next/icons": "catalog:",
+    "@bubblesjs/i18n-vue": "workspace:*",
+    "@vue/devtools-api": "catalog:",
     "alova": "catalog:",
     "antdv-next": "catalog:",
     "axios": "catalog:",

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/api/index.ts

@@ -2,6 +2,7 @@ import request from '@/utils/request'
 
 export const EXPIRE_TIME = 60 * 10 * 1000
 
+/** 创建树形示例数据请求，使用可恢复缓存并设置十分钟有效期。 */
 export function getTree() {
   return request.Get('/xxx/xx', {
     cacheFor: {

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/hooks/chart/useEcharts.ts

@@ -8,6 +8,11 @@ import echarts from './lib'
 
 type setOptionsType = (options: EChartsOption, clear?: boolean) => void
 
+/**
+ * 管理图表的懒初始化、容器尺寸监听和组件卸载清理。
+ * @param elRef 图表容器引用，容器尚未挂载时延后初始化。
+ * @returns 设置图表配置、调整尺寸和获取实例的方法及 ECharts 模块。
+ */
 export function useECharts(
   elRef: Ref<HTMLDivElement> | Readonly<ShallowRef<HTMLDivElement | null>>,
 ) {
@@ -18,6 +23,7 @@ export function useECharts(
     chartInstance?.resize()
   }
 
+  /** 容器就绪后创建图表，并以防抖监听容器尺寸变化。 */
   const initCharts = () => {
     if (!elRef)
       return
@@ -38,6 +44,11 @@ export function useECharts(
     chartInstance = echarts.init(el)
   }
 
+  /**
+   * 确保图表已初始化后应用配置；容器未就绪时忽略本次设置。
+   * @param options ECharts 图表配置。
+   * @param clear 是否先清空已有图表，默认为 `true`。
+   */
   const setOptions: setOptionsType = (options, clear = true) => {
     if (!chartInstance) {
       initCharts()
@@ -49,13 +60,14 @@ export function useECharts(
     chartInstance?.setOption(options)
   }
 
+  /** 按需初始化并返回图表实例；容器未就绪时返回 `null`。 */
   const getInstance: () => echarts.ECharts | null = () => {
     if (!chartInstance)
       initCharts()
     return chartInstance
   }
 
-  onUnmounted(() => {
+  onUnmounted(/** 释放图表和尺寸观察器，防止卸载后继续监听。 */ () => {
     chartInstance?.dispose()
     resizeObserver?.disconnect()
     resizeObserver = undefined

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/layout/default/header/index.vue

@@ -4,6 +4,7 @@ import { useUserStoreWithOut } from '@/store/modules/user'
 const userStore = useUserStoreWithOut()
 const router = useRouter()
 
+/** 处理用户菜单；退出登录时重置用户状态并跳转到登录页。 */
 function handleMenuClick({ key }: { key: string }) {
   if (key === 'logout') {
     userStore.$reset()