8b587163df
1. 添加 .node-version 和 .npmrc 配置文件，使用 Volta 锁定 Node.js 18.16.0 版本，强制使用 pnpm 作为包管理器 2. 更新 package.json，添加 packageManager 和 engines 字段限制依赖安装版本，替换 npm 脚本为 pnpm 3. 重构设备管理模块的接口 BASE 路径和路由路径，统一命名为 device_model/device_category 4. 完善 README.md，新增环境要求、安装启动流程、常用命令和目录结构说明
322 lines
11 KiB
Markdown
322 lines
11 KiB
Markdown
# MES-UI
|
||
|
||
基于 [D2 Admin](https://github.com/d2-projects/d2-admin)（Vue 2.7 + Element UI）的企业级 MES 中后台前端项目。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
本项目通过 **[Volta](https://volta.sh/)** 和 **[pnpm](https://pnpm.io/)** 锁定开发环境版本，确保团队成员使用完全一致的 Node.js 和包管理器版本。
|
||
|
||
| 工具 | 锁定版本 | 作用 |
|
||
| --- | --- | --- |
|
||
| **Node.js** | `18.16.0` | JavaScript 运行时（`.node-version` 文件） |
|
||
| **pnpm** | `10.33.0` | 包管理器（`package.json` → `packageManager` 字段） |
|
||
|
||
> 配置文件说明：
|
||
> - `.node-version` → Volta 读取，自动切换 Node.js 版本
|
||
> - `package.json` → `engines` 字段限制版本范围，`packageManager` 字段锁定 pnpm 版本
|
||
> - `.npmrc` → `engine-strict=true` 强制使用锁定版本，不满足则安装失败
|
||
|
||
---
|
||
|
||
## 从零开始安装到启动
|
||
|
||
### 第一步：安装 Volta（如果尚未安装）
|
||
|
||
Volta 会根据 `.node-version` 自动安装并切换到项目所需的 Node.js 版本。
|
||
|
||
**Windows（PowerShell）：**
|
||
|
||
```powershell
|
||
winget install Volta.Volta
|
||
# 重启终端后生效
|
||
volta --version
|
||
```
|
||
|
||
**macOS / Linux：**
|
||
|
||
```bash
|
||
curl https://get.volta.sh | bash
|
||
# 重新加载 shell 配置
|
||
source ~/.bashrc # 或 source ~/.zshrc
|
||
volta --version
|
||
```
|
||
|
||
> 更多安装方式请参考 [Volta 官方文档](https://docs.volta.sh/guide/getting-started)。
|
||
|
||
### 第二步：启用 pnpm（Volta 内置支持，无需额外安装）
|
||
|
||
```bash
|
||
# Volta 会根据 package.json 中的 packageManager 字段
|
||
# 自动安装并使用 pnpm@10.33.0
|
||
volta install pnpm@10.33.0
|
||
|
||
# 验证版本
|
||
pnpm --version # 应输出 10.33.0
|
||
```
|
||
|
||
> 如果没有 Volta，也可以手动安装 pnpm：
|
||
> ```bash
|
||
> npm install -g pnpm@10.33.0
|
||
> ```
|
||
|
||
### 第三步：克隆项目并安装依赖
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <仓库地址>
|
||
cd mes-ui
|
||
|
||
# Volta 会在进入目录时自动检测 .node-version，
|
||
# 提示你安装 Node.js 18.16.0（如尚未安装）
|
||
node --version # 确认输出 v18.16.0
|
||
|
||
# 安装依赖（pnpm 读取 packageManager 字段确保版本一致）
|
||
pnpm install
|
||
```
|
||
|
||
> `pnpm install` 会同时校验：
|
||
> - Node.js 版本是否在 `engines.node` 范围内（`>=18.16.0 <19`）
|
||
> - pnpm 版本是否在 `engines.pnpm` 范围内（`>=10.33.0 <11`）
|
||
> - 如果版本不匹配，`.npmrc` 中 `engine-strict=true` 会使安装直接失败，避免环境不一致问题。
|
||
|
||
### 第四步：配置环境变量
|
||
|
||
在项目根目录创建 `.env.development.local` 文件（此文件已在 `.gitignore` 中，不会提交）：
|
||
|
||
```bash
|
||
# 后台 API 地址
|
||
VUE_APP_API=http://你的后台服务器地址/
|
||
```
|
||
|
||
### 第五步：启动开发服务器
|
||
|
||
```bash
|
||
pnpm serve
|
||
```
|
||
|
||
浏览器会自动打开 `http://localhost:8080`（或终端提示的实际端口）。
|
||
|
||
---
|
||
|
||
## 常用命令速查
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `pnpm serve` | 启动开发服务器（自动打开浏览器） |
|
||
| `pnpm build` | 生产环境构建 |
|
||
| `pnpm build:preview` | 预发布环境构建 |
|
||
| `pnpm lint` | ESLint 代码检查并自动修复 |
|
||
| `pnpm test:unit` | 运行单元测试 |
|
||
| `pnpm install` | 安装依赖 |
|
||
| `pnpm add <包名>` | 添加新依赖（**禁止使用 npm install**） |
|
||
| `pnpm remove <包名>` | 移除依赖 |
|
||
|
||
---
|
||
|
||
## 版本锁定机制
|
||
|
||
### Node.js 版本锁定（Volta）
|
||
|
||
```
|
||
项目根目录
|
||
├── .node-version → 18.16.0（Volta 自动读取切换）
|
||
```
|
||
|
||
- Volta 进入项目目录时自动将 Node.js 切换为 `18.16.0`
|
||
- 如果该版本未安装，Volta 会自动下载并安装
|
||
- 传统方案（nvm）也兼容：`nvm use` 读取 `.nvmrc`，本项目同时提供 `.node-version` 供 Volta 使用
|
||
|
||
### pnpm 版本锁定
|
||
|
||
```
|
||
package.json
|
||
├── packageManager → pnpm@10.33.0（Corepack / Volta 识别）
|
||
├── engines.pnpm → >=10.33.0 <11（npm/pnpm install 时校验）
|
||
```
|
||
|
||
```ini
|
||
# .npmrc
|
||
engine-strict=true # 版本不满足 → 安装直接报错
|
||
```
|
||
|
||
### 依赖版本锁定
|
||
|
||
```
|
||
pnpm-lock.yaml → 锁定所有依赖的精确版本（等价于 npm 的 package-lock.json）
|
||
```
|
||
|
||
> `pnpm-lock.yaml` **必须提交到 Git**，保证所有环境安装的依赖版本完全一致。
|
||
|
||
---
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
mes-ui/
|
||
├── .github/ # GitHub 相关配置
|
||
├── docs/ # 项目文档
|
||
├── public/ # 静态资源（不经过 webpack 处理）
|
||
├── src/ # PC 端业务源码
|
||
│ ├── api/ # 接口请求层（按业务模块拆分）
|
||
│ │ ├── _service.js # axios 请求服务实例
|
||
│ │ └── production-master-data/ # 生产主数据模块 API
|
||
│ ├── assets/ # 静态资源（经 webpack 处理，含 SCSS / SVG）
|
||
│ ├── components/ # 公共组件
|
||
│ │ ├── page-table/ # CRUD 表格便捷组合体
|
||
│ │ └── page-dialog-form/ # 新增/编辑弹框组件
|
||
│ ├── composables/ # 可复用逻辑函数
|
||
│ │ ├── useTableColumns.js # 列定义工厂
|
||
│ │ ├── useTableButtons.js # 按钮定义工厂
|
||
│ │ └── useI18n.js # i18n Mixin 工厂
|
||
│ ├── layout/ # 页面布局（header-aside）
|
||
│ ├── libs/ # 工具函数
|
||
│ ├── locales/ # 国际化语言包（zh-chs / en）
|
||
│ ├── router/ # 路由配置（modules/ 按业务模块拆分）
|
||
│ ├── store/ # Vuex 状态管理
|
||
│ ├── utils/ # 通用工具（文件下载、Excel 读取等）
|
||
│ └── views/ # 业务页面（按模块三级目录组织）
|
||
│ ├── production-master-data/ # 生产主数据
|
||
│ ├── system-administration/ # 系统管理
|
||
│ ├── equipment-management/ # 设备管理
|
||
│ ├── quality-management/ # 质量管控
|
||
│ ├── planning-production/ # 计划生产
|
||
│ └── data-platform/ # 数据平台
|
||
├── src.mobile/ # 移动端业务源码
|
||
├── .browserslistrc # 浏览器兼容配置
|
||
├── .editorconfig # 编辑器统一配置
|
||
├── .env / .env.development / .env.preview # 环境变量
|
||
├── .eslintignore / .eslintrc.js # ESLint 配置
|
||
├── .gitignore # Git 忽略配置
|
||
├── .node-version # Volta Node.js 版本锁定（18.16.0）
|
||
├── .npmrc # pnpm 配置（版本强校验）
|
||
├── .postcssrc.js # PostCSS 配置
|
||
├── babel.config.js # Babel 配置
|
||
├── jest.config.js # Jest 单元测试配置
|
||
├── jsconfig.json # VS Code 路径别名提示
|
||
├── package.json # 项目依赖与脚本
|
||
├── pnpm-lock.yaml # pnpm 依赖锁定文件（必须提交）
|
||
├── vue.config.js # Vue CLI 构建配置
|
||
└── README.md # 项目说明（本文件）
|
||
```
|
||
|
||
---
|
||
|
||
## 项目文档
|
||
|
||
| 文档 | 说明 |
|
||
| --- | --- |
|
||
| [表格组件使用说明](./docs/表格组件使用说明.md) | `page-table` + `page-dialog-form` 完整使用手册 |
|
||
| [国际化规则](./docs/国际化规则.md) | i18n 使用规范与迁移指南 |
|
||
| [迁移提示词](./docs/迁移提示词.md) | 旧页面迁移到新方案的规则文档 |
|
||
| [SCT基础表格重构设计](./docs/SCT基础表格重构设计.md) | 旧 `sct-base-table` → 新架构设计文档 |
|
||
| [变更日志](./docs/变更日志.md) | 项目变更日志 |
|
||
|
||
---
|
||
|
||
## 关键目录说明
|
||
|
||
### `src/components/` — 公共组件
|
||
|
||
| 组件 | 作用 |
|
||
| --- | --- |
|
||
| `page-table` | CRUD 表格组合体（按钮栏 + 表格 + 分页 + 高度自适应 + 帮助按钮） |
|
||
| `page-dialog-form` | 新增/编辑弹框（表单渲染 + 校验 + i18n 自动翻译） |
|
||
| `d2-container` | 页面容器（卡片、全屏、透明等多种布局变体） |
|
||
| `d2-container-frame` | iframe 嵌套外部页面容器 |
|
||
|
||
> `page-table` 和 `page-dialog-form` 是本项目核心组件，详细用法见 [表格组件使用说明](./docs/表格组件使用说明.md)。
|
||
|
||
### `src/composables/` — 逻辑复用层
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `useTableColumns.js` | 列定义工厂，消除手动分配 `idx`，约定 `prop: '_actions'` 为操作列 |
|
||
| `useTableButtons.js` | 按钮工厂，一键生成工具栏 + 行内按钮，自动注入权限过滤 |
|
||
| `useI18n.js` | i18n Mixin 工厂，通过 `i18nMixin(prefix)` 注入 `key()` / `ckey()` |
|
||
| `useConfirmHandle.js` | 确认操作 Mixin，封装 `$confirm` + API 调用 |
|
||
|
||
### `src/router/modules/` — 路由模块
|
||
|
||
按业务一级模块拆分，examples:
|
||
|
||
| 文件 | 路由前缀 | 对应模块 |
|
||
| --- | --- | --- |
|
||
| `production-master-data.js` | `/production_configuration` | 生产主数据 |
|
||
| `system-administration.js` | `/system_settings` | 系统管理 |
|
||
| `equipment-management.js` | `/equipment_management` | 设备管理 |
|
||
| `quality-management.js` | `/quality_management` | 质量管控 |
|
||
| `planning-production.js` | `/planning_production` | 计划生产 |
|
||
| `data-platform.js` | `/data_platform` | 数据平台 |
|
||
|
||
### `src/api/` — 接口请求层
|
||
|
||
按业务模块父目录存放，命名规则：`{模块名}.js`。例如：
|
||
- `production-master-data/device-category.js` → 设备类型
|
||
- `production-master-data/factory-area.js` → 工厂区域
|
||
|
||
---
|
||
|
||
## 构建配置文件
|
||
|
||
| 文件 | 作用 |
|
||
| --- | --- |
|
||
| `vue.config.js` | Vue CLI 构建配置（多页入口、CDN、webpack 插件、主题色替换、SVG sprites、路径别名） |
|
||
| `babel.config.js` | Babel 转译配置 |
|
||
| `.postcssrc.js` | PostCSS 自动前缀等配置 |
|
||
| `.eslintrc.js` | ESLint 代码规范 |
|
||
| `jest.config.js` | 单元测试框架配置 |
|
||
| `jsconfig.json` | VS Code 路径别名智能提示（`@` → `src/`） |
|
||
| `.browserslistrc` | 目标浏览器范围 |
|
||
| `.editorconfig` | 编辑器缩进/换行风格统一 |
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
| 文件 | 说明 |
|
||
| --- | --- |
|
||
| `.env` | 所有环境通用变量 |
|
||
| `.env.development` | 开发环境变量 |
|
||
| `.env.development.local` | 本地开发环境变量（不提交 Git，需自行创建） |
|
||
| `.env.preview` | 预发布环境变量 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1：`pnpm install` 报错 "Unsupported engine"
|
||
|
||
Node.js 或 pnpm 版本不在 `engines` 范围内。解决：
|
||
|
||
```bash
|
||
# 检查版本
|
||
node --version # 必须为 18.16.x
|
||
pnpm --version # 必须为 10.33.x
|
||
|
||
# 使用 Volta 自动切换
|
||
volta install node@18.16.0
|
||
volta install pnpm@10.33.0
|
||
```
|
||
|
||
### Q2：启动后页面报跨域错误
|
||
|
||
在 `.env.development.local` 中确认 `VUE_APP_API` 指向正确的后台地址，且后台已开启 CORS。
|
||
|
||
### Q3：端口被占用
|
||
|
||
默认端口为 `8080`。如需修改，在 `.env.development.local` 中添加：
|
||
|
||
```bash
|
||
PORT=8081
|
||
```
|
||
|
||
### Q4：依赖安装慢
|
||
|
||
pnpm 默认使用 npm registry。如需加速，可配置镜像：
|
||
|
||
```bash
|
||
pnpm config set registry https://registry.npmmirror.com
|
||
```
|