前端根应用与启动流程.md 26 KB

前端根应用与启动流程

本文引用的文件

  • main.ts
  • App.vue
  • setupAntdPopupBehavior.ts
  • setupAntdTabsListenerPatch.ts
  • pageEnum.ts
  • serverSetting.ts

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与启动行为
  8. 常见问题排查
  9. 扩展指南
  10. 结论

引言

本文聚焦 ai-electron 前端根应用与启动流程,解释以下关键问题:

  • main.ts 如何初始化 UnoCSS、Ant Design Vue reset 样式、全局设计样式和 AI 模块样式;
  • 如何创建 Vue 应用、注册全局组件、国际化、路由、Store、错误处理;
  • 为什么需要 Tab 监听补丁和弹窗行为补丁;
  • 启动探测逻辑 waitForBackendReady 的重试策略、loading 提示、重连和服务地址入口;
  • App.vue 如何配置 Ant Design Vue 主题、语言、AppProvider,并通过授权接口写入水印;
  • isServerSetupMissing、getApiOrigin、PageEnum.BASE_AUTHORIZATION、PageEnum.BASE_SERVER_SETUP 在启动路由和授权判断中的作用;
  • 如何安全地新增全局初始化逻辑、扩展启动探测、处理授权缓存;
  • 后端连接失败、loading 卡住、授权信息不显示、路由跳转到 404、服务地址为空等问题的排查方法。

项目结构

前端根入口位于 ai-electron/frontend/src/main.ts,根视图位于 ai-electron/frontend/src/App.vue。启动流程由 main.ts 的 bootstrap() 函数驱动,负责样式加载、环境检测、后端就绪探测、路由跳转、登录态校验和应用挂载。App.vue 负责 Ant Design Vue 的主题、语言、应用容器和水印展示。

graph TB
  A["main.ts<br/>引导程序"] --> B["Vue.createApp(App)"]
  A --> C["setupStore(app)"]
  A --> D["initAppConfigStore()"]
  A --> E["setupI18n(app)"]
  A --> F["setupRouter(app)"]
  A --> G["setupRouterGuard(router)"]
  A --> H["setupGlobDirectives(app)"]
  A --> I["setupErrorHandle(app)"]
  A --> J["app.mount('#app')"]
  K["App.vue<br/>根组件"] --> L["StyleProvider + ConfigProvider"]
  L --> M["AppProvider"]
  M --> N["RouterView"]

图表来源

  • main.ts:232-399
  • App.vue:1-85

章节来源

  • main.ts:1-399
  • App.vue:1-85

核心组件

main.ts:根应用引导程序

main.ts 是前端启动的唯一入口。它按固定顺序完成以下工作:

  1. 加载样式资源:UnoCSS、Ant Design Vue reset 样式、全局设计样式、AI 模块样式。
  2. 解析窗口角色:区分主窗口和智能工作台窗口。
  3. 安装补丁:Ant Design Vue 弹窗行为和开发态 Tab 触摸监听补丁。
  4. 创建并配置 Vue 应用:Store、应用配置、跨窗口会话同步、全局组件、国际化、路由、路由守卫。
  5. 服务端地址检查:若未绑定服务地址,则进入授权页或关闭智能窗口。
  6. 后端就绪探测:最多重试 10 次,每次约 3 秒,调用健康检查接口。
  7. 启动授权与路由决策:根据授权状态、登录态和目标路径决定最终路由。
  8. 挂载应用:注册全局指令、错误处理,最后挂载到 #app。

章节来源

  • main.ts:1-399

App.vue:根组件与应用容器

App.vue 是 Vue 应用的根组件,主要负责:

  • 使用 StyleProvider 包裹整个应用,并启用 Ant Design Vue 的逻辑属性转换;
  • 通过 ConfigProvider 提供语言和主题;
  • 使用 AppProvider 作为应用上下文容器;
  • 计算并应用深色模式、主题色、圆角等样式 token;
  • 根据用户设置动态更新页面标题;
  • 在挂载后尝试获取授权单元,并将其写入水印。

章节来源

  • App.vue:1-85

setupAntdPopupBehavior.ts:弹窗行为补丁

该模块为 Ant Design Vue 的 Modal 提供统一行为:

  • 将 Modal 实例方法的默认 maskClosable 设为 false,防止用户误点遮罩关闭重要提示;
  • 对 confirm、info、success、error、warning、warn 等方法进行包装;
  • 同时修改 Modal 组件的 props 默认值,保证直接渲染 Modal 时行为一致。

这个补丁适合用于系统级提示、警告、成功反馈,避免业务侧重复配置遮罩行为。

章节来源

  • setupAntdPopupBehavior.ts:1-33

setupAntdTabsListenerPatch.ts:Tab 监听补丁

该模块仅在开发模式下启用,目的是减少 Ant Design Vue Tabs 在桌面端产生的非 passive 触摸事件警告:

  • 检测是否为可触摸设备;
  • 拦截 addEventListener;
  • 跳过 Ant Design Vue 内部用于 Tabs 拖拽/滚动的代理触摸监听;
  • 保留正常滚动行为,不接管 scrollLeft。

它不是核心业务逻辑,而是开发体验优化补丁。

章节来源

  • setupAntdTabsListenerPatch.ts:1-85

pageEnum.ts:页面常量

PageEnum 集中定义前端页面路径常量,包括:

  • /server-setup:服务端地址绑定页;
  • /authorization:授权与登录唯一入口;
  • /login:已废弃登录页常量,仅用于兼容老书签和回跳;
  • /case:案件主入口;
  • 其他数据、上传、清洗、异常、错误日志、修改密码等页面路径。

这些常量被启动路由、授权判断、登录门禁和跳转逻辑广泛使用,避免硬编码字符串导致的路径不一致。

章节来源

  • pageEnum.ts:1-21

serverSetting.ts:服务端地址与连接检测

serverSetting.ts 管理运行时绑定的后端服务地址:

  • 从 localStorage 读取已绑定的服务地址;
  • 维护最近使用过的地址历史;
  • 规范化用户输入的服务地址,只允许协议、主机和端口;
  • 暴露 getApiOrigin() 获取当前生效的接口 origin;
  • 暴露 isServerSetupMissing() 判断是否要求绑定但尚未绑定;
  • 暴露健康检查 URL 构造方法和原生 fetch 测试连接方法。

注意:不要在模块加载时缓存 getApiOrigin() 的结果,因为它是实时读取当前绑定值的。

章节来源

  • serverSetting.ts:1-200

架构总览

启动流程可以理解为一条“预检 → 探测 → 授权 → 登录 → 路由 → 挂载”的流水线。

flowchart TD
  Start(["应用启动"]) --> LoadStyles["加载样式<br/>UnoCSS / AntD reset / 全局样式 / AI 样式"]
  LoadStyles --> InitWindow["初始化窗口角色"]
  InitWindow --> InstallPatches["安装弹窗补丁<br/>可选安装 Tab 监听补丁"]
  InstallPatches --> CreateApp["创建 Vue 应用并注册 Store、组件、国际化、路由、守卫"]
  CreateApp --> CheckServerSetup{"是否缺少服务端地址?"}
  CheckServerSetup -->|是| RedirectAuth["跳转到授权页<br/>或关闭智能窗口"]
  CheckServerSetup -->|否| ProbeBackend["启动探测:最多 10 次 × 约 3 秒"]
  ProbeBackend --> BackendOk{"后端就绪?"}
  BackendOk -->|否| ShowReconnect["显示 loading 重试提示<br/>提供重连与服务地址入口"]
  BackendOk -->|是| ResolveRoute["解析启动路由"]
  ResolveRoute --> AuthCheck{"授权有效?"}
  AuthCheck -->|过期| RedirectExpired["跳转到授权页并带过期信息"]
  AuthCheck -->|有效| EnsureLogin{"是否有 token?"}
  EnsureLogin -->|无| RedirectAuth
  EnsureLogin -->|有| MountApp["注册全局指令、错误处理并挂载应用"]
  ShowReconnect --> UserRetry["用户点击重连或修改地址"]
  UserRetry --> ProbeBackend
  RedirectAuth --> MountApp
  RedirectExpired --> MountApp

图表来源

  • main.ts:232-399
  • main.ts:1-200

详细组件分析

main.ts 启动流程详解

样式初始化

