mes-ui-d2/README.md

# 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
```

> `winget` 安装完成后，**当前终端窗口不会自动加载 Volta**。选择以下任一方式生效：
>
> **方式一（关闭重开）：** 关掉当前终端，重新打开一个 PowerShell / VS Code 终端。
>
> **方式二（不重启立即生效）：** 在当前终端执行：
> ```powershell
> $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
> ```
>
> 生效后验证：
> ```powershell
> volta --version   # 应输出版本号（如 2.0.2）
> ```

**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
# 如果你本机没有这个版本，Volta 会提示 "Fetching node@18.16.0" —— 等它完成即可
node --version   # 应输出 v18.16.0

# 安装依赖
pnpm install
```

> **没有安装 Node 18.16.0 怎么办？**  
> **Volta 用户**：无需手动操作。进入项目目录时 Volta 会自动检测 `.node-version`，如果本机缺这个版本，它会**自动下载安装**，你只需等待几秒终端提示完成即可。  
> **nvm 用户**：执行 `nvm install 18.16.0 && nvm use 18.16.0`。  
> **手动安装**：去 [nodejs.org](https://nodejs.org/) 下载 Node.js 18.16.0 安装包。  
>
> 装完后建议运行 `node --version` 确认输出 `v18.16.0`，否则 `pnpm install` 会因为 `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 版本不在项目规定范围内，install 被阻断。

**先排查版本：**

```bash
node --version   # 项目要求 >=18.16.0 <19
pnpm --version   # 项目要求 >=10.33.0 <11
```

**谁把版本不对：**

| 情景 | 解决办法 |
| --- | --- |
| **用 Volta**（推荐） | `volta install node@18.16.0` + `volta install pnpm@10.33.0`，进入项目目录自动生效 |
| **用 nvm** | `nvm install 18.16.0 && nvm use 18.16.0`，再 `npm install -g pnpm@10.33.0` |
| **手动安装** | 去 [nodejs.org](https://nodejs.org/) 下载 18.16.0，再 `npm install -g pnpm@10.33.0` |
| **已有正确版本但切换不生效** | 重新打开终端，确保 `volta` / `nvm` 已正确加载 |

> 版本验证通过后，重新执行 `pnpm install`。

### Q2：启动后页面报跨域错误

在 `.env.development.local` 中确认 `VUE_APP_API` 指向正确的后台地址，且后台已开启 CORS。

### Q3：端口被占用

默认端口为 `8080`。如需修改，在 `.env.development.local` 中添加：

```bash
PORT=8081
```

### Q4：`volta` 命令无法识别 / "无法将 volta 项识别为 cmdlet"

> 原因：`winget install Volta.Volta` 不会自动刷新当前终端的 PATH 缓存。

**解决办法二选一：**

```powershell
# 方案 A：关掉当前终端，重新打开一个（推荐，最简单）
# 方案 B：在当前终端执行以下命令立即生效，免重启
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH", "User")
```

> 生效后 `volta --version` 应输出版本号。

### Q5：依赖安装慢

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

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