docs: add developer architecture handbook
This commit is contained in:
Misaka
@@ -66,7 +66,10 @@ docs/developer/
|
|||||||
- 新增核心模块时，同步补一篇对应的模块文档
|
- 新增核心模块时，同步补一篇对应的模块文档
|
||||||
- 发生重要重构时，更新相关架构文档和决策记录
|
- 发生重要重构时，更新相关架构文档和决策记录
|
||||||
- 文档优先解释“职责、边界、调用关系”，而不是堆砌实现细节
|
- 文档优先解释“职责、边界、调用关系”，而不是堆砌实现细节
|
||||||
- 每篇文档尽量附上关键文件路径和 `mermaid` 图
|
- 文档应当多用、善用 `mermaid` 做图形化表达
|
||||||
|
- 遇到结构、分层、调用链、时序、流程时，优先考虑先画图再解释
|
||||||
|
- 图负责帮助读者快速建立整体认知，文字负责解释细节和边界
|
||||||
|
- 文档尽量附上关键文件路径，并保持图和正文一一对应
|
||||||
- 文档中的路径、模块名、调用链描述应与当前代码保持一致
|
- 文档中的路径、模块名、调用链描述应与当前代码保持一致
|
||||||
|
|
||||||
## 当前状态
|
## 当前状态
|
||||||
|
|||||||
273
docs/developer/architecture/data-flow.md
Normal file
273
docs/developer/architecture/data-flow.md
Normal file
@@ -0,0 +1,273 @@
|
|||||||
|
# 数据流
|
||||||
|
|
||||||
|
本文档聚焦项目中的核心数据流，帮助开发者理解关键业务数据如何在 `renderer`、`preload`、`main` 和外部系统之间流动。
|
||||||
|
|
||||||
|
## 1. 数据流总览
|
||||||
|
|
||||||
|
项目中的数据大致分成五类：
|
||||||
|
|
||||||
|
- 用户输入数据
|
||||||
|
- 页面状态数据
|
||||||
|
- IPC 请求与响应数据
|
||||||
|
- 主进程领域数据
|
||||||
|
- 外部系统数据
|
||||||
|
|
||||||
|
整体关系如下：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
User[用户输入]
|
||||||
|
Renderer[Renderer State]
|
||||||
|
Preload[Preload API]
|
||||||
|
IPC[IPC Handlers]
|
||||||
|
Services[Main Services]
|
||||||
|
External[DB / ERP / Files / Update Source]
|
||||||
|
|
||||||
|
User --> Renderer
|
||||||
|
Renderer --> Preload
|
||||||
|
Preload --> IPC
|
||||||
|
IPC --> Services
|
||||||
|
Services --> External
|
||||||
|
External --> Services
|
||||||
|
Services --> IPC
|
||||||
|
IPC --> Preload
|
||||||
|
Preload --> Renderer
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 提取到清理的主数据流
|
||||||
|
|
||||||
|
项目里最核心的一条数据流是：
|
||||||
|
|
||||||
|
1. 用户输入订单号
|
||||||
|
2. Extractor 执行提取
|
||||||
|
3. 共享 Production IDs
|
||||||
|
4. Cleaner 基于共享数据做校验
|
||||||
|
5. 保存删除计划
|
||||||
|
6. 执行 ERP 清理
|
||||||
|
7. 生成报告与导出
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Input[订单号输入]
|
||||||
|
Extractor[Extractor 提取]
|
||||||
|
SharedIds[共享 Production IDs]
|
||||||
|
Validation[物料校验]
|
||||||
|
Plan[删除计划]
|
||||||
|
Cleaner[ERP 清理执行]
|
||||||
|
Report[报告 / 导出]
|
||||||
|
|
||||||
|
Input --> Extractor
|
||||||
|
Input --> SharedIds
|
||||||
|
Extractor --> SharedIds
|
||||||
|
SharedIds --> Validation
|
||||||
|
Validation --> Plan
|
||||||
|
Plan --> Cleaner
|
||||||
|
Cleaner --> Report
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Renderer 内部数据流
|
||||||
|
|
||||||
|
在 renderer 中，数据通常按下面路径流动：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
UI[页面 / 组件]
|
||||||
|
Hook[Hook]
|
||||||
|
Store[Store / Local State]
|
||||||
|
Bridge[window.electron facade]
|
||||||
|
|
||||||
|
UI --> Hook
|
||||||
|
Hook --> Store
|
||||||
|
Hook --> Bridge
|
||||||
|
Bridge --> Hook
|
||||||
|
Hook --> UI
|
||||||
|
```
|
||||||
|
|
||||||
|
具体表现为：
|
||||||
|
|
||||||
|
- 页面组件负责接收用户输入和渲染状态
|
||||||
|
- hook 负责请求编排、局部状态和副作用管理
|
||||||
|
- store 负责消息提示、日志或跨组件状态
|
||||||
|
- preload facade 负责把 bridge 调用标准化
|
||||||
|
|
||||||
|
## 4. Authentication 数据流
|
||||||
|
|
||||||
|
认证流程是应用启动时最先发生的一条数据流。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant App as App / useAppBootstrap
|
||||||
|
participant Preload as preload.auth
|
||||||
|
participant Handler as auth-handler
|
||||||
|
participant AppSvc as auth-application-service
|
||||||
|
participant Session as session-manager
|
||||||
|
|
||||||
|
App->>Preload: getComputerName()
|
||||||
|
App->>Preload: silentLogin()
|
||||||
|
Preload->>Handler: invoke auth channel
|
||||||
|
Handler->>AppSvc: silentLogin()
|
||||||
|
AppSvc->>Session: resolve session / user
|
||||||
|
Session-->>AppSvc: user info
|
||||||
|
AppSvc-->>Handler: login result
|
||||||
|
Handler-->>Preload: IpcResult
|
||||||
|
Preload-->>App: auth state
|
||||||
|
```
|
||||||
|
|
||||||
|
这条链路最终驱动：
|
||||||
|
|
||||||
|
- `UnauthenticatedApp`
|
||||||
|
- `AuthenticatedAppShell`
|
||||||
|
- 管理员代切用户流程
|
||||||
|
|
||||||
|
## 5. Extractor 数据流
|
||||||
|
|
||||||
|
Extractor 模块的数据流重点在“订单号输入”和“提取执行结果”。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant Page as ExtractorPage
|
||||||
|
participant Persist as usePersistentTextState
|
||||||
|
participant Shared as useSharedProductionIds
|
||||||
|
participant Hook as useExtractor
|
||||||
|
participant Preload as preload.extractor / validation
|
||||||
|
participant Main as extractor-handler + services
|
||||||
|
|
||||||
|
Page->>Persist: 保存订单号输入
|
||||||
|
Page->>Shared: debounce 同步共享 Production IDs
|
||||||
|
Page->>Hook: startExtraction(orderNumbers)
|
||||||
|
Hook->>Preload: setSharedProductionIds()
|
||||||
|
Hook->>Preload: runExtractor()
|
||||||
|
Preload->>Main: invoke
|
||||||
|
Main-->>Preload: extraction result
|
||||||
|
Preload-->>Hook: result
|
||||||
|
Hook-->>Page: progress / logs / complete
|
||||||
|
```
|
||||||
|
|
||||||
|
这里当前有两类数据：
|
||||||
|
|
||||||
|
- 持久化输入数据
|
||||||
|
通过 `sessionStorage`
|
||||||
|
- 跨模块共享数据
|
||||||
|
通过 `validation` 模块中的 shared production IDs
|
||||||
|
|
||||||
|
## 6. Validation / Cleaner 数据流
|
||||||
|
|
||||||
|
Cleaner 页面的数据流相对更复杂，包含筛选、校验、选择、保存和执行几个阶段。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
ValidationInput[校验模式 / 共享订单号]
|
||||||
|
Validate[请求校验]
|
||||||
|
Results[validationResults]
|
||||||
|
Filter[filteredResults]
|
||||||
|
Selection[selectedItems]
|
||||||
|
Plan[保存删除计划]
|
||||||
|
Execute[执行 ERP 清理]
|
||||||
|
Progress[progress]
|
||||||
|
Report[执行报告]
|
||||||
|
|
||||||
|
ValidationInput --> Validate
|
||||||
|
Validate --> Results
|
||||||
|
Results --> Filter
|
||||||
|
Results --> Selection
|
||||||
|
Filter --> Selection
|
||||||
|
Selection --> Plan
|
||||||
|
Plan --> Execute
|
||||||
|
Execute --> Progress
|
||||||
|
Execute --> Report
|
||||||
|
```
|
||||||
|
|
||||||
|
这一块当前的关键状态都集中在：
|
||||||
|
|
||||||
|
- `useCleaner`
|
||||||
|
- `src/renderer/src/hooks/cleaner/api.ts`
|
||||||
|
- `src/renderer/src/hooks/cleaner/helpers.ts`
|
||||||
|
|
||||||
|
## 7. Update 数据流
|
||||||
|
|
||||||
|
更新模块的数据流分成两部分：
|
||||||
|
|
||||||
|
- 被动状态流
|
||||||
|
main 进程通过事件推送状态变化
|
||||||
|
- 主动拉取流
|
||||||
|
renderer 在打开对话框或刷新时拉取 catalog / status / changelog
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant Hook as useAppBootstrap
|
||||||
|
participant Dialog as useUpdateDialogState
|
||||||
|
participant Preload as preload.update
|
||||||
|
participant Main as update-handler / update services
|
||||||
|
|
||||||
|
Main->>Preload: onStatusChanged
|
||||||
|
Preload->>Hook: update status event
|
||||||
|
Hook->>Preload: getStatus()
|
||||||
|
Hook->>Preload: getCatalog()
|
||||||
|
Dialog->>Preload: getChangelog(release)
|
||||||
|
Preload->>Main: invoke
|
||||||
|
Main-->>Preload: status / catalog / changelog
|
||||||
|
Preload-->>Hook: normalized result
|
||||||
|
Preload-->>Dialog: changelog content
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. 事件推送型数据流
|
||||||
|
|
||||||
|
项目中有一部分状态不是通过“请求一次拿一次”获取，而是主进程主动推送。
|
||||||
|
|
||||||
|
当前主要推送通道包括：
|
||||||
|
|
||||||
|
- cleaner progress
|
||||||
|
- extractor progress
|
||||||
|
- extractor log
|
||||||
|
- update status changed
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
MainService[Main Service]
|
||||||
|
EventChannel[IPC Event Channel]
|
||||||
|
PreloadListener[Preload Listener]
|
||||||
|
RendererHook[Renderer Hook]
|
||||||
|
UI[UI]
|
||||||
|
|
||||||
|
MainService --> EventChannel
|
||||||
|
EventChannel --> PreloadListener
|
||||||
|
PreloadListener --> RendererHook
|
||||||
|
RendererHook --> UI
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. 配置与持久化数据流
|
||||||
|
|
||||||
|
项目中的持久化既包含主进程配置，也包含 renderer 局部偏好。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
UI[Renderer UI]
|
||||||
|
Hook[Hook / Helper]
|
||||||
|
Session[sessionStorage]
|
||||||
|
ConfigIPC[config API]
|
||||||
|
ConfigSvc[ConfigManager]
|
||||||
|
ConfigFile[config.yaml]
|
||||||
|
|
||||||
|
UI --> Hook
|
||||||
|
Hook --> Session
|
||||||
|
Hook --> ConfigIPC
|
||||||
|
ConfigIPC --> ConfigSvc
|
||||||
|
ConfigSvc --> ConfigFile
|
||||||
|
```
|
||||||
|
|
||||||
|
当前典型例子：
|
||||||
|
|
||||||
|
- `cleaner_dryRun`
|
||||||
|
- `cleaner_headless`
|
||||||
|
- `cleaner_validationMode`
|
||||||
|
- `extractor_orderNumbers`
|
||||||
|
|
||||||
|
## 10. 开发建议
|
||||||
|
|
||||||
|
在处理数据流时，建议优先遵守这些原则：
|
||||||
|
|
||||||
|
- 页面输入态不要直接驱动高频 bridge 副作用
|
||||||
|
- 共享数据流要明确谁负责写入、谁负责消费
|
||||||
|
- preload 只做 facade，不在 bridge 层堆业务分支
|
||||||
|
- handler 只做转发和错误包装
|
||||||
|
- 复杂状态流尽量配套时序图或单测
|
||||||
326
docs/developer/architecture/decision-log.md
Normal file
326
docs/developer/architecture/decision-log.md
Normal file
@@ -0,0 +1,326 @@
|
|||||||
|
# 设计决策记录
|
||||||
|
|
||||||
|
本文档记录项目中值得被长期记住的关键架构决策。它不追求覆盖所有历史细节，而是保留那些会影响后续开发判断的决定。
|
||||||
|
|
||||||
|
## 1. 记录原则
|
||||||
|
|
||||||
|
这里主要记录三类决策：
|
||||||
|
|
||||||
|
- 影响整体结构的重构决策
|
||||||
|
- 影响跨层边界的接口决策
|
||||||
|
- 影响后续维护方式的工程化决策
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Problem[问题]
|
||||||
|
Decision[决策]
|
||||||
|
Impact[影响]
|
||||||
|
FollowUp[后续维护]
|
||||||
|
|
||||||
|
Problem --> Decision --> Impact --> FollowUp
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 决策一览
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
timeline
|
||||||
|
title 近期关键架构决策
|
||||||
|
2026-03-21 : 主进程 bootstrap 拆分
|
||||||
|
: IPC handler 薄壳化
|
||||||
|
: preload 按 domain 重组
|
||||||
|
: update 模块职责拆分
|
||||||
|
: React App 入口收敛
|
||||||
|
: Cleaner 页面拆分
|
||||||
|
: UpdateDialog 状态收敛
|
||||||
|
: renderer 重型弹窗按需加载
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 主进程入口拆分
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
此前主进程入口承载了过多职责，启动、窗口、运行时检查、IPC 注册和进程守卫都集中在单文件中。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
将主进程启动相关逻辑拆分到：
|
||||||
|
|
||||||
|
- `bootstrap/main-window.ts`
|
||||||
|
- `bootstrap/runtime.ts`
|
||||||
|
- `bootstrap/process-guards.ts`
|
||||||
|
|
||||||
|
### 结果
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
Before[单一 index.ts]
|
||||||
|
After[index.ts + bootstrap/*]
|
||||||
|
|
||||||
|
Before --> After
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- `index.ts` 更容易读
|
||||||
|
- 启动链路更容易定位问题
|
||||||
|
- 后续添加启动逻辑不必继续堆到一个入口文件里
|
||||||
|
|
||||||
|
## 4. IPC handler 薄壳化
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
部分 handler 曾经承担大量业务编排逻辑，尤其是认证、校验和清理流程。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
把核心编排下沉到 application service，handler 保持为薄壳。
|
||||||
|
|
||||||
|
当前典型结构：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Handler[IPC Handler]
|
||||||
|
AppService[Application Service]
|
||||||
|
Domain[Domain Service]
|
||||||
|
|
||||||
|
Handler --> AppService --> Domain
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- handler 更容易测试
|
||||||
|
- 业务逻辑更容易复用
|
||||||
|
- 主进程边界更清晰
|
||||||
|
|
||||||
|
## 5. Validation 模块拆分
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
`validation-handler` 曾同时承担 IPC、共享状态、数据库分支、SQL 拼接和数据富化。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
将职责拆分到独立模块：
|
||||||
|
|
||||||
|
- `shared-production-ids-store.ts`
|
||||||
|
- `validation-database.ts`
|
||||||
|
- `production-input-service.ts`
|
||||||
|
- `validation-application-service.ts`
|
||||||
|
|
||||||
|
### 结果
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Handler[validation-handler]
|
||||||
|
Store[shared-production-ids-store]
|
||||||
|
DB[validation-database]
|
||||||
|
Input[production-input-service]
|
||||||
|
AppSvc[validation-application-service]
|
||||||
|
|
||||||
|
Handler --> Store
|
||||||
|
Handler --> AppSvc
|
||||||
|
AppSvc --> DB
|
||||||
|
AppSvc --> Input
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- 共享订单号状态不再埋在 handler 中
|
||||||
|
- 数据库与输入识别边界更清晰
|
||||||
|
- 后续校验链路文档化和测试化更容易
|
||||||
|
|
||||||
|
## 6. Preload 按领域重组
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
preload 曾接近一个“大接口总表”，内部职责不够清晰。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
将 preload 改为按 domain 组织：
|
||||||
|
|
||||||
|
- `api/auth.ts`
|
||||||
|
- `api/cleaner.ts`
|
||||||
|
- `api/extractor.ts`
|
||||||
|
- `api/validation.ts`
|
||||||
|
- `api/materials.ts`
|
||||||
|
- `api/process.ts`
|
||||||
|
- `api/logger.ts`
|
||||||
|
|
||||||
|
### 结果
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
Before[单体 preload]
|
||||||
|
After[domain preload APIs]
|
||||||
|
|
||||||
|
Before --> After
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- renderer 使用的 bridge 更有语义
|
||||||
|
- preload 更适合继续维护
|
||||||
|
- 类型边界更稳定
|
||||||
|
|
||||||
|
## 7. Update 模块拆分
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
更新服务长期承担目录拉取、状态广播、下载、安装和版本决策等多类职责。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
将 update 模块拆成多个协作者：
|
||||||
|
|
||||||
|
- `update-service.ts`
|
||||||
|
- `update-catalog-service.ts`
|
||||||
|
- `update-installer.ts`
|
||||||
|
- `update-storage-client.ts`
|
||||||
|
- `update-status-publisher.ts`
|
||||||
|
- `update-support.ts`
|
||||||
|
|
||||||
|
### 结果
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
UpdateService[UpdateService]
|
||||||
|
Catalog[UpdateCatalogService]
|
||||||
|
Installer[UpdateInstaller]
|
||||||
|
Storage[UpdateStorageClient]
|
||||||
|
Publisher[UpdateStatusPublisher]
|
||||||
|
|
||||||
|
UpdateService --> Catalog
|
||||||
|
UpdateService --> Installer
|
||||||
|
UpdateService --> Storage
|
||||||
|
UpdateService --> Publisher
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- 更新职责边界更清晰
|
||||||
|
- 测试粒度更细
|
||||||
|
- 维护内部更新逻辑的成本下降
|
||||||
|
|
||||||
|
## 8. React 入口收敛
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
`App.tsx` 曾同时承担认证启动、更新状态刷新、导航、未认证态和已认证态 UI。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
拆出：
|
||||||
|
|
||||||
|
- `useAppBootstrap.ts`
|
||||||
|
- `AuthenticatedAppShell.tsx`
|
||||||
|
- `UnauthenticatedApp.tsx`
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- 入口组件回归组装层
|
||||||
|
- 认证与更新状态更容易追踪
|
||||||
|
- 后续页面和对话框拆分更容易
|
||||||
|
|
||||||
|
## 9. Cleaner 页面拆分
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
`CleanerPage` 曾是典型的大页面，包含筛选区、工具栏、表格、执行区和多个弹窗。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
拆分出：
|
||||||
|
|
||||||
|
- `CleanerSidebar.tsx`
|
||||||
|
- `CleanerToolbar.tsx`
|
||||||
|
- `CleanerResultsTable.tsx`
|
||||||
|
- `CleanerExecutionBar.tsx`
|
||||||
|
|
||||||
|
### 结果
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
CleanerPage[CleanerPage]
|
||||||
|
Sidebar[Sidebar]
|
||||||
|
Toolbar[Toolbar]
|
||||||
|
Table[ResultsTable]
|
||||||
|
Bar[ExecutionBar]
|
||||||
|
|
||||||
|
CleanerPage --> Sidebar
|
||||||
|
CleanerPage --> Toolbar
|
||||||
|
CleanerPage --> Table
|
||||||
|
CleanerPage --> Bar
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- 页面阅读成本下降
|
||||||
|
- UI 结构更清楚
|
||||||
|
- 后续继续拆 `useCleaner` 更安全
|
||||||
|
|
||||||
|
## 10. UpdateDialog 状态收敛
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
更新弹窗里选中版本和 changelog 请求状态容易产生旧请求覆盖新状态的问题。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
新增：
|
||||||
|
|
||||||
|
- `useUpdateDialogState.ts`
|
||||||
|
|
||||||
|
并把 changelog 请求保护和选中版本逻辑集中到 hook 中。
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- 异步状态更稳定
|
||||||
|
- 版本切换逻辑更容易测试
|
||||||
|
|
||||||
|
## 11. Renderer 重型弹窗按需加载
|
||||||
|
|
||||||
|
### 背景
|
||||||
|
|
||||||
|
多个重型弹窗并不是首屏关键路径，但此前会参与静态导入。
|
||||||
|
|
||||||
|
### 决策
|
||||||
|
|
||||||
|
对这些组件使用 `React.lazy + Suspense`：
|
||||||
|
|
||||||
|
- `UpdateDialog`
|
||||||
|
- `MaterialTypeManagementDialog`
|
||||||
|
- `ExecutionReportDialog`
|
||||||
|
- `ReportViewerDialog`
|
||||||
|
|
||||||
|
### 结果
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
Static[静态导入]
|
||||||
|
Lazy[按需加载]
|
||||||
|
|
||||||
|
Static --> Lazy
|
||||||
|
```
|
||||||
|
|
||||||
|
### 影响
|
||||||
|
|
||||||
|
- renderer 初始负担下降
|
||||||
|
- 常用主流程更轻
|
||||||
|
|
||||||
|
## 12. 后续记录方式
|
||||||
|
|
||||||
|
后续新增重大决策时，建议按这个格式补充：
|
||||||
|
|
||||||
|
1. 背景
|
||||||
|
2. 决策
|
||||||
|
3. 结果图
|
||||||
|
4. 影响
|
||||||
|
5. 相关文件
|
||||||
|
|
||||||
|
建议记录的场景包括：
|
||||||
|
|
||||||
|
- 新增跨层通信机制
|
||||||
|
- 重构核心模块边界
|
||||||
|
- 修改更新、认证、校验、清理主链路
|
||||||
|
- 引入新的状态管理或测试策略
|
||||||
288
docs/developer/architecture/file-map.md
Normal file
288
docs/developer/architecture/file-map.md
Normal file
@@ -0,0 +1,288 @@
|
|||||||
|
# 文件地图
|
||||||
|
|
||||||
|
本文档提供一个“高频核心文件地图”，帮助开发者快速定位项目里最值得先看的文件，而不是在目录树里盲找。
|
||||||
|
|
||||||
|
## 1. 快速定位图
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Root[项目入口]
|
||||||
|
Main[src/main/index.ts]
|
||||||
|
Preload[src/preload/index.ts]
|
||||||
|
Renderer[src/renderer/src/App.tsx]
|
||||||
|
Pages[src/renderer/src/pages]
|
||||||
|
IPC[src/main/ipc]
|
||||||
|
Services[src/main/services]
|
||||||
|
|
||||||
|
Root --> Main
|
||||||
|
Root --> Preload
|
||||||
|
Root --> Renderer
|
||||||
|
Renderer --> Pages
|
||||||
|
Main --> IPC
|
||||||
|
Main --> Services
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 最先阅读的文件
|
||||||
|
|
||||||
|
如果你刚进入仓库，建议优先看这些文件：
|
||||||
|
|
||||||
|
| 文件 | 作用 |
|
||||||
|
| ----------------------------------------------------------- | -------------------------- |
|
||||||
|
| `src/main/index.ts` | 主进程启动入口 |
|
||||||
|
| `src/main/bootstrap/runtime.ts` | 运行时初始化与 IPC 注册 |
|
||||||
|
| `src/main/ipc/index.ts` | 所有 IPC handler 注册中心 |
|
||||||
|
| `src/preload/index.ts` | preload 入口 |
|
||||||
|
| `src/preload/api/index.ts` | renderer 可用 API 聚合入口 |
|
||||||
|
| `src/renderer/src/App.tsx` | React 应用入口 |
|
||||||
|
| `src/renderer/src/components/app/AuthenticatedAppShell.tsx` | 已认证态主壳层 |
|
||||||
|
|
||||||
|
## 3. Main 进程文件地图
|
||||||
|
|
||||||
|
### 3.1 启动与窗口
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Index[index.ts]
|
||||||
|
Runtime[bootstrap/runtime.ts]
|
||||||
|
Guards[bootstrap/process-guards.ts]
|
||||||
|
Window[bootstrap/main-window.ts]
|
||||||
|
|
||||||
|
Index --> Runtime
|
||||||
|
Index --> Guards
|
||||||
|
Index --> Window
|
||||||
|
```
|
||||||
|
|
||||||
|
关键文件：
|
||||||
|
|
||||||
|
- `src/main/index.ts`
|
||||||
|
- `src/main/bootstrap/runtime.ts`
|
||||||
|
- `src/main/bootstrap/process-guards.ts`
|
||||||
|
- `src/main/bootstrap/main-window.ts`
|
||||||
|
|
||||||
|
### 3.2 IPC 注册层
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
IPCIndex[ipc/index.ts]
|
||||||
|
Auth[auth-handler.ts]
|
||||||
|
Cleaner[cleaner-handler.ts]
|
||||||
|
Extractor[extractor-handler.ts]
|
||||||
|
Validation[validation-handler.ts]
|
||||||
|
Update[update-handler.ts]
|
||||||
|
Settings[settings-handler.ts]
|
||||||
|
Report[report-handler.ts]
|
||||||
|
|
||||||
|
IPCIndex --> Auth
|
||||||
|
IPCIndex --> Cleaner
|
||||||
|
IPCIndex --> Extractor
|
||||||
|
IPCIndex --> Validation
|
||||||
|
IPCIndex --> Update
|
||||||
|
IPCIndex --> Settings
|
||||||
|
IPCIndex --> Report
|
||||||
|
```
|
||||||
|
|
||||||
|
建议优先关注：
|
||||||
|
|
||||||
|
- `src/main/ipc/index.ts`
|
||||||
|
- `src/main/ipc/auth-handler.ts`
|
||||||
|
- `src/main/ipc/cleaner-handler.ts`
|
||||||
|
- `src/main/ipc/extractor-handler.ts`
|
||||||
|
- `src/main/ipc/validation-handler.ts`
|
||||||
|
- `src/main/ipc/update-handler.ts`
|
||||||
|
|
||||||
|
### 3.3 核心服务层
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Services[services/]
|
||||||
|
Auth[auth/]
|
||||||
|
Cleaner[cleaner/]
|
||||||
|
Validation[validation/]
|
||||||
|
Update[update/]
|
||||||
|
Config[config/]
|
||||||
|
ERP[erp/]
|
||||||
|
Report[report/]
|
||||||
|
|
||||||
|
Services --> Auth
|
||||||
|
Services --> Cleaner
|
||||||
|
Services --> Validation
|
||||||
|
Services --> Update
|
||||||
|
Services --> Config
|
||||||
|
Services --> ERP
|
||||||
|
Services --> Report
|
||||||
|
```
|
||||||
|
|
||||||
|
高频核心文件：
|
||||||
|
|
||||||
|
- `src/main/services/auth/auth-application-service.ts`
|
||||||
|
- `src/main/services/cleaner/cleaner-application-service.ts`
|
||||||
|
- `src/main/services/validation/validation-application-service.ts`
|
||||||
|
- `src/main/services/validation/shared-production-ids-store.ts`
|
||||||
|
- `src/main/services/update/update-service.ts`
|
||||||
|
- `src/main/services/update/update-catalog-service.ts`
|
||||||
|
- `src/main/services/config/config-manager.ts`
|
||||||
|
|
||||||
|
## 4. Preload 文件地图
|
||||||
|
|
||||||
|
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]
|
||||||
|
Materials[api/materials.ts]
|
||||||
|
Process[api/process.ts]
|
||||||
|
Resolver[api/resolver.ts]
|
||||||
|
|
||||||
|
Preload --> API
|
||||||
|
API --> Auth
|
||||||
|
API --> Cleaner
|
||||||
|
API --> Extractor
|
||||||
|
API --> Validation
|
||||||
|
API --> Materials
|
||||||
|
API --> Process
|
||||||
|
API --> Resolver
|
||||||
|
API --> IPC
|
||||||
|
```
|
||||||
|
|
||||||
|
关键文件：
|
||||||
|
|
||||||
|
- `src/preload/index.ts`
|
||||||
|
- `src/preload/index.d.ts`
|
||||||
|
- `src/preload/api/index.ts`
|
||||||
|
- `src/preload/lib/ipc.ts`
|
||||||
|
|
||||||
|
## 5. Renderer 文件地图
|
||||||
|
|
||||||
|
### 5.1 应用壳层
|
||||||
|
|
||||||
|
关键文件：
|
||||||
|
|
||||||
|
- `src/renderer/src/App.tsx`
|
||||||
|
- `src/renderer/src/hooks/useAppBootstrap.ts`
|
||||||
|
- `src/renderer/src/components/app/AuthenticatedAppShell.tsx`
|
||||||
|
- `src/renderer/src/components/app/UnauthenticatedApp.tsx`
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
App[App.tsx]
|
||||||
|
Bootstrap[useAppBootstrap.ts]
|
||||||
|
Authenticated[AuthenticatedAppShell.tsx]
|
||||||
|
Unauthenticated[UnauthenticatedApp.tsx]
|
||||||
|
|
||||||
|
App --> Bootstrap
|
||||||
|
App --> Authenticated
|
||||||
|
App --> Unauthenticated
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 页面入口
|
||||||
|
|
||||||
|
关键页面：
|
||||||
|
|
||||||
|
- `src/renderer/src/pages/ExtractorPage.tsx`
|
||||||
|
- `src/renderer/src/pages/CleanerPage.tsx`
|
||||||
|
- `src/renderer/src/pages/SettingsPage.tsx`
|
||||||
|
|
||||||
|
### 5.3 Cleaner 相关
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Page[CleanerPage.tsx]
|
||||||
|
Hook[useCleaner.ts]
|
||||||
|
Sidebar[CleanerSidebar.tsx]
|
||||||
|
Toolbar[CleanerToolbar.tsx]
|
||||||
|
Table[CleanerResultsTable.tsx]
|
||||||
|
Bar[CleanerExecutionBar.tsx]
|
||||||
|
Helpers[hooks/cleaner/helpers.ts]
|
||||||
|
API[hooks/cleaner/api.ts]
|
||||||
|
|
||||||
|
Page --> Hook
|
||||||
|
Page --> Sidebar
|
||||||
|
Page --> Toolbar
|
||||||
|
Page --> Table
|
||||||
|
Page --> Bar
|
||||||
|
Hook --> Helpers
|
||||||
|
Hook --> API
|
||||||
|
```
|
||||||
|
|
||||||
|
关键文件：
|
||||||
|
|
||||||
|
- `src/renderer/src/pages/CleanerPage.tsx`
|
||||||
|
- `src/renderer/src/hooks/useCleaner.ts`
|
||||||
|
- `src/renderer/src/hooks/cleaner/api.ts`
|
||||||
|
- `src/renderer/src/hooks/cleaner/helpers.ts`
|
||||||
|
|
||||||
|
### 5.4 Extractor 相关
|
||||||
|
|
||||||
|
关键文件：
|
||||||
|
|
||||||
|
- `src/renderer/src/pages/ExtractorPage.tsx`
|
||||||
|
- `src/renderer/src/hooks/useExtractor.ts`
|
||||||
|
- `src/renderer/src/hooks/useSharedProductionIds.ts`
|
||||||
|
- `src/renderer/src/hooks/usePersistentTextState.ts`
|
||||||
|
- `src/renderer/src/components/OrderNumberInput.tsx`
|
||||||
|
|
||||||
|
### 5.5 更新相关
|
||||||
|
|
||||||
|
关键文件：
|
||||||
|
|
||||||
|
- `src/renderer/src/components/UpdateDialog.tsx`
|
||||||
|
- `src/renderer/src/hooks/useUpdateDialogState.ts`
|
||||||
|
- `src/renderer/src/hooks/useAppBootstrap.ts`
|
||||||
|
|
||||||
|
## 6. 测试文件地图
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Tests[tests/]
|
||||||
|
Unit[unit/]
|
||||||
|
Integration[integration/]
|
||||||
|
E2E[e2e/]
|
||||||
|
Manual[manual/]
|
||||||
|
|
||||||
|
Tests --> Unit
|
||||||
|
Tests --> Integration
|
||||||
|
Tests --> E2E
|
||||||
|
Tests --> Manual
|
||||||
|
```
|
||||||
|
|
||||||
|
和当前重构关系较强的测试包括：
|
||||||
|
|
||||||
|
- `tests/unit/preload-surface.test.ts`
|
||||||
|
- `tests/unit/auth-handler.test.ts`
|
||||||
|
- `tests/unit/cleaner-handler.test.ts`
|
||||||
|
- `tests/unit/bootstrap-runtime.test.ts`
|
||||||
|
- `tests/unit/update-catalog-service.test.ts`
|
||||||
|
- `tests/unit/use-shared-production-ids.test.ts`
|
||||||
|
- `tests/unit/use-update-dialog-state.test.ts`
|
||||||
|
|
||||||
|
## 7. 阅读建议
|
||||||
|
|
||||||
|
不同任务建议优先看不同文件：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
Task[开发任务]
|
||||||
|
Startup[启动问题]
|
||||||
|
Cleaner[Cleaner 功能]
|
||||||
|
Extractor[Extractor 功能]
|
||||||
|
Update[更新功能]
|
||||||
|
Auth[认证功能]
|
||||||
|
|
||||||
|
Task --> Startup
|
||||||
|
Task --> Cleaner
|
||||||
|
Task --> Extractor
|
||||||
|
Task --> Update
|
||||||
|
Task --> Auth
|
||||||
|
|
||||||
|
Startup --> A[src/main/index.ts / bootstrap]
|
||||||
|
Cleaner --> B[CleanerPage / useCleaner / cleaner-handler / cleaner service]
|
||||||
|
Extractor --> C[ExtractorPage / useExtractor / extractor-handler]
|
||||||
|
Update --> D[UpdateDialog / useAppBootstrap / update service]
|
||||||
|
Auth --> E[useAppBootstrap / auth-handler / auth service]
|
||||||
|
```
|
||||||
273
docs/developer/architecture/overview.md
Normal file
273
docs/developer/architecture/overview.md
Normal file
@@ -0,0 +1,273 @@
|
|||||||
|
# 项目总览
|
||||||
|
|
||||||
|
本文档用于帮助开发者快速建立对项目的整体认知，包括系统目标、核心能力、目录结构和主要运行路径。
|
||||||
|
|
||||||
|
## 1. 项目定位
|
||||||
|
|
||||||
|
`ERPAuto` 是一个基于 Electron + React + TypeScript 构建的内部桌面工具，主要用于辅助 ERP 相关的数据提取、校验、清理、配置和更新管理。
|
||||||
|
|
||||||
|
当前项目的核心业务能力主要包括：
|
||||||
|
|
||||||
|
- 批量提取 ERP 数据并导入本地数据库
|
||||||
|
- 基于数据库和共享订单号进行物料校验
|
||||||
|
- 执行 ERP 物料清理与结果导出
|
||||||
|
- 用户认证、管理员代切用户
|
||||||
|
- 桌面端应用更新
|
||||||
|
- 本地配置、日志、报告与文件处理
|
||||||
|
|
||||||
|
项目可以先粗略理解成下面这张图：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
mindmap
|
||||||
|
root((ERPAuto))
|
||||||
|
数据提取
|
||||||
|
订单号输入
|
||||||
|
批量导出
|
||||||
|
导入数据库
|
||||||
|
物料校验与清理
|
||||||
|
共享 Production IDs
|
||||||
|
校验结果
|
||||||
|
删除计划
|
||||||
|
ERP 执行
|
||||||
|
执行报告
|
||||||
|
用户与权限
|
||||||
|
silent login
|
||||||
|
管理员代切用户
|
||||||
|
系统能力
|
||||||
|
配置
|
||||||
|
日志
|
||||||
|
更新
|
||||||
|
报告
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 技术栈概览
|
||||||
|
|
||||||
|
- 桌面容器：Electron
|
||||||
|
- 前端渲染：React 19
|
||||||
|
- 构建工具：electron-vite / Vite
|
||||||
|
- 语言：TypeScript
|
||||||
|
- 样式：Tailwind CSS
|
||||||
|
- 测试：Vitest / Playwright
|
||||||
|
- 数据库：MySQL / SQL Server
|
||||||
|
- 自动化：Playwright
|
||||||
|
|
||||||
|
## 3. 顶层结构
|
||||||
|
|
||||||
|
项目核心代码主要分布在这几个目录：
|
||||||
|
|
||||||
|
- `src/main/`
|
||||||
|
Electron 主进程，负责窗口、IPC、服务编排、配置、日志、更新、ERP 相关主流程。
|
||||||
|
- `src/preload/`
|
||||||
|
preload bridge，向 renderer 暴露按领域组织的安全 API facade。
|
||||||
|
- `src/renderer/src/`
|
||||||
|
React 渲染层，负责页面、组件、hooks、状态管理和交互流程。
|
||||||
|
- `tests/`
|
||||||
|
单元测试、集成测试、e2e 和手工测试。
|
||||||
|
- `docs/`
|
||||||
|
项目说明、执行计划、架构文档和后续维护文档。
|
||||||
|
|
||||||
|
也可以从目录责任关系上理解：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Root[项目根目录]
|
||||||
|
Main[src/main]
|
||||||
|
Preload[src/preload]
|
||||||
|
Renderer[src/renderer/src]
|
||||||
|
Tests[tests]
|
||||||
|
Docs[docs]
|
||||||
|
|
||||||
|
Root --> Main
|
||||||
|
Root --> Preload
|
||||||
|
Root --> Renderer
|
||||||
|
Root --> Tests
|
||||||
|
Root --> Docs
|
||||||
|
|
||||||
|
Main --> MainDesc[主进程与服务执行]
|
||||||
|
Preload --> PreloadDesc[桥接 API 与 IPC 封装]
|
||||||
|
Renderer --> RendererDesc[页面 组件 Hooks 状态]
|
||||||
|
Tests --> TestsDesc[单测 集成 E2E]
|
||||||
|
Docs --> DocsDesc[说明 计划 开发文档]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. 运行时分层
|
||||||
|
|
||||||
|
项目运行时可简单理解为三层：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
Renderer[Renderer / React]
|
||||||
|
Preload[Preload API Facade]
|
||||||
|
Main[Main Process Services]
|
||||||
|
|
||||||
|
Renderer --> Preload
|
||||||
|
Preload --> Main
|
||||||
|
```
|
||||||
|
|
||||||
|
职责划分如下：
|
||||||
|
|
||||||
|
- `renderer`
|
||||||
|
负责页面展示、用户交互、状态管理和流程触发。
|
||||||
|
- `preload`
|
||||||
|
负责把 IPC 能力整理成前端可用的 API facade。
|
||||||
|
- `main`
|
||||||
|
负责真正的业务执行、数据库访问、ERP 自动化、文件和更新处理。
|
||||||
|
|
||||||
|
从用户操作到系统执行的主路径如下：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
User[用户操作]
|
||||||
|
Page[React 页面]
|
||||||
|
Hook[页面 Hook]
|
||||||
|
Preload[Preload API]
|
||||||
|
Handler[IPC Handler]
|
||||||
|
Service[Main Service]
|
||||||
|
External[数据库 / ERP / 文件 / 更新源]
|
||||||
|
|
||||||
|
User --> Page
|
||||||
|
Page --> Hook
|
||||||
|
Hook --> Preload
|
||||||
|
Preload --> Handler
|
||||||
|
Handler --> Service
|
||||||
|
Service --> External
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. 当前核心页面
|
||||||
|
|
||||||
|
当前渲染层主要有三个业务页面：
|
||||||
|
|
||||||
|
- `ExtractorPage`
|
||||||
|
负责订单号输入、批量提取和提取日志展示。
|
||||||
|
- `CleanerPage`
|
||||||
|
负责物料校验、负责人分配、删除计划保存、ERP 清理执行与结果查看。
|
||||||
|
- `SettingsPage`
|
||||||
|
负责系统设置与配置维护。
|
||||||
|
|
||||||
|
应用入口在：
|
||||||
|
|
||||||
|
- `src/renderer/src/App.tsx`
|
||||||
|
- `src/renderer/src/components/app/AuthenticatedAppShell.tsx`
|
||||||
|
- `src/renderer/src/components/app/UnauthenticatedApp.tsx`
|
||||||
|
|
||||||
|
页面级结构可以简化为：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
App[App.tsx]
|
||||||
|
Unauth[UnauthenticatedApp]
|
||||||
|
Shell[AuthenticatedAppShell]
|
||||||
|
Extractor[ExtractorPage]
|
||||||
|
Cleaner[CleanerPage]
|
||||||
|
Settings[SettingsPage]
|
||||||
|
|
||||||
|
App --> Unauth
|
||||||
|
App --> Shell
|
||||||
|
Shell --> Extractor
|
||||||
|
Shell --> Cleaner
|
||||||
|
Shell --> Settings
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. 当前主进程结构
|
||||||
|
|
||||||
|
主进程侧目前已经按职责拆成几类目录：
|
||||||
|
|
||||||
|
- `bootstrap/`
|
||||||
|
应用启动、窗口创建、进程守卫、运行时初始化。
|
||||||
|
- `ipc/`
|
||||||
|
IPC handler 注册与调用入口。
|
||||||
|
- `services/`
|
||||||
|
具体业务服务实现，按领域组织。
|
||||||
|
- `types/`
|
||||||
|
主进程与 preload/renderer 共享的类型定义。
|
||||||
|
|
||||||
|
`services/` 当前主要领域包括：
|
||||||
|
|
||||||
|
- `auth`
|
||||||
|
- `cleaner`
|
||||||
|
- `config`
|
||||||
|
- `database`
|
||||||
|
- `erp`
|
||||||
|
- `excel`
|
||||||
|
- `logger`
|
||||||
|
- `report`
|
||||||
|
- `rustfs`
|
||||||
|
- `update`
|
||||||
|
- `user`
|
||||||
|
- `validation`
|
||||||
|
|
||||||
|
主进程结构关系如下：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
MainIndex[index.ts]
|
||||||
|
Bootstrap[bootstrap/]
|
||||||
|
IPC[ipc/]
|
||||||
|
Services[services/]
|
||||||
|
Types[types/]
|
||||||
|
|
||||||
|
MainIndex --> Bootstrap
|
||||||
|
MainIndex --> IPC
|
||||||
|
IPC --> Services
|
||||||
|
Services --> Types
|
||||||
|
IPC --> Types
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7. 关键业务链路
|
||||||
|
|
||||||
|
项目最重要的几条业务链路可以概括为：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[登录与认证]
|
||||||
|
B[订单号提取]
|
||||||
|
C[共享 Production IDs]
|
||||||
|
D[物料校验]
|
||||||
|
E[删除计划保存]
|
||||||
|
F[ERP 清理执行]
|
||||||
|
G[报告与导出]
|
||||||
|
H[应用更新]
|
||||||
|
|
||||||
|
A --> B
|
||||||
|
B --> C
|
||||||
|
C --> D
|
||||||
|
D --> E
|
||||||
|
E --> F
|
||||||
|
F --> G
|
||||||
|
A --> H
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. 目录阅读建议
|
||||||
|
|
||||||
|
如果你是第一次进入代码库，建议按下面顺序读：
|
||||||
|
|
||||||
|
1. `src/main/index.ts`
|
||||||
|
2. `src/main/bootstrap/`
|
||||||
|
3. `src/preload/index.ts`
|
||||||
|
4. `src/renderer/src/App.tsx`
|
||||||
|
5. `src/renderer/src/pages/`
|
||||||
|
6. 对应业务模块的 `src/main/ipc/` 和 `src/main/services/`
|
||||||
|
|
||||||
|
阅读路径也可以理解成：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
A[src/main/index.ts]
|
||||||
|
B[src/main/bootstrap]
|
||||||
|
C[src/preload/index.ts]
|
||||||
|
D[src/renderer/src/App.tsx]
|
||||||
|
E[src/renderer/src/pages]
|
||||||
|
F[src/main/ipc]
|
||||||
|
G[src/main/services]
|
||||||
|
|
||||||
|
A --> B --> C --> D --> E --> F --> G
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. 相关文档
|
||||||
|
|
||||||
|
继续阅读建议：
|
||||||
|
|
||||||
|
- `runtime-architecture.md`
|
||||||
|
了解 `main / preload / renderer` 的分层与调用关系。
|
||||||
|
- 后续 `modules/` 目录中的模块文档
|
||||||
|
深入理解各业务模块。
|
||||||
381
docs/developer/architecture/runtime-architecture.md
Normal file
381
docs/developer/architecture/runtime-architecture.md
Normal file
@@ -0,0 +1,381 @@
|
|||||||
|
# 运行时架构
|
||||||
|
|
||||||
|
本文档说明项目在运行时的主要分层、进程边界和核心调用路径，帮助开发者理解请求是如何从 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`
|
||||||
Reference in New Issue
Block a user