CRMEB/frontend/admin

CRMEB 管理后台（frontend/admin）

CRMEB 开源版管理端，基于 Vue 3.5 + Element Plus 2.9 + Pinia 2 + Vue Router 4 + Vite 5（纯 JS）构建。

• 页面路由前缀 base: /admin；开发服务端口 1619
• 开发期 /adminapi 请求自动代理到后端 http://localhost:8011（见 vite.config.js），需先启动后端
• 架构与 UI 规范：AGENTS.md（真源在 .crmeb/skills/crmeb-admin-dev 与 .crmeb/skills/crmeb-admin-ui）

Node 版本要求

Node.js 最低 18.20.0，支持 18.20.x / 20 / 22（终端 node -v 确认）。sass、unplugin-auto-import、unplugin-vue-components 已固定为兼容 Node 18 的版本；保留 package-lock.json，建议 npm ci 安装锁定依赖。

快速开始

# 1. 先启动后端（仓库根）：./run.sh install 或 ./run.sh start
# 2. 启动管理端
cd frontend/admin
npm ci
npm run dev        # 自动打开浏览器 http://localhost:1619

默认账号 admin / crmeb.com（本地 Docker 安装向导完成后生效）。

命令一览

命令	用途	产物
npm run dev	开发模式（自动开浏览器，--mode dev）	—
npm run build	主应用生产构建	dist/
npm run build:ext	构建插件管理端扩展资源（UMD，可被后台动态加载）	dist/static/extensions/
npm run build:all	主应用 + 扩展一起构建（发布推荐）	dist/
npm run dev:ext	扩展构建监听模式（开发插件页面时热更新）	dist/static/extensions/
npm run preview	本地预览生产构建	—
npm run eslint	ESLint 检查并自动修复 src 下 .js/.vue	—
npm run prettier	Prettier 格式化	—

调试

• 接口代理：dev 模式下 /adminapi → http://localhost:8011（vite.config.js 的 server.proxy 已内置）；跨主机调试改 .env.dev 的 VITE_APP_API_URL
• H5 商城联动：管理端预览 / DIY 装修跳转的商城地址由 VITE_APP_H5_URL 控制，默认已指向 uni-app H5 dev server http://localhost:5173（同时启动 frontend/uni-app 的 npm run dev:h5 即可联调）
• 插件扩展页面：dev 模式下扩展源码经 src/plugin/ 开发加载器惰性加载并支持 HMR；插件 UMD 构建入口是 scripts/build-extensions.js，插件资源复用宿主 Vue / Element Plus 环境（不要把 vue/element-plus 打进扩展包）。修改插件页面后发布前必须 npm run build:ext，只构建主应用不包含扩展

环境变量

通过 .env 系列文件管理（Vite import.meta.env）：

变量	说明
VITE_APP_API_URL	接口地址；留空 = 同源 /adminapi（生产同域部署默认形态）
VITE_APP_H5_URL	H5 商城地址；留空为同源
VITE_APP_ENV / VITE_APP_TITLE	环境标识与页面 title

• .env.dev — dev 命令生效；.env.production — build 命令生效
• 同一事实以 src/setting.js 的取值为准：VITE_APP_API_URL 覆盖 apiBaseURL，VITE_APP_H5_URL 覆盖 h5BaseURL，routePre 固定 /admin

打包与部署

npm run build:all   # 主应用 + 插件扩展

• 产物输出到 frontend/admin/dist/；Vite base 为 /admin，生产资源最终需发布到后端 public/admin/ 可访问位置（发布流程需显式同步，构建不会自动写入）
• H5 商城产物来自 frontend/uni-app（npm run build:h5），部署链路见 帮助文档 · 部署指南

目录结构

├── index.html                 # HTML 模板
├── package.json               # 依赖与脚本（engines: node >=18.20）
├── vite.config.js             # Vite 配置（base /admin、/adminapi 代理、扩展静态服务、Monaco）
├── scripts/
│   └── build-extensions.js    # 插件扩展 UMD 构建入口
├── .env.dev / .env.production # 环境变量（接口地址等）
└── src/
    ├── api/                   # 接口封装（一个业务域一个文件，如 product.js / order.js）
    ├── config/                # 常量配置
    ├── diy/                   # DIY 装修组件与 API
    ├── filters/               # 全局过滤器
    ├── i18n/                  # 多语言（vue-i18n 9）
    ├── layout/                # 整体布局
    ├── libs/                  # axios 封装、socket、auth、start 等
    ├── plugin/                # 插件扩展加载器（dev HMR / 生产 UMD 动态加载）
    ├── router/                # 路由（routers.js 汇总 + 动态路由注册）
    ├── store/                 # Pinia 状态管理
    ├── styles/ theme/         # 样式与主题（含深色模式，只用 --prev-* 设计令牌）
    ├── utils/                 # 工具（上传、校验、Excel 等）
    ├── App.vue / main.js      # 应用入口
    └── setting.js             # 业务配置（apiBaseURL / routePre / h5BaseURL）

开发规范

• 页面用卡片分块（搜索卡 + 数据卡），按钮带 v-db-click，权限按钮带 v-auth，样式只用 --prev-* 令牌、禁止硬编码主题色——完整规范见 .crmeb/skills/crmeb-admin-ui/SKILL.md
• 接口契约变更必须全链路同步（后端路由/控制器 + src/api + 菜单权限），清单见 .crmeb/rules/前端规范.md
• 提交前：npm run eslint；涉及扩展时本地 npm run build:ext 验证
• AI 开发入口见根 AGENTS.md

页面组织与编码约定（速记）

完整约定真源：.crmeb/scopes/admin.md「目录结构」与「编码约定」。高频要点：

• 页面：src/pages/<模块>/<功能>/ 小驼峰，标准结构 index.vue + components/ + tableFrom.vue/tableList.vue + handle/
• 组件：一组件一目录（公共组件在 src/components/，DIY 三件套、SchemaPage 通用页面系统在内）
• API：一业务域一文件，export function userList(data) { return request({...}) } 模式带 JSDoc，url 相对 baseURL（不含 /adminapi）；请求头为约定拼写 Authori-zation: Bearer <token>（勿"修正"）
• 状态：Pinia setup 风格 useXxxStore()；Vuex 已卸载，勿再引入；src/libs/axios.js 是废弃遗留，封装用 src/libs/request.js
• 别名：@→src、_c→components、@api→api、@diy→diy；vue 别名指向 esm-bundler（保留运行时模板编译，勿改）
• 表单/确认：proxy.$modalForm(apiPromise) 渲染后端 form-create schema；删除确认用 utils/public.js 的 modalSure；事件总线 @/utils/bus（mitt，off 必须传具名函数）
• 权限：路由 meta.auth: ['perm']、按钮 v-auth="['perm']"
• 样式：SCSS；styles/common.scss 勿随意改；只用 --prev-* 主题令牌（桥接见 theme/app.scss）
• 插件路由：新增 plugin 子目录的 routes.js 不参与热更新，需重启 dev server（import.meta.glob 构建期收集）

相关项目

• 后端 API：仓库 backend/（ThinkPHP 8，多应用 /adminapi / /api / /outapi）
• 移动端：仓库 frontend/uni-app/（uni-app CLI 工程，H5 / 微信小程序 / 支付宝小程序 / APP）