xadmin 前端 —— 基于 vue-pure-admin 二次开发的元数据驱动管理界面
（表格列 / 表单 / 搜索项由后端 search-columns / search-fields 元数据生成，前端只注册渲染器）。
后端：xadmin-server（Django 6 + DRF + Channels）
版本 5.0.1：前端与后端必须同版本发布（CI 三方校验
xadmin-server/server/const.py↔ 本仓package.json↔ 发布 tag）。变更总览见 xadmin-server/CHANGELOG.md， 4.x → 5.0 升级步骤见 升级到 5.0。
https://xadmin.dvcloud.xin/
账号密码：admin/admin123（线上演示账号；本地后端初始化的账号见 xadmin-server README）
| 依赖 | 版本 | 说明 |
|---|---|---|
| Node.js | >= 24（.nvmrc = v24.20.0） |
engines 强校验 |
| pnpm | >= 11 | preinstall 强制（only-allow pnpm） |
pnpm install
pnpm dev # http://127.0.0.1:8848前置：后端运行在 127.0.0.1:8896（后端仓库一键起：bash xadmin-server/ops/dev_up.sh --backend-only）。
- 开发代理（
vite.config.ts）：/api、/media、/api-docs→http://127.0.0.1:8896，/ws→ws://127.0.0.1:8896（默认已配置）； - 后端不在默认端口：修改上述代理目标，或用环境变量
E2E_API_PORT覆盖代理端口； public/platform-config.json为启动必需文件（标题 / 布局 / 主题 / 路由缓存等运行期开关）。
按 Vite 约定分文件管理（均已入库，可直接修改；变量清单与注释见各文件）：
| 文件 | 变量 | 说明 |
|---|---|---|
.env |
VITE_PORT |
dev server 端口（默认 8848） |
VITE_HIDE_HOME |
是否隐藏首页 | |
.env.development |
VITE_PUBLIC_PATH / VITE_ROUTER_HISTORY / VITE_API_DOMAIN / VITE_WSS_DOMAIN |
开发态；域名留空 = 相对路径 + 代理 |
.env.production |
VITE_CDN / VITE_COMPRESSION / VITE_API_DOMAIN / VITE_WSS_DOMAIN |
生产构建；域名留空 = 同源反代 |
.env.staging |
同上 | 预发环境 |
pnpm build # 产物 dist/（同源反代部署可不改配置）
pnpm build:staging # 预发构建Docker 构建（先改 .env.production 的 API 域名）：
sh build.sh # 容器内构建前端产物到 dist/（需可运行 docker）托管与反代：生产推荐 dist/ 交给 nginx 托管并反代 /api、/ws、/media 到后端——
模板见 xadmin-web/ 仓库；需要 acme.sh 自动签发证书的自包含栈已迁至
xadmin-installer/deploy/web/（DIST_DIR 指向本仓 dist/ 后 docker compose up -d --build）。
pnpm typecheck # 类型检查（strict 全仓，单轨）
pnpm lint # eslint + prettier + stylelint
pnpm test:run # vitest（覆盖率阈值）
pnpm check:contract # 与后端契约镜像一致性
pnpm check:menu-permissions # 权限点 ↔ 菜单种子双向对账（需检出 xadmin-server）
pnpm check:version # 与后端版本号一致性
pnpm check:bundle-size # 首屏体积基线（代码/i18n 双账本各 +15KB 预算）
pnpm check:module-cycles # 顶层静态导入图成环检测（豁免项按批次登记）
pnpm check:as-unknown # `as unknown as` 双重断言防回潮
pnpm check:hook-length # 超长 hook（≥120 行）防回潮契约变更流程（服务端为唯一真源）：后端改 xadmin-server/docs/schema/ 后，在本仓执行
pnpm sync:contract（同步镜像 + 重新生成 src/api/types/*.d.ts），连同生成物一起提交；
版本号提升需两仓同步（package.json ↔ server/const.py），pnpm check:version 与发布 tag 门禁双重校验。
E2E（Playwright，chromium + webkit）：pnpm test:e2e / pnpm test:e2e:smoke；
改了后端代码必须用 pnpm test:e2e:fresh（防旧进程假失败）。默认依赖同级目录 ../xadmin-server（自动拉起 E2E 后端），
独立检出运行方式与陷阱清单见 e2e/README.md。
| 问题 | 解决 |
|---|---|
pnpm dev 接口 404 |
确认后端在 8896；代理目标见 vite.config.ts |
| 页面空白但路由存在 | 后端未下发 search-columns 元数据（检查后端 Meta.table_fields）或权限码与组件名不一致 |
| 新增 Element Plus 组件不渲染 | 需在 src/plugins/elementPlus.ts 手动登记（组件 + 样式） |
| 图标不显示 | 图标需在离线集内（ep / ri / fa-solid）或随包注册，详见 ReIcon 组件 |
| 构建产物部署后请求地址错误 | 改 .env.production 的 VITE_API_DOMAIN / VITE_WSS_DOMAIN 后重新构建 |
- 前端开发指引（含独立检出）：docs/development-guide.md
- 开发约定与门禁清单：CONTRIBUTING.md
- E2E 纪律与陷阱表：e2e/README.md
- 后端文档中心（架构 / 三层权限 / 元数据契约）：
xadmin-server/docs/README.md - 在线文档：https://docs.dvcloud.xin/