382 lines
8.9 KiB
Markdown
382 lines
8.9 KiB
Markdown
# 运行时架构
|
||
|
||
本文档说明项目在运行时的主要分层、进程边界和核心调用路径，帮助开发者理解请求是如何从 React 页面一路进入主进程服务的。
|
||
|
||
## 1. 运行时结构
|
||
|
||
项目运行时由三部分组成：
|
||
|
||
- Electron `main` 进程
|
||
- Electron `preload`
|
||
- Electron `renderer` 渲染进程
|
||
|
||
它们之间的关系如下：
|
||
|
||
```mermaid
|
||
graph LR
|
||
Renderer[Renderer\nReact Pages / Hooks / Components]
|
||
Preload[Preload\nDomain APIs + IPC Wrapper]
|
||
IPC[IPC Handlers]
|
||
Services[Main Services]
|
||
External[DB / ERP / Files / Update Source]
|
||
|
||
Renderer --> Preload
|
||
Preload --> IPC
|
||
IPC --> Services
|
||
Services --> External
|
||
```
|
||
|
||
如果从 Electron 的进程边界来理解，可以进一步看成：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph RendererProcess[Renderer Process]
|
||
UI[Pages / Components]
|
||
Hooks[Hooks / Stores]
|
||
end
|
||
|
||
subgraph PreloadLayer[Preload Layer]
|
||
Facade[Domain APIs]
|
||
IPCClient[ipc wrapper]
|
||
end
|
||
|
||
subgraph MainProcess[Main Process]
|
||
Bootstrap[Bootstrap]
|
||
Handlers[IPC Handlers]
|
||
DomainServices[Domain Services]
|
||
end
|
||
|
||
UI --> Hooks
|
||
Hooks --> Facade
|
||
Facade --> IPCClient
|
||
IPCClient --> Handlers
|
||
Handlers --> DomainServices
|
||
Bootstrap --> Handlers
|
||
```
|
||
|
||
## 2. Main 进程
|
||
|
||
主进程是应用的执行中心，负责：
|
||
|
||
- 应用启动和窗口创建
|
||
- 进程守卫和异常处理
|
||
- IPC 注册
|
||
- 配置、日志、数据库、文件、更新等系统能力
|
||
- ERP 自动化与业务流程执行
|
||
|
||
关键入口文件：
|
||
|
||
- `src/main/index.ts`
|
||
- `src/main/bootstrap/main-window.ts`
|
||
- `src/main/bootstrap/runtime.ts`
|
||
- `src/main/bootstrap/process-guards.ts`
|
||
|
||
### 2.1 Bootstrap 层
|
||
|
||
`bootstrap/` 负责把主进程入口收敛成薄启动文件。
|
||
|
||
当前主要模块：
|
||
|
||
- `main-window.ts`
|
||
创建 `BrowserWindow`，配置窗口行为与生命周期。
|
||
- `runtime.ts`
|
||
负责运行时初始化、服务初始化和 IPC 注册。
|
||
- `process-guards.ts`
|
||
负责全局异常、未处理拒绝和进程级兜底。
|
||
|
||
bootstrap 层内部关系如下：
|
||
|
||
```mermaid
|
||
graph TD
|
||
Index[index.ts]
|
||
Guards[process-guards.ts]
|
||
Runtime[runtime.ts]
|
||
Window[main-window.ts]
|
||
AppReady[app.whenReady]
|
||
|
||
Index --> Guards
|
||
Index --> AppReady
|
||
AppReady --> Runtime
|
||
AppReady --> Window
|
||
```
|
||
|
||
### 2.2 IPC 层
|
||
|
||
`src/main/ipc/` 中的 handler 负责注册 IPC 通道，并把请求转发到应用服务或领域服务。
|
||
|
||
当前主要 handler 包括：
|
||
|
||
- `auth-handler.ts`
|
||
- `cleaner-handler.ts`
|
||
- `extractor-handler.ts`
|
||
- `validation-handler.ts`
|
||
- `update-handler.ts`
|
||
- `settings-handler.ts`
|
||
- `report-handler.ts`
|
||
|
||
当前设计目标是：handler 尽量保持“薄壳”，只做参数接收、错误包装和 service 转发。
|
||
|
||
这层的目标结构是：
|
||
|
||
```mermaid
|
||
graph LR
|
||
Request[IPC Request]
|
||
Handler[Handler]
|
||
AppService[Application Service]
|
||
DomainService[Domain Service / Repository]
|
||
Response[IpcResult Response]
|
||
|
||
Request --> Handler
|
||
Handler --> AppService
|
||
AppService --> DomainService
|
||
DomainService --> AppService
|
||
AppService --> Handler
|
||
Handler --> Response
|
||
```
|
||
|
||
### 2.3 Services 层
|
||
|
||
`src/main/services/` 是主进程的核心实现层。
|
||
|
||
主要领域：
|
||
|
||
- `auth/`
|
||
用户登录、silent login、用户切换。
|
||
- `cleaner/`
|
||
ERP 清理执行编排。
|
||
- `update/`
|
||
更新目录拉取、状态广播、下载和安装。
|
||
- `validation/`
|
||
物料校验、共享订单号、数据库查询封装。
|
||
- `config/`
|
||
配置加载与保存。
|
||
- `logger/`
|
||
日志服务。
|
||
- `report/`
|
||
报告查询与下载。
|
||
|
||
当前主进程服务从领域上大致可视化为：
|
||
|
||
```mermaid
|
||
graph TD
|
||
Services[services/]
|
||
Auth[auth]
|
||
Validation[validation]
|
||
Cleaner[cleaner]
|
||
Update[update]
|
||
Config[config]
|
||
ERP[erp]
|
||
Report[report]
|
||
Logger[logger]
|
||
|
||
Services --> Auth
|
||
Services --> Validation
|
||
Services --> Cleaner
|
||
Services --> Update
|
||
Services --> Config
|
||
Services --> ERP
|
||
Services --> Report
|
||
Services --> Logger
|
||
```
|
||
|
||
## 3. Preload 层
|
||
|
||
preload 是 renderer 与 main 之间的桥接层，负责把 IPC 能力封装成按领域组织的 API。
|
||
|
||
关键入口文件：
|
||
|
||
- `src/preload/index.ts`
|
||
- `src/preload/index.d.ts`
|
||
|
||
当前 preload 内部结构：
|
||
|
||
- `src/preload/api/`
|
||
按领域拆分的 API facade
|
||
- `src/preload/lib/ipc.ts`
|
||
统一的 IPC 调用封装
|
||
|
||
当前已经拆分出的 API 模块包括：
|
||
|
||
- `auth.ts`
|
||
- `cleaner.ts`
|
||
- `database.ts`
|
||
- `extractor.ts`
|
||
- `file.ts`
|
||
- `logger.ts`
|
||
- `materials.ts`
|
||
- `process.ts`
|
||
- `resolver.ts`
|
||
- `validation.ts`
|
||
|
||
preload 组织方式如下：
|
||
|
||
```mermaid
|
||
graph TD
|
||
Preload[index.ts]
|
||
API[api/index.ts]
|
||
IPC[lib/ipc.ts]
|
||
Auth[api/auth.ts]
|
||
Cleaner[api/cleaner.ts]
|
||
Extractor[api/extractor.ts]
|
||
Validation[api/validation.ts]
|
||
UpdateLike[api/process.ts / logger.ts / file.ts]
|
||
|
||
Preload --> API
|
||
API --> Auth
|
||
API --> Cleaner
|
||
API --> Extractor
|
||
API --> Validation
|
||
API --> UpdateLike
|
||
API --> IPC
|
||
```
|
||
|
||
preload 的职责不是承载业务，而是：
|
||
|
||
- 隐藏 IPC 细节
|
||
- 为 renderer 提供稳定的调用接口
|
||
- 维持类型边界
|
||
|
||
## 4. Renderer 层
|
||
|
||
renderer 是 React 应用本体，负责页面展示、交互和前端状态管理。
|
||
|
||
关键入口文件：
|
||
|
||
- `src/renderer/src/main.tsx`
|
||
- `src/renderer/src/App.tsx`
|
||
|
||
当前主要目录：
|
||
|
||
- `pages/`
|
||
页面级容器，例如 `ExtractorPage`、`CleanerPage`、`SettingsPage`
|
||
- `components/`
|
||
通用 UI、业务组件、对话框
|
||
- `hooks/`
|
||
页面逻辑、状态收敛、bridge 调用编排
|
||
- `stores/`
|
||
状态存储与消息提示
|
||
- `lib/`
|
||
前端侧辅助工具和持久化 helper
|
||
|
||
renderer 层当前结构可以简化为：
|
||
|
||
```mermaid
|
||
graph TD
|
||
App[App.tsx]
|
||
Pages[pages/]
|
||
Components[components/]
|
||
Hooks[hooks/]
|
||
Stores[stores/]
|
||
Lib[lib/]
|
||
|
||
App --> Pages
|
||
Pages --> Components
|
||
Pages --> Hooks
|
||
Hooks --> Stores
|
||
Hooks --> Lib
|
||
```
|
||
|
||
## 5. 一次典型调用链
|
||
|
||
以 Cleaner 校验流程为例，一次从页面到主进程的调用链大致如下：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant UI as CleanerPage / useCleaner
|
||
participant Preload as preload.validation
|
||
participant IPC as validation-handler
|
||
participant AppSvc as validation-application-service
|
||
participant DB as database / repository
|
||
|
||
UI->>Preload: validate(request)
|
||
Preload->>IPC: ipcRenderer.invoke(...)
|
||
IPC->>AppSvc: service.validate(...)
|
||
AppSvc->>DB: query / enrich / aggregate
|
||
DB-->>AppSvc: validation results
|
||
AppSvc-->>IPC: payload
|
||
IPC-->>Preload: IpcResult
|
||
Preload-->>UI: normalized response
|
||
```
|
||
|
||
## 6. 页面与模块关系
|
||
|
||
当前主要页面与主进程模块的对应关系大致如下：
|
||
|
||
- `ExtractorPage`
|
||
对应 `extractor`、`validation`
|
||
- `CleanerPage`
|
||
对应 `validation`、`cleaner`、`materials`、`report`
|
||
- `SettingsPage`
|
||
对应 `settings`、`config`
|
||
- `UpdateDialog`
|
||
对应 `update`
|
||
|
||
```mermaid
|
||
graph LR
|
||
ExtractorPage --> ExtractorSvc[extractor / validation]
|
||
CleanerPage --> CleanerSvc[validation / cleaner / report]
|
||
SettingsPage --> SettingsSvc[settings / config]
|
||
UpdateDialog --> UpdateSvc[update]
|
||
```
|
||
|
||
## 7. 事件与状态流
|
||
|
||
项目里常见的状态流主要有三类：
|
||
|
||
- 页面内局部状态
|
||
例如表单输入、当前选中项、弹窗开关。
|
||
- preload bridge 调用结果
|
||
例如查询结果、校验结果、更新目录。
|
||
- 主进程主动推送事件
|
||
例如 cleaner 执行进度、update 状态变化。
|
||
|
||
当前典型事件订阅点包括：
|
||
|
||
- `window.electron.cleaner.onProgress(...)`
|
||
- `window.electron.update.onStatusChanged(...)`
|
||
- `window.electron.extractor.onProgress(...)`
|
||
- `window.electron.extractor.onLog(...)`
|
||
|
||
事件流可以概括成：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Main as Main Service
|
||
participant IPC as IPC / Preload
|
||
participant Hook as Renderer Hook
|
||
participant UI as React UI
|
||
|
||
Main->>IPC: push progress/status
|
||
IPC->>Hook: onProgress / onStatusChanged
|
||
Hook->>UI: update state
|
||
UI->>UI: rerender
|
||
```
|
||
|
||
## 8. 当前架构特点
|
||
|
||
当前项目运行时架构有几个比较明显的特点：
|
||
|
||
- 主进程侧已经完成一轮职责收敛，bootstrap、handler、service 边界更清晰
|
||
- preload 已从大文件重组为按领域组织的 facade
|
||
- renderer 正在从“大页面 + 大 hook”逐步收敛为更小的页面边界
|
||
- 更新模块、validation 模块、Cleaner 页面都已经完成阶段性重构
|
||
|
||
## 9. 开发建议
|
||
|
||
在这个运行时架构下，建议按下面原则进行开发：
|
||
|
||
- 新业务优先落在 main service，而不是直接堆到 handler
|
||
- renderer 不直接感知 IPC channel，统一走 preload facade
|
||
- 页面容器尽量只负责组装，复杂流程下沉到 hook
|
||
- 共享类型优先放在稳定的 `types/` 目录
|
||
- 重要状态流尽量画出调用链或补单测
|
||
|
||
## 10. 后续阅读
|
||
|
||
如果你已经理解了运行时分层，下一步建议继续读：
|
||
|
||
- 后续的 `modules/cleaner.md`
|
||
- 后续的 `modules/extractor.md`
|
||
- 后续的 `modules/validation.md`
|
||
- 后续的 `modules/update.md`
|