scottpan/my-mom-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
my-mom-system/.cursor/plans/mom-ui_tech_stack_migration_ddb51afc.plan.md

447 lines
19 KiB
Markdown
Raw Permalink Normal View History

commit content
2026-03-06 02:02:59 +08:00
---
name: MOM-UI Tech Stack Migration
overview: 将 mom-backend-ui 从 Vue CLI + Vue 2 + Element UI 渐进式升级到 Vite + Vue 3 + Element Plus，与 erp-frontend-vue 技术栈保持一致，方便后续合并。
todos:
- id: phase1-vite-setup
content: "Phase 1: 创建 vite.config.js，移动 index.html 到根目录，更新 package.json scripts，安装 Vite + Vue 3 + @vue/compat 依赖，移除 Vue CLI/Webpack 依赖"
status: completed
- id: phase2-core-modules
content: "Phase 2: 更新 main.js (createApp)，升级 Vue Router 4，升级 Vuex 4，替换 SVG 图标系统 (vite-plugin-svg-icons)，修改 permission.js"
status: completed
- id: phase3a-element-plus-deps
content: "Phase 3a: 替换 Element Plus 依赖 + 更新 main.js 导入 + 迁移公共组件 (31 个 dialog 组件) + 迁移采购入库页面 (4 个 Vue 文件) 作为验证试点"
status: in_progress
- id: phase3a-2-layout-components
content: "Phase 3a-2: 迁移 src/layout/ + src/components/ 中非 dialog 组件 (~38 个 Vue 文件)，确保公共组件完全脱离 Element UI"
status: completed
- id: phase3b-wm-module
content: "Phase 3b: 迁移仓库管理模块其余页面 (wm, 64 个 Vue 文件)，验证整个模块功能正常"
status: pending
- id: phase3c-remaining-pages
content: "Phase 3c: 迁移其余所有页面 (MES 其他 98 + system 19 + monitor 8 + tool 12 + print 6 + 其他 5 = ~148 个 Vue 文件) + 全局样式修正"
status: pending
- id: phase4-third-party
content: "Phase 4: 更新第三方依赖为 Vue 3 兼容版本 (vuedraggable, vue-cropper, echarts, quill, axios 等)"
status: completed
- id: phase5-cleanup
content: "Phase 5: 删除旧配置文件，迁移环境变量 (VUE_APP_ -> VITE_)，移除 @vue/compat，最终清理"
status: pending
isProject: false
---
# mom-backend-ui 技术栈升级计划
## 当前差异对比
| 维度 | mom-backend-ui (当前) | erp-frontend-vue (目标) |
| ------ | ----------------------------------- | -------------------------------- |
| 构建工具 | Vue CLI 4 (Webpack) | Vite 7 |
| 框架 | Vue 2.6 | Vue 3.5 |
| UI 库 | Element UI 2.15 | Element Plus 2.x |
| 路由 | Vue Router 3.4 | Vue Router 4.6 |
| 状态管理 | Vuex 3.6 | 自定义 reactive store |
| 语言 | JavaScript | TypeScript (暂保留 JS) |
| 组件风格 | Options API | Composition API `<script setup>` |
| SVG 图标 | svg-sprite-loader + require.context | @element-plus/icons-vue |
## 核心挑战
项目有 **305 个 Vue 文件 + 225 个 JS 文件**，无法一步到位。采用 **Vue 3 兼容模式 (`@vue/compat`)** 进行渐进式迁移，确保大部分 Vue 2 代码可以在 Vue 3 下运行，然后逐步修复。
---
## Phase 1: Vite 构建工具替换 + Vue 3 兼容模式
### 1.1 创建 Vite 配置
在 [mom-backend-ui/](mom-backend-ui/) 根目录创建 `vite.config.js`，参考 [erp-frontend-vue/vite.config.ts](erp-frontend-vue/vite.config.ts) 的结构：
```javascript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
export default defineConfig({
plugins: [
vue(),
createSvgIconsPlugin({
iconDirs: [path.resolve(__dirname, 'src/assets/icons/svg')],
symbolId: 'icon-[name]'
})
],
resolve: {
alias: { '@': path.resolve(__dirname, './src') },
// Vue 3 compat mode
dedupe: ['vue']
},
server: {
port: 80,
proxy: {
'/dev-api': {
target: 'http://localhost:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/dev-api/, '')
},
'/ureport': {
target: 'http://localhost:8080',
changeOrigin: true
}
}
},
css: {
preprocessorOptions: {
scss: { api: 'modern-compiler' }
}
}
})
```
### 1.2 移动并更新 index.html
将 [mom-backend-ui/public/index.html](mom-backend-ui/public/index.html) 移到项目根目录，移除 Webpack 模板语法：
- `<%= BASE_URL %>` 改为 `/`
- `<%= webpackConfig.name %>` 改为固定标题
- 添加 `<script type="module" src="/src/main.js"></script>`
### 1.3 更新 package.json
- 添加 `"type": "module"`
- 更新 scripts：
- `"dev": "vite"`
- `"build": "vite build"`
- `"preview": "vite preview"`
### 1.4 安装新依赖，移除旧依赖
**安装：**
- `vue@^3.5` + `@vue/compat@^3.5`（兼容模式）
- `vite` + `@vitejs/plugin-vue`
- `vite-plugin-svg-icons` + `fast-glob`（替代 svg-sprite-loader）
- `sass-embedded`（替代 sass + sass-loader）
**移除：**
- `@vue/cli-service`, `@vue/cli-plugin-babel`, `@vue/cli-plugin-eslint`
- `vue-template-compiler`
- `webpack` 相关: `compression-webpack-plugin`, `script-ext-html-webpack-plugin`, `svg-sprite-loader`, `sass-loader`, `less-loader`
- `babel-eslint`, `babel-plugin-dynamic-import-node`, `cross-env`
- `core-js`
### 1.5 配置 @vue/compat
在 `vite.config.js` 中配置别名，让 `vue` 指向兼容构建：
```javascript
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'vue': '@vue/compat'
}
}
```
同时需要配置 `@vitejs/plugin-vue` 的 compat 编译器选项：
```javascript
vue({
template: {
compilerOptions: {
compatConfig: { MODE: 2 }
}
}
})
```
---
## Phase 2: 更新入口文件和核心模块
### 2.1 更新 main.js
将 [mom-backend-ui/src/main.js](mom-backend-ui/src/main.js) 从 `new Vue()` 改为 `createApp()`：
- `import { createApp } from 'vue'` 替代 `import Vue from 'vue'`
- `const app = createApp(App)` 替代 `new Vue({...})`
- `Vue.prototype.xxx` 改为 `app.config.globalProperties.xxx`
- `Vue.component(...)` 改为 `app.component(...)`
- `Vue.use(...)` 改为 `app.use(...)`
- `app.use(store).use(router).mount('#app')`
### 2.2 更新 SVG 图标系统
将 [mom-backend-ui/src/assets/icons/index.js](mom-backend-ui/src/assets/icons/index.js) 中的 `require.context` 替换为 Vite 的 `import.meta.glob`：
```javascript
import 'virtual:svg-icons-register'
// SvgIcon 组件需要在 main.js 中用 app.component 注册
```
### 2.3 升级 Vue Router 3 -> 4
修改 [mom-backend-ui/src/router/index.js](mom-backend-ui/src/router/index.js)：
- `import { createRouter, createWebHistory } from 'vue-router'`
- `new Router({mode: 'history', ...})` 改为 `createRouter({ history: createWebHistory(), ... })`
- 移除 `Vue.use(Router)`
- `scrollBehavior: () => ({ y: 0 })` 改为 `scrollBehavior: () => ({ top: 0 })`
修改 [mom-backend-ui/src/permission.js](mom-backend-ui/src/permission.js)：
- `router.addRoutes(accessRoutes)` 改为循环调用 `router.addRoute(route)`
- `Message` 从 Element Plus 导入
### 2.4 升级 Vuex 3 -> 4
修改 [mom-backend-ui/src/store/index.js](mom-backend-ui/src/store/index.js)：
- `import { createStore } from 'vuex'`
- `new Vuex.Store({...})` 改为 `createStore({...})`
- 移除 `Vue.use(Vuex)`
- 各 modules 文件暂时不动（Vuex 4 向后兼容 module 写法）
---
## Phase 3: Element UI -> Element Plus 迁移（分步进行）
这是工作量最大的部分，影响所有 306 个 Vue 文件。为保证项目平稳升级，拆分为 **3a → 3b → 3c** 三步，先拿采购入库页面做试点验证，确认方案可行后再逐步扩展到全模块。
### Element UI -> Element Plus 通用变更清单
以下变更适用于所有步骤，每步迁移页面时需逐项检查：
- **size 属性**: `size="mini"` -> `size="small"`, `size="medium"` -> `size="default"`
- **图标**: `<i class="el-icon-xxx">` -> `<el-icon><Xxx /></el-icon>` 或对应 Element Plus 图标组件
- **v-model 变更**: `.sync` 修饰符移除，改用 `v-model:propName`
- `:visible.sync` -> `v-model`（Dialog）
- `:current-page.sync` -> `v-model:current-page`（Pagination）
- `:page-size.sync` -> `v-model:page-size`（Pagination）
- **事件名变更**: `@current-change` 等部分组件事件保持不变；`.native` 修饰符移除
- **Slot 变更**: 部分具名插槽名称变化
- **移除的属性**: `el-button` 的 `type="text"` 改为 `link` 或 `text` 属性
- **DatePicker**: `value-format` 格式字符串变更 (如 `yyyy-MM-dd` -> `YYYY-MM-DD`)
---
### Phase 3a: 替换依赖 + 迁移公共组件 + 采购入库页面试点
**目标**: 完成 Element Plus 基础切换，优先迁移 `src/components` 中的公共组件（避免页面迁移时遇到依赖问题），再以采购入库页面（`itemrecpt`）作为验证试点。
#### 3a.1 替换依赖
- 卸载 `element-ui`
- 安装 `element-plus` + `@element-plus/icons-vue`
- 删除 [mom-backend-ui/src/assets/styles/element-variables.scss](mom-backend-ui/src/assets/styles/element-variables.scss)，改用 Element Plus 主题配置
#### 3a.2 更新 main.js 中的 Element 导入
```javascript
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
import * as ElementPlusIconsVue from '@element-plus/icons-vue'
// 注册图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
app.component(key, component)
}
app.use(ElementPlus, { locale: zhCn, size: 'default' })
```
#### 3a.3 更新 plugins/modal.js 中的 Element 导入
将 `import { Message, MessageBox, Notification, Loading } from 'element-ui'` 改为 `import { ElMessage, ElMessageBox, ElNotification, ElLoading } from 'element-plus'`，并更新对应的 API 调用。
同时更新 `permission.js` 中的 `Message` 导入。
#### 3a.4 迁移公共组件（31 个包含 Dialog 的组件，优先处理）
**目标**: 修复所有 `src/components` 中使用 `:visible.sync` 的组件，避免页面迁移时遇到 `[ElOnlyChild]` 错误。
需要迁移的组件列表（按目录分组）：
| 组件分类 | 文件路径 | 数量 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| Select 组件 | vendorSelect, iqcSelect, noticeSelect, itemSelect, clientSelect, batchSelect, userSelect, stockSelect, machinerySelect, warehouseSelect, workstationSelect, workorderSelect, procardSelect, qcindexSelect, reportSelect, TaskSelect, defectSelect, dvsubjectSelect, calTeamSelect, oqcSelect, itemBomSelect, dvplanSelect, stocktakingplanSelect, package | 31 |
| 其他 | DictSelect, ImageUpload | 2 |
**关键变更点**（适用所有组件）：
- `:visible.sync="showFlag"` -> `v-model="showFlag"`
- 移除 `v-if="showFlag"`（Element Plus dialog 自带显示控制）
- `<el-dialog>` 必须有单个根元素：添加 `<div class="dialog-content-wrapper">` 包裹所有 slot 默认内容
- `<div slot="footer">` -> `<template #footer>`
**当前进度**（已完成部分）：
- ✅ vendorSelect/single.vue
- ✅ iqcSelect/single.vue
- ✅ noticeSelect/single.vue
- ⏳ noticeSelect/lineSingle.vue (进行中)
- ⏳ itemSelect/single.vue (进行中)
- 🔲 其余 26 个组件待迁移
#### 3a.5 迁移采购入库页面（试点验证）
逐一修改以下 4 个文件，按照通用变更清单做 Element Plus 适配：
| 文件 | 说明 |
| --------------------------------------- | ------- |
| `src/views/mes/wm/itemrecpt/index.vue` | 采购入库列表页 |
| `src/views/mes/wm/itemrecpt/form.vue` | 采购入库表单页 |
| `src/views/mes/wm/itemrecpt/line.vue` | 采购入库明细行 |
| `src/views/mes/wm/itemrecpt/detail.vue` | 采购入库详情页 |
**验收标准**: 启动 `vite dev`，能正常访问采购入库列表、新增、编辑、查看详情，无控制台报错。
---
### Phase 3a-2: 迁移公共布局和非 Dialog 组件（~38 个 Vue 文件）
**目标**: 完成 `src/layout/` 和 `src/components/` 中剩余的非 dialog 组件迁移，确保所有公共组件脱离 Element UI。
#### 需要迁移的文件类型
**Layout 组件** (`src/layout/`):
- Layout 主布局组件
- Navbar, Sidebar, TagsView 等导航组件
- AppMain, Settings 等布局子组件
- 约 10-15 个文件
**非 Dialog 公共组件** (`src/components/`):
- Pagination（分页组件）
- FileUpload（文件上传）
- Editor（富文本编辑器，可能使用 Element UI 依赖）
- Breadcrumb（面包屑）
- SvgIcon（SVG 图标，已迁移）
- Dict 相关组件（数据字典）
- TreeSelect, Cascader 等表单组件
- 其他工具类组件（约 20-25 个文件）
**迁移要点**:
- 替换所有 Element UI 组件为 Element Plus
- 更新 `size="mini"` -> `size="small"`
- 移除 `.native` 修饰符
- 更新图标引用方式
- 检查并修复任何使用 `$message`, `$alert` 等全局方法的调用
**验收标准**: 所有 `src/components/` 和 `src/layout/` 文件中不再有 `element-ui` 导入，项目启动无 Element UI 相关警告。
---
### Phase 3b: 仓库管理模块其余页面（64 个 Vue 文件）
**目标**: 确认试点方案可行后，将整个仓库管理模块（`views/mes/wm/`）全部迁移完成。
需要迁移的子模块（按业务分组）：
| 分组 | 子模块 | 文件数 |
| --- | -------------------------------------------------------------------------------------------------------- | --- |
| 入库 | arrivalnotice (到货通知), itemrecpt (采购入库✅已完成), outsourcerecpt (委外入库), productrecpt (产品入库), miscrecpt (其他入库) | ~15 |
| 出库 | issue (生产领料), productsales (销售出库), outsourceissue (委外出库), miscissue (其他出库), itemconsume (物料消耗) | ~15 |
| 退料 | rtissue (生产退料), rtsales (销售退货), rtvendor (供应商退货) | ~9 |
| 库存 | wmstock (库存查询), stocktaking (盘点), stocktakingplan (盘点计划), transfer (调拨) | ~10 |
| 基础 | warehouse (仓库), location (库区), area (库位), barcode (条码), batch (批次), sn (序列号), package (包装) | ~13 |
| 通知 | salesnotice (销售通知), mrnotice (物料需求通知) | ~5 |
**验收标准**: 仓库管理菜单下所有页面（列表/表单/详情）均可正常操作，无控制台 Element 组件报错。
---
### Phase 3c: 其余所有页面（~148 个 Vue 文件）+ 全局样式修正
**目标**: 完成所有剩余页面的迁移，项目彻底脱离 Element UI。
| 分组 | 范围 | 文件数 |
| ------ | ------------------------------------------------------------ | --- |
| MES 其他 | `views/mes/` 除 wm 外 (md, pro, dv, qc, report 等) | ~98 |
| 系统管理 | `views/system/` (user, role, menu, dept, dict 等) | ~19 |
| 监控 | `views/monitor/` (online, job, server, cache 等) | ~8 |
| 工具 | `views/tool/` (gen, build 等) | ~12 |
| 打印 | `views/print/` | ~6 |
| 其他 | `views/login.vue`, `views/register.vue`, `views/index.vue` 等 | ~5 |
#### 3c.1 全局样式文件更新
- 更新 [mom-backend-ui/src/assets/styles/](mom-backend-ui/src/assets/styles/) 下的 SCSS 文件中引用 Element UI 类名的部分
- Element Plus 的 CSS 变量命名有差异（如 `--el-color-primary` 等）
- `el-icon-loading` spinner 等全局引用需更新
**验收标准**: 全站所有页面功能正常，无 Element UI 残留引用，`vite build` 成功。
---
## Phase 4: 更新第三方依赖
以下 Vue 2 专属库需要更新为 Vue 3 兼容版本：
| 当前依赖 | 操作 |
| ------------------------- | ------------------------------------------------- |
| `vue-meta` 2.x | 移除，改用 `@unhead/vue` 或 `document.title` |
| `vuedraggable` 2.x | 升级到 `vuedraggable@next` (4.x) |
| `vue-cropper` 0.5 | 升级到 `vue-cropper@next` |
| `@riophae/vue-treeselect` | 替换为 `vue3-treeselect` 或 Element Plus 的 TreeSelect |
| `vue-count-to` | 替换为 Vue 3 兼容版本或自行实现 |
| `vue-plugin-hiprint` | 确认 Vue 3 兼容性，可能需要替换 |
| `echarts` 4.9 | 升级到 5.x |
| `@dhtmlx/trial-vue-gantt` | 确认 Vue 3 兼容版本 |
| `quill` | 替换为 `@vueup/vue-quill` |
| `axios` 0.24 | 升级到 1.x |
---
## Phase 5: 清理和收尾
### 5.1 移除旧配置文件
- 删除 `vue.config.js`
- 删除 `babel.config.js`
- 删除 `.eslintrc.js`（后续可按需重新配置 ESLint flat config）
- 删除 `build/` 目录（preview 脚本）
### 5.2 移除 @vue/compat
当所有组件和功能正常运行后：
- 在 `vite.config.js` 中移除 `'vue': '@vue/compat'` 别名
- 移除 `compatConfig` 编译器选项
- 卸载 `@vue/compat`
- 修复剩余的 Vue 2 兼容性警告
### 5.3 环境变量迁移
- `VUE_APP_*` 环境变量需改为 `VITE_*` 前缀
- `process.env.VUE_APP_*` 改为 `import.meta.env.VITE_*`
- 创建 `.env.development` 和 `.env.production` 文件
---
## 执行建议
- **Phase 1-2** 是基础，已完成，项目可用 `vite` 启动和构建
- **Phase 3a** 先做依赖切换 + 采购入库试点，验证迁移方案的完整流程和模式
- **Phase 3b** 试点通过后，在仓库管理模块内推广，以模块为单位验证
- **Phase 3c** 最后全面铺开，涵盖剩余 layout/components/views
- **Phase 4** 可以与 Phase 3 并行，按需处理
- **Phase 5** 在所有功能验证通过后进行
- 整个过程中暂保留 JavaScript，不转 TypeScript，后续按需迁移
- 每步完成后都应启动 `vite dev` 实际操作验证，确认无功能回退再进入下一步
Reference in New Issue Copy Permalink