BLD-ERPAuto/BIPMaterialManager

Fork 0

Files

Misaka 57ca1d5650 docs: add developer architecture handbook

2026-03-21 20:25:45 +08:00

6.7 KiB

Raw Blame History

数据流

本文档聚焦项目中的核心数据流，帮助开发者理解关键业务数据如何在 renderer、preload、main 和外部系统之间流动。

1. 数据流总览

项目中的数据大致分成五类：

用户输入数据
页面状态数据
IPC 请求与响应数据
主进程领域数据
外部系统数据

整体关系如下：

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. 提取到清理的主数据流

项目里最核心的一条数据流是：

用户输入订单号
Extractor 执行提取
共享 Production IDs
Cleaner 基于共享数据做校验
保存删除计划
执行 ERP 清理
生成报告与导出

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 中，数据通常按下面路径流动：

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 数据流

认证流程是应用启动时最先发生的一条数据流。

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 模块的数据流重点在“订单号输入”和“提取执行结果”。

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 页面的数据流相对更复杂，包含筛选、校验、选择、保存和执行几个阶段。

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

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

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 局部偏好。

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 只做转发和错误包装
复杂状态流尽量配套时序图或单测

6.7 KiB Raw Blame History Unescape Escape

数据流