桌面客户端.md 26 KB

桌面客户端

本文引用的文件

  • electron/main.ts
  • preload/lifecycle.ts
  • preload/index.ts
  • preload/bridge.ts
  • controller/windowCtl.ts
  • frontend/src/App.vue
  • frontend/src/main.ts
  • frontend/src/core/logics/appWindow.ts
  • frontend/src/core/settings/serverSetting.ts
  • frontend/src/core/utils/license.ts
  • frontend/src/core/utils/map/offlineMap.ts
  • package.json

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与行为特性
  8. 常见问题排查
  9. 扩展指南:新增页面、组件、IPC 与服务
  10. 结论

简介

本仓库包含一个基于 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

图示来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73
  • preload/index.ts:1-16
  • preload/bridge.ts:1-10
  • controller/windowCtl.ts:1-123
  • frontend/src/main.ts:1-399
  • frontend/src/App.vue:1-85
  • frontend/src/core/logics/appWindow.ts:1-183
  • frontend/src/core/settings/serverSetting.ts:1-248
  • frontend/src/core/utils/license.ts:1-124
  • frontend/src/core/utils/map/offlineMap.ts:1-228

章节来源

  • electron/main.ts:1-19
  • frontend/src/main.ts:1-399

核心组件

  • 主进程入口:创建 ElectronEgg,注册 ready、electron-app-ready、window-ready、before-close 生命周期,并注册 preload。
  • 生命周期管理:处理双实例聚焦、主窗口尺寸定位、延迟显示、智能窗口焦点切换。
  • 预加载桥接:创建托盘和安全服务,仅向渲染进程暴露 electron.ipcRenderer,不直接暴露全部 Electron API。
  • 窗口控制器:统一封装打开/关闭/查询智能窗口、聚焦主窗口、按 webContents 判断角色、跨窗口状态同步。
  • 前端引导程序:解析窗口角色、初始化 Store/路由/i18n、检测后端地址与健康、授权校验、登录门禁、挂载应用。
  • 授权与许可证:解析服务端返回的授权字段、计算过期时间、区分试用与正式授权、写入本地缓存。
  • 服务地址绑定:把用户输入的 http/https origin 保存到 localStorage,构建健康检查 URL,并在未绑定时阻止正常启动。
  • 离线地图:根据配置优先从本机绝对路径读取 PMTiles,否则回退到前端静态资源中的 china.pmtiles。

章节来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73
  • preload/index.ts:1-16
  • preload/bridge.ts:1-10
  • controller/windowCtl.ts:1-123
  • frontend/src/main.ts:1-399
  • frontend/src/core/utils/license.ts:1-124
  • frontend/src/core/settings/serverSetting.ts:1-248
  • frontend/src/core/utils/map/offlineMap.ts:1-228

架构总览

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

图示来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73
  • preload/index.ts:1-16
  • preload/bridge.ts:1-10
  • controller/windowCtl.ts:1-123
  • frontend/src/main.ts:1-399

详细组件分析

主进程生命周期

主进程只负责最少的启动工作:创建应用、注册生命周期、注册 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
    

图示来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73

章节来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73

预加载桥接的安全模型

预加载模块在渲染进程加载前执行,职责是:

  1. 初始化托盘服务和系统安全服务。
  2. 通过 contextBridge.exposeInMainWorld('electron', ...) 暴露受限对象。
  3. 当前只暴露 ipcRenderer,避免渲染进程直接访问完整 Electron API。

这种设计符合“最小权限”原则:渲染端通过 invokeIpc 调用主进程注册的 IPC,而不是直接操作文件系统、网络或窗口对象。

graph LR
    Renderer["渲染进程<br/>Vue 应用"] --> Ctx["contextBridge"]
    Ctx --> World["globalThis.electron"]
    World --> Ipc["ipcRenderer"]
    Ipc --> IPC["主进程 IPC 通道"]

图示来源

  • preload/bridge.ts:1-10
  • controller/windowCtl.ts:1-123

章节来源

  • preload/index.ts:1-16
  • preload/bridge.ts:1-10

窗口控制器与服务封装

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 : "枚举/查找窗口"

图示来源

  • controller/windowCtl.ts:1-123

章节来源

  • controller/windowCtl.ts:1-123

前端根组件 App.vue 初始化流程

App.vue 是 Vue 应用的顶层容器,主要完成:

  1. 使用 Ant Design Vue 的 StyleProvider 和 ConfigProvider 包裹全局 UI。
  2. 初始化语言配置、深色模式、主题色、圆角等视觉 token。
  3. 初始化标题监听和水印钩子。
  4. 在挂载后尝试获取授权单元:

    • 若已有缓存则跳过。
    • 若尚未绑定后端地址,则不调用后端。
    • 调用 /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["设置水印"]
      

