create-bubbles 0.1.25 → 0.1.27

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/server/tsconfig.scripts.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": "." },
+  "include": ["src/**/*.ts"]
+}

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//347/273/204/344/273/266/345/244/215/347/224/250.md

@@ -0,0 +1,7 @@
+# 组件复用与静态内容
+
+- 开始新增或修改页面、布局或 React 组件前，先检查是否已有可复用组件，并识别页面结构中可复用的展示或交互，再根据全部引用方的实际范围确定组件归属。
+- 供整个前端应用复用的组件统一放在 `@/components`。该目录优先放置跨页面、低业务耦合且接口稳定的通用组件。
+- 只在局部范围复用的组件放在所有引用方最近公共祖先目录下的 `components` 中。组件新增了该目录之外的引用方时，须重新计算最近公共祖先，将组件移动到新公共范围对应的 `components`，并同步更新引用；复用范围扩展到整个应用时，移动到 `@/components`。
+- 不依赖父组件本次渲染局部值的静态常量、配置和 JSX 放在 React 组件函数外。小且仅属于当前页面的内容可放在同一文件的模块顶层；较多配置抽离到当前功能目录的 `config/index.ts`、`config/index.tsx` 或其他职责明确的配置文件；具有独立 UI 职责或适合复用的内容抽成 `components/<ComponentName>`。
+- 在 React 组件函数内声明的子组件须移到函数外或相应的 `components` 目录；需要父组件的数据或回调时，通过 props 显式传入。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//350/241/250/345/215/225/345/233/236/345/241/253.md

@@ -0,0 +1,4 @@
+# 表单回填
+
+- 开启浏览器回填（自动填充）的输入框，必须为 `:autofill`/`:-webkit-autofill`（含 `:hover`、`:focus`、`:active`）状态设置 `transition: background-color 900000000s ease-in-out 0s;`，冻结浏览器注入的填充底色，保持输入框自身底色；该底色是带 `!important` 的 UA 样式，普通背景声明无法覆盖。
+- 填充态文字色用 `-webkit-text-fill-color` 指定，并显式设置 `caret-color` 保证光标可见。

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,25 @@
+## 适用范围
+
+本文件适用于 `apps/web` 及其子目录，同时遵循[根目录 AGENTS.md](../../AGENTS.md)中的通用规则。
+
+## 自动导入
+
+- `react`、`react-router`、`react-dom` 的 API 和类型通过 `unplugin-auto-import` 自动导入，业务代码和测试不再手动导入这些包；`react-dom/client` 的 `createRoot` 同样自动导入。
+- 使用尚未覆盖的 API 或类型时，先补充 `vite.config.ts` 的自动导入配置，再由插件更新 `src/types/auto-imports.d.ts`，不要手动修改生成声明。
+- 同名 API 必须配置明确的别名：React 的 `createContext` 保持原名，React Router 的 `createContext` 使用 `createRouterContext`，避免上下文类型混用。
+- React 的 `ViewTransition` 使用 `ReactViewTransition` 别名，避免与浏览器原生 `ViewTransition` 全局类型冲突。
+
+## 按需规则
+
+根据当前任务匹配下表，在执行相关操作前读取对应规则；命中多项时分别读取。不要预先加载整个 `.agents/rules/` 目录；任务范围变化时补读新命中的规则。
+
+| 适用条件                                                            | 规则文件                              |
+| ------------------------------------------------------------------- | ------------------------------------- |
+| 当前修改的 Web 代码文件已超过或将超过 300 行                        | [文件拆分](.agents/rules/文件拆分.md) |
+| 新增、修改或移动页面相关的 API 请求代码                             | [页面接口](.agents/rules/页面接口.md) |
+| 新增、修改、抽取或移动 React 组件，或调整组件复用范围与静态内容放置 | [组件复用](.agents/rules/组件复用.md) |
+| 新增、修改、移动或重命名 `components` 下的组件文件、组件目录或组件  | [组件命名](.agents/rules/组件命名.md) |
+| 新增、封装或修改弹窗组件，或调整其打开、关闭及传参方式              | [弹窗组件](.agents/rules/弹窗组件.md) |
+| 新增、修改或重构表格类增删改查列表页面（含草稿功能）                | [表格页面](.agents/rules/表格页面.md) |
+| 新增、修改或使用 SVG                                                | [SVG 使用](.agents/rules/SVG使用.md)  |
+| 新增、修改开启浏览器回填（自动填充）的表单或输入框                  | [表单回填](.agents/rules/表单回填.md) |

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

