本文引用的文件
本仓库包含一个基于 Electron 的桌面客户端。主进程使用 ee-core 提供的 ElectronEgg 生命周期框架;预加载脚本负责初始化托盘与安全能力,并通过 contextBridge 暴露受限 IPC;前端基于 Vue 3 + Ant Design Vue,完成主题、国际化、水印和授权单元初始化;启动流程会绑定后端地址、健康探测、离线授权校验、登录门禁,并支持智能工作台多窗口场景。地图子系统通过 MapLibre GL 与 PMTiles 协议读取内置或本机离线瓦片数据;自动更新依赖 electron-updater。
graph TB
subgraph "Electron 主进程"
M["main.ts"]
L["preload/lifecycle.ts"]
P["preload/index.ts"]
B["preload/bridge.ts"]
W["controller/windowCtl.ts"]
end
subgraph "前端渲染进程"
FMain["frontend/src/main.ts"]
App["frontend/src/App.vue"]
Window["core/logics/appWindow.ts"]
Server["core/settings/serverSetting.ts"]
License["core/utils/license.ts"]
OfflineMap["core/utils/map/offlineMap.ts"]
end
M --> L
M --> P
M --> B
P -->|"创建托盘/安全服务"| P
FMain --> App
FMain --> Window
App --> License
App --> Server
FMain --> Server
FMain --> License
Window -->|"IPC: windowCtl/*"| W
OfflineMap -->|"IPC: readBinaryFileRange/readTextFile"| W
图示来源
章节来源
ElectronEgg,注册 ready、electron-app-ready、window-ready、before-close 生命周期,并注册 preload。electron.ipcRenderer,不直接暴露全部 Electron API。china.pmtiles。章节来源
sequenceDiagram
participant OS as "操作系统"
participant Main as "主进程 main.ts"
participant Life as "生命周期 lifecycle.ts"
participant Pre as "预加载 index.ts"
participant Bridge as "桥接 bridge.ts"
participant WinCtl as "窗口控制器 windowCtl.ts"
participant Front as "前端 main.ts / App.vue"
OS->>Main: 启动 ElectronEgg
Main->>Life: 注册 ready / electron-app-ready / window-ready / before-close
Main->>Pre: 注册 preload
Pre->>Pre: 创建托盘与安全服务
Pre->>Bridge: 暴露 contextBridge.electron.ipcRenderer
Main->>Front: 加载渲染进程 HTML
Front->>Front: initWindowRole()
Front->>WinCtl: invokeIpc("getWindowRole")
WinCtl-->>Front: { role: "main" | "smart" }
Front->>Front: setupStore/setupI18n/setupRouter
Front->>Front: isServerSetupMissing()
alt 未绑定服务地址
Front->>Front: 跳转授权页(含服务地址卡片)
else 已绑定
Front->>Front: waitForBackendReady(healthApi)
Front->>Front: checkAuthApi()
Front->>Front: resolveAuthorizationCache()
Front->>Front: ensureLoggedIn()
Front->>Front: app.mount("#app")
end
图示来源
主进程只负责最少的启动工作:创建应用、注册生命周期、注册 preload、运行。具体行为由 Lifecycle 实现:
ready:记录 ee-core 应用就绪。electron-appReady:监听 second-instance,双击图标时恢复最小化主窗口,优先聚焦智能工作台。windowReady:根据主屏工作区大小按比例设置主窗口尺寸,并按配置决定是否延迟显示。beforeClose:预留清理逻辑。
flowchart TD
Start(["Electron 启动"]) --> Register["注册生命周期与 preload"]
Register --> Ready["ready"]
Ready --> AppReady["electron-app-ready"]
AppReady --> SecondInstance{"是否第二实例?"}
SecondInstance -->|是| Focus["恢复主窗口<br/>优先聚焦智能窗口"]
SecondInstance -->|否| WindowReady["window-ready"]
Focus --> WindowReady
WindowReady --> SetBounds["按比例设置窗口位置与尺寸"]
SetBounds --> Show{"是否延迟显示?"}
Show -->|是| WaitShow["等待 ready-to-show 后显示"]
Show -->|否| End(["主窗口可用"])
WaitShow --> End
图示来源
章节来源
预加载模块在渲染进程加载前执行,职责是:
contextBridge.exposeInMainWorld('electron', ...) 暴露受限对象。ipcRenderer,避免渲染进程直接访问完整 Electron API。这种设计符合“最小权限”原则:渲染端通过 invokeIpc 调用主进程注册的 IPC,而不是直接操作文件系统、网络或窗口对象。
graph LR
Renderer["渲染进程<br/>Vue 应用"] --> Ctx["contextBridge"]
Ctx --> World["globalThis.electron"]
World --> Ipc["ipcRenderer"]
Ipc --> IPC["主进程 IPC 通道"]
图示来源
章节来源
WindowCtl 是主进程对窗口能力的统一封装,同时承担两类职责:
它的方法统一返回 { success, data? | message },失败时捕获异常并记录日志,避免错误直接抛出到 Electron 层。
classDiagram
class WindowCtl {
+openSmartWindow(params)
+closeSmartWindow()
+isSmartWindowOpen()
+focusMainWindow()
+getWindowRole(params, event)
+syncState(params, event)
}
class BrowserWindow {
+getAllWindows()
+fromWebContents(webContents)
+webContents
+isDestroyed()
}
class SmartWindowService {
+openSmartWindow(options)
+closeSmartWindow()
+isSmartWindowOpen()
+focusSmartWindow()
+focusMainWindow()
}
WindowCtl --> SmartWindowService : "委托窗口操作"
WindowCtl --> BrowserWindow : "枚举/查找窗口"
图示来源
章节来源
App.vue 是 Vue 应用的顶层容器,主要完成:
StyleProvider 和 ConfigProvider 包裹全局 UI。在挂载后尝试获取授权单元:
/sys/info 相关接口,提取 authorizationUnit 并写入 store。授权单元变化时设置或清空水印。
flowchart TD
Mount["App.vue onMounted"] --> HasUnit{"是否有授权单元缓存?"}
HasUnit -->|有| WatchUnit["监听授权单元变化"]
HasUnit -->|无| Missing{"后端地址是否可用?"}
Missing -->|否| Skip["跳过授权请求"]
Missing -->|是| Fetch["调用授权信息接口"]
Fetch --> Extract["提取 authorizationUnit"]
Extract --> Cache["写入页面缓存"]
Cache --> WatchUnit
WatchUnit --> Watermark{"授权单元是否为空?"}
Watermark -->|是| ClearWatermark["清除水印"]
Watermark -->|否| SetWatermark["设置水印"]
图示来源
章节来源
前端引导程序是客户端启动的核心编排器,顺序非常关键:
main。如果已绑定后端地址:
最后挂载应用。
flowchart TD
Bootstrap["bootstrap()"] --> Role["initWindowRole()"]
Role --> InitCore["setupStore/initAppConfigStore/initSessionSync/registerGlobComp"]
InitCore --> I18n["setupI18n()"]
I18n --> Router["setupRouter/setupRouterGuard()"]
Router --> CheckServer{"是否缺少服务地址?"}
CheckServer -->|是| ToAuth["跳转授权页并挂载"]
CheckServer -->|否| Health["waitForBackendReady()"]
Health --> Ready{"后端可连接?"}
Ready -->|否| Reconnect["显示重连/修改地址"]
Ready -->|是| Auth["checkAuthApi() + resolveAuthorizationCache()"]
Auth --> Route["resolveStartupRoute()"]
Route --> Login["ensureLoggedIn()"]
Login --> Mount["app.mount('#app')"]
图示来源
章节来源
服务地址绑定由前端侧管理:
SERVER_BASE_URL__ 直接写入 localStorage,不参与 AES 加密快照。SERVER_BASE_URL_HISTORY__,最多保留 5 条。http:// 或 https://,且不能带业务路径。VITE_GLOB_API_URL_PREFIX 和 VITE_GLOB_ADMIN_PATH 拼接而成。生产构建可通过 VITE_GLOB_REQUIRE_SERVER_SETUP 强制要求启动时绑定地址。
flowchart TD
Input["用户输入服务地址"] --> Normalize["normalizeServerOrigin()"]
Normalize --> Valid{"格式合法?"}
Valid -->|否| Error["提示地址格式错误"]
Valid -->|是| Save["setBoundServerOrigin()"]
Save --> History["rememberServerOrigin()"]
History --> Get["getApiOrigin()"]
Get --> Use["前端 HTTP 请求使用运行时 origin"]
图示来源
章节来源
自动更新依赖 electron-updater,包版本位于 ai-electron/package.json。该依赖表示客户端具备接入自动更新的能力;实际更新策略、发布服务器、增量更新规则通常由打包配置和部署产物决定。
章节来源
离线地图能力由前端侧实现,主进程提供文件读取 IPC:
china.pmtiles。resource/map/china.pmtiles。readBinaryFileRange 以分块方式读取,不走后端。pmtiles:// 协议,key 与 Source 对象的 getKey() 返回值一致。自定义样式 behavior-spacetime-style.json 也可从本机目录读取,失败时回退内置样式。
flowchart TD
Config["离线地图目录"] --> LocalPath{"是否存在本机 china.pmtiles?"}
LocalPath -->|是| UseLocal["ElectronPmtilesSource<br/>readBinaryFileRange"]
LocalPath -->|否| UseStatic["HttpPmtilesSource<br/>内置 resource/map/china.pmtiles"]
UseLocal --> Style["MapLibre 样式 pmtiles://key"]
UseStatic --> Style
Style --> Map["渲染矢量地图"]
图示来源
章节来源
在当前代码库中,未发现对 regInfo.exe 的直接调用;许可证校验主要由前端侧完成:
overDateTime、unit、authorizationLabel 等字段。overDateTime 特殊值和标签字段区分。如果需要集成 regInfo.exe,应遵循现有 IPC 模式:在主进程侧调用可执行程序、收集机器码或许可证结果,再通过 IPC 返回给前端。
章节来源
graph TB
EE["ee-core"]
EU["electron-updater"]
Vue["Vue 3"]
Ant["Ant Design Vue"]
MapLibre["maplibre-gl"]
PMTiles["pmtiles"]
Electron["electron"]
Main["electron/main.ts"] --> EE
Main --> Electron
Lifecycle["preload/lifecycle.ts"] --> EE
Controller["controller/windowCtl.ts"] --> Electron
FMain["frontend/src/main.ts"] --> Vue
FMain --> Ant
App["frontend/src/App.vue"] --> Ant
Offline["core/utils/map/offlineMap.ts"] --> MapLibre
Offline --> PMTiles
Package["package.json"] --> EU
图示来源
章节来源
type 和 payload,接收方自行解释业务。[本节为一般性说明,不直接分析具体代码片段]
Lifecycle 中 second-instance、window-ready 的逻辑是否触发异常。ready、electron-app-ready、window-ready、before-close 的执行顺序。章节来源
globalThis.electron 时报权限错误或方法不存在。contextBridge 暴露的对象可用;当前只暴露 ipcRenderer。contextBridge 暴露受控方法。章节来源
china.pmtiles 文件缺失。readBinaryFileRange 读取。resource/map/china.pmtiles。pmtiles:// key 是否与 Source getKey() 返回值一致。章节来源
App.vue 不会发起授权请求。overDateTime、unit、authorizationLabel。authorizationUnit 是否写入成功。章节来源
frontend/src/plat/views 或对应业务目录下新增 .vue 页面。ensureLoggedIn 能将其重定向到授权页。offlineMap.ts 和 license.ts。章节来源
frontend/src 下合适功能目录。ant-design-vue 组件库时,确保主题和国际化已初始化。App.vue 的 store 或 hooks 中读取。章节来源
推荐做法:
windowCtl 对应 windowCtl 通道。{ success, data? | message }。invokeIpc 调用。示例参考:
章节来源
推荐做法:
electron/service 下,按系统能力划分目录。create() 工厂方法,供 preload 初始化。trayService.create()、securityService.create() 模式启动。章节来源
桌面客户端采用清晰的主进程-预加载-渲染进程分层:主进程专注应用生命周期和多窗口协调,预加载负责最小权限桥接,前端负责业务启动编排。服务地址绑定、健康探测、授权校验、登录门禁和离线地图共同构成完整的客户端启动体验。新增功能应遵循现有 IPC 契约、窗口角色判断和授权流程,以保持多窗口行为和用户体验一致。
[本节为总结性内容,不直接分析具体代码片段]