兴光微服务平台 (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`)

// 预定义的固定路由，不依赖后端菜单数据
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 路由扁平化与面包屑

// 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`)

// 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 服务文件遵循统一模式：

// 以 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 自动聚合机制

// 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 按钮级权限实现

// 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;

// 模板中使用
<el-button v-if="hasPermission('sys:user:add')">新增</el-button>

7.4 菜单权限过滤

// 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 角色权限检查

// 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	用户头像/消息/待办/退出/设置入口
tags.vue	多标签页管理 (打开/关闭/刷新/右键菜单)
setting.vue	系统设置抽屉 (布局/主题/语言/标签)
NavMenu.vue	侧边菜单递归组件
NavMenu2.vue	顶部菜单递归组件
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 组件缓存策略

// keepAlive.js store模块
keepLiveRoute: [],  // 需要保持活性的路由组件名列表
// 配合 <router-view> + <keep-alive> 使用
// 关闭标签时从 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 跨微服务调用示例

// 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
手机验证码登录	`/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 主题切换流程

// 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 构建配置

// 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 可用命令

npm run dev       # 开发模式 (端口 2800)
npm run build     # 生产构建 (最大 8GB 内存)
npm run preview   # 预览构建结果

十五、数据字典机制

15.1 字典缓存策略

// 应用启动时或手动调用 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 字典使用场景

<!-- 表格列中转换 -->
<el-table-column prop="status" label="状态">
  <template #default="{ row }">
    {{ $dictUtils.getDictLabel('sys_status', row.status) }}
  </template>
</el-table-column>

十六、关键工具函数索引

函数	文件	说明
`hasPermission(perm)`	utils/index.js	按钮级权限判断
`treeDataTranslate(data)`	utils/index.js	扁平数据 → 树形结构
`recover(target, source)`	utils/index.js	表单对象属性覆盖赋值
`recoverNotNull(target, source)`	utils/index.js	非空属性覆盖
`deepClone(data)`	utils/index.js	对象深拷贝
`validatenull(val)`	utils/index.js	空值判断 (含数组/对象)
`downloadExcel(data, name)`	utils/index.js	Blob 文件下载
`t2(code)`	utils/index.js	动态国际化翻译
`tool.data.get/set/remove`	utils/tool.js	localStorage 读写 (JSON 序列化)
`tool.crypto.MD5/AES/BASE64`	utils/tool.js	加解密 (CryptoJS)
`tool.dateFormat(date)`	utils/tool.js	日期格式化
`getDictLabel(type, val)`	utils/dictUtils.js	字典值转标签

十七、自定义指令

指令	文件	功能
`v-copy`	directives/copy.js	一键复制文本到剪贴板
`v-time`	directives/time.js	时间格式化显示
`v-noMoreClick`	directives/noMoreClick.js	防重复点击 (2秒禁用)

十八、配置文件参考

18.1 默认系统配置 (`config/index.js`)

{
  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 已知问题

双重入口: 主系统和数据大屏各自独立的项目结构，维护成本较高
localStorage 依赖: 大量核心数据（菜单、权限、用户信息）都存储在 localStorage，存在 XSS 风险
API 索引未实际使用: src/api/index.js 扫描路径写的是 ./model/*.js，但实际项目 API 文件在子目录下直接使用
jQuery 依赖: package.json 中包含 jQuery，但 Vue3 项目中基本不应使用
已注释的功能: Dify 聊天机器人、全局错误捕获等被注释掉

19.2 改进建议

考虑将数据大屏合并到主系统作为子路由
敏感数据（Token）建议使用 httpOnly Cookie 替代 localStorage
建议统一 API 模块的导入方式
清理未使用的依赖（jQuery, mockjs 等）

二十、文件快速索引

关键文件	路径	说明
应用入口	src/main.js	Vue 应用初始化，全局注册
根组件	src/App.vue	主题/语言/路由刷新控制
全局注册	src/components.js	组件/指令/图标全局注册
路由核心	src/router/index.js	Hash路由 + 动态加载 + 守卫
静态路由	src/router/systemRouter.js	基础路由定义
布局入口	src/layout/index.vue	4种布局系统
HTTP 封装	src/utils/httpRequest.js	Axios 拦截器/错误处理
微服务路径	src/api/AppPath.js	14个微服务前缀定义
工具集	src/utils/index.js	核心工具函数
基础工具	src/utils/tool.js	localStorage/加解密/日期
字典工具	src/utils/dictUtils.js	数据字典操作
表单校验	src/utils/validate.js	48个基础校验方法
系统配置	src/config/index.js	默认系统参数
构建配置	vite.config.js	Vite + 代理 + 多入口
环境变量	.env.development	开发环境变量
大屏入口	src/datav/main.js	数据大屏独立应用
登录 API	src/api/auth/loginService.js	认证接口
用户 API	src/api/sys/userService.js	用户管理接口 (284行)
工作流API	src/api/flowable/taskService.js	工作流任务接口
国际化	src/i18n/index.js	中/英/日三语
用户工具栏	src/layout/components/userbar.vue	用户菜单/待办/消息

生成时间: 2026-06-01
分析方式: 完整源码索引 + 架构推理
覆盖范围: 全部核心模块 (路由/状态/API/权限/布局/组件/工具/国际化/构建)

PROJECT_ARCHITECTURE_WIKI.md 48 KB Историја Датотека

兴光微服务平台 (xg_total_process_master_cloud_vue) - 项目架构百科

一、项目概览

1.1 基本信息

1.2 业务领域

1.3 核心依赖一览

二、技术栈全景图

三、项目目录结构

四、路由配置体系

4.1 路由模式

4.2 静态路由 (systemRouter.js)

4.3 动态路由加载流程

4.4 导航守卫关键逻辑

4.5 路由扁平化与面包屑

五、状态管理体系 (Vuex)

5.1 模块架构

5.2 数据持久化策略

六、API 请求封装与微服务交互规范

6.1 HTTP 客户端架构

6.2 微服务路径定义 (AppPath.js)

6.3 API 服务文件编写规范

6.4 API 自动聚合机制

6.5 Vite 代理配置

6.6 实际请求 URL 示例

七、权限控制体系

7.1 多层次权限架构

7.2 权限数据流

7.3 按钮级权限实现

7.4 菜单权限过滤

7.5 角色权限检查

八、组件分层架构

8.1 组件分层图

8.2 布局系统详解

8.3 关键布局组件

8.4 业务组件分类

8.5 Keep-Alive 组件缓存策略

九、后端微服务交互全景

9.1 微服务调用关系图

9.2 微服务清单与职责

9.3 跨微服务调用示例

十、登录认证流程

10.1 完整登录链路

10.2 登录方式

10.3 退出登录

十一、数据大屏 (DataV) 子系统

11.1 独立入口

11.2 与主系统的区别

十二、国际化 (i18n)

12.1 语言支持

12.2 实现机制

十三、主题系统

13.1 主题配置

13.2 主题切换流程

十四、构建与部署

14.1 构建配置

14.2 环境变量

14.3 可用命令

十五、数据字典机制

15.1 字典缓存策略

15.2 字典使用场景

十六、关键工具函数索引

十七、自定义指令

十八、配置文件参考

18.1 默认系统配置 (config/index.js)

18.2 全局组件注册 (components.js)

十九、项目技术债务与注意事项

19.1 已知问题

19.2 改进建议

二十、文件快速索引

PROJECT_ARCHITECTURE_WIKI.md 48 KB

Историја Датотека

4.2 静态路由 (`systemRouter.js`)

6.2 微服务路径定义 (`AppPath.js`)

18.1 默认系统配置 (`config/index.js`)

18.2 全局组件注册 (`components.js`)