@@ -0,0 +1,181 @@
+# 通用平台 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` | 通用操作图标；平台菜单图标使用 `src/assets/svg/` |
+| `@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、ProComponents（通过 `IntlType`）、Day.js 和 `<html lang>` 跟随应用当前语言；
+  `src/i18n/ui-locale.ts` 集中维护这些适配关系。
+- `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/BasicLayout.module.css` 管理布局品牌，
+  首页和国际化示例各自使用页面目录中的 `index.module.css`。
+  模块样式及其响应式规则统一放在 `@layer components` 中；层名控制覆盖顺序，CSS Modules 负责类名隔离。
+- React 19 可直接使用 Ant Design 6，无需 Ant Design 5 的 React 19 兼容补丁。
+
+需要消息提示、通知或确认弹窗时，在 AntdApp 子组件中使用上下文实例：
+
+```tsx
+import { useI18n } from '@bubblesjs/i18n-react'
+import { App, Button } from 'antd'
+
+export default function MessageExample() {
+  const { message } = App.useApp()
+  const { tr } = useI18n()
+  return <Button onClick={() => void message.success(tr('操作成功'))}>{tr('显示提示')}</Button>
+}
+```
+
+组件内通过上下文实例继承主题与语言设置；请求配置沿用直接调用 `message.success()` / `message.error()` 的简单写法。
+
+## 国际化规则
+
+- 国际化仅作用于 `apps/web` 前端，统一使用 `@bubblesjs/i18n-core` 和
+  `@bubblesjs/i18n-react`。应用只在 `src/main.tsx` 注册一个 `I18nProvider`，页面或功能模块不得创建独立
+  store 或嵌套 Provider。
+- 支持的语言在 `src/i18n/config.ts` 中统一声明；词条由 `src/i18n/instance.ts` 懒加载，并将用户选择保存到
+  localStorage。新增语言时必须同步补充语言配置、词条加载器、`ui-locale.ts` 中的 Ant Design、
+  Pro Components `IntlType` 与 Day.js 语言包。
+- React 组件内使用 `useI18n()` 获取 `tr`、`locale` 和 `loadLocale`；组件外的路由、请求等逻辑从
+  `@/i18n` 导入全局 `tr`。用户可见的标题、按钮、表单标签、校验提示、空状态、通知、错误信息和无障碍文本
+  均不得硬编码。
+- 词条使用简体中文原文作为 key，例如 `tr('保存')`。动态内容使用占位符和参数
+  `tr('你好，{name}', { name })`，不要通过字符串拼接组成可翻译句子。
+- 需要在切换语言后更新的静态配置必须在渲染时重新生成，或使用 `() => tr('菜单名称')` 等延迟解析函数；
+  长期存活的请求实例，其默认成功和错误提示同样必须使用 `() => tr(...)`，不得在模块初始化时固定翻译结果。
+- 中英文词典分别位于 `src/locales/zh_CN.json` 和 `src/locales/en_US.json`。新增或修改文案后，在 Monorepo
+  根目录先执行 `pnpm i18n:sync` 同步词条，补全 `en_US.json` 的英文翻译，再执行
+  `pnpm i18n:check`，确保不存在缺失、废弃或未使用词条：
+
+```bash
+pnpm i18n:sync
+pnpm i18n:check
+```
+
+## 布局与页面
+
+- `src/layouts/BasicLayout/index.tsx`：ProLayout 基础布局、菜单与 React Router 的 Outlet；配套样式放在同一目录。
+- `src/layouts/WorkspaceLayout/index.tsx`：工作区布局；配套样式放在同一目录。
+- `/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:",
@@ -28,9 +32,11 @@
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
     "@vitejs/plugin-react": "catalog:",
+    "happy-dom": "catalog:",
     "typescript": "catalog:",
     "unplugin-auto-import": "catalog:",
     "vite": "catalog:",
+    "vite-plugin-svgr": "catalog:",
     "vite-plus": "catalog:"
   }
 }