docs: add developer architecture handbook

docs/developer/architecture/data-flow.md

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