docs: 记录前端 vben 对接进度与本地环境待办

docs/change-log/2026-08-24.md

@@ -188,3 +188,34 @@
 - 冒烟测试已建 opuser/op 测试角色，可清理。
 - 菜单管理接口的 assignMenu 权限码暂无独立接口（角色授权在 role update 中完成），保留扩展位。
 - 生产环境 JWT_SECRET/DB_DSN 必须通过环境变量提供（${ENV} 不会自动替换）。
+
+---
+
+## 追加（23:05）：前端 vben 对接（源码完成，本地启动验证受阻）
+
+### 请求
+
+继续做 vben 前端（admin.xpcool.com，vben 5.7.0 monorepo），对接后端登录/菜单/按钮级权限/RBAC/日志监控。
+
+### 变更（前端独立仓库 commit 4615e7c）
+
+- `.env.development`：`VITE_GLOB_API_URL` 置空、关闭 mock
+- `vite.config.ts`：代理 `/admin`、`/api` → `http://localhost:8000`
+- `preferences.ts`：`accessMode: 'backend'`（动态路由）、关闭 token 自动刷新
+- `api/core/auth.ts`：登录/权限码路径改 `/admin/v1/...`，codes 解包 `data.codes`
+- `api/core/user.ts`：`/admin/v1/auth/info` 字段映射（adminId→userId、nickname→realName、homePath）
+- `api/core/menu.ts`：`/admin/v1/menu/routes` 解包 `data.routes`
+- 新增 `api/system.ts`、`api/log.ts`
+- 新增页面：`views/system/admin|role|menu/index.vue`（CRUD+按钮级权限）、`views/monitor/log/index.vue`（文件列表/tail/关键词过滤/自动刷新）
+
+### 决策与理由
+
+- **后端 component 值 `system/admin/index` 与 vben 映射**：vben `normalizeViewPath` 会去前缀、补前导 `/`、去 `/views`，最终匹配 `views/**/*.vue`，无需 `.vue` 后缀。
+- **前端请求路径写完整 `/admin/v1/...` + apiURL 置空**：因 user(`/api/v1`)、open(`/api/open/v1`)、admin(`/admin/v1`) 前缀不同，写全路径最清晰，避免 proxy rewrite 混乱。
+- **字段映射在后端/前端约定**：后端返回 `adminId/nickname`，前端映射为 vben `UserInfo(userId/realName)`。
+
+### 待办与风险（本地启动验证受阻）
+
+- **node 环境**：system node 23.0.0 未编译 `node:sqlite`（`ERR_UNKNOWN_BUILTIN_MODULE`），pnpm 11.16.0 依赖它；已用 managed node 22.22.2 + corepack wrapper 绕过。
+- **`pnpm install` 卡住**：已配 `.npmrc`（npmmirror 镜像 + `node-linker=hoisted` + `store-dir=E:/.pnpm-store`），但 install 在 "added 27→98" 反复循环，疑似某 native 依赖 postinstall 失败重试。**dev server 未能启动验证**。
+- 后续步骤：① 定位卡住的依赖（`pnpm install --reporter=append-only` 看具体包）；② 或跳过 postinstall（`pnpm install --ignore-scripts` 后手动补 esbuild 等二进制）；③ 完成 install 后 `pnpm dev:antd` 启动，浏览器验证登录/菜单/权限/日志。