274 lines
6.7 KiB
Markdown
274 lines
6.7 KiB
Markdown
# 数据流
|
||
|
||
本文档聚焦项目中的核心数据流，帮助开发者理解关键业务数据如何在 `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 只做转发和错误包装
|
||
- 复杂状态流尽量配套时序图或单测
|