前端系统架构

本文说明 art-design-pro-ui 的前端架构。阅读本页后，你应该能理解应用从启动到渲染页面的主链路，以及页面、路由、接口、状态和配置之间的关系。

架构分层

商业版前端可以按 5 层理解：

层级	主要目录	职责
启动层	src/main.ts、src/App.vue	创建 Vue 应用，挂载 store、router、i18n、指令、插件和全局错误处理
路由层	src/router	静态路由、动态路由、菜单转换、路由注册、导航守卫
状态层	src/store/modules	用户、菜单、站点配置、主题设置、通知、工作标签页等状态
业务层	src/views、src/api、src/types/api	页面实现、接口封装、接口类型
基础能力层	src/components、src/hooks、src/utils、src/config	通用组件、组合式函数、工具方法、系统配置

启动流程

应用启动入口在 src/main.ts，主要流程如下：

flowchart TD
  A["createApp(App)"] --> B["initStore(app)"]
  B --> C["initRouter(app)"]
  C --> D["setupGlobDirectives(app)"]
  D --> E["setupErrorHandle(app)"]
  E --> F["setupElementPlusLocale()"]
  F --> G["app.use(i18n)"]
  G --> H["app.mount('#app')"]
  H --> I["loadPublicSiteSettings()"]
  I --> J["未登录时应用默认语言"]

这条链路说明：站点公开配置并不是在页面内部临时读取，而是在应用启动后由站点配置 store 统一加载。

路由与菜单主链路

商业版前端的页面访问不是纯静态路由决定的。登录后的页面通常经过以下链路：

flowchart TD
  A["进入路由守卫"] --> B["检查登录状态"]
  B --> C["必要时恢复 Access Token"]
  C --> D["获取用户信息"]
  D --> E["获取菜单数据"]
  E --> F["MenuProcessor 转换菜单"]
  F --> G["RouteRegistry 注册动态路由"]
  G --> H["渲染菜单与页面"]

相关核心文件：

• src/router/guards/beforeEach.ts
• src/router/core/MenuProcessor.ts
• src/router/core/RouteRegistry.ts
• src/router/core/RoutePermissionValidator.ts
• src/store/modules/user.ts
• src/store/modules/menu.ts

请求主链路

业务页面不应直接散落请求实现，常规请求链路是：

src/views/<module>
  -> src/api/*.ts
  -> src/utils/http/index.ts
  -> /api/v1/**
  -> art-design-pro-server

src/utils/http/index.ts 统一处理：

• Authorization: Bearer <token>
• Access Token 刷新
• API 安全头
• JSON 请求处理
• 统一错误消息
• 未授权处理

模块开发落点

新增或调整一个业务页面时，通常需要同时关注：

目标	推荐落点
页面实现	src/views/<module>
接口封装	src/api/*.ts
路由模板	src/router/modules/*.ts
菜单权限	后端菜单数据与前端路由模板保持一致
共享逻辑	src/components、src/hooks、src/utils
类型定义	src/types/api 或对应业务类型文件

设计原则

• 页面只负责组织交互和展示，不直接承担全局鉴权、路由注册、菜单转换等职责。
• 接口请求统一进入 src/api 和 HTTP 封装层，避免页面中直接创建临时 Axios 请求。
• 动态路由、菜单和权限必须作为一条链路理解，不能只看页面文件是否存在。
• 站点展示配置优先通过站点配置 store 读取，避免多个页面各自维护展示状态。