图示来源

  • frontend/src/App.vue:1-85
  • frontend/src/core/utils/license.ts:1-124

章节来源

  • frontend/src/App.vue:1-85

前端 main.ts 应用挂载流程

前端引导程序是客户端启动的核心编排器,顺序非常关键:

  1. 解析窗口角色:桌面端通过 IPC 询问主进程,浏览器端回退为 main。
  2. 初始化全局弹窗行为、Store、内部配置、跨窗口会话同步、全局组件、国际化、路由和守卫。
  3. 如果未绑定后端地址:
    • 智能窗口中先聚焦主窗口并关闭自身。
    • 主窗口跳转到授权页,挂载应用。
  4. 如果已绑定后端地址:

    • 非授权/服务地址页时进行最多 10 次 × 3 秒的健康探测。
    • 连接失败时停在 loading 页,提供重连或修改服务地址。
    • 连接成功后执行授权校验、首次导航落定、登录态检查。
    • 智能窗口遇到授权页时关闭自身,让主窗口处理提示。
    • 最后挂载应用。

      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')"]
      

图示来源

  • frontend/src/main.ts:1-399
  • frontend/src/core/logics/appWindow.ts:1-183

章节来源

  • frontend/src/main.ts:1-399
  • frontend/src/core/logics/appWindow.ts:1-183

客户端与服务端地址绑定及 localStorage 缓存

服务地址绑定由前端侧管理:

  • 键名 SERVER_BASE_URL__ 直接写入 localStorage,不参与 AES 加密快照。
  • 最近成功地址保存在 SERVER_BASE_URL_HISTORY__,最多保留 5 条。
  • 输入值必须为 http:// 或 https://,且不能带业务路径。
  • 健康检查 URL 由 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"]
    

图示来源

  • frontend/src/core/settings/serverSetting.ts:1-248

章节来源

  • frontend/src/core/settings/serverSetting.ts:1-248

自动更新(electron-updater)

自动更新依赖 electron-updater,包版本位于 ai-electron/package.json。该依赖表示客户端具备接入自动更新的能力;实际更新策略、发布服务器、增量更新规则通常由打包配置和部署产物决定。

章节来源

  • package.json:38-42

离线地图(MapLibre GL + PMTiles china.pmtiles)

离线地图能力由前端侧实现,主进程提供文件读取 IPC:

  • 若配置了本机离线地图目录,则优先使用本机绝对路径的 china.pmtiles。
  • 未配置时回退到前端静态资源中的 resource/map/china.pmtiles。
  • 本机路径通过 readBinaryFileRange 以分块方式读取,不走后端。
  • 样式 JSON 中的 vector source 使用 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["渲染矢量地图"]
    

图示来源

  • frontend/src/core/utils/map/offlineMap.ts:1-228
  • frontend/public/resource/map/behavior-spacetime-style.json:5-9

章节来源

  • frontend/src/core/utils/map/offlineMap.ts:1-228

regInfo.exe 与许可证校验

在当前代码库中,未发现对 regInfo.exe 的直接调用;许可证校验主要由前端侧完成:

  • 前端调用授权相关接口,解析 overDateTime、unit、authorizationLabel 等字段。
  • 若授权过期,引导用户进入授权页并展示提示信息。
  • 授权单元用于生成水印。
  • 试用与正式授权通过 overDateTime 特殊值和标签字段区分。

如果需要集成 regInfo.exe,应遵循现有 IPC 模式:在主进程侧调用可执行程序、收集机器码或许可证结果,再通过 IPC 返回给前端。

章节来源

  • frontend/src/core/utils/license.ts:1-124
  • frontend/src/main.ts:1-399

依赖关系分析

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

图示来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73
  • controller/windowCtl.ts:1-123
  • frontend/src/main.ts:1-399
  • frontend/src/App.vue:1-85
  • frontend/src/core/utils/map/offlineMap.ts:1-228
  • package.json:38-42

章节来源

  • package.json:38-42

性能与行为特性

  • 启动探测上限固定:最多 10 次健康探测,每次不超过 3 秒,整体约 30 秒,避免重试时间膨胀。
  • 窗口角色优先于路由:通过 IPC 判断主窗口与智能窗口,避免路由替换导致 query 丢失。
  • 智能窗口只承载工作台:遇到授权失效或登录入口时主动关闭自身,由主窗口统一提示。
  • 跨窗口状态广播轻量:只转发 type 和 payload,接收方自行解释业务。
  • 离线地图按需分块读取:PMTiles 通过 Range 或 IPC 分块取数据,避免一次性加载整个瓦片文件。
  • 服务地址明文存储但非敏感:便于排障,且不受通用缓存清理影响。

[本节为一般性说明,不直接分析具体代码片段]

常见问题排查