main.ts 在模块顶层导入四类样式:

  • virtual:uno.css:UnoCSS 虚拟样式;
  • ant-design-vue/dist/reset.css:Ant Design Vue 重置样式;
  • @/core/design/index.less:全局设计样式;
  • @/ai/index:AI 数据分析模块的全局样式入口。

这些导入会在模块加载阶段执行,确保后续渲染前样式已就位。

章节来源

  • main.ts:1-12

启动探测 waitForBackendReady

waitForBackendReady 实现固定节拍重试:

  • 最大重试次数为 10;
  • 每次间隔约 3 秒;
  • 调用 healthApi 探测后端健康检查接口;
  • 响应码为 200 表示后端就绪;
  • 每次尝试都更新 loading 页提示;
  • 超过 10 次仍未连接时,停止自动探测,交给调用方展示重连或服务地址入口。

探测过程不依赖 UI 框架,直接操作静态 DOM 类名来切换“重试中”“成功”“失败”状态。

flowchart TD
  S["开始等待后端就绪"] --> Loop["循环 attempt=1..10"]
  Loop --> UpdateTip["更新 loading 提示"]
  UpdateTip --> CallHealth["调用 healthApi"]
  CallHealth --> Ok{"响应码为 200?"}
  Ok -->|是| Success["标记成功并返回 true"]
  Ok -->|否| Wait["计算下次等待时间"]
  Wait --> NextAttempt{"还有剩余次数?"}
  NextAttempt -->|是| Loop
  NextAttempt -->|否| Fail["显示最终失败提示并返回 false"]

图表来源

  • main.ts:27-120

章节来源

  • main.ts:27-120

重连与服务地址入口

当 10 次探测失败后,showReconnectState 会:

  • 显示 .app-loading-actions 区域;
  • 绑定重连按钮事件,再次执行一轮探测;
  • 成功后整页 reload,重新走正常启动流程;
  • 失败后恢复按钮可用状态;
  • 绑定“修改服务地址”按钮,跳转到授权页并附带 error=unreachable。

这保证了用户在服务地址不可达时不会卡在空白界面。

章节来源

  • main.ts:122-171

启动路由解析与授权判断

resolveStartupRoute 的核心逻辑如下:

  1. 读取当前 hash 或 pathname,还原完整路径;
  2. 如果目标是授权页或服务地址页,跳过启动授权检查;
  3. 调用 checkAuthApi() 校验授权;
  4. 授权有效且未过期时,解析目标路径并替换路由;
  5. 授权过期时跳转到授权页并携带过期信息;
  6. 授权失败时跳转到授权页;
  7. 特殊处理 HTTP 层返回 200 但响应体包含授权数据的边界情况。

shouldRunStartupAuthCheck 排除授权页和服务地址页,避免这两个自持页面参与启动授权流程。

getAuthorizedTarget 将首页、旧测试页、入口页、服务地址页、已删除登录页统一落到案件页,其他路径保留原始完整路径。

flowchart TD
  RStart["解析启动路由"] --> Skip{"是否为授权页或服务地址页?"}
  Skip -->|是| Return["直接返回"]
  Skip -->|否| CheckAuth["调用 checkAuthApi"]
  CheckAuth --> AuthOk{"授权有效?"}
  AuthOk -->|否| ToAuth["跳转到授权页"]
  AuthOk -->|是| Expired{"授权已过期?"}
  Expired -->|是| ToExpired["跳转到授权页并带过期信息"]
  Expired -->|否| Target["计算目标路径并替换路由"]

图表来源

  • main.ts:201-267

章节来源

  • main.ts:173-267
  • pageEnum.ts:1-21

登录门禁 ensureLoggedIn

登录后门针对当前路由做二次判断:

  • 授权页和服务地址页不参与登录门禁;
  • 若无 token,则跳转到授权页;
  • 若存在回跳来源,则把来源放入 query;
  • 不再使用已删除的 /login,避免登录后跳转到 404。

章节来源

  • main.ts:269-299

bootstrap 主流程

