From 57ca1d565072d4e31c60b2b4a9ebb0fb43bcd4f9 Mon Sep 17 00:00:00 2001
From: Misaka <pengqiangqiang@gmail.com>
Date: Sat, 21 Mar 2026 20:25:45 +0800
Subject: [PATCH] docs: add developer architecture handbook

---
 docs/developer/README.md                      |   5 +-
 docs/developer/architecture/data-flow.md      | 273 +++++++++++++
 docs/developer/architecture/decision-log.md   | 326 +++++++++++++++
 docs/developer/architecture/file-map.md       | 288 +++++++++++++
 docs/developer/architecture/overview.md       | 273 +++++++++++++
 .../architecture/runtime-architecture.md      | 381 ++++++++++++++++++
 6 files changed, 1545 insertions(+), 1 deletion(-)
 create mode 100644 docs/developer/architecture/data-flow.md
 create mode 100644 docs/developer/architecture/decision-log.md
 create mode 100644 docs/developer/architecture/file-map.md
 create mode 100644 docs/developer/architecture/overview.md
 create mode 100644 docs/developer/architecture/runtime-architecture.md

diff --git a/docs/developer/README.md b/docs/developer/README.md
index 335f6fc..20f3cc7 100644
--- a/docs/developer/README.md
+++ b/docs/developer/README.md
@@ -66,7 +66,10 @@ docs/developer/
 - 新增核心模块时，同步补一篇对应的模块文档
 - 发生重要重构时，更新相关架构文档和决策记录
 - 文档优先解释“职责、边界、调用关系”，而不是堆砌实现细节
-- 每篇文档尽量附上关键文件路径和 `mermaid` 图
+- 文档应当多用、善用 `mermaid` 做图形化表达
+- 遇到结构、分层、调用链、时序、流程时，优先考虑先画图再解释
+- 图负责帮助读者快速建立整体认知，文字负责解释细节和边界
+- 文档尽量附上关键文件路径，并保持图和正文一一对应
 - 文档中的路径、模块名、调用链描述应与当前代码保持一致
 
 ## 当前状态
diff --git a/docs/developer/architecture/data-flow.md b/docs/developer/architecture/data-flow.md
new file mode 100644
index 0000000..28f607b
--- /dev/null
+++ b/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 只做转发和错误包装
+- 复杂状态流尽量配套时序图或单测
diff --git a/docs/developer/architecture/decision-log.md b/docs/developer/architecture/decision-log.md
new file mode 100644
index 0000000..96aec67
--- /dev/null
+++ b/docs/developer/architecture/decision-log.md
@@ -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. 相关文件
+
+建议记录的场景包括：
+
+- 新增跨层通信机制
+- 重构核心模块边界
+- 修改更新、认证、校验、清理主链路
+- 引入新的状态管理或测试策略
diff --git a/docs/developer/architecture/file-map.md b/docs/developer/architecture/file-map.md
new file mode 100644
index 0000000..79d4460
--- /dev/null
+++ b/docs/developer/architecture/file-map.md
@@ -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]
+```
diff --git a/docs/developer/architecture/overview.md b/docs/developer/architecture/overview.md
new file mode 100644
index 0000000..908d391
--- /dev/null
+++ b/docs/developer/architecture/overview.md
@@ -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/` 目录中的模块文档
+  深入理解各业务模块。
diff --git a/docs/developer/architecture/runtime-architecture.md b/docs/developer/architecture/runtime-architecture.md
new file mode 100644
index 0000000..a0f6274
--- /dev/null
+++ b/docs/developer/architecture/runtime-architecture.md
@@ -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`