Web 前端架构

技术栈

技术	版本	用途
Vue 3	3.5+	UI 框架（Composition API）
TypeScript	5.x	类型安全
Vite	6.x	构建工具
Element Plus	2.9+	UI 组件库
Pinia	2.x	状态管理
Vue Router	4.x	路由管理
TailwindCSS	3.x	原子化 CSS
vue-i18n	9.x	国际化
ECharts	5.x	图表库
Monaco Editor	-	代码编辑器
Lucide Icons	-	图标库

项目结构

项目采用 Monorepo（pnpm workspace）架构：

web/
├── apps/
│   └── web-ele/                    # 主应用（Element Plus 版本）
│       ├── src/
│       │   ├── adapter/            # 适配层（组件/权限/偏好）
│       │   ├── api/                # API 接口定义
│       │   │   └── core/           # 核心模块 API
│       │   ├── components/         # 业务组件
│       │   ├── composables/        # 组合式函数
│       │   ├── layouts/            # 布局组件
│       │   ├── locales/            # 国际化文件
│       │   ├── router/             # 路由配置
│       │   ├── store/              # Pinia Store
│       │   ├── utils/              # 工具函数
│       │   ├── views/              # 页面视图
│       │   │   └── _core/          # 核心业务页面（43+模块）
│       │   └── main.ts             # 入口文件
│       └── vite.config.mts         # Vite 配置
├── packages/                       # 共享包
│   ├── @core/                      # 核心库
│   ├── constants/                  # 常量定义
│   ├── effects/                    # 副作用库
│   ├── icons/                      # 图标管理
│   ├── locales/                    # 共享国际化
│   ├── preferences/                # 偏好配置
│   ├── stores/                     # 共享 Store
│   ├── styles/                     # 共享样式
│   ├── types/                      # TypeScript 类型
│   └── utils/                      # 共享工具
└── internal/                       # 内部工具
    ├── lint-configs/               # ESLint/Prettier 配置
    ├── tailwind-config/            # TailwindCSS 配置
    └── node-utils/                 # Node.js 工具

应用入口

main.ts 负责应用初始化：

解析 URL：从路径提取 appCode 和 mode（运行/开发）
加载应用信息：从后端获取子应用详情
加载 UI 偏好：从后端获取 UI 配置（主题、布局、菜单等）
合并配置：将后端配置与默认偏好合并
初始化 Preferences：应用偏好设置
启动 Vue 应用：创建并挂载 Vue 实例

typescript

// URL 格式
// /app/{appCode}/...     → 运行模式
// /app-dev/{appCode}/... → 开发模式

const { appCode, mode } = parseUrlAppInfo();
const appDetails = await getApplicationDetailApi(appCode);
const uiPreferences = await getUIPreferencesApi();

路由系统

路由配置

typescript

const router = createRouter({
  history: createWebHistory(),
  scrollBehavior: () => ({ left: 0, top: 0 }),
  routes: [], // 动态路由
});

动态路由

菜单数据从后端获取，动态注册为路由：

后端菜单树 → 转换为 Vue Router 路由 → router.addRoute()

菜单 component 字段映射到前端组件：

_core/xxx/index → views/_core/xxx/index.vue
在线表单 → views/_core/form-render/index.vue
在线页面 → views/_core/page-render/index.vue

路由守卫

请求 → 白名单检查 → Token 检查 → 用户信息加载 → 动态路由注册 → 放行
         ↓ 无Token      ↓ 无用户信息
       登录页          获取用户信息+菜单

状态管理

Pinia Store 架构

Store	说明
`useUserStore`	用户信息、角色、权限
`useAccessStore`	路由、菜单树、访问权限
`useTabbarStore`	标签页管理
`useAppContextStore`	当前应用上下文（appCode, mode）

appContextStore

管理当前子应用上下文：

typescript

const appContextStore = useAppContextStore();
appContextStore.appCode;        // 当前应用编码
appContextStore.applicationId;  // 当前应用 ID
appContextStore.mode;           // run / dev
appContextStore.isDevMode;      // 是否开发模式

Vite 配置

API 代理

typescript

server: {
  proxy: {
    '/basic-api': {
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/basic-api/, ''),
      target: 'http://localhost:8000',
      ws: true,  // 支持 WebSocket
    },
  },
}

Element Plus 自动导入

通过 unplugin-element-plus 实现按需导入。

国际化

文件结构

locales/
├── zh-CN/               # 简体中文
│   ├── common.json
│   ├── form.json
│   ├── workflow.json
│   ├── ai-platform.json
│   └── ...
├── zh-TW/               # 繁体中文
└── en/                   # 英文

使用方式