bootstrap 是启动调度器,关键分支如下:

  1. 初始化窗口角色;
  2. 安装弹窗补丁;
  3. 创建 Vue 应用;
  4. 注册 Store、应用配置、会话同步、全局组件、国际化、路由、路由守卫;
  5. 若缺少服务端地址:
    • 智能窗口则聚焦主窗口并关闭自身;
    • 否则跳转到授权页,挂载应用后直接返回;
  6. 若非授权页或服务地址页,则执行后端探测;
  7. 探测失败则显示重连入口;
  8. 探测成功则解析路由;
  9. 等待首次导航落定;
  10. 校验登录态;
  11. 智能窗口在授权页场景下关闭自身;
  12. 注册全局指令、错误处理,挂载应用。

    sequenceDiagram
    participant Boot as "bootstrap"
    participant Win as "窗口角色"
    participant Patch as "弹窗补丁"
    participant Vue as "Vue 应用"
    participant Router as "路由"
    participant Server as "服务端地址检查"
    participant Health as "健康检查"
    participant Auth as "授权检查"
    participant Login as "登录门禁"
    
    Boot->>Win: 初始化窗口角色
    Boot->>Patch: 安装弹窗行为
    Boot->>Vue: createApp + Store + I18n + Router
    Boot->>Server: isServerSetupMissing
    alt 缺少服务地址
    Boot->>Win: 智能窗口聚焦主窗口并关闭
    Boot->>Router: 跳转到授权页
    Boot->>Vue: 挂载应用
    else 已有服务地址
    Boot->>Health: waitForBackendReady
    alt 后端不可达
      Boot->>Boot: showReconnectState
    else 后端可达
      Boot->>Auth: resolveStartupRoute
      Boot->>Router: router.isReady
      Boot->>Login: ensureLoggedIn
      Boot->>Win: 智能窗口处理授权页
      Boot->>Vue: 挂载应用
    end
    end
    

图表来源

  • main.ts:232-399

章节来源

  • main.ts:232-399

App.vue 主题、语言与水印

App.vue 的关键职责:

  • 使用 StyleProvider 和 ConfigProvider 提供 Ant Design Vue 样式与主题;
  • 根据深色模式和主题设置计算 getTheme;
  • 使用 useLocale 获取 Ant Design Vue 的语言;
  • 使用 useTitle 动态更新页面标题;
  • 在挂载后调用 ensureAuthorizationUnit;
  • 监听授权单元变化,写入或清除水印。

ensureAuthorizationUnit 会:

  • 如果已有授权单元则跳过;
  • 如果处于服务地址页或没有 API origin,则跳过请求;
  • 调用 authorizationInfoApi 获取授权信息;
  • 使用 extractAuthorizationCache 提取授权单元并写入页面缓存;
  • 请求失败时清空水印。

    flowchart TD
    Mounted["onMounted"] --> HasUnit{"已有授权单元?"}
    HasUnit -->|是| WatchWatermark["监听授权单元变化"]
    HasUnit -->|否| MissingServer{"服务地址缺失或无 API origin?"}
    MissingServer -->|是| Skip["跳过授权请求"]
    MissingServer -->|否| FetchAuth["调用 authorizationInfoApi"]
    FetchAuth --> Extract["extractAuthorizationCache"]
    Extract --> SetCache["写入 authorizationUnit"]
    SetCache --> WatchWatermark
    WatchWatermark --> Watermark{"授权单元为空?"}
    Watermark -->|是| ClearWatermark["清空水印"]
    Watermark -->|否| SetWatermark["设置水印"]
    

图表来源

  • App.vue:1-85

章节来源

  • App.vue:1-85

关键常量与设置的作用

PageEnum.BASE_AUTHORIZATION

  • 是授权与登录的统一入口;
  • 启动路由检查时会跳过该路径;
  • 授权失败、过期、无 token 时都会跳转到该路径;
  • 智能窗口检测到授权页时会主动关闭自身,让主窗口处理授权提示。

PageEnum.BASE_SERVER_SETUP

  • 是服务端地址绑定页;
  • 启动路由检查时会跳过该路径;
  • 若应用要求绑定地址但本地未绑定,bootstrap 会直接跳转到该路径;
  • 探测失败后也可跳转到该路径,并附带 error=unreachable。

isServerSetupMissing

  • 判断当前构建是否要求绑定服务地址;
  • 并且本地尚未保存服务地址;
  • 若为真,bootstrap 会提前跳转授权页,避免在无地址情况下空等后端。

