# 兴光微服务平台 (xg_total_process_master_cloud_vue) - 项目架构百科
> **项目名称**: jeeplus-ui v1.6.3 (兴光微服务平台)
> **定位**: 企业级 Vue3 前端管理系统，基于 Jeeplus 快速开发平台
> **核心能力**: 工作流引擎 (Flowable)、动态表单、数据可视化、多租户、多微服务集成
---
## 一、项目概览
### 1.1 基本信息
| 属性 | 值 |
|------|-----|
| 项目标识 | `jeeplus-ui` v1.6.3 |
| 系统名称 | 兴光微服务平台 |
| 运行入口 | `index.html` (主系统) / `datav.html` (数据大屏) |
| 开发端口 | 2800 |
| 浏览器兼容 | `> 1%`, `last 2 versions`, `not dead` |
### 1.2 业务领域
本项目服务于 **江苏兴光** 集团，涵盖以下业务板块：
| 业务 | 说明 |
|------|------|
| 会计师事务所 (cw) | 审计、财务管理 |
| 资产评估 (pg) | 资产估价 |
| 中审众环 (zs) | 审计业务 |
| 项目管理 (xm) | 工程项目管理 |
| 培训咨询 (zx) | 咨询服务 |
### 1.3 核心依赖一览
```
Vue 3.2.45 # 前端框架
Vue Router 4.1.5 # 路由管理
Vuex 4.0.2 # 状态管理
Element Plus 2.2.22 # UI 组件库
Vite 3.x # 构建工具
Axios 0.26.1 # HTTP 客户端
ECharts 5.3.3 # 图表可视化
AntV/G2 4.1.1 # 数据可视化
VXE-Table 4.3.5 # 高级表格
DataV 2.10.0 # 数据大屏
Monaco Editor 0.34.1 # 代码编辑器
TinyMCE 5.10.2 # 富文本编辑器
WangEditor 5.1.23 # 轻量富文本
CropperJS 1.5.12 # 图片裁剪
Splitpanes 3.1 # 面板分割
```
---
## 二、技术栈全景图
```
┌─────────────────────────────────────────────────────────────┐
│ 浏览器 (Browser) │
├─────────────────────────────────────────────────────────────┤
│ 入口HTML: index.html (主系统) │ datav.html (数据大屏) │
├─────────────────────────────────────────────────────────────┤
│ Vue 3.x (Composition API) │
├─────────────────────────────────────────────────────────────┤
│ Vue Router 4.x (Hash模式) │ Vuex 4.x │ Vue I18n 9.x │
├─────────────────────────────────────────────────────────────┤
│ Element Plus 2.x │ VXE-Table │ ECharts │ AVue │ ... │
├─────────────────────────────────────────────────────────────┤
│ Jeeplus 三件套: Devtools │ Flowable │ Form-Making │
├─────────────────────────────────────────────────────────────┤
│ Axios (HTTP Layer) │
├─────────────────────────────────────────────────────────────┤
│ Vite 3.x (Build & Dev Server) │
│ Proxy: /api → backend /file-server → backend │
├─────────────────────────────────────────────────────────────┤
│ 后端微服务集群 │
│ auth │ system │ flowable │ file │ finance │ human │ ... │
└─────────────────────────────────────────────────────────────┘
```
---
## 三、项目目录结构
```
xg_total_process_master_cloud_vue/
├── index.html # 主系统入口 HTML
├── datav.html # 数据大屏专用入口 HTML
├── vite.config.js # Vite 构建 & 代理配置
├── package.json # 依赖管理
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── babel.config.js # Babel 配置
├── .eslintrc.js # ESLint 配置
│
├── public/ # 静态资源 (不经过编译)
│ ├── datav/ # 数据大屏静态资源
│ │ ├── cdn/ # CDN 脚本 (echarts, html2canvas)
│ │ ├── css/ # 大屏样式
│ │ ├── img/ # 大屏图片
│ │ ├── components.js # 大屏全局组件注册
│ │ └── config.js # 大屏全局配置
│ ├── img/ # 通用图片资源
│ ├── locales/ # 静态国际化文件 (ru.js, zh.js)
│ └── favicon.ico
│
├── src/
│ ├── main.js # 【主系统入口】Vue 应用初始化
│ ├── App.vue # 【根组件】主题/语言/路由刷新
│ ├── components.js # 【全局注册】组件/指令/图标注册
│ │
│ ├── api/ # ★ API 接口层 (按微服务分包)
│ │ ├── AppPath.js # ★ 微服务路由前缀定义 (14个微服务)
│ │ ├── index.js # 自动聚合全部 API 模块
│ │ ├── auth/ # 认证服务 (loginService)
│ │ ├── sys/ # 系统管理 (28个服务文件)
│ │ ├── flowable/ # 工作流 (17个服务文件)
│ │ ├── cw/ # 财务业务 (12个目录)
│ │ ├── human/ # 人力资源 (3个目录)
│ │ ├── finance/ # 发票服务
│ │ ├── psi/ # 进销存 (13个文件)
│ │ ├── program/ # 项目管理 (5个文件)
│ │ ├── ccpm/ # 项目公司报销
│ │ ├── consultancy/ # 咨询公司报销
│ │ ├── devtools/ # 开发工具
│ │ ├── database/ # 数据库相关
│ │ ├── datav/ # 大屏数据
│ │ ├── mail/ # 邮件服务
│ │ ├── materialManagement/ # 物资管理
│ │ ├── monitor/ # 监控服务
│ │ ├── reports/ # 报表服务
│ │ ├── tools/ # 工具服务
│ │ ├── wps/ # WPS 集成
│ │ └── ...
│ │
│ ├── router/ # ★ 路由系统
│ │ ├── index.js # 【核心】路由实例 + 动态路由加载 + 导航守卫
│ │ ├── systemRouter.js # 静态基础路由 (layout, login, 内嵌页面)
│ │ └── scrollBehavior.js # 滚动行为记忆
│ │
│ ├── store/ # ★ 状态管理 (Vuex)
│ │ ├── index.js # 自动聚合 modules
│ │ ├── getters.js # 全局 getters (isPrimaryTenant)
│ │ └── modules/
│ │ ├── global.js # 全局状态 (布局/语言/租户/主题)
│ │ ├── user.js # 用户信息
│ │ ├── viewTags.js # 多标签页状态
│ │ ├── iframe.js # iframe 内嵌页管理
│ │ └── keepAlive.js # 组件缓存控制
│ │
│ ├── layout/ # ★ 布局系统 (4种布局)
│ │ ├── index.vue # 【核心】布局入口 (default/left/top/mix)
│ │ ├── components/
│ │ │ ├── userbar.vue # 用户工具栏 (头像/待办/消息/设置)
│ │ │ ├── tags.vue # 多标签页组件
│ │ │ ├── topbar.vue # 顶部导航栏 (default 布局)
│ │ │ ├── topbar2.vue # 面包屑导航 (left/top 布局)
│ │ │ ├── setting.vue # 系统设置抽屉
│ │ │ ├── search.vue # 全局搜索
│ │ │ ├── NavMenu.vue # 侧边菜单 (递归)
│ │ │ ├── NavMenu2.vue # 顶部菜单 (递归)
│ │ │ ├── sideM.vue # 移动端侧边栏
│ │ │ └── iframeView.vue # iframe 内嵌视图
│ │ └── other/
│ │ ├── 404.vue # 404 页面
│ │ └── empty.vue # 空组件 (用于 iframe 嵌入)
│ │
│ ├── views/ # ★ 业务视图层
│ │ ├── sys/ # 系统管理 (17个子模块)
│ │ ├── flowable/ # 工作流相关 (5个子模块)
│ │ ├── cw/ # 财务业务 (12个子模块)
│ │ ├── datav/ # 数据大屏页面
│ │ ├── gen/ # 代码生成
│ │ ├── form/ # 表单设计
│ │ ├── echarts/ # 图表管理
│ │ ├── dd/ # 钉钉集成
│ │ ├── program/ # 项目
│ │ ├── psiManagement/ # 进销存管理
│ │ ├── materialManagement/ # 物资管理
│ │ ├── common/ # 通用功能
│ │ └── ...
│ │
│ ├── datav/ # ★ 数据大屏独立入口
│ │ ├── main.js # 大屏 Vue 应用初始化
│ │ ├── App.vue # 大屏根组件
│ │ ├── axios.js # 大屏独立 HTTP 客户端
│ │ ├── router.js # 大屏路由
│ │ ├── config.js # 大屏配置
│ │ ├── components/ # 大屏组件
│ │ ├── echart/ # 大屏图表
│ │ ├── page/ # 大屏页面
│ │ ├── option/ # 图表配置
│ │ ├── styles/ # 大屏样式
│ │ └── utils/ # 大屏工具
│ │
│ ├── components/ # ★ 可复用业务组件
│ │ ├── upload/ # 上传组件 (图片/文件)
│ │ ├── editor/ # 富文本编辑器封装
│ │ ├── userSelect/ # 用户选择器 (多个变体)
│ │ ├── officeSelect/ # 部门选择器
│ │ ├── roleSelect/ # 角色选择器
│ │ ├── treeSelect/ # 树形选择器
│ │ ├── gridSelect/ # 表格选择器
│ │ ├── areaSelect/ # 区域选择器
│ │ ├── cropper/ # 图片裁剪
│ │ ├── iconSelect/ # 图标选择器
│ │ ├── statistic/ # 统计组件
│ │ └── vueEcharts/ # ECharts 封装
│ │
│ ├── utils/ # ★ 工具函数库
│ │ ├── index.js # 核心工具集 (hasPermission, treeDataTranslate, deepClone 等)
│ │ ├── tool.js # 基础工具 (localStorage, 日期, 加解密)
│ │ ├── httpRequest.js # ★ Axios 封装 (拦截器/错误处理)
│ │ ├── dictUtils.js # 字典工具 (数据字典读取/刷新)
│ │ ├── validate.js # 基础验证函数库 (48个校验方法)
│ │ ├── validator.js # Element Plus 表单验证器 (适配 validate)
│ │ ├── validateXG.js # 兴光专用校验库
│ │ ├── validatorXG.js # 兴光专用验证器
│ │ ├── common.js # 通用业务工具 (GPS转换/深拷贝/格式化)
│ │ ├── businessInfo.js # 业务主体信息 (公司名/税号)
│ │ ├── errorHandler.js # 全局代码错误捕获
│ │ ├── filter.js # 过滤器
│ │ ├── color.js # 主题颜色工具
│ │ ├── print.js # 打印工具
│ │ ├── useTabs.js # 标签页 Hooks
│ │ └── icons.js # 图标工具
│ │
│ ├── directives/ # 自定义指令
│ │ ├── copy.js # v-copy 一键复制
│ │ ├── time.js # v-time 时间格式化
│ │ └── noMoreClick.js # v-noMoreClick 防重复点击
│ │
│ ├── i18n/ # 国际化
│ │ └── index.js # 中/英/日三语支持
│ │
│ ├── config/ # 全局配置
│ │ └── index.js # 默认系统配置 (APP名称/Token/布局/主题)
│ │
│ ├── style/ # 全局样式
│ │ ├── theme/ # 暗色/亮色主题
│ │ ├── app.scss / fix.scss / media.scss / pages.scss
│ │ └── vxtable.scss
│ │
│ └── assets/ # 编译态资源
│ ├── icons/ # SVG 图标集 (550+个)
│ ├── fonts/ # 字体文件
│ ├── img/ # 图片资源
│ └── avue/ # AVue 资源
```
---
## 四、路由配置体系
### 4.1 路由模式
- **模式**: `createWebHashHistory()` —— Hash 模式 (`/#/path`)
- **目录自动发现**: `import.meta.glob("./../views/**/*.vue")` 扫描全部视图文件
### 4.2 静态路由 (`systemRouter.js`)
```javascript
// 预定义的固定路由，不依赖后端菜单数据
routes = [
{
name: "layout",
path: "/",
component: layout/index.vue, // 布局容器
redirect: DASHBOARD_URL, // 默认跳转仪表盘
children: [
// 工作流内嵌表单 (TaskForm / TaskFormEdit / TaskFormDetail)
// 动态表单展示 (GenerateList / GenerateChart / Preview)
// UReport 报表 (iframe 嵌入)
// 通用 iframe 嵌入
]
},
{ path: "/login", component: login.vue }, // 登录页
{ path: "/ddLogin", component: ddLogin.vue }, // 钉钉免登录
]
```
### 4.3 动态路由加载流程
```
用户登录成功
│
▼
后端返回 MENU 数据 → 存入 localStorage("MENU")
│
▼
router.beforeEach 守卫
│
├─ 无 token → 重定向 /login
├─ 有 token & 路由未加载 → filterAsyncRouter(MENU) 转换菜单为路由
│ │
│ ├─ iframe 外部链接 → /i/{id} 路径 + empty 组件
│ ├─ 普通页面 → views/ 目录自动匹配 .vue 文件
│ └─ 空路径 → empty 组件
│ │
│ ▼
│ flatAsyncRoutes() 扁平化并生成面包屑 breadcrumb
│ │
│ ▼
│ router.addRoute("layout", route) 注册到 layout 子路由
│
▼
isGetRouter = true (路由已加载，后续不再重复)
```
### 4.4 导航守卫关键逻辑
| 场景 | 行为 |
|------|------|
| 访问 `/login` 或 `/ddlogin` | 重置路由，清除动态路由 |
| 无 Token | 重定向到 `/login` |
| `fullpage: true` 路由 | 保留最后一级 matched (整页模式) |
| 路由未加载 | 从 localStorage 读 MENU，动态注册路由 |
| 路由不匹配 (matched.length==0) | 重新导航到完整路径 |
### 4.5 路由扁平化与面包屑
```javascript
// flatAsyncRoutes 将嵌套路由树展平，并为每个路由生成 breadcrumb 数组
// 例如: /sys/user/list 的面包屑:
// [系统管理] → [用户管理] → [用户列表]
```
---
## 五、状态管理体系 (Vuex)
### 5.1 模块架构
```
store
├── global # ★ 全局配置状态
│ ├── backlogCount # 待办数量
│ ├── ismobile # 是否移动端
│ ├── layout # 布局类型 (default/left/top/mix/dock)
│ ├── menuIsCollapse # 菜单折叠状态
│ ├── layoutTags # 是否显示多标签
│ ├── toolbarTags # 是否显示面包屑
│ ├── tenantList # 租户列表
│ ├── language # 当前语言 (zh/en/ja)
│ ├── appName # 应用名称
│ └── languageMap # 语言映射表
│
├── user # ★ 用户信息
│ ├── id / name / loginName / no / photo
│ ├── office # 所属部门
│ ├── company # 所属公司
│ └── timer1/2/3 # 定时器引用
│
├── viewTags # 多标签页
│ └── viewTags[] # 已打开的标签数组
│
├── iframe # iframe 内嵌页
│ └── iframeList[] # iframe 页面栈
│
└── keepAlive # 组件缓存
├── keepLiveRoute[] # 需要缓存的组件列表
├── routeKey # 当前路由 key
└── routeShow # 路由显示状态
```
### 5.2 数据持久化策略
- **localStorage** (通过 `tool.data`):
- `TOKEN` - 认证令牌
- `MENU` - 用户菜单权限
- `PERMISSIONS` - 按钮级权限列表
- `USER_INFO` - 用户信息
- `DICT_LIST` - 数据字典缓存
- `APP_LAYOUT` / `APP_LANG` / `APP_COLOR` / `APP_NAME` / `APP_THEME` - 用户偏好
- `TENANT_LIST` - 租户列表
- **sessionStorage** (通过 `tool.session`): 会话级别临时数据
- **Cookie**: Token 备份 (`VueCookies`)
---
## 六、API 请求封装与微服务交互规范
### 6.1 HTTP 客户端架构
```
httpRequest.js (axios 实例)
│
├─ 请求拦截器 (request)
│ ├─ 可选的 Loading 遮罩 (config.loading = true)
│ ├─ 自动注入 Token: headers.token
│ ├─ 自动注入域名: headers.domain
│ ├─ URL 前缀处理: /api + config.url
│ ├─ POST: qs.stringify 参数序列化
│ └─ GET: paramsSerializer 参数序列化
│
└─ 响应拦截器 (response)
├─ 成功: 关闭 Loading，返回 response.data
└─ 错误状态码处理:
├─ 408: 无权限 → 弹窗确认重新登录
├─ 401: Token 过期 → 清除登录信息 → 跳转登录
├─ 404: 路径找不到 → ElNotification 提示
├─ 503: 服务不可用 → ElNotification 提示
├─ 504: 网络连接错误 → ElNotification 提示
├─ 400: 请求失败 → ElNotification 提示
└─ 其他: 系统错误 → ElNotification 提示
```
### 6.2 微服务路径定义 (`AppPath.js`)
```javascript
// 14 个微服务路由前缀
export const AUTH_PATH = "/auth-server" // 认证服务
export const SYS_PATH = "/system-server" // 系统管理
export const FLOW_PATH = "/flowable-server" // 工作流引擎
export const DEVTOOLS_PATH = "/devtools-server" // 开发工具
export const FILE_PATH = "/file-server" // 文件服务
export const UREPORT_PATH = "/ureport-server" // 报表服务
export const WPS_PATH = "/wps-server" // WPS 集成
export const TEST_PATH = "/test-server" // 测试服务
export const ASSESS_PATH = "/assess-server" // 评估服务
export const FINANCE_PATH = "/finance-server" // 财务服务
export const PUBLIC_MODULES_PATH = "/public-modules-server" // 公共模块
export const CENTRECAREFUL_PATH = "/centrecareful-server" // 中审服务
export const REGISTER_PATH = "/human-server" // 人力资源
export const CCPM_PATH = "/ccpm-server" // 项目公司
export const CONSULTANCY_PATH = "/consultancy-server" // 咨询公司
export const PSI_MANAGEMANT = "/psi-management-server" // 进销存系统
```
### 6.3 API 服务文件编写规范
每个 API 服务文件遵循统一模式：
```javascript
// 以 loginService.js 为例
import request from "@/utils/httpRequest";
import { AUTH_PATH as prefix } from "../AppPath";
export default {
// GET 请求 (查询)
getCode: function () {
return request({
url: prefix + "/user/getCode",
method: "get",
});
},
// POST 请求 (提交)
login: function (data) {
return request({
url: prefix + "/user/login",
method: "post",
data: data,
});
},
// GET 请求 (带参数)
queryById: function (id) {
return request({
url: prefix + "/user/queryById",
method: "get",
params: { id: id },
});
},
// DELETE 请求
delete: function (ids) {
return request({
url: prefix + "/user/delete",
method: "delete",
params: { ids: ids },
});
},
// 文件下载 (blob)
exportExcel: function (params) {
return request({
url: prefix + "/user/export",
method: "get",
params: params,
responseType: "blob",
});
},
};
```
### 6.4 API 自动聚合机制
```javascript
// src/api/index.js
const files = import.meta.globEager("./model/*.js");
// 注意: 实际扫描的是 src/api/ 下的各个子目录中的 *.js 文件
// 导出聚合对象: { loginService, userService, menuService, taskService, ... }
```
### 6.5 Vite 代理配置
```
开发环境:
/api → http://localhost:8088 (后端网关)
/file-server → http://localhost:8088/file-server
生产环境:
/api → 同域后端 (Nginx 反向代理)
```
### 6.6 实际请求 URL 示例
| 前端调用 | 微服务 | 最终请求路径 |
|----------|--------|------------|
| `loginService.login()` | auth-server | `/api/auth-server/user/login` |
| `userService.list()` | system-server | `/api/system-server/sys/user/list` |
| `taskService.todoList()` | flowable-server | `/api/flowable-server/flowable/task/todo` |
| `menuService.treeData()` | system-server | `/api/system-server/sys/menu/treeData` |
---
## 七、权限控制体系
### 7.1 多层次权限架构
```
┌─────────────────────────────────────────────┐
│ 路由级权限 (路由守卫) │
│ 未登录 → 拦截到 /login │
│ 已登录 → 动态加载用户 MENU → 注册路由 │
├─────────────────────────────────────────────┤
│ 菜单级权限 (MENU 数据) │
│ 后端返回菜单树 → layout 渲染可见菜单 │
│ filterUrl() 过滤 isShow !== "1" 的菜单 │
├─────────────────────────────────────────────┤
│ 按钮级权限 (PERMISSIONS) │
│ v-if="hasPermission('sys:user:add')" │
│ hasPermission(permission) 函数检查 │
└─────────────────────────────────────────────┘
```
### 7.2 权限数据流
```
用户登录
│
▼
POST /auth-server/user/login
│
▼
后端返回: { token, user, permissions[], menus[] }
│
├─ token → localStorage("token")
├─ user → localStorage("USER_INFO")
├─ permissions[] → localStorage("PERMISSIONS") ← 按钮级权限
└─ menus[] → localStorage("MENU") ← 菜单+路由权限
```
### 7.3 按钮级权限实现
```javascript
// src/utils/index.js
export function hasPermission(permission) {
let permissions = tool.data.get("PERMISSIONS");
if (!permissions) return false;
return permissions.includes(permission);
}
// 全局注入
app.config.globalProperties.hasPermission = hasPermission;
// 模板中使用
新增
```
### 7.4 菜单权限过滤
```javascript
// layout/index.vue
filterUrl(map) {
var newMap = [];
map && map.forEach((item) => {
// 隐藏项 (isShow !== "1") 不渲染
if (item.meta.isShow !== "1") return false;
// iframe 链接重写路径
if (item.meta.target == "iframe") {
item.path = `/i/${item.meta.id}`;
}
// 递归过滤子菜单
if (item.children && item.children.length > 0) {
item.children = this.filterUrl(item.children);
}
newMap.push(item);
});
return newMap;
}
```
### 7.5 角色权限检查
```javascript
// userService 提供多种角色检查 API:
is() // 是否管理员 (isAdmin)
isKjsz() // 是否科技所长
isZj() // 是否总局
isSs() // 是否所长
isDgsbxBmzr() // 是否部门主任
isSzZyx() // 是否所长/专业线
isZjbry() // 是否总局办人员
isBggdgly() // 是否报告归档管理员
```
---
## 八、组件分层架构
### 8.1 组件分层图
```
┌──────────────────────────────────────────────────────┐
│ Page Views (业务页面) │
│ views/sys/*, views/flowable/*, views/cw/*, ... │
├──────────────────────────────────────────────────────┤
│ Layout Components (布局组件) │
│ layout/index.vue (4种布局) + 10个子组件 │
├──────────────────────────────────────────────────────┤
│ Business Components (业务组件) │
│ userSelect, officeSelect, roleSelect, treeSelect... │
├──────────────────────────────────────────────────────┤
│ Base Components (基础组件) │
│ upload/*, editor/*, cropper, vueDialog, vueEcharts │
├──────────────────────────────────────────────────────┤
│ UI Framework (Element Plus + AVue + VXE-Table) │
└──────────────────────────────────────────────────────┘
```
### 8.2 布局系统详解
| 布局 | 特征 | 适用场景 |
|------|------|---------|
| `default` | 左侧一二级菜单分离 + 顶部用户栏 + 标签页 | 标准后台 |
| `left` | 左侧单级完整菜单 + 顶部用户栏 + 标签页 | 简单导航 |
| `top` | 顶部水平菜单 + 标签页 | 宽屏展示 |
| `mix` | 顶部一级菜单 + 左侧二级菜单 (混合模式) | 复杂导航 |
| `dock` | 功能坞模式 (关闭标签和面包屑) | 沉浸式操作 |
### 8.3 关键布局组件
| 组件 | 职责 |
|------|------|
| [userbar.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\userbar.vue) | 用户头像/消息/待办/退出/设置入口 |
| [tags.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\tags.vue) | 多标签页管理 (打开/关闭/刷新/右键菜单) |
| [setting.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\setting.vue) | 系统设置抽屉 (布局/主题/语言/标签) |
| [NavMenu.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\NavMenu.vue) | 侧边菜单递归组件 |
| [NavMenu2.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\NavMenu2.vue) | 顶部菜单递归组件 |
| [iframeView.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\iframeView.vue) | iframe 页面管理 (加载/关闭/刷新) |
### 8.4 业务组件分类
| 组件类别 | 包含组件 | 说明 |
|----------|---------|------|
| 用户选择 | userSelect, userSelect2, userSelectAll, userSelectButton, userSelectV2, userSelectKjXmPg | 多场景用户选人 |
| 组织选择 | officeSelect, roleSelect, postSelect, areaSelect | 组织架构选择 |
| 数据选择 | treeSelect, gridSelect, iconSelect | 数据展示型选择 |
| 上传 | ImageSelect, ImageUpload, FileUpload | 文件/图片上传封装 |
| 编辑器 | editor/* (Monaco/TinyMCE/WangEditor) | 编辑器封装 |
| 弹窗 | vueDialog | 通用对话框 |
### 8.5 Keep-Alive 组件缓存策略
```javascript
// keepAlive.js store模块
keepLiveRoute: [], // 需要保持活性的路由组件名列表
// 配合 + 使用
// 关闭标签时从 keepLiveRoute 移除对应组件
```
---
## 九、后端微服务交互全景
### 9.1 微服务调用关系图
```
┌────────────────────────────────────────────────────────────┐
│ 前端 (Vue3 SPA) │
│ /api → 后端网关 │
└──────────────────────┬─────────────────────────────────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ auth-server │ │ system │ │ flowable │
│ 认证/登录 │ │ -server │ │ -server │
│ /auth-server│ │ 系统管理 │ │ 工作流引擎 │
└──────────────┘ └──────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ file-server │ │ human │ │ finance │
│ 文件管理 │ │ -server │ │ -server │
│ /file-server│ │ 人力资源 │ │ 财务/发票 │
└──────────────┘ └──────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ ccpm-server │ │consultancy│ │ psi │
│ 项目公司 │ │ -server │ │ management │
│ (报销) │ │ 咨询公司 │ │ -server │
└──────────────┘ └──────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ devtools │ │ wps │ │ public │
│ -server │ │ -server │ │ modules │
│ 开发工具 │ │ WPS集成 │ │ 公共模块 │
└──────────────┘ └──────────┘ └──────────────┘
```
### 9.2 微服务清单与职责
| 微服务 | 前缀路径 | 职责 | API 文件数 |
|--------|---------|------|-----------|
| **auth-server** | `/auth-server` | 登录认证、Token 管理、验证码、单点登录 | 1 (loginService) |
| **system-server** | `/system-server` | 用户/角色/菜单/部门/岗位/字典/日志/配置/租户 | 28 |
| **flowable-server** | `/flowable-server` | 工作流引擎 (模型/流程/任务/表单/监听器) | 17 |
| **file-server** | `/file-server` | 文件上传/下载/管理 | 通过 sys/fileService |
| **finance-server** | `/finance-server` | 发票管理、财务单据 | 2 (invoice) |
| **human-server** | `/human-server` | 人力资源 (花名册/薪酬/考勤) | 3 |
| **ccpm-server** | `/ccpm-server` | 项目公司报销管理 | 3 |
| **consultancy-server** | `/consultancy-server` | 咨询公司报销管理 | 3 |
| **centrecareful-server** | `/centrecareful-server` | 中审众环业务 | 3 |
| **psi-management-server** | `/psi-management-server` | 进销存系统 | 13 |
| **devtools-server** | `/devtools-server` | 代码生成、开发辅助 | 9 |
| **wps-server** | `/wps-server` | WPS 文档在线编辑 | 2 |
| **ureport-server** | `/ureport-server` | UReport 报表引擎 | iframe嵌入 |
| **test-server** | `/test-server` | 测试模块 | 12 |
| **mail-server** | `/mail-server` | 邮件收发 | 3 |
| **public-modules-server** | `/public-modules-server` | 公共业务模块 | 1 |
| **assess-server** | `/assess-server` | 资产评估 | 未直接使用 |
### 9.3 跨微服务调用示例
```javascript
// loginService.js - 一个服务内调用两个微服务
import { AUTH_PATH as prefix } from "../AppPath"; // auth-server
import { SYS_PATH as sysPrefix } from "../AppPath"; // system-server
export default {
login(data) {
return request({ url: prefix + "/user/login", ... }); // → auth-server
},
getPhoneCode(loginForm) {
return request({ url: sysPrefix + "/sys/user/getPhoneCode", ... }); // → system-server
},
};
```
---
## 十、登录认证流程
### 10.1 完整登录链路
```
用户进入系统
│
▼
router.beforeEach → 检查 token
│
├─ 无 token → /login 页面
│ │
│ ▼
│ 输入用户名/密码/验证码
│ │
│ ▼
│ loginService.login(data) → POST /auth-server/user/login
│ │
│ ▼
│ 后端返回: { token, user, permissions[], menus[] }
│ │
│ ▼
│ 存储到 localStorage: TOKEN, USER_INFO, PERMISSIONS, MENU
│ │
│ ▼
│ 跳转 DASHBOARD_URL (/dashboard/index)
│
└─ 有 token → 加载动态路由 → 进入主界面
```
### 10.2 登录方式
| 方式 | 接口 | 文件 |
|------|------|------|
| 用户名密码登录 | `/auth-server/user/login` | [loginService.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\api\auth\loginService.js) |
| 手机验证码登录 | `/system-server/sys/user/getPhoneCode` + `/system-server/sys/user/saveNewPassword` | 同上 |
| 钉钉免登录 | `/auth-server/user/sys/ddLogin` | 同上 + ddLogin.vue |
| CAS 单点登录 | `VITE_APP_CAS_SERVER` 配置 | 环境变量 |
### 10.3 退出登录
```
用户点击退出
│
▼
loginService.logout() → GET /auth-server/user/logout
│
▼
清除: localStorage, cookies, sessionStorage
│
▼
清除: Vuex 状态, 定时器, 动态路由
│
▼
router.push("/login")
```
---
## 十一、数据大屏 (DataV) 子系统
### 11.1 独立入口
- **HTML**: `datav.html`
- **主 JS**: `src/datav/main.js`
- **独立路由**: `src/datav/router.js`
- **独立 HTTP**: `src/datav/axios.js`
- **独立组件**: `src/datav/page/`, `src/datav/components/`
### 11.2 与主系统的区别
| 特性 | 主系统 | 数据大屏 |
|------|--------|---------|
| Vuex | 使用 | 不适用 (独立状态) |
| Element Plus | 完整使用 | 用于基础组件 |
| AVue | 不直接使用 | 核心框架 (avue-draggable) |
| DataV | 组件级使用 | 完整大屏展示 |
| ECharts | 组件级 | CDN 加载 (5.4.0) |
| 路由 | Hash 模式 | 独立的 Hash 路由 |
| 构建 | Vite 多入口 | 独立打包输出 |
---
## 十二、国际化 (i18n)
### 12.1 语言支持
| 语言 | 标识 | 使用场景 |
|------|------|---------|
| 简体中文 | `zh` | 默认语言 |
| English | `en` | 英文界面 |
| 日本語 | `ja` | 日文界面 |
### 12.2 实现机制
- **框架**: `vue-i18n` 9.x
- **语言包**: 静态语言 (VXE-Table 内置) + 动态语言映射 (从后端 `languageService.getLanguageMap()` 获取)
- **存储**: `localStorage("APP_LANG")`
- **切换**: `$store.commit("updateLanguage", lang)` → 全局响应式更新
- **翻译函数**: `$t2(code)` — 从 `languageMap` 中按 `{code}_{language}` 键查找
---
## 十三、主题系统
### 13.1 主题配置
| 配置项 | 存储 Key | 说明 |
|--------|---------|------|
| 主题颜色 | `APP_COLOR` | 主色调 (默认 `#2d8cf0`) |
| 暗色/亮色 | `APP_THEME` | `dark` / `white` |
| 布局类型 | `APP_LAYOUT` | `default` / `left` / `top` / `mix` |
### 13.2 主题切换流程
```javascript
// App.vue created()
const app_color = this.$TOOL.data.get("APP_COLOR") || this.$CONFIG.COLOR;
colorTool.setAppColors(app_color); // 动态设置 CSS 变量
// HTML body 属性
document.body.setAttribute('data-theme', theme); // dark/white
document.body.setAttribute('data-layout', layout); // default/left/top/mix
```
---
## 十四、构建与部署
### 14.1 构建配置
```javascript
// vite.config.js
{
base: './', // 相对路径 (方便部署到任意子目录)
resolve: {
alias: {
'~': './', // 根路径别名
'@': './src' // src 别名
}
},
build: {
rollupOptions: {
input: { // 多入口构建
index: 'index.html', // 主系统
datav: 'datav.html' // 数据大屏
}
}
},
server: {
port: 2800,
proxy: {
'/api': { target: VITE_APP_BASE, ... },
'/file-server': { target: VITE_APP_BASE, ... }
}
}
}
```
### 14.2 环境变量
| 变量 | 开发环境 | 生产环境 | 说明 |
|------|---------|---------|------|
| `VITE_APP_ENV` | `development` | `production` | 环境标识 |
| `VITE_APP_API` | `/api` | `` | API 前缀 |
| `VITE_APP_BASE` | `http://localhost:8088` | `/api` | 后端地址 |
| `VITE_APP_SSO_LOGIN` | `false` | `false` | 单点登录开关 |
| `VITE_APP_CAS_SERVER` | CAS 地址 | CAS 地址 | CAS 服务地址 |
### 14.3 可用命令
```bash
npm run dev # 开发模式 (端口 2800)
npm run build # 生产构建 (最大 8GB 内存)
npm run preview # 预览构建结果
```
---
## 十五、数据字典机制
### 15.1 字典缓存策略
```javascript
// 应用启动时或手动调用 refreshDictList()
dictService.getDictMap() // GET /system-server/sys/dict/getDictMap
│
▼
tool.data.set("DICT_LIST", data) // 存入 localStorage
// 使用时:
getDictLabel(type, value) // 根据字典类型+值 → 获取中文标签
getDictValue(type, label) // 根据字典类型+标签 → 获取值
getDictList(type) // 获取指定类型的全部字典项
```
### 15.2 字典使用场景
```vue
{{ $dictUtils.getDictLabel('sys_status', row.status) }}
```
---
## 十六、关键工具函数索引
| 函数 | 文件 | 说明 |
|------|------|------|
| `hasPermission(perm)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 按钮级权限判断 |
| `treeDataTranslate(data)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 扁平数据 → 树形结构 |
| `recover(target, source)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 表单对象属性覆盖赋值 |
| `recoverNotNull(target, source)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 非空属性覆盖 |
| `deepClone(data)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 对象深拷贝 |
| `validatenull(val)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 空值判断 (含数组/对象) |
| `downloadExcel(data, name)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | Blob 文件下载 |
| `t2(code)` | [utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 动态国际化翻译 |
| `tool.data.get/set/remove` | [utils/tool.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\tool.js) | localStorage 读写 (JSON 序列化) |
| `tool.crypto.MD5/AES/BASE64` | [utils/tool.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\tool.js) | 加解密 (CryptoJS) |
| `tool.dateFormat(date)` | [utils/tool.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\tool.js) | 日期格式化 |
| `getDictLabel(type, val)` | [utils/dictUtils.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\dictUtils.js) | 字典值转标签 |
---
## 十七、自定义指令
| 指令 | 文件 | 功能 |
|------|------|------|
| `v-copy` | [directives/copy.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\directives\copy.js) | 一键复制文本到剪贴板 |
| `v-time` | [directives/time.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\directives\time.js) | 时间格式化显示 |
| `v-noMoreClick` | [directives/noMoreClick.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\directives\noMoreClick.js) | 防重复点击 (2秒禁用) |
---
## 十八、配置文件参考
### 18.1 默认系统配置 (`config/index.js`)
```javascript
{
APP_NAME: "兴光微服务平台",
DASHBOARD_URL: "/dashboard/index",
API_URL: "/api",
TIMEOUT: 10000,
TOKEN: "token",
LAYOUT: "default", // default | header | menu | dock
THEME: "dark",
COLOR: "#2d8cf0",
MENU_IS_COLLAPSE: false,
MENU_UNIQUE_OPENED: true, // 手风琴菜单
LAYOUT_TAGS: true, // 多标签
TOOLBAR_TAGS: true, // 面包屑
LANG: "zh-cn",
}
```
### 18.2 全局组件注册 (`components.js`)
| 注册方式 | 名称 | 类型 |
|----------|------|------|
| `app.component` | QuillEditor | 富文本编辑器 |
| `app.component` | ImageSelect | 图片选择 |
| `app.component` | ImageUpload | 图片上传 |
| `app.component` | FileUpload | 文件上传 |
| `app.component` | v-dialog | 通用对话框 |
| `app.component` | v-chart | ECharts 图表 |
| `app.component` | ElIcon* (全部) | Element Plus 图标 |
| `app.component` | svg-* (550+) | 自定义 SVG 图标 |
| `app.directive` | time | 时间指令 |
| `app.directive` | copy | 复制指令 |
| `app.directive` | noMoreClick | 防重复点击指令 |
| `app.config.globalProperties` | $CONFIG | 系统配置 |
| `app.config.globalProperties` | $TOOL | 工具对象 |
| `app.config.globalProperties` | $http | HTTP 客户端 |
| `app.config.globalProperties` | $utils | 工具函数集 |
| `app.config.globalProperties` | $dictUtils | 字典工具 |
| `app.config.globalProperties` | hasPermission | 权限判断 |
| `app.config.globalProperties` | validator / validate | 表单校验器 |
| `app.config.globalProperties` | validatorXG / validateXG | 兴光专用校验器 |
| `app.config.globalProperties` | $cookies | Cookie 操作 |
---
## 十九、项目技术债务与注意事项
### 19.1 已知问题
1. **双重入口**: 主系统和数据大屏各自独立的项目结构，维护成本较高
2. **localStorage 依赖**: 大量核心数据（菜单、权限、用户信息）都存储在 localStorage，存在 XSS 风险
3. **API 索引未实际使用**: `src/api/index.js` 扫描路径写的是 `./model/*.js`，但实际项目 API 文件在子目录下直接使用
4. **jQuery 依赖**: `package.json` 中包含 jQuery，但 Vue3 项目中基本不应使用
5. **已注释的功能**: Dify 聊天机器人、全局错误捕获等被注释掉
### 19.2 改进建议
1. 考虑将数据大屏合并到主系统作为子路由
2. 敏感数据（Token）建议使用 httpOnly Cookie 替代 localStorage
3. 建议统一 API 模块的导入方式
4. 清理未使用的依赖（jQuery, mockjs 等）
---
## 二十、文件快速索引
| 关键文件 | 路径 | 说明 |
|----------|------|------|
| 应用入口 | [src/main.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\main.js) | Vue 应用初始化，全局注册 |
| 根组件 | [src/App.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\App.vue) | 主题/语言/路由刷新控制 |
| 全局注册 | [src/components.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\components.js) | 组件/指令/图标全局注册 |
| 路由核心 | [src/router/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\router\index.js) | Hash路由 + 动态加载 + 守卫 |
| 静态路由 | [src/router/systemRouter.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\router\systemRouter.js) | 基础路由定义 |
| 布局入口 | [src/layout/index.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\index.vue) | 4种布局系统 |
| HTTP 封装 | [src/utils/httpRequest.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\httpRequest.js) | Axios 拦截器/错误处理 |
| 微服务路径 | [src/api/AppPath.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\api\AppPath.js) | 14个微服务前缀定义 |
| 工具集 | [src/utils/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\index.js) | 核心工具函数 |
| 基础工具 | [src/utils/tool.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\tool.js) | localStorage/加解密/日期 |
| 字典工具 | [src/utils/dictUtils.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\dictUtils.js) | 数据字典操作 |
| 表单校验 | [src/utils/validate.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\utils\validate.js) | 48个基础校验方法 |
| 系统配置 | [src/config/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\config\index.js) | 默认系统参数 |
| 构建配置 | [vite.config.js](file://D:\java_project\xg_total_process_master_cloud_vue\vite.config.js) | Vite + 代理 + 多入口 |
| 环境变量 | [.env.development](file://D:\java_project\xg_total_process_master_cloud_vue\.env.development) | 开发环境变量 |
| 大屏入口 | [src/datav/main.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\datav\main.js) | 数据大屏独立应用 |
| 登录 API | [src/api/auth/loginService.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\api\auth\loginService.js) | 认证接口 |
| 用户 API | [src/api/sys/userService.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\api\sys\userService.js) | 用户管理接口 (284行) |
| 工作流API | [src/api/flowable/taskService.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\api\flowable\taskService.js) | 工作流任务接口 |
| 国际化 | [src/i18n/index.js](file://D:\java_project\xg_total_process_master_cloud_vue\src\i18n\index.js) | 中/英/日三语 |
| 用户工具栏 | [src/layout/components/userbar.vue](file://D:\java_project\xg_total_process_master_cloud_vue\src\layout\components\userbar.vue) | 用户菜单/待办/消息 |
---
> **生成时间**: 2026-06-01
> **分析方式**: 完整源码索引 + 架构推理
> **覆盖范围**: 全部核心模块 (路由/状态/API/权限/布局/组件/工具/国际化/构建)