chore(frontend): adopt pnpm and NestJS default

- Pin Node 22.12.0 and pnpm 12.3.4 for reproducible installs.\n- Keep Java 7690 available through pnpm dev:java for contract comparison.

.gitignore

@@ -29,6 +29,9 @@ backend/.mvn/jvm.config
 
 # Local configuration, IDE state, and generated browser-test artifacts.
 .env
+# 前端本机后端地址覆盖：只属于个人环境。.env.java 是团队共享的对拍配置，仍进仓库。
+.env.local
+frontend/.env.local
 .idea/
 .vite/
 frontend/.playwright-cli/
@@ -47,6 +50,7 @@ db-seed/
 # 契约快照含测试库真实业务数据（姓名、手机号），默认不进仓库。
 # 需要团队共享基准时，改为只提交 error.* 这类不含个人信息的快照。
 scripts/contract/snapshots/
+scripts/contract/snapshots-backup-*/
 
 # Office 打开文档时生成的锁文件，不进仓库。
 ~$*

README.md

@@ -65,27 +65,31 @@ node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
 
 ### 前端
 
+前端包管理器固定为 pnpm，版本由 `frontend/package.json` 的 `packageManager` 与 `volta` 字段约束。请勿在 `frontend/` 混用 npm，否则会生成冲突的 `package-lock.json` 与不同结构的 `node_modules`。
+
 ```bash
 cd frontend
-npm install
-npm run dev
+pnpm install
+pnpm dev
 ```
 
-访问 `http://localhost:5173/asset/`。默认连 Java 后端（7690）。
+访问 `http://localhost:5173/asset/`。**默认连 NestJS 后端（7691）。**
 
-连 NestJS 后端时加环境变量：
+回退到 Java 后端（7690）对拍：
 
 ```bash
-VITE_API_TARGET=http://127.0.0.1:7691 npm run dev
+pnpm dev:java
 ```
 
-PowerShell：
+后端地址不写在命令里，由文件管理：
 
-```bash
-$env:VITE_API_TARGET="http://127.0.0.1:7691"; npm run dev
-```
+| 位置 | 作用 | 是否进仓库 |
+|---|---|---|
+| `vite.config.js` 默认值 | NestJS `7691`，`pnpm dev` 用它 | 是 |
+| `frontend/.env.java` | Java `7690`，`pnpm dev:java` 用它 | 是 |
+| `frontend/.env.local` | 本机临时覆盖，改一行即生效 | 否 |
 
-关掉终端重开即恢复默认，随时可与 Java 对照。
+优先级：命令行环境变量 > `.env` 文件 > `vite.config.js` 默认值。
 
 ### NestJS 后端（7691）
 
@@ -120,7 +124,7 @@ mvn -DskipTests spring-boot:run
 ```bash
 cd backend-nest && npm test        # NestJS 单元测试
 cd backend && mvn test             # Java 单元测试（迁移期基准）
-cd frontend && npm run test:e2e    # 端到端测试
+cd frontend && pnpm test:e2e       # 端到端测试
 ```
 
 ## 契约比对

frontend/.env.java

+# 文件用途（白话）：迁移期回退到 Java 后端对拍时用的后端地址，由 `pnpm dev:java` 通过 --mode java 加载。
+# 默认（pnpm dev）连 NestJS 7691，见 vite.config.js。
+VITE_API_TARGET=http://127.0.0.1:7690

frontend/package.json

