架构与目录

概述

前端工程基于 vue-vben-admin v5.7.0 模板构建，采用 pnpm + Turbo 的 Monorepo 方案：

一个业务应用 apps/web-ele（包名 @vben/web-ele）
一组高度解耦、可独立复用的包 packages/*
一批工程化配置与脚本 internal/*、scripts/*

技术栈：Vue 3 + Vite + TypeScript + Pinia + Vue Router + Element Plus，UI 组件在 @vben-core/ui-kit（shadcn 风格）基础上桥接 Element Plus。

Monorepo 工程结构

根目录 frontend/ 的关键文件：

文件	作用
`pnpm-workspace.yaml`	定义工作区包含的目录与依赖版本目录（catalog），统一管理三方依赖版本
`turbo.json`	Turbo 任务编排：`build` / `dev` / `typecheck` / `preview` 等，带依赖拓扑与缓存
`package.json`	根脚本（`dev`、`build`、`lint`、`test` 等）与共享 devDependencies
`oxlint.config.ts` / `oxfmt.config.ts` / `eslint.config.mjs` / `stylelint.config.mjs`	代码检查与格式化配置
`lefthook.yml`	Git 提交钩子（commit / pre-commit 校验）
`vitest.config.ts`	单元测试配置
`tea.yaml`	容器/镜像构建相关配置

依赖安装与启动：

bash

# 安装依赖（强制 pnpm）
pnpm install

# 启动 web-ele 应用
pnpm dev:ele # 或直接 pnpm dev

# 全量构建
pnpm build

目录总览

packages/ 内部的依赖分层（从上层业务到下层基础设施）：

apps/web-ele 应用结构

apps/web-ele/src/ 是日常开发的主战场：

text

src/
├── adapter/        # 组件适配层：桥接 Vben 表单/弹窗与 Element Plus
│   ├── component/index.ts   # 注册表单可用组件（Input/Select/Upload…）
│   ├── form.ts              # Vben Form Schema 适配器
│   └── vxe-table.ts         # VxeTable 适配器
├── api/            # 接口请求层（按后端模块分组）
│   ├── core/ system/ ai/ bpm/ infra/
│   ├── request.ts          # RequestClient 实例化与拦截器挂载
│   └── index.ts
├── assets/         # 静态资源（图片、svg 等）
├── components/     # 业务组件（富文本、上传、BPM 设计器等）
├── layouts/        # 应用布局（基础布局、空白布局等）
├── locales/        # 应用级国际化资源与初始化
├── plugins/        # 插件注册（form-create 表单设计器）
├── router/         # 前端路由
│   ├── routes/modules/      # 各模块路由定义
│   ├── access.ts            # 基于后端菜单生成可访问路由
│   ├── guard.ts             # 路由守卫（登录、权限、标题）
│   └── index.ts
├── store/          # 应用级 Pinia store（auth 等）
├── types/          # 应用级类型声明
├── utils/          # 应用级工具函数
├── views/          # 页面视图（按业务模块组织）
├── app.vue         # 根组件
├── bootstrap.ts    # 应用引导：初始化插件、i18n、store、路由
├── main.ts         # 入口
└── preferences.ts  # 项目偏好配置（覆盖默认值）

启动链路

应用启动时 bootstrap.ts 按顺序完成初始化：

视图模块与后端映射

views/ 的目录与后端 module_* 一一对应，是前后端模块对齐的直观体现：

views 目录	对应后端	说明
`_core/`	框架核心	登录认证、个人中心、关于、兜底页等基础视图
`system/`	`module_system`	用户、部门、岗位、角色、菜单、字典、租户、登录/操作日志、短信/邮箱/站内信
`infra/`	`module_infra`	参数配置、文件、定时任务、监控与连接
`ai/`	`module_ai`	模型、知识库、聊天、写作等 AI 能力
`bpm/`	`module_bpm`	流程模型、表单、实例、任务、设计器
`dashboard/`	—	工作台首页

新增业务模块时，通常需要在 views/、api/、./router/routes/modules/ 三处同时建立同名子目录，保持结构对称。

packages 分层

@core —— 核心基础设施

packages/@core 是框架级基础 SDK 与 UI 组件，严禁写入任何业务逻辑：

base/：设计变量（design）、图标（icons）、共享工具（shared）、类型声明（typings）
composables/：通用组合式函数
preferences/：用户偏好（主题、布局等）持久化
ui-kit/：UI 组件库，细分为
- shadcn-ui/：shadcn 风格基础组件（按钮、表单控件等）
- form-ui/ layout-ui/ menu-ui/ popup-ui/ tabs-ui/：布局/菜单/弹窗/标签页等区块组件

effects —— 公共能力层

packages/effects 用于存放与公共能力、状态、路由、特定组件库耦合的代码：

request/：基于 axios 的 RequestClient 与预设拦截器（packages/effects/request/src/request-client/）
access/：权限指令（v-access）与权限判定组合式函数
common-ui/：通用业务 UI（如 ApiComponent、Tippy、加载指令）
hooks/：通用组合式 hook
layouts/：可复用布局框架
plugins/：第三方插件封装（Motion 等）

基础设施包（平铺于 packages）

包	职责
`utils`	多应用通用工具，继承 `@vben-core/shared/utils`
`constants`	全局常量
`types`	全局类型
`icons`	图标资源
`locales`	国际化核心
`styles`	全局样式与主题（含 Element Plus 样式）
`stores`	全局 Pinia store（`access`、`user`、`dict`、`tabbar`、`timezone`）
`preferences`	偏好配置入口

pnpm-workspace.yaml 中保留了 packages/business/* 的占位，用于未来沉淀跨应用业务组件；当前业务组件仍直接维护在 apps/web-ele/src/components。

internal 与 scripts

internal/：不被打包发布，仅服务于工程化
- lint-configs/：eslint / oxlint / stylelint / commitlint 配置
- vite-config/：共享 Vite 配置（@vben/vite-config）
- tsconfig/：TS 基础配置
- tailwind-config/：Tailwind 配置
- node-utils/：Node 侧工具（脚本/构建使用）
scripts/：
- turbo-run/：本地 turbo run 封装
- vsh/：统一 lint / format 入口（pnpm lint / pnpm format）
- deploy/：Docker 镜像构建脚本

请求与适配链路

从页面到后端的典型调用链：

关键约定

统一响应字段：code / data / msg，成功码 0，由 defaultResponseInterceptor 归一化
请求头自动携带：Authorization（Bearer）、Accept-Language、tenant-id / visit-tenant-id
支持 API 加解密（AES，由 VITE_APP_API_ENCRYPT_* 控制）
令牌过期自动走 doRefreshToken → refreshTokenApi 刷新，失败则登出

配置与环境变量

应用配置主要来自两处：

apps/web-ele/src/preferences.ts：覆盖默认偏好，如 accessMode: 'backend'（后端菜单模式）、enableRefreshToken、应用名、主题、页脚、版权等。
apps/web-ele/.env*：运行期环境变量，重点包括：

变量	说明
`VITE_APP_TITLE`	应用标题（Mars AI Studio）
`VITE_APP_NAMESPACE`	缓存 / store 前缀，保证隔离
`VITE_GLOB_API_URL` / `VITE_PROXY_PREFIX` / `VITE_BASE_URL`	接口路径与开发代理目标（`vite.config.ts` 使用）
`VITE_APP_TENANT_ENABLE`	多租户开关
`VITE_APP_CAPTCHA_ENABLE`	验证码开关
`VITE_APP_API_ENCRYPT_ENABLE` 等	API 请求/响应加解密（AES 算法与密钥）

修改 preferences.ts 后建议清空浏览器缓存，否则可能不生效。

小结

工程是 pnpm + Turbo Monorepo，apps/web-ele 是唯一业务应用，其余皆是可复用包。
目录分层清晰：effects（公共能力层）→ @core（核心）→ 基础设施包（utils/types/styles…），禁止在 @core 写入业务。
业务代码集中在 apps/web-ele/src 的 views / api / router/routes/modules，且与后端 module_* 模块一一对应。
接口统一经 api/request.ts 的 RequestClient 拦截器链，完成鉴权、租户、加解密与响应归一化。

架构与目录 ​

概述 ​

Monorepo 工程结构 ​

目录总览 ​

apps/web-ele 应用结构 ​

启动链路 ​

视图模块与后端映射 ​

packages 分层 ​

@core —— 核心基础设施 ​

effects —— 公共能力层 ​

基础设施包（平铺于 packages） ​

internal 与 scripts ​

请求与适配链路 ​

配置与环境变量 ​

小结 ​