typescript

import { useI18n } from 'vue-i18n';

const { t } = useI18n();
t('common.save');       // 保存
t('form.title');        // 表单标题

核心业务组件

ZQ 组件库

平台封装了一套业务组件：

组件	说明
`zq-dialog`	统一弹窗组件
`zq-drawer`	统一抽屉组件
`zq-table`	增强表格（排序/筛选/导出）
`zq-form` / `useVbenForm`	增强表单
`zq-tabs`	标签页组件
`zq-sub-table`	子表格组件
`fu-page`	页面布局组件
`card-list`	卡片列表组件

表单设计器 (form-design)

可视化拖拽设计表单，支持 40+ 字段类型。

工作流设计器 (workflow/designer)

钉钉/飞书风格的流程设计器：

树形节点结构
拖拽配置
条件/并行分支
撤销/重做

仪表盘设计器 (dashboard-design)

可视化仪表盘设计：

拖拽布局（Grid Layout）
28 种 Widget 组件
实时预览
数据源配置

AI 工作流编辑器 (ai-platform/workflow)

AI 工作流可视化编辑器：

节点拖拽编辑
属性面板配置
运行调试
变量管理

页面模块 (views/_core/)

43+ 个核心业务模块页面：

组织架构

user/ — 用户管理
role/ — 角色管理
dept/ — 部门管理
post/ — 岗位管理
menu/ — 菜单管理
permission/ — 权限管理

业务引擎

form-manager/ — 表单管理
form-render/ — 表单渲染
workflow/ — 工作流（管理/发起/待办/已办/抄送）
page-manager/ — 页面管理
page-render/ — 页面渲染
ai-platform/ — AI 平台

系统管理

application/ — 子应用管理
dict/ — 数据字典
system-config/ — 系统配置
ui-config/ — UI 配置
login-log/ — 登录日志

文件与通信

file-manager/ — 文件管理
message/ — 消息管理
announcement/ — 公告管理
chat/ — 即时聊天

数据管理

database-manager/ — 数据库管理
database-monitor/ — 数据库监控
data-source/ — 数据源配置
redis-manager/ — Redis 管理
redis-monitor/ — Redis 监控
server-monitor/ — 服务器监控

工具

document-generator/ — 文档生成器
contract/ — 合同管理
electronic-seal/ — 电子印章
screen-design/ — 大屏设计

样式系统

TailwindCSS

优先使用 TailwindCSS 编写样式，避免硬编码颜色值（支持 dark/light 主题切换）。

CSS 变量

颜色使用 CSS 变量，确保主题切换兼容：

css

/* 正确 */
color: var(--color-primary);
background-color: hsl(var(--background));

/* 错误 - 硬编码 */
color: #409eff;
background-color: #ffffff;

暗色模式

系统支持 light/dark 主题自动切换，所有组件和页面必须适配两种模式。

图标管理

图标统一从 @vben/icons 导入，基于 Lucide：

typescript

import { IconSettings, IconUser, IconSearch } from '@vben/icons';

如需新增图标，在 web/packages/@core/base/icons/src/lucide.ts 中添加。

Web 前端架构 ​

技术栈 ​

项目结构 ​

应用入口 ​

路由系统 ​

路由配置 ​

动态路由 ​

路由守卫 ​

状态管理 ​

Pinia Store 架构 ​

appContextStore ​

Vite 配置 ​

API 代理 ​

Element Plus 自动导入 ​

国际化 ​

文件结构 ​

使用方式 ​

核心业务组件 ​

ZQ 组件库 ​

表单设计器 (form-design) ​

工作流设计器 (workflow/designer) ​

仪表盘设计器 (dashboard-design) ​

AI 工作流编辑器 (ai-platform/workflow) ​

页面模块 (views/_core/) ​

组织架构 ​

业务引擎 ​

系统管理 ​

文件与通信 ​

数据管理 ​

工具 ​

样式系统 ​

TailwindCSS ​

CSS 变量 ​

暗色模式 ​

图标管理 ​

Web 前端架构

技术栈

项目结构

应用入口

路由系统

路由配置

动态路由

路由守卫

状态管理

Pinia Store 架构

appContextStore

Vite 配置

API 代理

Element Plus 自动导入

国际化

文件结构

使用方式

核心业务组件

ZQ 组件库

表单设计器 (form-design)

工作流设计器 (workflow/designer)

仪表盘设计器 (dashboard-design)

AI 工作流编辑器 (ai-platform/workflow)

页面模块 (views/_core/)

组织架构

业务引擎

系统管理

文件与通信

数据管理

工具

样式系统

TailwindCSS

CSS 变量

暗色模式

图标管理