主进程崩溃

  • 现象:桌面应用闪退、无法打开、任务栏图标消失。
  • 重点检查:
    • Lifecycle 中 second-instance、window-ready 的逻辑是否触发异常。
    • 主进程是否成功注册 preload。
    • 智能窗口相关服务是否可正常创建。
  • 建议:查看主进程日志输出,确认 ready、electron-app-ready、window-ready、before-close 的执行顺序。

章节来源

  • electron/main.ts:1-19
  • preload/lifecycle.ts:1-73

preload 权限不足

  • 现象:渲染进程访问 globalThis.electron 时报权限错误或方法不存在。
  • 原因:上下文隔离下只有 contextBridge 暴露的对象可用;当前只暴露 ipcRenderer。
  • 解决:
    • 不要假设渲染进程可直接调用 Electron API。
    • 如需新能力,应在主进程注册 IPC,并在 preload 中通过 contextBridge 暴露受控方法。
    • 注意不要在 bridge 中泄露危险原生对象。

章节来源

  • preload/bridge.ts:1-10

地图加载失败

  • 现象:轨迹图、基站图或行为时空图中地图空白、无瓦片。
  • 可能原因:
    • 本机离线地图目录未配置或路径无效。
    • china.pmtiles 文件缺失。
    • 自定义样式 JSON 不可读。
    • 内置静态资源未被正确打包。
  • 排查步骤:
    1. 确认是否配置了本机离线地图目录。
    2. 检查本机路径是否能被 readBinaryFileRange 读取。
    3. 检查是否回退到 resource/map/china.pmtiles。
    4. 检查样式文件中 pmtiles:// key 是否与 Source getKey() 返回值一致。

章节来源

  • frontend/src/core/utils/map/offlineMap.ts:1-228

授权信息不显示

  • 现象:页面没有水印,或顶部/设置中看不到授权单位、试用标识。
  • 可能原因:
    • 后端地址未绑定,App.vue 不会发起授权请求。
    • 授权接口返回字段不符合预期。
    • 授权已过期,前端直接跳转到授权页。
    • 授权单元为空字符串。
  • 排查步骤:
    1. 确认已绑定服务地址并能连通后端。
    2. 检查授权接口返回结构中是否存在 overDateTime、unit、authorizationLabel。
    3. 检查授权是否被判定为过期。
    4. 检查 store 中 authorizationUnit 是否写入成功。

章节来源

  • frontend/src/App.vue:1-85
  • frontend/src/core/utils/license.ts:1-124
  • frontend/src/main.ts:1-399

扩展指南:新增页面、组件、IPC 和服务

新增前端页面

  1. 在 frontend/src/plat/views 或对应业务目录下新增 .vue 页面。
  2. 在路由配置中注册页面路径。
  3. 如果页面需要登录后才能访问,确保 ensureLoggedIn 能将其重定向到授权页。
  4. 如果页面涉及地图或授权信息,复用 offlineMap.ts 和 license.ts。

章节来源

  • frontend/src/main.ts:1-399

新增前端组件

  1. 放在 frontend/src 下合适功能目录。
  2. 使用 ant-design-vue 组件库时,确保主题和国际化已初始化。
  3. 如果需要水印或授权单元,从 App.vue 的 store 或 hooks 中读取。

章节来源

  • frontend/src/App.vue:1-85

新增 IPC 接口

推荐做法:

  1. 在主进程 service 或 controller 中实现方法。
  2. 使用 ee-core 的文件名自动注册机制,例如 windowCtl 对应 windowCtl 通道。
  3. 返回统一结构 { success, data? | message }。
  4. 在 preload 或前端工具中通过 invokeIpc 调用。

示例参考:

  • 主进程窗口控制器:controller/windowCtl.ts:1-123
  • 前端调用窗口控制器:frontend/src/core/logics/appWindow.ts:1-183

章节来源

  • controller/windowCtl.ts:1-123
  • frontend/src/core/logics/appWindow.ts:1-183

新增 Electron service

推荐做法:

  1. 放在 electron/service 下,按系统能力划分目录。
  2. 提供 create() 工厂方法,供 preload 初始化。
  3. 通过 preload 的 trayService.create()、securityService.create() 模式启动。
  4. 对外暴露稳定能力,不直接暴露底层 Electron API。

章节来源

  • preload/index.ts:1-16

结论

桌面客户端采用清晰的主进程-预加载-渲染进程分层:主进程专注应用生命周期和多窗口协调,预加载负责最小权限桥接,前端负责业务启动编排。服务地址绑定、健康探测、授权校验、登录门禁和离线地图共同构成完整的客户端启动体验。新增功能应遵循现有 IPC 契约、窗口角色判断和授权流程,以保持多窗口行为和用户体验一致。

[本节为总结性内容,不直接分析具体代码片段]