diff --git a/.node-version b/.node-version new file mode 100644 index 00000000..6d80269a --- /dev/null +++ b/.node-version @@ -0,0 +1 @@ +18.16.0 diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..d9408c6b --- /dev/null +++ b/.npmrc @@ -0,0 +1,8 @@ +# pnpm 配置 +# 强制通过 pnpm 安装,禁止使用 npm / yarn +engine-strict=true +# 使用 lockfile 锁定依赖版本 +lockfile=true +# 依赖提升模式(兼容旧项目) +shamefully-hoist=true +# 允许在 package.json 中通过 packageManager 字段指定包管理器版本 diff --git a/README.md b/README.md index 79c34fa8..52f6ba91 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,153 @@ # MES-UI -基于 [D2 Admin](https://github.com/d2-projects/d2-admin)(Vue 2 + Element 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**,保证所有环境安装的依赖版本完全一致。 --- @@ -12,234 +159,109 @@ mes-ui/ ├── docs/ # 项目文档 ├── public/ # 静态资源(不经过 webpack 处理) ├── src/ # PC 端业务源码 -│ ├── api/ # 接口请求层 -│ ├── assets/ # 静态资源(经 webpack 处理) +│ ├── api/ # 接口请求层(按业务模块拆分) +│ │ ├── _service.js # axios 请求服务实例 +│ │ └── production-master-data/ # 生产主数据模块 API +│ ├── assets/ # 静态资源(经 webpack 处理,含 SCSS / SVG) │ ├── components/ # 公共组件 +│ │ ├── page-table/ # CRUD 表格便捷组合体 +│ │ └── page-dialog-form/ # 新增/编辑弹框组件 │ ├── composables/ # 可复用逻辑函数 -│ ├── layout/ # 页面布局 +│ │ ├── useTableColumns.js # 列定义工厂 +│ │ ├── useTableButtons.js # 按钮定义工厂 +│ │ └── useI18n.js # i18n Mixin 工厂 +│ ├── layout/ # 页面布局(header-aside) │ ├── libs/ # 工具函数 -│ ├── locales/ # 国际化语言包 -│ ├── menu/ # 菜单配置 -│ ├── plugin/ # Vue 插件 -│ ├── router/ # 路由配置 +│ ├── locales/ # 国际化语言包(zh-chs / en) +│ ├── router/ # 路由配置(modules/ 按业务模块拆分) │ ├── store/ # Vuex 状态管理 -│ └── views/ # 业务页面 +│ ├── 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 依赖锁定文件 +├── pnpm-lock.yaml # pnpm 依赖锁定文件(必须提交) ├── vue.config.js # Vue CLI 构建配置 └── README.md # 项目说明(本文件) ``` --- -## 各目录详解 - -### `.github/` - -GitHub 相关配置,包含 Issue 模板和 CI/CD 工作流(`workflows/`)。 - -### `docs/` - -项目文档目录,存放变更日志、修复记录等 Markdown 文档。子目录 `image/` 存放文档引用的图片。 +## 项目文档 | 文档 | 说明 | -|------|------| -| [表格组件使用说明](./docs/表格组件使用说明.md) | page-table / page-dialog-form 的完整使用手册 | -| [SCT基础表格重构设计](./docs/SCT基础表格重构设计.md) | 旧 sct-base-table → 新架构的设计文档 | -| [Sass废弃修复](./docs/Sass废弃修复.md) | Sass 废弃警告修复记录 | +| --- | --- | +| [表格组件使用说明](./docs/表格组件使用说明.md) | `page-table` + `page-dialog-form` 完整使用手册 | +| [国际化规则](./docs/国际化规则.md) | i18n 使用规范与迁移指南 | +| [迁移提示词](./docs/迁移提示词.md) | 旧页面迁移到新方案的规则文档 | +| [SCT基础表格重构设计](./docs/SCT基础表格重构设计.md) | 旧 `sct-base-table` → 新架构设计文档 | | [变更日志](./docs/变更日志.md) | 项目变更日志 | -### `public/` +--- -**静态资源目录**,文件会原样复制到构建产物中,不经过 webpack 编译。 +## 关键目录说明 -| 子目录 | 作用 | -|--------|------| -| `lib/UEditor/` | 百度 UEditor 富文本编辑器(第三方库,通过 `