本文引用的文件
本文聚焦 ai-electron 前端根应用与启动流程,解释以下关键问题:
main.ts 如何初始化 UnoCSS、Ant Design Vue reset 样式、全局设计样式和 AI 模块样式;waitForBackendReady 的重试策略、loading 提示、重连和服务地址入口;App.vue 如何配置 Ant Design Vue 主题、语言、AppProvider,并通过授权接口写入水印;isServerSetupMissing、getApiOrigin、PageEnum.BASE_AUTHORIZATION、PageEnum.BASE_SERVER_SETUP 在启动路由和授权判断中的作用;前端根入口位于 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 是前端启动的唯一入口。它按固定顺序完成以下工作:
#app。章节来源
App.vue 是 Vue 应用的根组件,主要负责:
StyleProvider 包裹整个应用,并启用 Ant Design Vue 的逻辑属性转换;ConfigProvider 提供语言和主题;AppProvider 作为应用上下文容器;章节来源
该模块为 Ant Design Vue 的 Modal 提供统一行为:
maskClosable 设为 false,防止用户误点遮罩关闭重要提示;confirm、info、success、error、warning、warn 等方法进行包装;这个补丁适合用于系统级提示、警告、成功反馈,避免业务侧重复配置遮罩行为。
章节来源
该模块仅在开发模式下启用,目的是减少 Ant Design Vue Tabs 在桌面端产生的非 passive 触摸事件警告:
addEventListener;scrollLeft。它不是核心业务逻辑,而是开发体验优化补丁。
章节来源
PageEnum 集中定义前端页面路径常量,包括:
/server-setup:服务端地址绑定页;/authorization:授权与登录唯一入口;/login:已废弃登录页常量,仅用于兼容老书签和回跳;/case:案件主入口;这些常量被启动路由、授权判断、登录门禁和跳转逻辑广泛使用,避免硬编码字符串导致的路径不一致。
章节来源
serverSetting.ts 管理运行时绑定的后端服务地址:
getApiOrigin() 获取当前生效的接口 origin;isServerSetupMissing() 判断是否要求绑定但尚未绑定;注意:不要在模块加载时缓存 getApiOrigin() 的结果,因为它是实时读取当前绑定值的。
章节来源
启动流程可以理解为一条“预检 → 探测 → 授权 → 登录 → 路由 → 挂载”的流水线。
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 在模块顶层导入四类样式:
virtual:uno.css:UnoCSS 虚拟样式;ant-design-vue/dist/reset.css:Ant Design Vue 重置样式;@/core/design/index.less:全局设计样式;@/ai/index:AI 数据分析模块的全局样式入口。这些导入会在模块加载阶段执行,确保后续渲染前样式已就位。
章节来源
waitForBackendReady 实现固定节拍重试:
healthApi 探测后端健康检查接口;探测过程不依赖 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"]
图表来源
章节来源
当 10 次探测失败后,showReconnectState 会:
.app-loading-actions 区域;error=unreachable。这保证了用户在服务地址不可达时不会卡在空白界面。
章节来源
resolveStartupRoute 的核心逻辑如下:
checkAuthApi() 校验授权;shouldRunStartupAuthCheck 排除授权页和服务地址页,避免这两个自持页面参与启动授权流程。
getAuthorizedTarget 将首页、旧测试页、入口页、服务地址页、已删除登录页统一落到案件页,其他路径保留原始完整路径。
flowchart TD
RStart["解析启动路由"] --> Skip{"是否为授权页或服务地址页?"}
Skip -->|是| Return["直接返回"]
Skip -->|否| CheckAuth["调用 checkAuthApi"]
CheckAuth --> AuthOk{"授权有效?"}
AuthOk -->|否| ToAuth["跳转到授权页"]
AuthOk -->|是| Expired{"授权已过期?"}
Expired -->|是| ToExpired["跳转到授权页并带过期信息"]
Expired -->|否| Target["计算目标路径并替换路由"]
图表来源
章节来源
登录后门针对当前路由做二次判断:
/login,避免登录后跳转到 404。章节来源
bootstrap 是启动调度器,关键分支如下:
注册全局指令、错误处理,挂载应用。
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
图表来源
章节来源
App.vue 的关键职责:
StyleProvider 和 ConfigProvider 提供 Ant Design Vue 样式与主题;getTheme;useLocale 获取 Ant Design Vue 的语言;useTitle 动态更新页面标题;ensureAuthorizationUnit;ensureAuthorizationUnit 会:
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["设置水印"]
图表来源
章节来源
bootstrap 会直接跳转到该路径;error=unreachable。bootstrap 会提前跳转授权页,避免在无地址情况下空等后端。App.vue 使用该函数判断是否在真正有后端的情况下拉取授权信息。章节来源
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"]
图表来源
章节来源
App.vue 挂载后按需拉取,避免阻塞首屏;现象:loading 页一直显示重试提示,最终提示连接失败。
原因:
排查步骤:
testServerConnection 或手动访问健康检查接口;isServerBindingEnabled 与实际部署策略一致;相关位置
现象:页面停留在 loading 状态,没有主界面也没有明确错误。
可能原因:
.app-loading-tip 或 .app-loading-actions。排查步骤:
[bootstrap] waiting for backend to be ready 和重试次数;showReconnectState;相关位置
现象:水印没有显示授权单元,或授权信息未更新。
可能原因:
authorizationInfoApi 请求失败;排查步骤:
isServerSetupMissing() 是否为真;getApiOrigin() 是否返回有效地址;authorizationInfoApi 的返回结果;authorizationUnit;App.vue 的 ensureAuthorizationUnit 是否被执行;相关位置
现象:登录后或启动后跳转到未知页面。
可能原因:
/login 作为回跳来源;VITE_PUBLIC_PATH 前缀处理异常;排查步骤:
getStartupRouteInfo 的 hash 或 pathname 解析;VITE_ROUTE_WEB_HISTORY 和 VITE_PUBLIC_PATH;getAuthorizedTarget 是否把入口页映射到案件页;/login 已不再注册为路由。相关位置
现象:应用无法请求后端,或始终停留在服务地址绑定页。
可能原因:
SERVER_BASE_URL__;排查步骤:
SERVER_BASE_URL__;isServerBindingEnabled 是否启用;getBoundServerOrigin 和 getApiOrigin 返回值;focusMainWindow 和 closeSmartWindow。相关位置
建议在 bootstrap 中现有初始化链之后添加,并确保不影响路由和挂载顺序。推荐插入位置:
app.mount('#app') 之后。示例思路:
bootstrap 中调用;isServerSetupMissing();router.isReady();参考位置
如需增加探测维度(例如同时检查多个后端能力):
waitForBackendReady 成功后再执行;showReconnectState,保持用户体验一致。参考位置
授权缓存涉及两个层面:
useUserStoreWithOut().setPageCache 写入 authorizationLabel、licenseOverDateTime、authorizationUnit;App.vue 读取 authorizationUnit 并写入水印。新增授权字段时:
syncAuthorizationCache 中同步新字段;App.vue 中监听并展示;resolveStartupRoute 或路由守卫中处理;authorizationInfoApi 返回结构兼容;isAuthorizationExpired 和 redirectToExpiredAuthorization 的逻辑。参考位置
main.ts 是前端根应用的启动中枢,负责样式加载、环境检测、后端探测、授权校验、登录门禁和路由挂载;App.vue 负责应用级主题、语言、容器和水印展示。两者共同构成了“启动前预检 → 启动中探测 → 启动后渲染”的稳定流程。
在实际维护中,新增全局逻辑应遵循: