96fe85b3be
1. 重命名README中的文档链接为中文名称 2. 新增数据中台、质量管理、系统设置、设备管理、计划与生产5个业务路由模块 3. 新增CRUD页面迁移、Sass废弃修复、布局组件迁移、国际化规范、登录页面搬迁、变更日志等文档
369 lines
15 KiB
Markdown
369 lines
15 KiB
Markdown
# header-aside 布局组件迁移报告
|
||
|
||
> 迁移日期：2026-05-28
|
||
> 迁移范围：`src/layout/header-aside/`
|
||
> 适用项目：MES-UI（基于 D2Admin）
|
||
|
||
---
|
||
|
||
## 一、迁移概览
|
||
|
||
| 项目 | 迁改前 | 迁改后 |
|
||
|------|--------|--------|
|
||
| **修改文件数** | — | **14 个** |
|
||
| **硬编码中文处数** | **~35 处** | **0 处** |
|
||
| **删除死代码** | — | **1 处**（pageKeepAliveClean） |
|
||
| **新增 i18n key** | 0 | **47 个**（zh-chs/en/ja/zh-cht 各 47 个） |
|
||
| **语言包覆盖** | 仅 zh-chs + en | zh-chs / en / ja / zh-cht 四语言完整覆盖 |
|
||
|
||
---
|
||
|
||
## 二、执行逻辑判断结果
|
||
|
||
### 全部 16 个组件均在新项目中生效，无废弃组件
|
||
|
||
| 文件 | 状态 | 依赖 | 判断依据 |
|
||
|------|------|------|----------|
|
||
| `layout.vue` | ✅ 生效 | d2admin store 全模块 | 全局注册组件齐全 |
|
||
| `menu-side/index.js` | ✅ 生效 | d2admin/menu, d2-scrollbar | 组件已全局注册 |
|
||
| `menu-header/index.js` | ✅ 生效 | d2admin/menu + resize | throttle 正常 |
|
||
| `tabs/index.vue` | ✅ 生效 | d2admin/page, sortablejs | sortablejs 已安装 |
|
||
| `header-search/index.vue` | ✅ 生效 | 纯 emit | 无额外依赖 |
|
||
| `header-user/index.vue` | ✅ 生效 | d2admin/user + account | store 模块存在 |
|
||
| `header-fullscreen/index.vue` | ✅ 生效 | d2admin/fullscreen | store 模块存在 |
|
||
| `header-theme/index.vue` | ✅ 生效 | d2admin/theme | store 模块存在 |
|
||
| `header-theme/list/index.vue` | ✅ 生效 | d2admin/theme | store 模块存在 |
|
||
| `header-size/index.vue` | ✅ 生效 | d2admin/size | store 模块存在 |
|
||
| `header-color/index.vue` | ✅ 生效 | d2admin/color | store 模块存在 |
|
||
| `header-locales/index.vue` | ✅ 生效 | localeMixin | mixin 正常 |
|
||
| `header-log/index.vue` | ✅ 生效 | d2admin/log, 路由 log | log 路由存在 |
|
||
| `contextmenu/index.vue` | ✅ 生效 | 纯 UI | 无额外依赖 |
|
||
| `panel-search/index.vue` | ✅ 生效 | d2admin/search, fuse.js | fuse.js 已安装 |
|
||
| `locales/mixin.js` | ✅ 生效 | $i18n | i18n 已初始化 |
|
||
|
||
---
|
||
|
||
## 三、各文件改动明细
|
||
|
||
### 3.1 模板硬编码 → `$t()` (共 11 个文件)
|
||
|
||
| 文件 | 改动项 | 旧值 | 新值 |
|
||
|------|--------|------|------|
|
||
| **header-user/index.vue** | 用户问候 | `` `你好 ${info.name}` `` | `$t('page.layout.user.greeting', { name })` |
|
||
| | 未登录占位 | `'未登录'` | `$t('page.layout.user.not_logged_in')` |
|
||
| | 登出按钮 | `注销` | `$t('page.layout.user.logout')` |
|
||
| **header-fullscreen/index.vue** | 全屏 tooltip | `'全屏'` / `'退出全屏'` | `$t('page.layout.fullscreen.enter/exit')` |
|
||
| **header-theme/index.vue** | 主题按钮 tooltip | `content="主题"` | `:content="$t('page.layout.theme.title')"` |
|
||
| | 弹框标题 | `title="主题"` | `:title="$t('page.layout.theme.title')"` |
|
||
| **header-theme/list/index.vue** | 预览列标题 | `label="预览"` | `:label="$t('page.layout.theme.preview')"` |
|
||
| | 已激活按钮 | `已激活` | `$t('page.layout.theme.active')` |
|
||
| | 使用按钮 | `使用` | `$t('page.common.use')` |
|
||
| **header-size/index.vue** | 尺寸选项 | `'默认'/'中'/'小'/'最小'` | `$t('page.layout.size.*')` |
|
||
| | 通知标题 | `'提示'` | `$t('page.layout.size.notification_title')` |
|
||
| | 通知内容 | 硬编码 HTML | `$t('page.layout.size.notification_message')` |
|
||
| **header-log/index.vue** | tooltip 文本 | 模板字符串拼接 | `$t('page.layout.log.tooltip/no_log', {...})` |
|
||
| **menu-side/index.js** | 空菜单提示 | `没有侧栏菜单` | `this.$t('page.layout.menu.no_sidebar')` |
|
||
| **tabs/index.vue** | Tab 默认名 | `'未命名'` | `$t('page.layout.tabs.unnamed')` |
|
||
| | 关闭操作文字 | `关闭左侧/右侧/其它/全部` | `$t('page.layout.tabs.close_*')` |
|
||
| | 刷新文字 | `刷新` | `$t('page.layout.tabs.refresh')` |
|
||
| | 错误提示 | `'无效的操作'` | `$t('page.layout.tabs.invalid_operation')` |
|
||
| **panel-search/index.vue** | 搜索 placeholder | `placeholder="搜索页面"` | `:placeholder="$t('page.layout.search.placeholder')"` |
|
||
| | 快捷键提示 | 含 span 的散装文本 | `v-html="$t('page.layout.search.tip', {...})"` |
|
||
| **mixin/menu.js** | 临时菜单提示 | `'临时菜单'` | `$t('page.layout.menu.temp_menu')` |
|
||
| **libs/util.menu.js** | 菜单 fallback | `'未命名菜单'` | `this.$t('page.layout.menu.unnamed_menu')` |
|
||
| **locales/mixin.js** | 语言切换通知 | `'当前语言：...'/'语言变更'` | `$t('page.layout.locales.*')` |
|
||
|
||
### 3.2 data() → computed() 转换（响应式 i18n）
|
||
|
||
| 文件 | 属性 | 原因 |
|
||
|------|------|------|
|
||
| **header-size/index.vue** | `options` → `sizeOptions` | 确保语言切换时下拉选项也跟随更新 |
|
||
| **tabs/index.vue** | `contextmenuListIndex` | 确保右键菜单 title 切换语言时跟随更新 |
|
||
| | `contextmenuList` | 同上 |
|
||
|
||
### 3.3 删除死代码
|
||
|
||
| 文件 | 删除项 | 原因 |
|
||
|------|--------|------|
|
||
| **header-size/index.vue** | `...mapMutations({ pageKeepAliveClean })` | 引入后从未被调用 |
|
||
| 同步删除了 `import { mapMutations }` | `mapMutations` 不再需要 | 单一用途，移除了整个 import |
|
||
|
||
---
|
||
|
||
## 四、新增 i18n Key 清单
|
||
|
||
所有 key 位于 `page.layout.*` 命名空间下，四语言同步添加：
|
||
|
||
```
|
||
page.layout.
|
||
├── user.greeting / not_logged_in / logout
|
||
├── fullscreen.enter / exit
|
||
├── theme.title / preview / active
|
||
├── size.default / medium / small / mini / notification_title / notification_message
|
||
├── log.no_log / tooltip / tooltip_zero
|
||
├── menu.no_sidebar / temp_menu / unnamed_menu
|
||
├── tabs.unnamed / refresh / close_left / close_right / close_other / close_all / invalid_operation
|
||
├── search.placeholder / tip
|
||
└── locales.changed / notification_title / preview_warning / preview_doc
|
||
```
|
||
|
||
加上 `page.common.use`，共计 **48 个新 key × 4 语言 = 192 条翻译**。
|
||
|
||
---
|
||
|
||
## 五、开发者注意事项
|
||
|
||
### 5.1 涉及 4 个语言包文件
|
||
|
||
> ⚠️ 所有修改的语言包 `zh-chs.json / en.json / ja.json / zh-cht.json` 已通过 `JSON.parse()` 验证合法性。
|
||
|
||
### 5.2 JSX 渲染函数的特殊语法
|
||
|
||
`menu-side/index.js` 和 `libs/util.menu.js` 使用 JSX 渲染函数，`$t()` 调用语法为 `{ this.$t('...') }`（单花括号），与 `.vue` 模板的 `{{ }}`（双花括号）不同。
|
||
|
||
### 5.3 `v-html` 使用处
|
||
|
||
`panel-search/index.vue` 的提示文本包含内联 `<span class="panel-search__key">` 标签，必须使用 `v-html` 绑定。
|
||
|
||
### 5.4 `data()` → `computed()` 的 Reactivity
|
||
|
||
`header-size` 和 `tabs` 组件中原来在 `data()` 里的中文文本数组已经移到 `computed`，确保 `$t()` 是响应式的。未来如果要在 `data()` 中放翻译文本，必须使用 computed 或确保使用者是组件内部翻译。
|
||
|
||
---
|
||
|
||
## 六、回滚指南
|
||
|
||
如需回滚任一组件的改动：
|
||
|
||
1. **布局组件** — `git checkout` 对应的组件文件即可，所有改动互相独立
|
||
2. **语言包** — 回滚 `src/locales/*.json`，新增的 `page.layout` 命名空间不影响业务页面
|
||
3. **localeMixin** — 回滚 `src/locales/mixin.js`
|
||
|
||
---
|
||
|
||
## 七、验证清单
|
||
|
||
| 验证项 | 方法 |
|
||
|--------|------|
|
||
| JSON 合法性 | `node -e "JSON.parse(require('fs').readFileSync('src/locales/zh-chs.json','utf8'))"` |
|
||
| 全量 JSON | 逐个检查 zh-chs/en/ja/zh-cht（已通过） |
|
||
| 语言切换 | 打开页面 → 切换中文/English/日本語/繁體中文 → 观察全部 header 文字是否跟随变化 |
|
||
| 搜索面板 | `Ctrl+K` 打开搜索面板 → 检查 placeholder + 快捷键提示 |
|
||
| 右键 Tab | 右键点击 Tab → 检查菜单文字 |
|
||
| 全屏切换 | 鼠标悬停全屏按钮 → 检查 tooltip |
|
||
| 主题弹框 | 打开主题弹框 → 检查标题 + "预览"/"已激活"/"使用" |
|
||
| 组件尺寸 | 切换组件尺寸 → 检查通知弹框 |
|
||
| 用户区 | 检查用户问候语 + 登出按钮 |
|
||
|
||
---
|
||
|
||
## 八、菜单 i18n 翻译方案（2026-05-28 追加）
|
||
|
||
### 8.1 问题背景
|
||
|
||
旧项目中，当用户切换语言（中文 → English）时，侧边栏菜单和顶部一级导航菜单的文字会跟随切换为英文。当前项目迁移后缺少这个能力，菜单文字始终为后端返回的单一语言文本。
|
||
|
||
### 8.2 方案设计
|
||
|
||
采用**双重保障**机制：
|
||
|
||
```
|
||
┌─ 方案 A：$t() 包装（客户端翻译）
|
||
语言切换 ──────────┤
|
||
└─ 方案 B：menuReload（重新拉取后端菜单）
|
||
```
|
||
|
||
#### 方案 A：渲染层 `$t()` 包装
|
||
|
||
将菜单渲染节点中的所有 `menu.title` 包裹 `$t()`。
|
||
|
||
**修改文件**：
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `src/layout/header-aside/components/libs/util.menu.js` | `elMenuItem` 和 `elSubmenu` 中 `menu.title` → `this.$t(menu.title)` |
|
||
| `src/components/d2-module-index-menu/components/group.vue` | `{{menu.title}}` → `{{ $t(menu.title) }}`（2 处） |
|
||
| `src/components/d2-module-index-menu/components/item.vue` | `{{menu.title}}` → `{{ $t(menu.title) }}` |
|
||
|
||
**工作原理**：
|
||
|
||
```
|
||
后端返回 title 是 i18n key → $t() 返回对应语言的翻译 ✓
|
||
后端返回 title 是纯文本 → $t() 找不到 key，返回原文本（fallback）✓
|
||
```
|
||
|
||
无需修改后端接口即可兼容两种模式。
|
||
|
||
#### 方案 B：语言切换时重新拉取菜单
|
||
|
||
在 `src/store/modules/d2admin/modules/menu.js` 新增 `menuReload` action：
|
||
|
||
```js
|
||
async menuReload ({ state, dispatch }) {
|
||
// 1. 清空 localStorage 缓存
|
||
await dispatch('d2admin/db/set', {
|
||
dbName: 'database',
|
||
path: '$menu.sourceData',
|
||
value: [],
|
||
user: true
|
||
}, { root: true })
|
||
state.sourceData = []
|
||
// 2. 重新从后端拉取（后端根据当前语言返回对应文本）
|
||
await dispatch('sourceDataLoad')
|
||
}
|
||
```
|
||
|
||
在 `src/locales/mixin.js` 的 `onChangeLocale` 末尾追加：
|
||
|
||
```js
|
||
this.$store.dispatch('d2admin/menu/menuReload')
|
||
```
|
||
|
||
### 8.3 工作流程
|
||
|
||
```
|
||
用户点击切换语言
|
||
│
|
||
├─ this.$i18n.locale = 'en' → 客户端组件重新渲染
|
||
│ $t(menu.title) 即时生效 ✓
|
||
│
|
||
├─ $store.dispatch('menuReload') → 清缓存 → 调后端
|
||
│ getMenuAll() 返回英文菜单
|
||
│ menu.install() 重建 header/aside
|
||
│ 侧栏 + 顶栏全部更新 ✓
|
||
│
|
||
└─ $notify({ title: 'Language Changed' }) → 通知用户
|
||
```
|
||
|
||
> **注意**：如果后端 `getMenuAll()` 接口**不支持**根据语言返回不同内容，方案 B 不会生效，此时仅依赖方案 A（`$t()` 包装）。建议后续后端添加多语言菜单数据返回。
|
||
|
||
### 8.4 修改清单
|
||
|
||
| 文件 | 操作 | 行数 |
|
||
|------|------|------|
|
||
| `src/layout/header-aside/components/libs/util.menu.js` | `menu.title` → `this.$t(menu.title)` | 2 处 |
|
||
| `src/components/d2-module-index-menu/components/group.vue` | `{{menu.title}}` → `{{ $t(menu.title) }}` | 2 处 |
|
||
| `src/components/d2-module-index-menu/components/item.vue` | `{{menu.title}}` → `{{ $t(menu.title) }}` | 1 处 |
|
||
| `src/store/modules/d2admin/modules/menu.js` | 新增 `menuReload` action | +15 行 |
|
||
| `src/locales/mixin.js` | `onChangeLocale` 末尾追加 `menuReload` | +1 行 |
|
||
|
||
### 8.5 验证方法
|
||
|
||
1. 启动项目，确认**当前展示的菜单文字正确**（方案 A 生效）
|
||
2. 切换语言，观察侧边栏和顶部导航栏文字是否更新（方案 A + B 双重生效）
|
||
3. 如果切换语言后菜单文字不变，检查：
|
||
- 后端 `getMenuAll()` 是否支持多语言
|
||
- 菜单数据中的 `name` 是否为可翻译的 i18n key 路径
|
||
|
||
---
|
||
|
||
## 九、一级模块首页复用方案（2026-05-28 追加）
|
||
|
||
### 9.1 问题背景
|
||
|
||
旧项目中，每个一级模块（如 `planning_production`）都有一个 `index/index.vue`：
|
||
|
||
```vue
|
||
<template>
|
||
<d2-container>
|
||
<page-navi class="cs-m" v-model="root"/>
|
||
</d2-container>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
name: 'produce-index',
|
||
components: {
|
||
PageNavi: () => import('@/layout/header-aside/components/header-navi')
|
||
},
|
||
data() { return { root: '/planning_production' } }
|
||
}
|
||
</script>
|
||
```
|
||
|
||
这些文件结构**高度重合**，仅 `root` 值不同。随着模块增多（对照表中约 20+ 个一级模块），需要逐个创建这些文件。
|
||
|
||
### 9.2 方案：通用 `module-index.vue`
|
||
|
||
创建一个**共享的路由级组件**，动态读取路由 meta 中的 `root` 来展示模块首页。
|
||
|
||
**文件**：`src/views/system/function/module-index.vue`（已创建）
|
||
|
||
**核心逻辑**：
|
||
|
||
```vue
|
||
<template>
|
||
<d2-container class="module-index-page">
|
||
<template #header>
|
||
<d2-module-index-banner
|
||
:title="$t(headerMenu.title)"
|
||
:sub-title="$t(headerMenu.title)" />
|
||
</template>
|
||
<d2-module-index-menu :menu="asideMenu" />
|
||
</d2-container>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
computed: {
|
||
rootPath () { return this.$route.meta.root || this.$route.path },
|
||
headerMenu () {
|
||
return this.$store.state.d2admin.menu.header.find(
|
||
m => m.path === this.rootPath
|
||
) || { title: this.rootPath }
|
||
},
|
||
asideMenu () {
|
||
return this.$store.state.d2admin.menu.aside.find(
|
||
m => m.path === this.rootPath
|
||
) || { children: [] }
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 9.3 使用方式
|
||
|
||
在路由模块中，为每个一级模块添加一个指向同一组件的空路径路由：
|
||
|
||
**路由示例**（`src/router/modules/production-master-data.js`）：
|
||
|
||
```js
|
||
export default {
|
||
path: '/production_configuration',
|
||
component: layoutHeaderAside,
|
||
children: (pre => [
|
||
// ★ 模块首页 — 所有一级模块共用同一个组件
|
||
{
|
||
path: '',
|
||
name: `${pre}index`,
|
||
meta: { ...meta, title: '生产配置', root: '/production_configuration' },
|
||
component: _import('system/function/module-index')
|
||
},
|
||
// 三级模块页面...
|
||
{
|
||
path: 'factory_model/factory_area',
|
||
name: `${pre}factory_model-factory_area`,
|
||
meta: { ...meta, cache: true, title: '工厂区域' },
|
||
component: _import('production-master-data/factory-model/factory-area')
|
||
}
|
||
])('production_configuration-')
|
||
}
|
||
```
|
||
|
||
### 9.4 对比
|
||
|
||
| 维度 | 旧方案 | 新方案 |
|
||
|------|--------|--------|
|
||
| **文件数** | 每个一级模块 1 个 index.vue（20+ 个） | 全局共享 1 个 `module-index.vue` |
|
||
| **模板代码** | 每个文件 20 行重复代码 | 0 行重复 |
|
||
| **root 值** | 硬编码在每个 data() 中 | 路由 `meta.root` 动态读取 |
|
||
| **i18n** | 无 | 通过 `$t(menu.title)` 自动翻译 |
|
||
| **新增模块** | 创建目录 + 创建 index.vue + 写重复代码 | 仅需添加路由配置行 |
|
||
|
||
### 9.5 验证方法
|
||
|
||
1. 访问 `/production_configuration`（不带子路径），应显示"生产配置"模块的二级和三级模块导航
|
||
2. 切换语言，banner 标题和菜单项应跟随翻译
|
||
3. 点击菜单项，正确跳转到对应页面对应的三级模块页面
|