create-bubbles 0.1.25 → 0.1.26

package/template-vp-monorepo-react-nestjs/apps/server/test/task-queue.integration.spec.ts

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto'
+import { getQueueToken } from '@nestjs/bullmq'
+import { ConfigModule } from '@nestjs/config'
+import { Test, type TestingModule } from '@nestjs/testing'
+import { type Queue, QueueEvents } from 'bullmq'
+import { afterAll, beforeAll, describe, expect, it } from 'vite-plus/test'
+import queueConfig from '@/config/queue.config'
+import { TaskQueueModule } from '@/modules/task-queue/task-queue.module'
+import { TaskQueueService } from '@/modules/task-queue/task-queue.service'
+import { TASK_JOB_NAMES, TASK_QUEUE_NAME } from '@/modules/task-queue/task-queue.constants'
+import { ENV_ARR } from '@/utils/env-arr'
+
+const describeQueueIntegration =
+  process.env.RUN_QUEUE_INTEGRATION === 'true' ? describe : describe.skip
+
+describeQueueIntegration('TaskQueue Redis integration', () => {
+  let testingModule: TestingModule | undefined
+  let queue: Queue | undefined
+  let queueEvents: QueueEvents | undefined
+  let taskQueueService: TaskQueueService | undefined
+
+  const previousPrefix = process.env.QUEUE_PREFIX
+  const previousWorkerEnabled = process.env.QUEUE_WORKER_ENABLED
+  const uniquePrefix = 'bubbles:test:' + randomUUID() + ':queue'
+
+  beforeAll(async () => {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('Queue integration test must not run in production')
+    }
+
+    process.env.QUEUE_PREFIX = uniquePrefix
+    process.env.QUEUE_WORKER_ENABLED = 'true'
+
+    testingModule = await Test.createTestingModule({
+      imports: [
+        ConfigModule.forRoot({
+          isGlobal: true,
+          envFilePath: ENV_ARR,
+          load: [queueConfig],
+        }),
+        TaskQueueModule,
+      ],
+    }).compile()
+
+    // 必须调用。compile() 本身不会触发
+    // QueueWorkerBootstrap.onApplicationBootstrap()
+    await testingModule.init()
+
+    queue = testingModule.get<Queue>(getQueueToken(TASK_QUEUE_NAME))
+    taskQueueService = testingModule.get(TaskQueueService)
+
+    // QueueEvents 必须与 Queue 使用完全相同的
+    // connection、DB 和 prefix。
+    queueEvents = new QueueEvents(TASK_QUEUE_NAME, {
+      connection: queue.opts.connection,
+      prefix: queue.opts.prefix,
+    })
+
+    // 必须先 ready，再投递，避免错过完成事件。
+    await queueEvents.waitUntilReady()
+  })
+
+  it('completes a Job through real Redis', async () => {
+    if (!queue || !queueEvents || !taskQueueService) {
+      throw new Error('Queue integration test was not initialized')
+    }
+
+    const queued = await taskQueueService.enqueue(
+      TASK_JOB_NAMES.QUEUE_SMOKE,
+      {
+        marker: 'redis-smoke',
+        enqueuedAt: new Date().toISOString(),
+      },
+      {
+        jobId: 'queue-smoke-' + randomUUID(),
+      },
+    )
+
+    const job = await queue.getJob(queued.jobId)
+
+    if (!job) {
+      throw new Error('Smoke Job was not found')
+    }
+
+    const result = await job.waitUntilFinished(queueEvents, 10_000)
+
+    expect(result.marker).toBe('redis-smoke')
+  }, 15_000)
+
+  afterAll(async () => {
+    try {
+      await queueEvents?.close()
+
+      if (queue) {
+        if (queue.opts.prefix !== uniquePrefix) {
+          throw new Error('Refusing to clean a non-test Queue prefix')
+        }
+
+        // 这里只清理由随机 Prefix 创建的测试队列。
+        await queue.obliterate({ force: true })
+      }
+    } finally {
+      try {
+        await testingModule?.close()
+      } finally {
+        if (previousPrefix === undefined) {
+          delete process.env.QUEUE_PREFIX
+        } else {
+          process.env.QUEUE_PREFIX = previousPrefix
+        }
+
+        if (previousWorkerEnabled === undefined) {
+          delete process.env.QUEUE_WORKER_ENABLED
+        } else {
+          process.env.QUEUE_WORKER_ENABLED = previousWorkerEnabled
+        }
+      }
+    }
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/server/test/task-queue.processor.spec.ts

@@ -0,0 +1,63 @@
+import type { Job } from 'bullmq'
+import { UnrecoverableError } from 'bullmq'
+import { describe, expect, it, vi } from 'vite-plus/test'
+import { TASK_JOB_NAMES } from '@/modules/task-queue/task-queue.constants'
+import { TaskQueueProcessor } from '@/modules/task-queue/task-queue.processor'
+
+function createJob(name: string, data: unknown): Job {
+  return { name, data } as unknown as Job
+}
+
+describe('TaskQueueProcessor', () => {
+  it('completes a smoke task with marker and processedAt', async () => {
+    const processor = new TaskQueueProcessor()
+
+    const result = await processor.process(
+      createJob(TASK_JOB_NAMES.QUEUE_SMOKE, {
+        marker: 'smoke-marker',
+        enqueuedAt: new Date().toISOString(),
+      }),
+    )
+
+    expect(result).toMatchObject({ marker: 'smoke-marker' })
+    expect(typeof (result as { processedAt: string }).processedAt).toBe('string')
+    expect(Number.isNaN(Date.parse((result as { processedAt: string }).processedAt))).toBe(false)
+  })
+
+  it('throws UnrecoverableError for invalid payload', async () => {
+    const processor = new TaskQueueProcessor()
+
+    await expect(
+      processor.process(
+        createJob(TASK_JOB_NAMES.QUEUE_SMOKE, {
+          marker: '',
+          enqueuedAt: 'not-a-datetime',
+        }),
+      ),
+    ).rejects.toBeInstanceOf(UnrecoverableError)
+  })
+
+  it('throws UnrecoverableError for unknown task names', async () => {
+    const processor = new TaskQueueProcessor()
+
+    await expect(processor.process(createJob('unknown.task.v1', { any: 'data' }))).rejects.toThrow(
+      'Unsupported task name',
+    )
+  })
+
+  it('does not swallow ordinary handler errors', async () => {
+    const processor = new TaskQueueProcessor()
+    const toISOString = vi.spyOn(Date.prototype, 'toISOString').mockImplementation(() => {
+      throw new Error('clock failure')
+    })
+
+    await expect(
+      processor.process(
+        createJob(TASK_JOB_NAMES.QUEUE_SMOKE, {
+          marker: 'smoke-marker',
+          enqueuedAt: '2026-01-01T00:00:00.000Z',
+        }),
+      ),
+    ).rejects.toThrow('clock failure')
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/server/test/task-queue.service.spec.ts

@@ -0,0 +1,106 @@
+import type { Queue } from 'bullmq'
+import { describe, expect, it, vi } from 'vite-plus/test'
+import { TASK_JOB_NAMES } from '@/modules/task-queue/task-queue.constants'
+import { TaskQueueService } from '@/modules/task-queue/task-queue.service'
+
+function createQueue(add: ReturnType<typeof vi.fn> = vi.fn()) {
+  return { add } as unknown as Queue
+}
+
+function validPayload() {
+  return {
+    marker: 'test',
+    enqueuedAt: new Date().toISOString(),
+  }
+}
+
+describe('TaskQueueService', () => {
+  it('enqueues a typed task and converts jobId and delayMs', async () => {
+    const add = vi.fn().mockResolvedValue({ id: 'queue-smoke-1' })
+    const service = new TaskQueueService(createQueue(add))
+
+    const payload = validPayload()
+
+    const result = await service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, payload, {
+      jobId: 'queue-smoke-1',
+      delayMs: 100,
+    })
+
+    expect(add).toHaveBeenCalledOnce()
+    expect(add).toHaveBeenCalledWith(TASK_JOB_NAMES.QUEUE_SMOKE, payload, {
+      jobId: 'queue-smoke-1',
+      delay: 100,
+    })
+    expect(result).toEqual({
+      queueName: 'server-tasks',
+      jobId: 'queue-smoke-1',
+      name: TASK_JOB_NAMES.QUEUE_SMOKE,
+    })
+  })
+
+  it('omits jobId and delay options when not provided', async () => {
+    const add = vi.fn().mockResolvedValue({ id: 'queue-smoke-2' })
+    const service = new TaskQueueService(createQueue(add))
+    const payload = validPayload()
+
+    await service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, payload)
+
+    expect(add).toHaveBeenCalledWith(TASK_JOB_NAMES.QUEUE_SMOKE, payload, {})
+  })
+
+  it('rejects jobId containing a colon', async () => {
+    const add = vi.fn()
+    const service = new TaskQueueService(createQueue(add))
+
+    await expect(
+      service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, validPayload(), { jobId: 'bad:id' }),
+    ).rejects.toThrow('colon')
+
+    expect(add).not.toHaveBeenCalled()
+  })
+
+  it('rejects negative delayMs', async () => {
+    const add = vi.fn()
+    const service = new TaskQueueService(createQueue(add))
+
+    await expect(
+      service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, validPayload(), { delayMs: -1 }),
+    ).rejects.toThrow('non-negative')
+
+    expect(add).not.toHaveBeenCalled()
+  })
+
+  it('rejects non-safe-integer delayMs', async () => {
+    const add = vi.fn()
+    const service = new TaskQueueService(createQueue(add))
+
+    await expect(
+      service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, validPayload(), { delayMs: 1.5 }),
+    ).rejects.toThrow('non-negative')
+
+    expect(add).not.toHaveBeenCalled()
+  })
+
+  it('rejects invalid payload before reaching the queue', async () => {
+    const add = vi.fn()
+    const service = new TaskQueueService(createQueue(add))
+
+    await expect(
+      service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, {
+        marker: '',
+        enqueuedAt: 'not-a-datetime',
+      }),
+    ).rejects.toThrow()
+
+    expect(add).not.toHaveBeenCalled()
+  })
+
+  it('throws when BullMQ returns a Job without an id', async () => {
+    const add = vi.fn().mockResolvedValue({ id: undefined })
+    const service = new TaskQueueService(createQueue(add))
+
+    await expect(service.enqueue(TASK_JOB_NAMES.QUEUE_SMOKE, validPayload())).rejects.toThrow(
+      'without an id',
+    )
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules/SVG/344/275/277/347/224/250.md

@@ -0,0 +1,8 @@
+# SVG 使用
+
+- 图标通过 `*.svg?react` 导入，使用 `@/components/Icon/svg-icon/SvgIcon` 渲染；用 `size`、`color` 控制大小和颜色，默认继承父级。
+- 公共图标放 `src/assets/svg/`，页面专用图标放所属页面的 `assets/svg/`。
+- 保留 `viewBox`；单色图标用 `currentColor`，保留 `none`、多色和渐变。
+- 图片或背景直接导入 `*.svg` 获取 URL。
+
+参数、无障碍设置及示例见 [SvgIcon 使用说明](../../src/components/Icon/svg-icon/README.md)。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//345/274/271/347/252/227/347/273/204/344/273/266.md

@@ -0,0 +1,4 @@
+# 弹窗组件
+
+- 封装弹窗组件时，组件必须向外暴露 `show`、`hide` 方法。
+- 打开弹窗及传入所需数据统一通过 `show()` 完成，关闭弹窗通过 `hide()` 完成。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//346/226/207/344/273/266/346/213/206/345/210/206.md

@@ -0,0 +1,4 @@
+# 文件拆分
+
+- 当单个文件的内容超过 300 行时，须考虑按职责拆分，将适合抽离的方法或配置放到当前目录下的 `config/index.ts`、`config/index.tsx` 或 `config/xxx.ts` 中。
+- 抽离的公用方法仍须遵循[共享代码](../../../../.agents/rules/共享代码.md)规则。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//347/273/204/344/273/266/345/221/275/345/220/215.md

@@ -0,0 +1,3 @@
+# 组件命名
+
+- `components` 目录下的组件文件名、组件目录名和组件名必须使用大驼峰命名（PascalCase），例如 `UserCard.tsx`、`UserCard/`。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//350/241/250/346/240/274/351/241/265/351/235/242.md

@@ -0,0 +1,11 @@
+# 表格页面
+
+适用于以表格为主体，包含查询、新增、编辑、删除等操作的列表页面。
+
+- 普通表格类增删改查页面统一使用 [FullHeightProTable](../../src/components/FullHeightProTable/FullHeightProTable.tsx)。包含草稿或草稿箱功能时统一使用 [DraftProTable](../../src/components/DraftProTable/DraftProTable.tsx)，使用前阅读其 [组件说明](../../src/components/DraftProTable/README.md)。业务页面复用现有封装，不直接使用原生 `ProTable` 重复实现同类布局和草稿入口。
+- 沿用组件的固定表头、表体独立滚动、分页贴底布局。父容器需有明确高度，位于 flex 布局时按需设置 `min-h-0`；组件内部已包含 `w-full h-full p-[16px]`，页面不要重复添加同一层间距或改成整个表格外层滚动。
+- `columns`、`request`、`params`、`actionRef`、`pagination`、`toolBarRender` 等沿用 ProTable 参数，并保留行数据和查询参数的类型。查询、新增、编辑、删除、表单及权限等业务逻辑由页面负责，不放进通用表格组件。
+- 使用 `DraftProTable` 时，由页面受控维护 `view: 'list' | 'draft'`，默认显示 `list`，通过 `onViewChange` 切换。草稿箱入口放在刷新、列设置旁，点击选中并显示草稿，再次点击取消选中、返回列表。
+- 通过 `draftCount` 传入草稿总数，使用组件自带的右上角数字角标；0 条或未传入时隐藏，超过 99 显示 `99+`，不使用 Tooltip 展示数量。
+- 使用 `request` 时，通过 `params` 传递当前列表或草稿视图对应的查询条件。切换视图时由页面重置分页和行选择，并按业务需要重置筛选条件。草稿保存、继续编辑、提交、数据刷新和数量更新由页面及其接口处理。
+- 基础用法参考 [基础示例](../../src/pages/examples/pro-table/index.tsx)，草稿用法参考 [草稿示例](../../src/pages/examples/pro-table/draft/index.tsx)。示例中的本地存储和固定演示用户仅用于 Demo，实际业务按项目接口和权限规则接入。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//351/241/265/351/235/242/346/216/245/345/217/243.md

@@ -0,0 +1,3 @@
+# 页面接口
+
+- 页面相关的 API 请求代码统一放在对应的 `pages/<页面>/` 文件夹下，例如 `pages/<页面>/api.ts` 或 `pages/<页面>/api/index.ts`。

package/template-vp-monorepo-react-nestjs/apps/web/.env.dev

@@ -1 +1 @@
-VITE_API_URL = http://localhost:10000
+VITE_API_URL = http://localhost:13000

package/template-vp-monorepo-react-nestjs/apps/web/AGENTS.md

@@ -0,0 +1,16 @@
+## 适用范围
+
+本文件适用于 `apps/web` 及其子目录，同时遵循[根目录 AGENTS.md](../../AGENTS.md)中的通用规则。
+
+## 按需规则
+
+根据当前任务匹配下表，在执行相关操作前读取对应规则；命中多项时分别读取。不要预先加载整个 `.agents/rules/` 目录；任务范围变化时补读新命中的规则。
+
+| 适用条件                                                           | 规则文件                              |
+| ------------------------------------------------------------------ | ------------------------------------- |
+| 当前修改的 Web 代码文件已超过或将超过 300 行                       | [文件拆分](.agents/rules/文件拆分.md) |
+| 新增、修改或移动页面相关的 API 请求代码                            | [页面接口](.agents/rules/页面接口.md) |
+| 新增、修改、移动或重命名 `components` 下的组件文件、组件目录或组件 | [组件命名](.agents/rules/组件命名.md) |
+| 新增、封装或修改弹窗组件，或调整其打开、关闭及传参方式             | [弹窗组件](.agents/rules/弹窗组件.md) |
+| 新增、修改或重构表格类增删改查列表页面（含草稿功能）               | [表格页面](.agents/rules/表格页面.md) |
+| 新增、修改或使用 SVG                                               | [SVG 使用](.agents/rules/SVG使用.md)  |

package/template-vp-monorepo-react-nestjs/apps/web/README.MD

@@ -0,0 +1,153 @@
+# 通用平台 Web
+
+基于 React 19、React Router 和 Vite+，作为通用业务平台的前端入口，不限定行业或业务类型。
+
+## 开发
+
+在 Monorepo 根目录执行：
+
+```bash
+pnpm --filter web dev
+pnpm --filter web build
+pnpm --filter web test --run
+```
+
+开发地址为 `http://localhost:9999`。`/api` 沿用现有代理，转发到 NestJS Server
+（开发环境为 `http://localhost:13000`）。工作台提供 ProTable 项目管理演示入口，演示页无需启动后端。
+
+## 组件库与版本
+
+依赖版本统一在根目录 `pnpm-workspace.yaml` 的 `catalog` 管理：
+
+| 依赖 | 接入版本 | 用途 |
+| --- | --- | --- |
+| `antd` | `^6.6.2` | 基础组件、中文语言包与主题 |
+| `@ant-design/pro-components` | `3.1.14-7`（固定 beta 版本） | ProLayout、PageContainer、ProCard，以及后续的 ProTable / ProForm |
+| `@ant-design/icons` | `^6.3.4` | 平台导航图标 |
+| `@ant-design/cssinjs` | `^2.1.2` | CSS 样式层级配置 |
+
+接入时，ProComponents 的 `latest` 为 2.8.10，其 peerDependencies 仅声明支持 Ant Design 4/5；
+`beta` 为 3.1.14-7，声明支持 Ant Design 6 和 React 18+。
+因此固定使用兼容的 beta 版本，升级时需重新验证，不要直接安装 `@latest`。
+ProComponents 3 的部分 API 已调整，例如 ProCard 使用 `variant="outlined"`，不再使用 `bordered`。
+
+## 全局配置
+
+- `src/App.tsx`：`StyleProvider → ConfigProvider → ProConfigProvider → AntdApp`。
+  Ant Design 使用 `zh_CN`，ProComponents 跟随 ConfigProvider 的语言；Day.js 使用 `zh-cn`。
+- `src/config/theme.ts`：统一配置主题 token，Ant Design 与 ProComponents 共同使用。
+- `src/styles/index.css`：声明 `theme → base → antd → antd-pro → components → utilities`
+  样式层级、引入基础重置并设置 `html / body / #root` 的全局基础样式，配合 `StyleProvider layer` 使用。
+  组件库样式在基础重置之后，业务样式和 Tailwind 工具类在组件库之后。
+- 页面和组件的专属样式放在同目录的 `*.module.css`，通过 `styles.xxx` 引用；
+  `App.module.css` 管理应用容器，`layouts/BasicLayout.module.css` 管理布局品牌，
+  首页和国际化示例各自使用页面目录中的 `index.module.css`。
+  模块样式及其响应式规则统一放在 `@layer components` 中；层名控制覆盖顺序，CSS Modules 负责类名隔离。
+- React 19 可直接使用 Ant Design 6，无需 Ant Design 5 的 React 19 兼容补丁。
+
+需要消息提示、通知或确认弹窗时，在 AntdApp 子组件中使用上下文实例：
+
+```tsx
+import { App, Button } from 'antd'
+
+export default function MessageExample() {
+  const { message } = App.useApp()
+  return <Button onClick={() => void message.success('操作成功')}>显示提示</Button>
+}
+```
+
+组件内通过上下文实例继承主题与语言设置；请求配置沿用直接调用 `message.success()` / `message.error()` 的简单写法。
+
+## 布局与页面
+
+- `src/layouts/BasicLayout.tsx`：ProLayout 基础布局、菜单与 React Router 的 Outlet。
+- `/login`：独立登录页，使用 LoginForm / ProFormText，支持账号校验、密码显隐、提交状态与接口错误提示。
+- `/home`：工作台，使用 PageContainer 与 ProCard，提供项目管理演示入口。
+- `/examples/pro-table`：带菜单的 ProTable 项目管理演示，包含 18 条模拟数据，支持名称或编号搜索、
+  状态/负责人/优先级/日期筛选、排序、分页、列设置、新增、编辑、删除和批量删除。
+  数据仅保存在页面内存中，刷新或离开页面后恢复初始状态。新增和编辑使用 ModalForm，
+  通过组件 ref 的 `show(project?)` / `hide()` 打开和关闭，不请求后端接口。
+- `/examples/i18n`：保留原有的独立语言作用域示例。
+- 未匹配的地址显示 404，并可返回工作台。
+
+新增页面时，在 `src/pages` 创建组件，在 `src/router/index.tsx` 注册懒加载子路由，
+并在 BasicLayout 的 `menuRoutes` 添加菜单项。页面内使用 PageContainer，复用外层布局。
+
+后续接入 NestJS 接口时，前后端接口类型和返回类型统一从 `shared/types` 导入
+（源码为 `packages/shared/src/types`），公用方法从 `shared/utils` 导入
+（源码为 `packages/shared/src/utils`）。ProTable 的 `request` 需要返回
+`{ data, success, total }`，应在前端适配业务 API 的统一响应。
+
+## 浏览器存储
+
+- `src/utils/storage/cookie.ts`：`cookie.get / set / remove`，用于 Cookie 的读取、写入、更新和删除。
+  默认 `Path=/`、`SameSite=Lax`，HTTPS 下自动设置 `Secure`；支持过期时间、有效秒数和域名。
+  删除自定义作用域的 Cookie 时，传入与写入时相同的 `path`、`domain`。
+- `src/utils/storage/session.ts`：`local` 对应 localStorage，`session` 对应 sessionStorage，
+  均提供 `get / set / remove / clear`。值自动转换为 JSON；不存在或 JSON 无效时读取返回 `null`。
+  `set` 同时用于新增和更新，浏览器存储失败时将错误交给调用方处理。
+
+```ts
+import { cookie } from '@/utils/storage/cookie'
+import { local, session } from '@/utils/storage/session'
+
+cookie.set('preference', 'compact')
+cookie.get('preference')
+cookie.remove('preference')
+
+local.set('settings', { theme: 'light' })
+local.get<{ theme: string }>('settings')
+session.set('draft', { title: '草稿' })
+session.remove('draft')
+```
+
+## 登录与会话
+
+`src/pages/login/api.ts` 定义登录请求，`src/api/auth.ts` 定义布局使用的退出请求，
+分别复用共享包中的 LoginRequest、LoginResult 和 LogoutResult：
+
+| 接口 | 用途 |
+| --- | --- |
+| `POST /auth/login` | 使用 `account`、`password` 登录，返回不透明 Session Token |
+| `POST /auth/logout` | 撤销当前 Session |
+
+浏览器通过 `/api` 代理访问以上接口。Server 成功时直接返回业务数据，失败时返回 HTTP 错误状态和
+`{ code, message, details? }`，因此 Web 请求默认 `isWrapped: false`。后续接其他包装格式的接口时，
+可以在 method 的 `meta` 中覆盖 `isWrapped`。请求 core 默认使用 Axios，所有 2xx 响应进入
+`responded.onSuccess`，仅解析数据及检查包装响应的业务 `code`；不再配置 `statusMap.success`。
+非 2xx 错误进入 `responded.onError`，使用原生 `Error` 承载错误消息，并附加 `status` 和 `code`，
+并通过 `statusMap.unAuthorized` 处理 HTTP 401。业务检查抛出的错误直接传给调用方，不会再次进入
+全局 `onError`。自定义适配器须遵守相同的 HTTP 错误拒绝约定，并在 `error.response` 中保留响应。
+页面自己展示错误时设置 `isShowErrorMessage: false`，避免重复提示。
+
+- 登录令牌通过 `cookie` 工具保存在 `token` Cookie 中，过期时间使用接口返回的
+  `absoluteExpiresAt`；请求从 Cookie 读取令牌并携带 `Authorization: Bearer <token>`。
+  登录、退出和 401 清理统一使用 Cookie，不在 localStorage 或 sessionStorage 中保存令牌。
+- 登录成功后跳转 `/home`；路由直接渲染页面，不进行前置会话校验或登录回跳。
+- 顶部根据令牌是否存在显示登录或退出入口；退出时先请求 Server 撤销会话，成功后清除令牌并跳转登录页。
+- 登录和退出请求关闭缓存与请求共享。
+- 请求成功和失败提示直接写在 `successMessageFunc`、`errorMessageFunc` 中；
+  `unAuthorizedResponseFunc` 清除令牌、提示并跳转登录页。
+- 请求配置不设置客户端超时，统一由 Nginx 控制。
+
+当前 Server 使用 PostgreSQL 保存用户及 Argon2 密码哈希，Redis 保存 Session 并处理过期与撤销，
+不是 JWT。接口访问控制由 NestJS 的 SessionAuthGuard 完成。
+令牌在浏览器内可由 JavaScript 读取，部署时需使用 HTTPS 并防范 XSS；如改为 HttpOnly Cookie，
+必须同时调整 Server 的认证协议与 CSRF 防护。
+
+真实联调需要先启动 Docker Desktop，再在仓库根目录启动 PostgreSQL、Redis 和 Server：
+
+```bash
+docker compose up -d postgres redis
+pnpm --filter server dev
+pnpm --filter web dev
+```
+
+后两条命令各在一个终端运行。数据库需要具备现有迁移定义的表。当前没有内置默认账号，
+可使用已有账号，或通过 Server Swagger 的 `POST /auth/register` 创建开发账号。
+开发接口文档为 `http://localhost:13000/api-docs`。
+
+`test/storage.spec.ts` 验证 Cookie 编解码、作用域与过期属性，以及 local/session 的数据读写与隔离。
+`test/request.spec.ts` 使用临时 HTTP 服务验证 Axios 响应适配、Bearer 请求头、2xx 成功、
+401 / 422 / 503 错误及 HTTP 200 下的业务失败，
+这些测试不依赖 PostgreSQL 或 Redis，也不代替真实数据库认证联调。

package/template-vp-monorepo-react-nestjs/apps/web/index.html

@@ -1,10 +1,11 @@
 <!doctype html>
-<html lang="en">
+<html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>vp-react</title>
+    <meta name="description" content="通用平台，为不同业务提供统一的工作空间。" />
+    <title>通用平台</title>
   </head>
   <body>
     <div id="root"></div>

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

@@ -6,10 +6,14 @@
   "scripts": {
     "dev": "vp dev --mode dev",
     "build": "tsc && vp build --mode dev",
-    "preview": "vp preview"
+    "preview": "vp preview",
+    "test": "vp test"
   },
   "dependencies": {
     "@alova/adapter-axios": "catalog:",
+    "@ant-design/cssinjs": "catalog:",
+    "@ant-design/icons": "catalog:",
+    "@ant-design/pro-components": "catalog:",
     "@bubblesjs/i18n-core": "workspace:*",
     "@bubblesjs/i18n-react": "workspace:*",
     "@tailwindcss/vite": "catalog:",
@@ -31,6 +35,7 @@
     "typescript": "catalog:",
     "unplugin-auto-import": "catalog:",
     "vite": "catalog:",
+    "vite-plugin-svgr": "catalog:",
     "vite-plus": "catalog:"
   }
 }

package/template-vp-monorepo-react-nestjs/apps/web/public/favicon.svg

@@ -1 +1,9 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="48" height="46" fill="none" viewBox="0 0 48 46"><path fill="#863bff" d="M25.946 44.938c-.664.845-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.287c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.497 0-3.578-1.842-3.578H1.237c-.92 0-1.456-1.04-.92-1.788L10.013.474c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.579 1.842 3.579h11.377c.943 0 1.473 1.088.89 1.83L25.947 44.94z" style="fill:#863bff;fill:color(display-p3 .5252 .23 1);fill-opacity:1"/><mask id="a" width="48" height="46" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#000" d="M25.842 44.938c-.664.844-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.183c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.498 0-3.579-1.842-3.579H1.133c-.92 0-1.456-1.04-.92-1.787L9.91.473c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.578 1.842 3.578h11.377c.943 0 1.473 1.088.89 1.832L25.843 44.94z" style="fill:#000;fill-opacity:1"/></mask><g mask="url(#a)"><g filter="url(#b)"><ellipse cx="5.508" cy="14.704" fill="#ede6ff" rx="5.508" ry="14.704" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -4.47 31.516)"/></g><g filter="url(#c)"><ellipse cx="10.399" cy="29.851" fill="#ede6ff" rx="10.399" ry="29.851" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -39.328 7.883)"/></g><g filter="url(#d)"><ellipse cx="5.508" cy="30.487" fill="#7e14ff" rx="5.508" ry="30.487" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -25.913 -14.639)scale(1 -1)"/></g><g filter="url(#e)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -32.644 -3.334)scale(1 -1)"/></g><g filter="url(#f)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -34.34 30.47)"/></g><g filter="url(#g)"><ellipse cx="14.072" cy="22.078" fill="#ede6ff" rx="14.072" ry="22.078" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="rotate(93.35 24.506 48.493)scale(-1 1)"/></g><g filter="url(#h)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#i)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#j)"><ellipse cx=".387" cy="8.972" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(39.51 .387 8.972)"/></g><g filter="url(#k)"><ellipse cx="47.523" cy="-6.092" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 47.523 -6.092)"/></g><g filter="url(#l)"><ellipse cx="41.412" cy="6.333" fill="#47bfff" rx="5.971" ry="9.665" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 41.412 6.333)"/></g><g filter="url(#m)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#n)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#o)"><ellipse cx="35.651" cy="29.907" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 35.651 29.907)"/></g><g filter="url(#p)"><ellipse cx="38.418" cy="32.4" fill="#47bfff" rx="5.971" ry="15.297" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 38.418 32.4)"/></g></g><defs><filter id="b" width="60.045" height="41.654" x="-19.77" y="16.149" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="c" width="90.34" height="51.437" x="-54.613" y="-7.533" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="d" width="79.355" height="29.4" x="-49.64" y="2.03" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="e" width="79.579" height="29.4" x="-45.045" y="20.029" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="f" width="79.579" height="29.4" x="-43.513" y="21.178" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="g" width="74.749" height="58.852" x="15.756" y="-17.901" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="h" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="i" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="j" width="56.045" height="63.649" x="-27.636" y="-22.853" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="k" width="54.814" height="64.646" x="20.116" y="-38.415" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="l" width="33.541" height="35.313" x="24.641" y="-11.323" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="m" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="n" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="o" width="54.814" height="64.646" x="8.244" y="-2.416" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="p" width="39.409" height="43.623" x="18.713" y="10.588" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter></defs></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#176f88"/>
+  <g stroke="white" stroke-width="1.6">
+    <rect x="7" y="7" width="7" height="7" rx="1.5"/>
+    <rect x="18" y="7" width="7" height="7" rx="1.5"/>
+    <rect x="7" y="18" width="7" height="7" rx="1.5"/>
+    <rect x="18" y="18" width="7" height="7" rx="1.5"/>
+  </g>
+</svg>

package/template-vp-monorepo-react-nestjs/apps/web/src/App.module.css

@@ -0,0 +1,5 @@
+@layer components {
+  .app {
+    min-height: 100vh;
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/web/src/App.tsx

@@ -1,24 +1,31 @@
-import { ConfigProvider } from 'antd'
+import { StyleProvider } from '@ant-design/cssinjs'
+import { ProConfigProvider } from '@ant-design/pro-components'
+import { App as AntdApp, ConfigProvider } from 'antd'
+import zhCN from 'antd/locale/zh_CN'
 import dayjs from 'dayjs'
 import 'dayjs/locale/zh-cn'
 import { Suspense } from 'react'
 import { RouterProvider } from 'react-router'
 import PageLoading from '@/components/Loading/PageLoading'
+import { appTheme } from '@/config/theme'
+import styles from './App.module.css'
 import { router } from './router'
 
 dayjs.locale('zh-cn')
 
-// const i18nStore = await i18n.init()
-
 function App() {
   return (
-    // <I18nProvider store={i18nStore}>
-    <Suspense fallback={<PageLoading />}>
-      <ConfigProvider>
-        <RouterProvider router={router} />
+    <StyleProvider layer>
+      <ConfigProvider locale={zhCN} theme={appTheme}>
+        <ProConfigProvider>
+          <AntdApp className={styles.app}>
+            <Suspense fallback={<PageLoading />}>
+              <RouterProvider router={router} />
+            </Suspense>
+          </AntdApp>
+        </ProConfigProvider>
       </ConfigProvider>
-    </Suspense>
-    // </I18nProvider>
+    </StyleProvider>
   )
 }
 

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

@@ -0,0 +1,9 @@
+import type { LogoutResult } from 'shared/types'
+import request from '@/utils/request'
+
+export const logout = () =>
+  request.Post<LogoutResult>('/auth/logout', undefined, {
+    cacheFor: 0,
+    shareRequest: false,
+    meta: { isShowErrorMessage: false },
+  })