@@ -3,6 +3,7 @@
   "private": true,
   "scripts": {
     "dev": "vite --host 0.0.0.0",
+    "dev:java": "vite --host 0.0.0.0 --mode java",
     "build": "vite build",
     "preview": "vite preview",
     "test:e2e": "playwright test"
@@ -10,6 +11,11 @@
   "engines": {
     "node": ">=20.19.0 || >=22.12.0"
   },
+  "packageManager": "pnpm@12.3.4",
+  "volta": {
+    "node": "22.12.0",
+    "pnpm": "12.3.4"
+  },
   "dependencies": {
     "element-plus": "^2.14.2",
     "vue": "^3.5.39",

frontend/playwright.config.js

@@ -3,5 +3,5 @@ import { defineConfig } from '@playwright/test';
 export default defineConfig({
   testDir: './tests',
   use: { baseURL: 'http://127.0.0.1:5173', browserName: 'chromium' },
-  webServer: { command: 'npm run dev -- --host 127.0.0.1', url: 'http://127.0.0.1:5173/', reuseExistingServer: true, timeout: 30_000 }
+  webServer: { command: 'pnpm dev -- --host 127.0.0.1', url: 'http://127.0.0.1:5173/', reuseExistingServer: true, timeout: 30_000 }
 });

frontend/playwright.device.config.js

@@ -4,5 +4,5 @@ import { defineConfig } from '@playwright/test';
 export default defineConfig({
   testDir: './tests',
   use: { baseURL: 'http://127.0.0.1:5174', browserName: 'chromium' },
-  webServer: { command: 'npm run dev -- --host 127.0.0.1 --port 5174', url: 'http://127.0.0.1:5174/', reuseExistingServer: false, timeout: 30_000 }
+  webServer: { command: 'pnpm dev -- --host 127.0.0.1 --port 5174', url: 'http://127.0.0.1:5174/', reuseExistingServer: false, timeout: 30_000 }
 });

frontend/pnpm-workspace.yaml

+# esbuild 是 Vite 的底层打包器，其安装脚本负责下载平台二进制文件。
+# 不放行会导致 pnpm install 以 ERR_PNPM_IGNORED_BUILDS 非零退出。
+allowBuilds:
+  esbuild: true

frontend/vite.config.js

-import { defineConfig } from 'vite';
+import { defineConfig, loadEnv } from 'vite';
 
 /**
  * 代码作用（白话）：把前端固定部署在 /asset/ 前缀下，并把浏览器的 /api 请求转发给本机后端，避免接口请求被 Vite 回退成 HTML 页面。
- * 关联文件：frontend/src/router/index.js、frontend/src/modules/phone/phone-api-client.js、backend/src/main/resources/application.yml。
- * 关联逻辑（调用链/消息链/数据流）：/asset/#/phone-assets -> Vue Hash 路由；/api/phone-assets -> Vite proxy -> 127.0.0.1:7690 后端接口。
+ * 关联文件：frontend/.env.java、frontend/src/router/index.js、frontend/src/modules/phone/phone-api-client.js、backend-nest/src/main.ts。
+ * 关联逻辑（调用链/消息链/数据流）：/asset/#/phone-assets -> Vue Hash 路由；/api/phone-assets -> Vite proxy -> 127.0.0.1:7691 NestJS 接口。
  */
-export default defineConfig({
-  base: '/asset/',
-  define: {
-    __VUE_OPTIONS_API__: true,
-    __VUE_PROD_DEVTOOLS__: false,
-    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: false
-  },
-  server: {
-    port: 5173,
-    strictPort: true,
-    proxy: {
-      '/api': {
-        // 迁移期用环境变量切换后端：不设时连 Java(7690)，设 VITE_API_TARGET 可指向 NestJS(7691)。
-        // 这样验证新后端不需要改任何代码，切换与回退都是一条命令的事。
-        target: process.env.VITE_API_TARGET || 'http://127.0.0.1:7690',
-        changeOrigin: true
+export default defineConfig(({ mode }) => {
+  // 后端地址优先级：命令行环境变量 > .env 文件 > 默认值。
+  // 默认连 NestJS(7691)；`pnpm dev:java` 走 --mode java 读 .env.java，回退到 Java(7690) 对拍。
+  const fileEnv = loadEnv(mode, process.cwd(), 'VITE_');
+  const apiTarget = process.env.VITE_API_TARGET || fileEnv.VITE_API_TARGET || 'http://127.0.0.1:7691';
+
+  return {
+    base: '/asset/',
+    define: {
+      __VUE_OPTIONS_API__: true,
+      __VUE_PROD_DEVTOOLS__: false,
+      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: false
+    },
+    server: {
+      port: 5173,
+      strictPort: true,
+      proxy: {
+        '/api': {
+          target: apiTarget,
+          changeOrigin: true
+        }
       }
-    }
-  },
-  preview: { port: 4173, strictPort: true }
+    },
+    preview: { port: 4173, strictPort: true }
+  };
 });