getApiOrigin

  • 返回当前生效的后端接口 origin;
  • 优先取 localStorage 中的绑定地址;
  • 其次取构建期环境变量;
  • 开发态可能返回空串,此时请求走 Vite 代理;
  • App.vue 使用该函数判断是否在真正有后端的情况下拉取授权信息。

章节来源

  • pageEnum.ts:1-21
  • serverSetting.ts:120-200
  • main.ts:232-399
  • App.vue:1-85

依赖关系分析

graph LR
  Main["main.ts"] --> AppVue["App.vue"]
  Main --> Popup["setupAntdPopupBehavior.ts"]
  Main --> TabsPatch["setupAntdTabsListenerPatch.ts"]
  Main --> PageEnum["core/enums/pageEnum.ts"]
  Main --> ServerSetting["core/settings/serverSetting.ts"]
  AppVue --> ServerSetting
  AppVue --> PageEnum
  Main --> ApiLogin["core/api/sys/login"]
  Main --> License["core/utils/license"]

图表来源

  • main.ts:1-399
  • App.vue:1-85
  • pageEnum.ts:1-21
  • serverSetting.ts:1-200

章节来源

  • main.ts:1-399
  • App.vue:1-85

性能与启动行为

  • 样式加载发生在模块顶层,属于同步副作用,应尽量避免引入过大的样式包;
  • 启动探测采用固定间隔重试,而不是“探测超时后再等一个间隔”,因此整体耗时上限可控;
  • 10 次 × 3 秒约为 30 秒,适合网络较慢或后端冷启动的场景;
  • 授权信息只在 App.vue 挂载后按需拉取,避免阻塞首屏;
  • 服务地址缺失时尽早跳转,不浪费健康检查资源;
  • 智能窗口在授权页场景下主动关闭自身,避免多窗口重复提示。

常见问题排查

后端连接失败

现象:loading 页一直显示重试提示,最终提示连接失败。
原因:

  • 服务地址错误;
  • 后端未启动;
  • 网络不通;
  • 健康检查接口不可用;
  • 构建期或运行期 API origin 配置不正确。

排查步骤:

  1. 确认服务地址是否正确;
  2. 确认后端进程是否正常运行;
  3. 检查浏览器控制台的网络请求,确认健康检查 URL;
  4. 使用 testServerConnection 或手动访问健康检查接口;
  5. 确认 isServerBindingEnabled 与实际部署策略一致;
  6. 若生产环境要求绑定地址,请通过授权页的服务地址卡片重新绑定。

相关位置

  • main.ts:27-120
  • main.ts:122-171
  • serverSetting.ts:120-200

loading 卡住

现象:页面停留在 loading 状态,没有主界面也没有明确错误。
可能原因:

  • 10 次探测全部失败;
  • 授权检查或路由跳转异常;
  • 应用未在预期分支挂载;
  • 静态 DOM 选择器找不到 .app-loading-tip 或 .app-loading-actions。

排查步骤:

  1. 查看控制台日志中 [bootstrap] waiting for backend to be ready 和重试次数;
  2. 检查是否进入了 showReconnectState;
  3. 检查 HTML 中是否存在 loading 相关 DOM;
  4. 检查是否因缺少服务地址而提前跳转授权页;
  5. 如果是智能窗口,检查是否被主窗口接管后关闭。

相关位置

  • main.ts:27-171
  • main.ts:232-399

授权信息不显示

现象:水印没有显示授权单元,或授权信息未更新。
可能原因:

  • 服务地址缺失;
  • 没有 API origin;
  • authorizationInfoApi 请求失败;
  • 授权单元为空;
  • 授权缓存未正确写入页面缓存。

排查步骤:

  1. 检查 isServerSetupMissing() 是否为真;
  2. 检查 getApiOrigin() 是否返回有效地址;
  3. 检查 authorizationInfoApi 的返回结果;
  4. 检查页面缓存中的 authorizationUnit;
  5. 检查 App.vue 的 ensureAuthorizationUnit 是否被执行;
  6. 检查授权过期逻辑是否跳转到授权页。

