mes-ui-d2/README.md

# MES-UI

基于 [D2 Admin](https://github.com/d2-projects/d2-admin)（Vue 2 + Element UI）的企业级中后台前端项目。

---

## 项目目录结构

```
mes-ui/
├── .github/                    # GitHub 相关配置
├── docs/                       # 项目文档
├── public/                     # 静态资源（不经过 webpack 处理）
├── src/                        # PC 端业务源码
│   ├── api/                    # 接口请求层
│   ├── assets/                 # 静态资源（经 webpack 处理）
│   ├── components/             # 公共组件
│   ├── composables/            # 可复用逻辑函数
│   ├── layout/                 # 页面布局
│   ├── libs/                   # 工具函数
│   ├── locales/                # 国际化语言包
│   ├── menu/                   # 菜单配置
│   ├── plugin/                 # Vue 插件
│   ├── router/                 # 路由配置
│   ├── store/                  # Vuex 状态管理
│   └── views/                  # 业务页面
├── src.mobile/                 # 移动端业务源码
├── .browserslistrc             # 浏览器兼容配置
├── .editorconfig               # 编辑器统一配置
├── .env / .env.development / .env.preview  # 环境变量
├── .eslintignore / .eslintrc.js            # ESLint 配置
├── .gitignore                  # Git 忽略配置
├── .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                   # 项目说明（本文件）
```

---

## 各目录详解

### `.github/`

GitHub 相关配置，包含 Issue 模板和 CI/CD 工作流（`workflows/`）。

### `docs/`

项目文档目录，存放变更日志、修复记录等 Markdown 文档。子目录 `image/` 存放文档引用的图片。

| 文档 | 说明 |
|------|------|
| [表格组件使用说明](./docs/表格组件使用说明.md) | page-table / page-dialog-form 的完整使用手册 |
| [sct-base-table 重构方案](./docs/sct-base-table-refactor-design.md) | 旧 sct-base-table → 新架构的设计文档 |
| [sass-deprecation-fixes.md](./docs/sass-deprecation-fixes.md) | Sass 废弃警告修复记录 |
| [CHANGELOG.md](./docs/CHANGELOG.md) | 项目变更日志 |

### `public/`

**静态资源目录**，文件会原样复制到构建产物中，不经过 webpack 编译。

| 子目录 | 作用 |
|--------|------|
| `lib/UEditor/` | 百度 UEditor 富文本编辑器（第三方库，通过 `<script>` 直接引入） |
| `image/theme/` | 各主题的 Logo 图片和预览图（chester / d2 / element / line / star / tomorrow-night-blue / violet） |
| `image/loading/` | 页面加载动画的 SVG |
| `html/` | 独立 HTML 页面（如 demo.html） |
| `index.html` | SPA 入口 HTML 模板 |
| `icon.ico` | 网站 Favicon |

### `src/` — PC 端源码

#### `src/api/`
**接口请求层**。封装后端 API 调用，按业务模块拆分为独立文件。
- `_service.js` — 基于 axios 的请求服务实例
- `_tools.js` — 请求工具函数
- `demo.js` — 演示接口
- `sys.user.js` — 用户相关接口

#### `src/assets/`
**静态资源**，会被 webpack 处理。

| 子目录 | 作用 |
|--------|------|
| `style/unit/color.scss` | 全局颜色变量定义 |
| `style/public.scss` | 全局 SCSS 变量、mixin、placeholder（通过 `additionalData` 自动注入每个组件） |
| `style/public-class.scss` | 全局通用 CSS class（间距、浮动、文字对齐等工具类） |
| `style/fixed/` | 第三方库样式覆盖（element / markdown / n-progress / vue-splitpane 等） |
| `style/animate/` | 过渡动画样式（vue-transition） |
| `style/theme/` | 主题切换样式，每个主题独立目录，含 `index.scss` + `setting.scss` |
| `svg-icons/icons/` | SVG 图标文件，通过 `svg-sprite-loader` 生成雪碧图 |
| `svg-icons/index.js` | SVG 图标自动注册脚本 |

#### `src/components/`
**公共组件库**，所有可复用组件集中管理。

| 组件 | 作用 |
|------|------|
| `d2-container` | 页面容器组件，提供卡片、全屏、透明等多种布局变体 |
| `d2-container-frame` | iframe 嵌套外部页面容器 |
| `d2-count-up` | 数字滚动动画组件 |
| `d2-highlight` | 代码高亮展示组件 |
| `d2-icon` / `d2-icon-svg` | 图标组件（Font Awesome / SVG） |
| `d2-icon-select` / `d2-icon-svg-select` | 图标选择器组件 |
| `d2-link-btn` | 链接式按钮 |
| `d2-markdown` | Markdown 渲染组件 |
| `d2-module-index-banner` | 首页 Banner 展示组件 |
| `d2-module-index-menu` | 首页菜单组件 |
| `d2-quill` | Quill 富文本编辑器封装 |
| `d2-scrollbar` | 自定义滚动条组件 |
| `d2-ueditor` | 百度 UEditor 编辑器封装 |
| `page-table` | **新** CRUD 表格便捷组合体（按钮栏 + 表格 + 分页 + 高度自适应 + 帮助按钮） |
| `page-dialog-form` | **新** 增删改查弹框组件（表单渲染 + 校验 + i18n） |

> `page-table` 和 `page-dialog-form` 的详细用法见：[表格组件使用说明](./docs/表格组件使用说明.md)

#### `src/composables/`
**可复用的逻辑函数（Composition Utilities）**。把散落在各页面中的重复 JS 逻辑抽成纯函数，组件只需调用即可。

| 文件 | 作用 |
|------|------|
| `useTableColumns.js` | 列定义工厂，消除手动分配 `idx` 序号；约定 `prop: '_actions'` 为操作列 |
| `useTableButtons.js` | 按钮定义工厂，一键生成顶部工具栏 + 行内操作按钮，自动注入权限过滤 |
| `useI18n.js` | i18n Mixin 工厂，通过 `i18nMixin(prefix)` 注入 `key()` / `ckey()` 方法，消除每个页面手写 `T` 常量 |

> **为什么放在 `src/` 根目录？**  
> composable 不是 UI 组件（不需要 `<template>`），也不属于 `libs/`（通用工具库）。它是介于**组件和逻辑之间**的中间层——被多个组件调用，但本身不渲染 DOM。放在 `src/` 根目录下与 `components/`、`views/` 同级，方便一眼看到项目的公共逻辑层。

#### `src/layout/`
**页面布局**。当前使用 `header-aside` 布局（顶栏 + 侧边栏 + 主内容区）。

| 子目录 | 作用 |
|--------|------|
| `layout.vue` | 布局主文件 |
| `components/menu-side/` | 侧边菜单组件 |
| `components/menu-header/` | 顶部导航菜单组件 |
| `components/header-user/` | 顶栏用户信息下拉 |
| `components/header-theme/` | 主题切换面板 |
| `components/header-color/` | 主题色切换 |
| `components/header-locales/` | 多语言切换 |
| `components/header-fullscreen/` | 全屏切换 |
| `components/header-search/` | 全局搜索 |
| `components/header-log/` | 操作日志 |
| `components/header-size/` | 字号大小切换 |
| `components/tabs/` | 多标签页栏 |
| `components/contextmenu/` | 标签页右键菜单 |
| `components/panel-search/` | 全局搜索面板 |
| `mixins/search.js` | 搜索 mixin |
| `mixins/` | 菜单相关 mixin |

#### `src/libs/`
**工具函数库**。
- `util.js` — 通用工具方法
- `util.cookies.js` — Cookie 操作
- `util.db.js` — 本地存储（基于 lowdb）
- `util.log.js` — 日志工具
- `util.import.development.js` / `util.import.production.js` — 开发/生产环境动态加载

#### `src/locales/`
**国际化（i18n）**。JSON 格式的语言文件，支持：
- `zh-chs` — 简体中文
- `zh-cht` — 繁体中文
- `en` — 英文
- `ja` — 日文
- `mixin.js` — Vue 国际化 mixin

#### `src/menu/`
**菜单配置**。按业务模块拆分，定义侧边栏菜单结构。`modules/` 下按 demo-components、demo-playground、demo-plugins 组织。

#### `src/plugin/`
**Vue 插件**。
- `d2admin/` — D2Admin 核心插件（初始化全局功能）
- `error/` — 全局错误捕获
- `log/` — 通用日志输出
- `open/` — 新窗口打开工具

#### `src/router/`
**路由配置**。`modules/` 下按 components、playground、plugins 拆分路由表。`routes.js` 为汇总路由，`index.js` 创建 Vue Router 实例。

#### `src/store/`
**Vuex 状态管理**。`modules/d2admin/` 下按功能拆分为独立模块：

| 模块 | 作用 |
|------|------|
| `account` | 用户账户信息 |
| `color` | 主题色管理 |
| `db` | 本地数据库状态 |
| `fullscreen` | 全屏状态 |
| `gray` | 灰度模式 |
| `log` | 操作日志 |
| `menu` | 菜单状态（展开/收缩/激活项） |
| `page` | 页面缓存与标签页 |
| `releases` | 版本信息 |
| `search` | 全局搜索 |
| `size` | 字号大小 |
| `theme` | 主题切换 |
| `transition` | 页面过渡动画 |
| `ua` | 用户代理信息 |
| `user` | 用户登录态 |

#### `src/views/`
**页面视图**。
- `demo/` — 各功能展示页面（组件演示 / 插件演示 / 功能试验场）
- `system/` — 系统级页面（首页 / 登录 / 404 / 日志 / 重定向 / 刷新）
- `production-master-data/` — 生产配置模块（工厂区域 / 产线 / 工艺 / 产品 / 物料等）

> 页面按一级模块 → 二级模块 → 三级模块 三层目录组织，与 [后台Webman界面截图对照表](./后台Webman界面截图对照表.md) 中的英文命名一致。

#### `src/` 根文件

| 文件 | 作用 |
|------|------|
| `main.js` | PC 端应用入口 |
| `App.vue` | 根组件 |
| `setting.js` | 全局设置（站点标题等） |
| `i18n.js` | 国际化初始化 |

---

### `src.mobile/` — 移动端源码

基于 Vant UI 的移动端适配版本，与 PC 端共用部分业务逻辑。

| 文件/目录 | 作用 |
|-----------|------|
| `main.js` | 移动端应用入口 |
| `App.vue` | 移动端根组件 |
| `vant.js` | Vant UI 按需引入配置 |
| `router/` | 移动端路由 |
| `store/` | 移动端状态管理 |
| `views/` | 移动端页面 |

---

### 构建配置文件

| 文件 | 作用 |
|------|------|
| `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.preview` | 预发布环境变量 |

---

## 常用命令

| 命令 | 说明 |
|------|------|
| `pnpm serve` | 启动开发服务器 |
| `pnpm build` | 生产环境构建 |
| `pnpm build:preview` | 预发布环境构建 |
| `pnpm lint` | ESLint 检查并自动修复 |
| `pnpm test:unit` | 运行单元测试 |