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

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

### 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: [],  // 需要保持活性的路由组件名列表
// 配合 <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 跨微服务调用示例

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

---

## 十六、关键工具函数索引

| 函数 | 文件 | 说明 |
|------|------|------|
| `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/权限/布局/组件/工具/国际化/构建)