相关位置

  • App.vue:1-85
  • main.ts:201-267
  • serverSetting.ts:120-200

路由跳转到 404

现象:登录后或启动后跳转到未知页面。
可能原因:

  • 使用了已删除的 /login 作为回跳来源;
  • 启动路径解析错误;
  • hash 模式与 history 模式混用;
  • VITE_PUBLIC_PATH 前缀处理异常;
  • 目标路径不在路由注册表中。

排查步骤:

  1. 检查 getStartupRouteInfo 的 hash 或 pathname 解析;
  2. 确认是否启用了 history 模式;
  3. 检查 VITE_ROUTE_WEB_HISTORY 和 VITE_PUBLIC_PATH;
  4. 检查 getAuthorizedTarget 是否把入口页映射到案件页;
  5. 确认 /login 已不再注册为路由。

相关位置

  • main.ts:173-200
  • main.ts:269-299
  • pageEnum.ts:1-21

服务地址为空

现象:应用无法请求后端,或始终停留在服务地址绑定页。
可能原因:

  • localStorage 中没有 SERVER_BASE_URL__;
  • 构建期要求绑定服务地址;
  • 用户清除了缓存;
  • 智能窗口切换到主窗口但未完成授权。

排查步骤:

  1. 打开浏览器存储面板,检查 SERVER_BASE_URL__;
  2. 检查 isServerBindingEnabled 是否启用;
  3. 通过授权页的服务地址卡片重新绑定;
  4. 检查 getBoundServerOrigin 和 getApiOrigin 返回值;
  5. 确认智能窗口是否调用了 focusMainWindow 和 closeSmartWindow。

相关位置

  • serverSetting.ts:1-120
  • main.ts:232-399

扩展指南

新增全局初始化逻辑

建议在 bootstrap 中现有初始化链之后添加,并确保不影响路由和挂载顺序。推荐插入位置:

  • Store 初始化之后;
  • 国际化初始化之前或之后;
  • 路由初始化之前;
  • 不要放在 app.mount('#app') 之后。

示例思路:

  1. 新增初始化函数;
  2. 在 bootstrap 中调用;
  3. 如依赖后端,先判断 isServerSetupMissing();
  4. 如依赖路由,先调用 router.isReady();
  5. 如可能失败,使用 try/catch 保护,避免阻塞应用启动。

参考位置

  • main.ts:232-399

扩展启动探测逻辑

如需增加探测维度(例如同时检查多个后端能力):

  1. 封装新的探测函数;
  2. 在 waitForBackendReady 成功后再执行;
  3. 失败时复用现有的 loading 提示和重连入口;
  4. 不要改变默认的 10 次 × 3 秒上限,除非业务确实需要更长等待;
  5. 在探测失败分支中使用 showReconnectState,保持用户体验一致。

参考位置

  • main.ts:27-120
  • main.ts:122-171

处理授权缓存

授权缓存涉及两个层面:

  1. 页面缓存:通过 useUserStoreWithOut().setPageCache 写入 authorizationLabel、licenseOverDateTime、authorizationUnit;
  2. 组件展示:App.vue 读取 authorizationUnit 并写入水印。

新增授权字段时:

  1. 在 syncAuthorizationCache 中同步新字段;
  2. 在 App.vue 中监听并展示;
  3. 如果新字段影响路由或权限,应在 resolveStartupRoute 或路由守卫中处理;
  4. 如果新字段来自后端,确保 authorizationInfoApi 返回结构兼容;
  5. 如果新字段可能过期,复用 isAuthorizationExpired 和 redirectToExpiredAuthorization 的逻辑。

参考位置

  • main.ts:201-267
  • App.vue:1-85

结论

main.ts 是前端根应用的启动中枢,负责样式加载、环境检测、后端探测、授权校验、登录门禁和路由挂载;App.vue 负责应用级主题、语言、容器和水印展示。两者共同构成了“启动前预检 → 启动中探测 → 启动后渲染”的稳定流程。

在实际维护中,新增全局逻辑应遵循:

  • 不阻塞样式和基础初始化;
  • 尊重服务地址缺失和后端不可达状态;
  • 复用已有的枚举、设置和授权工具;
  • 对用户可见的错误提供可操作的下一步,例如重连或修改服务地址。