MES-UI

基于 D2 Admin（Vue 2.7 + Element UI）的企业级 MES 中后台前端项目。

---

环境要求

本项目通过 Volta 和 pnpm 锁定开发环境版本，确保团队成员使用完全一致的 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）：

winget install Volta.Volta
# 重启终端后生效
volta --version

macOS / Linux：

curl https://get.volta.sh | bash
# 重新加载 shell 配置
source ~/.bashrc   # 或 source ~/.zshrc
volta --version

更多安装方式请参考 Volta 官方文档。

第二步：启用 pnpm（Volta 内置支持，无需额外安装）

# Volta 会根据 package.json 中的 packageManager 字段
# 自动安装并使用 pnpm@10.33.0
volta install pnpm@10.33.0

# 验证版本
pnpm --version   # 应输出 10.33.0

如果没有 Volta，也可以手动安装 pnpm：

npm install -g pnpm@10.33.0

第三步：克隆项目并安装依赖

# 克隆仓库
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 中，不会提交）：

# 后台 API 地址
VUE_APP_API=http://你的后台服务器地址/

第五步：启动开发服务器

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 时校验）

# .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                   # 项目说明（本文件）

---

项目文档

文档	说明
表格组件使用说明	page-table + page-dialog-form 完整使用手册
国际化规则	i18n 使用规范与迁移指南
迁移提示词	旧页面迁移到新方案的规则文档
SCT基础表格重构设计	旧 sct-base-table → 新架构设计文档
变更日志	项目变更日志

---

关键目录说明

src/components/ — 公共组件

组件	作用
page-table	CRUD 表格组合体（按钮栏 + 表格 + 分页 + 高度自适应 + 帮助按钮）
page-dialog-form	新增/编辑弹框（表单渲染 + 校验 + i18n 自动翻译）
d2-container	页面容器（卡片、全屏、透明等多种布局变体）
d2-container-frame	iframe 嵌套外部页面容器

page-table 和 page-dialog-form 是本项目核心组件，详细用法见 表格组件使用说明。

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 范围内。解决：

# 检查版本
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 中添加：

PORT=8081

Q4：依赖安装慢

pnpm 默认使用 npm registry。如需加速，可配置镜像：

pnpm config set registry https://registry.npmmirror.com