docs: add developer module guides
This commit is contained in:
Misaka
119
docs/developer/modules/auth.md
Normal file
119
docs/developer/modules/auth.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Auth 模块
|
||||
|
||||
`Auth` 模块负责桌面端用户认证、silent login、管理员代切用户，以及把用户上下文同步给更新等后续模块。
|
||||
|
||||
## 1. 模块职责
|
||||
|
||||
- 获取机器名
|
||||
- 执行 silent login
|
||||
- 用户名密码登录
|
||||
- 管理员查看用户列表并切换用户
|
||||
- 登出并清理会话
|
||||
- 同步当前用户类型到更新模块
|
||||
|
||||
## 2. 模块结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
App[useAppBootstrap]
|
||||
Preload[preload.auth]
|
||||
Handler[auth-handler]
|
||||
AppSvc[auth-application-service]
|
||||
Session[session-manager]
|
||||
Update[update-service]
|
||||
|
||||
App --> Preload
|
||||
Preload --> Handler
|
||||
Handler --> AppSvc
|
||||
AppSvc --> Session
|
||||
AppSvc --> Update
|
||||
```
|
||||
|
||||
## 3. 关键入口文件
|
||||
|
||||
- `src/renderer/src/hooks/useAppBootstrap.ts`
|
||||
- `src/renderer/src/components/app/UnauthenticatedApp.tsx`
|
||||
- `src/main/ipc/auth-handler.ts`
|
||||
- `src/main/services/auth/auth-application-service.ts`
|
||||
- `src/main/services/user/session-manager.ts`
|
||||
|
||||
## 4. 认证主流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as 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
|
||||
Handler->>AppSvc: silentLogin()
|
||||
AppSvc->>Session: loginByComputerName()
|
||||
Session-->>AppSvc: userInfo
|
||||
AppSvc-->>Handler: login result
|
||||
Handler-->>Preload: IpcResult
|
||||
Preload-->>App: auth state
|
||||
```
|
||||
|
||||
## 5. 管理员分支
|
||||
|
||||
如果 silent login 或显式登录得到的是管理员账号，认证流程不会直接结束，而是进入“代切用户”分支。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Login[登录成功]
|
||||
Admin{是否 Admin}
|
||||
Select[getAllUsers]
|
||||
Switch[switchUser]
|
||||
Authenticated[进入已认证态]
|
||||
|
||||
Login --> Admin
|
||||
Admin -- 否 --> Authenticated
|
||||
Admin -- 是 --> Select
|
||||
Select --> Switch
|
||||
Switch --> Authenticated
|
||||
```
|
||||
|
||||
## 6. 与更新模块的关系
|
||||
|
||||
Auth 模块和 Update 模块之间有明确联动：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Auth[AuthApplicationService]
|
||||
UserType[UserType]
|
||||
Update[UpdateService]
|
||||
|
||||
Auth --> UserType
|
||||
UserType --> Update
|
||||
```
|
||||
|
||||
在以下时机会同步用户上下文：
|
||||
|
||||
- silent login 成功
|
||||
- 显式登录成功
|
||||
- 用户切换成功
|
||||
- logout
|
||||
|
||||
## 7. 最近的结构优化
|
||||
|
||||
Auth 相关逻辑最近做过两项关键收敛：
|
||||
|
||||
- 把编排逻辑从 `auth-handler` 下沉到 `auth-application-service`
|
||||
- 在 `silentLogin()` 中加入并发去重，避免重复 silent login 触发连接风暴
|
||||
|
||||
## 8. 常见改动点
|
||||
|
||||
- 改前端启动认证：`useAppBootstrap.ts`
|
||||
- 改登录与切换流程：`auth-application-service.ts`
|
||||
- 改会话层：`session-manager.ts`
|
||||
- 改 IPC 契约：`auth-handler.ts`
|
||||
|
||||
## 9. 修改建议
|
||||
|
||||
- 页面不要直接堆认证细节，优先继续收敛到 bootstrap hook
|
||||
- 用户上下文变化时，记得考虑 update 状态是否需要同步
|
||||
- silent login 流程不要破坏当前的防重入保护
|
||||
197
docs/developer/modules/cleaner.md
Normal file
197
docs/developer/modules/cleaner.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Cleaner 模块
|
||||
|
||||
`Cleaner` 模块负责物料校验结果的展示、筛选、负责人分配、删除计划保存，以及最终 ERP 清理执行与报告展示。
|
||||
|
||||
## 1. 模块职责
|
||||
|
||||
- 展示校验后的物料列表
|
||||
- 负责人筛选与内联编辑
|
||||
- 勾选待处理物料
|
||||
- 保存删除计划到数据库
|
||||
- 执行 ERP 清理
|
||||
- 展示执行进度和执行报告
|
||||
|
||||
## 2. 模块结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Page[CleanerPage]
|
||||
Hook[useCleaner]
|
||||
Sidebar[CleanerSidebar]
|
||||
Toolbar[CleanerToolbar]
|
||||
Table[CleanerResultsTable]
|
||||
Bar[CleanerExecutionBar]
|
||||
Helpers[hooks/cleaner/helpers.ts]
|
||||
API[hooks/cleaner/api.ts]
|
||||
Preload[preload.cleaner / validation / materials]
|
||||
Handler[cleaner-handler / validation-handler]
|
||||
MainSvc[cleaner-application-service]
|
||||
|
||||
Page --> Hook
|
||||
Page --> Sidebar
|
||||
Page --> Toolbar
|
||||
Page --> Table
|
||||
Page --> Bar
|
||||
Hook --> Helpers
|
||||
Hook --> API
|
||||
API --> Preload
|
||||
Preload --> Handler
|
||||
Handler --> MainSvc
|
||||
```
|
||||
|
||||
## 3. 关键入口文件
|
||||
|
||||
- `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`
|
||||
- `src/renderer/src/components/cleaner/CleanerSidebar.tsx`
|
||||
- `src/renderer/src/components/cleaner/CleanerToolbar.tsx`
|
||||
- `src/renderer/src/components/cleaner/CleanerResultsTable.tsx`
|
||||
- `src/renderer/src/components/cleaner/CleanerExecutionBar.tsx`
|
||||
- `src/main/ipc/cleaner-handler.ts`
|
||||
- `src/main/services/cleaner/cleaner-application-service.ts`
|
||||
|
||||
## 4. 页面主流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Load[页面初始化]
|
||||
Validate[获取并校验物料]
|
||||
Results[validationResults]
|
||||
Filter[筛选与隐藏]
|
||||
Select[勾选与负责人编辑]
|
||||
Plan[保存删除计划]
|
||||
Execute[执行 ERP 清理]
|
||||
Report[执行报告 / 查看报告]
|
||||
|
||||
Load --> Validate
|
||||
Validate --> Results
|
||||
Results --> Filter
|
||||
Results --> Select
|
||||
Select --> Plan
|
||||
Plan --> Execute
|
||||
Execute --> Report
|
||||
```
|
||||
|
||||
## 5. 前端状态组织
|
||||
|
||||
当前 `useCleaner` 管理的主要状态包括：
|
||||
|
||||
- 页面初始化与权限
|
||||
- 校验结果与筛选结果
|
||||
- 勾选状态与隐藏状态
|
||||
- 负责人编辑状态
|
||||
- 执行设置
|
||||
- 进度状态
|
||||
- 报告弹窗状态
|
||||
- 确认弹窗状态
|
||||
|
||||
可以理解成：
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
root((useCleaner))
|
||||
权限与初始化
|
||||
isAdmin
|
||||
currentUsername
|
||||
managers
|
||||
校验结果
|
||||
validationResults
|
||||
filteredResults
|
||||
selectedItems
|
||||
hiddenItems
|
||||
执行状态
|
||||
isRunning
|
||||
isExecuting
|
||||
progress
|
||||
reportData
|
||||
设置
|
||||
dryRun
|
||||
headless
|
||||
processConcurrency
|
||||
交互
|
||||
editingCell
|
||||
confirmDialog
|
||||
dialogs
|
||||
```
|
||||
|
||||
## 6. 主进程执行链路
|
||||
|
||||
Cleaner 真正执行 ERP 清理时，主进程调用链大致如下：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as useCleaner
|
||||
participant Preload as preload.cleaner
|
||||
participant Handler as cleaner-handler
|
||||
participant AppSvc as cleaner-application-service
|
||||
participant ERP as CleanerService / ErpAuthService
|
||||
participant Report as report / rustfs
|
||||
|
||||
UI->>Preload: runCleaner(input)
|
||||
Preload->>Handler: invoke
|
||||
Handler->>AppSvc: runCleaner(...)
|
||||
AppSvc->>ERP: 登录并执行清理
|
||||
ERP-->>AppSvc: cleaner result
|
||||
AppSvc->>Report: 生成并上传报告
|
||||
AppSvc-->>Handler: result
|
||||
Handler-->>Preload: IpcResult
|
||||
Preload-->>UI: 执行结果
|
||||
```
|
||||
|
||||
## 7. 模块边界
|
||||
|
||||
Cleaner 依赖多个模块：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Cleaner[Cleaner]
|
||||
Validation[Validation]
|
||||
Materials[Materials / MaterialType]
|
||||
Report[Report]
|
||||
Config[Config]
|
||||
ERP[ERP Services]
|
||||
|
||||
Cleaner --> Validation
|
||||
Cleaner --> Materials
|
||||
Cleaner --> Report
|
||||
Cleaner --> Config
|
||||
Cleaner --> ERP
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
- `validation`
|
||||
提供校验结果和 Cleaner 可消费数据
|
||||
- `materials`
|
||||
提供负责人和删除计划相关能力
|
||||
- `report`
|
||||
提供报告查看与生成
|
||||
- `config`
|
||||
提供执行配置
|
||||
|
||||
## 8. 最近的结构优化
|
||||
|
||||
这一块近期做过两轮收敛：
|
||||
|
||||
- `CleanerPage` 拆成 `Sidebar / Toolbar / ResultsTable / ExecutionBar`
|
||||
- `useCleaner` 内部 API / helpers 已经第一轮抽离
|
||||
|
||||
同时页面中的重型弹窗也已经改成按需加载。
|
||||
|
||||
## 9. 常见改动点
|
||||
|
||||
- 改筛选或展示：`CleanerPage.tsx` 与 `components/cleaner/*`
|
||||
- 改前端执行逻辑：`useCleaner.ts`
|
||||
- 改校验请求与导出：`hooks/cleaner/api.ts`
|
||||
- 改纯逻辑：`hooks/cleaner/helpers.ts`
|
||||
- 改主进程执行：`cleaner-application-service.ts`
|
||||
- 改 ERP 清理细节：`src/main/services/erp/cleaner.ts`
|
||||
|
||||
## 10. 修改建议
|
||||
|
||||
- 优先保持页面组件继续做“组装层”
|
||||
- 如果新增复杂交互，优先下沉到 hook 或 helper
|
||||
- 执行链路的真实业务逻辑放在主进程 service
|
||||
- 报告、导出、上传等后处理不要塞回 UI 层
|
||||
133
docs/developer/modules/extractor.md
Normal file
133
docs/developer/modules/extractor.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Extractor 模块
|
||||
|
||||
`Extractor` 模块负责接收订单号输入、触发提取流程、同步共享订单号，并把提取结果导入后续链路可消费的数据形态。
|
||||
|
||||
## 1. 模块职责
|
||||
|
||||
- 接收和持久化订单号输入
|
||||
- 将订单号同步为共享 `Production IDs`
|
||||
- 触发批量提取流程
|
||||
- 展示提取进度和日志
|
||||
- 为 `Cleaner` 等后续模块提供共享订单号基础
|
||||
|
||||
## 2. 模块结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Page[ExtractorPage]
|
||||
Input[OrderNumberInput]
|
||||
Persist[usePersistentTextState]
|
||||
Shared[useSharedProductionIds]
|
||||
Hook[useExtractor]
|
||||
Preload[preload.extractor / validation]
|
||||
Handler[extractor-handler]
|
||||
Service[ERP Extractor Service]
|
||||
|
||||
Page --> Input
|
||||
Page --> Persist
|
||||
Page --> Shared
|
||||
Page --> Hook
|
||||
Hook --> Preload
|
||||
Preload --> Handler
|
||||
Handler --> Service
|
||||
```
|
||||
|
||||
## 3. 关键入口文件
|
||||
|
||||
- `src/renderer/src/pages/ExtractorPage.tsx`
|
||||
- `src/renderer/src/hooks/useExtractor.ts`
|
||||
- `src/renderer/src/hooks/usePersistentTextState.ts`
|
||||
- `src/renderer/src/hooks/useSharedProductionIds.ts`
|
||||
- `src/renderer/src/components/OrderNumberInput.tsx`
|
||||
- `src/main/ipc/extractor-handler.ts`
|
||||
- `src/main/services/erp/extractor.ts`
|
||||
|
||||
## 4. 主要流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as ExtractorPage
|
||||
participant Persist as usePersistentTextState
|
||||
participant Shared as useSharedProductionIds
|
||||
participant Hook as useExtractor
|
||||
participant Preload as preload.extractor
|
||||
participant Main as extractor-handler / extractor service
|
||||
|
||||
UI->>Persist: 保存输入
|
||||
UI->>Shared: debounce 同步共享 IDs
|
||||
UI->>Hook: startExtraction(orderNumbers)
|
||||
Hook->>Preload: setSharedProductionIds()
|
||||
Hook->>Preload: runExtractor()
|
||||
Preload->>Main: invoke
|
||||
Main-->>Preload: 提取结果
|
||||
Preload-->>Hook: success / error / progress
|
||||
Hook-->>UI: 更新日志与状态
|
||||
```
|
||||
|
||||
## 5. 关键状态
|
||||
|
||||
当前前端侧最重要的状态包括：
|
||||
|
||||
- `orderNumbers`
|
||||
用户输入的订单号文本
|
||||
- `isRunning`
|
||||
是否正在提取
|
||||
- `progress`
|
||||
当前提取进度
|
||||
- `logs`
|
||||
提取过程日志
|
||||
- `error`
|
||||
当前错误
|
||||
- `isComplete`
|
||||
提取是否结束
|
||||
|
||||
## 6. 与其他模块的关系
|
||||
|
||||
Extractor 与其他模块的关系如下：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Extractor[Extractor]
|
||||
SharedIds[shared Production IDs]
|
||||
Validation[Validation]
|
||||
Cleaner[Cleaner]
|
||||
|
||||
Extractor --> SharedIds
|
||||
SharedIds --> Validation
|
||||
Validation --> Cleaner
|
||||
```
|
||||
|
||||
它最重要的跨模块输出不是页面本身，而是：
|
||||
|
||||
- 共享 `Production IDs`
|
||||
- 导入数据库的数据
|
||||
|
||||
## 7. 最近的结构优化
|
||||
|
||||
最近这一块做过两类收敛：
|
||||
|
||||
- 把订单号持久化抽到 `usePersistentTextState`
|
||||
- 把共享订单号同步抽到 `useSharedProductionIds`
|
||||
|
||||
这样页面不再自己同时处理：
|
||||
|
||||
- 输入状态
|
||||
- `sessionStorage`
|
||||
- bridge 副作用
|
||||
|
||||
## 8. 常见改动点
|
||||
|
||||
如果你要改 Extractor，通常会落在这些位置：
|
||||
|
||||
- 改输入与格式统计：`OrderNumberInput.tsx`
|
||||
- 改页面交互：`ExtractorPage.tsx`
|
||||
- 改前端提取编排：`useExtractor.ts`
|
||||
- 改共享订单号同步：`useSharedProductionIds.ts`
|
||||
- 改主进程执行：`extractor-handler.ts` / `erp/extractor.ts`
|
||||
|
||||
## 9. 修改建议
|
||||
|
||||
- 输入变化不要直接叠加更多高频副作用
|
||||
- 共享订单号写入尽量维持单一入口
|
||||
- 提取日志和进度流优先保持事件推送式结构
|
||||
- 如果新增提取后处理，优先放在主进程 service，而不是塞回页面
|
||||
103
docs/developer/modules/settings.md
Normal file
103
docs/developer/modules/settings.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Settings 模块
|
||||
|
||||
`Settings` 模块当前主要负责 ERP 登录凭据的查看、编辑和保存，并通过当前用户上下文对配置进行按用户管理。
|
||||
|
||||
## 1. 模块职责
|
||||
|
||||
- 加载当前用户的 ERP 配置
|
||||
- 编辑 ERP 用户名和密码
|
||||
- 保存配置到后端持久化存储
|
||||
- 提示保存结果
|
||||
|
||||
## 2. 模块结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Page[SettingsPage]
|
||||
Preload[preload.settings]
|
||||
Handler[settings-handler]
|
||||
Config[Config / User ERP Config Service]
|
||||
Storage[数据库中的用户配置]
|
||||
|
||||
Page --> Preload
|
||||
Preload --> Handler
|
||||
Handler --> Config
|
||||
Config --> Storage
|
||||
```
|
||||
|
||||
## 3. 关键入口文件
|
||||
|
||||
- `src/renderer/src/pages/SettingsPage.tsx`
|
||||
- `src/main/ipc/settings-handler.ts`
|
||||
- `src/main/services/config/config-manager.ts`
|
||||
- `src/main/services/user/user-erp-config-service.ts`
|
||||
|
||||
## 4. 主流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Page as SettingsPage
|
||||
participant Preload as preload.settings
|
||||
participant Handler as settings-handler
|
||||
participant Service as config / user-erp-config-service
|
||||
|
||||
Page->>Preload: getSettings()
|
||||
Preload->>Handler: invoke
|
||||
Handler->>Service: load current user config
|
||||
Service-->>Handler: settings payload
|
||||
Handler-->>Preload: IpcResult
|
||||
Preload-->>Page: ERP credentials
|
||||
|
||||
Page->>Preload: saveSettings(payload)
|
||||
Preload->>Handler: invoke
|
||||
Handler->>Service: persist config
|
||||
Service-->>Handler: save result
|
||||
Handler-->>Preload: IpcResult
|
||||
Preload-->>Page: success / error
|
||||
```
|
||||
|
||||
## 5. 页面状态
|
||||
|
||||
当前设置页非常轻量，主要状态包括：
|
||||
|
||||
- `credentials`
|
||||
- `isModified`
|
||||
- `isLoading`
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Load[加载配置]
|
||||
Edit[编辑账号密码]
|
||||
Dirty[isModified = true]
|
||||
Save[保存配置]
|
||||
Success[提示成功]
|
||||
|
||||
Load --> Edit
|
||||
Edit --> Dirty
|
||||
Dirty --> Save
|
||||
Save --> Success
|
||||
```
|
||||
|
||||
## 6. 与其他模块的关系
|
||||
|
||||
Settings 模块与这些模块关系较强：
|
||||
|
||||
- `auth`
|
||||
当前用户决定读取和保存哪份 ERP 配置
|
||||
- `cleaner`
|
||||
Cleaner 执行时会读取 ERP 账号密码
|
||||
- `extractor`
|
||||
提取链路也依赖 ERP 登录能力
|
||||
|
||||
## 7. 常见改动点
|
||||
|
||||
- 改页面交互：`SettingsPage.tsx`
|
||||
- 改 IPC 契约：`settings-handler.ts`
|
||||
- 改配置存储逻辑：`user-erp-config-service.ts`
|
||||
- 改全局配置：`config-manager.ts`
|
||||
|
||||
## 8. 修改建议
|
||||
|
||||
- 保持“页面只编辑当前用户配置”的边界清晰
|
||||
- 不要把 ERP 凭据保存逻辑重新分散到多个模块
|
||||
- 如果后续扩展更多设置项，建议引入更清晰的分组和局部表单结构
|
||||
153
docs/developer/modules/update.md
Normal file
153
docs/developer/modules/update.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Update 模块
|
||||
|
||||
`Update` 模块负责应用版本目录拉取、状态广播、更新包下载、安装器启动，以及为不同用户类型生成不同的更新视图。
|
||||
|
||||
## 1. 模块职责
|
||||
|
||||
- 检查更新是否可用
|
||||
- 拉取更新目录
|
||||
- 为 `User` / `Admin` 生成不同的更新决策
|
||||
- 下载更新包并校验
|
||||
- 启动安装流程
|
||||
- 广播更新状态给 renderer
|
||||
|
||||
## 2. 模块结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Hook[useAppBootstrap]
|
||||
Dialog[UpdateDialog / useUpdateDialogState]
|
||||
Preload[preload.update]
|
||||
Handler[update-handler]
|
||||
Service[UpdateService]
|
||||
Catalog[UpdateCatalogService]
|
||||
Installer[UpdateInstaller]
|
||||
Storage[UpdateStorageClient]
|
||||
Publisher[UpdateStatusPublisher]
|
||||
|
||||
Hook --> Preload
|
||||
Dialog --> Preload
|
||||
Preload --> Handler
|
||||
Handler --> Service
|
||||
Service --> Catalog
|
||||
Service --> Installer
|
||||
Service --> Storage
|
||||
Service --> Publisher
|
||||
```
|
||||
|
||||
## 3. 关键入口文件
|
||||
|
||||
- `src/renderer/src/hooks/useAppBootstrap.ts`
|
||||
- `src/renderer/src/components/UpdateDialog.tsx`
|
||||
- `src/renderer/src/hooks/useUpdateDialogState.ts`
|
||||
- `src/main/ipc/update-handler.ts`
|
||||
- `src/main/services/update/update-service.ts`
|
||||
- `src/main/services/update/update-catalog-service.ts`
|
||||
- `src/main/services/update/update-installer.ts`
|
||||
- `src/main/services/update/update-storage-client.ts`
|
||||
- `src/main/services/update/update-status-publisher.ts`
|
||||
|
||||
## 4. 更新数据流
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Hook as useAppBootstrap
|
||||
participant Dialog as useUpdateDialogState
|
||||
participant Preload as preload.update
|
||||
participant Handler as update-handler
|
||||
participant Service as UpdateService
|
||||
participant Catalog as UpdateCatalogService
|
||||
|
||||
Hook->>Preload: getStatus()
|
||||
Hook->>Preload: getCatalog()
|
||||
Dialog->>Preload: getChangelog(release)
|
||||
Preload->>Handler: invoke
|
||||
Handler->>Service: getStatus / getCatalog / getChangelog
|
||||
Service->>Catalog: resolve dialog catalog
|
||||
Catalog-->>Service: release decisions
|
||||
Service-->>Handler: update data
|
||||
Handler-->>Preload: IpcResult
|
||||
Preload-->>Hook: status / catalog
|
||||
Preload-->>Dialog: changelog
|
||||
```
|
||||
|
||||
## 5. 状态模型
|
||||
|
||||
更新模块当前最核心的是 `UpdateStatus`：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> idle
|
||||
idle --> checking
|
||||
checking --> available
|
||||
checking --> downloaded
|
||||
checking --> error
|
||||
available --> downloading
|
||||
downloading --> downloaded
|
||||
downloading --> error
|
||||
downloaded --> installing
|
||||
installing --> [*]
|
||||
```
|
||||
|
||||
同时 `UpdateDialogCatalog` 会根据用户角色形成不同视图：
|
||||
|
||||
- `user`
|
||||
- `admin`
|
||||
- `disabled`
|
||||
|
||||
## 6. 用户与管理员差异
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Context[当前用户类型]
|
||||
User[User]
|
||||
Admin[Admin]
|
||||
UserCatalog[推荐稳定版]
|
||||
AdminCatalog[Stable + Preview 目录]
|
||||
|
||||
Context --> User
|
||||
Context --> Admin
|
||||
User --> UserCatalog
|
||||
Admin --> AdminCatalog
|
||||
```
|
||||
|
||||
普通用户主要消费：
|
||||
|
||||
- 推荐版本
|
||||
- 已下载版本
|
||||
- 安装动作
|
||||
|
||||
管理员主要消费：
|
||||
|
||||
- 完整版本目录
|
||||
- Stable / Preview 版本切换
|
||||
- 手动下载并安装
|
||||
|
||||
## 7. 最近的结构优化
|
||||
|
||||
Update 模块已经做过多轮职责拆分：
|
||||
|
||||
- 版本目录决策拆到 `update-catalog-service`
|
||||
- 下载与安装拆到 `update-installer`
|
||||
- 状态广播拆到 `update-status-publisher`
|
||||
- 对象存储访问拆到 `update-storage-client`
|
||||
|
||||
同时前端侧：
|
||||
|
||||
- `useUpdateDialogState` 收敛了选中版本和 changelog 状态
|
||||
- `UpdateDialog` 已改成按需加载
|
||||
|
||||
## 8. 常见改动点
|
||||
|
||||
- 改 renderer 状态流：`useAppBootstrap.ts` / `useUpdateDialogState.ts`
|
||||
- 改弹窗展示：`UpdateDialog.tsx`
|
||||
- 改更新检查与轮询：`update-service.ts`
|
||||
- 改版本决策：`update-catalog-service.ts`
|
||||
- 改安装流程：`update-installer.ts`
|
||||
|
||||
## 9. 修改建议
|
||||
|
||||
- 更新决策逻辑优先放在 main service，不要回流到 renderer
|
||||
- changelog、catalog、status 要保持边界清晰
|
||||
- 用户类型变化时要考虑 status/catalog 的复位逻辑
|
||||
- 如果新增发布通道，优先扩展 catalog service
|
||||
147
docs/developer/modules/validation.md
Normal file
147
docs/developer/modules/validation.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Validation 模块
|
||||
|
||||
`Validation` 模块负责共享订单号管理、输入识别、数据库校验查询、物料结果富化，以及为 Cleaner 提供可消费的数据。
|
||||
|
||||
## 1. 模块职责
|
||||
|
||||
- 存储与读取共享 `Production IDs`
|
||||
- 将输入转换为可校验的 source numbers
|
||||
- 查询数据库中的物料记录
|
||||
- 结合类型关键词和已标记物料生成校验结果
|
||||
- 为 Cleaner 提供订单号与物料代码
|
||||
|
||||
## 2. 模块结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Handler[validation-handler]
|
||||
AppSvc[validation-application-service]
|
||||
Store[shared-production-ids-store]
|
||||
Input[production-input-service]
|
||||
DB[validation-database]
|
||||
DAO[DAO / database services]
|
||||
|
||||
Handler --> Store
|
||||
Handler --> AppSvc
|
||||
AppSvc --> Input
|
||||
AppSvc --> DB
|
||||
DB --> DAO
|
||||
```
|
||||
|
||||
## 3. 关键入口文件
|
||||
|
||||
- `src/main/ipc/validation-handler.ts`
|
||||
- `src/main/services/validation/validation-application-service.ts`
|
||||
- `src/main/services/validation/shared-production-ids-store.ts`
|
||||
- `src/main/services/validation/production-input-service.ts`
|
||||
- `src/main/services/validation/validation-database.ts`
|
||||
- `src/renderer/src/hooks/useValidation.ts`
|
||||
|
||||
## 4. 主流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as Renderer / useValidation / useCleaner
|
||||
participant Handler as validation-handler
|
||||
participant Store as shared-production-ids-store
|
||||
participant AppSvc as validation-application-service
|
||||
participant Input as production-input-service
|
||||
participant DB as validation-database
|
||||
|
||||
UI->>Handler: set/get shared Production IDs
|
||||
Handler->>Store: read/write sender scoped IDs
|
||||
|
||||
UI->>Handler: validate(request)
|
||||
Handler->>AppSvc: validate(...)
|
||||
AppSvc->>Input: resolve source numbers
|
||||
AppSvc->>DB: query material records
|
||||
DB-->>AppSvc: rows
|
||||
AppSvc-->>Handler: validation results + stats
|
||||
Handler-->>UI: response
|
||||
```
|
||||
|
||||
## 5. 共享 Production IDs
|
||||
|
||||
共享订单号是 Validation 模块最重要的跨页面状态之一。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Extractor[Extractor]
|
||||
Store[shared-production-ids-store]
|
||||
Validation[Validation]
|
||||
Cleaner[Cleaner]
|
||||
|
||||
Extractor --> Store
|
||||
Store --> Validation
|
||||
Validation --> Cleaner
|
||||
```
|
||||
|
||||
这个状态当前按 `senderId` 维度存储，主要被：
|
||||
|
||||
- `Extractor`
|
||||
写入
|
||||
- `Validation`
|
||||
读取和解析
|
||||
- `Cleaner`
|
||||
间接消费
|
||||
|
||||
## 6. 结果生成逻辑
|
||||
|
||||
校验结果不仅是数据库原始数据，还会叠加：
|
||||
|
||||
- 已标记删除状态
|
||||
- 负责人关键词匹配
|
||||
- 用户权限作用域
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
DBRows[数据库物料记录]
|
||||
Marked[已标记物料]
|
||||
Keywords[类型关键词]
|
||||
Scope[用户作用域]
|
||||
Result[ValidationResult]
|
||||
|
||||
DBRows --> Result
|
||||
Marked --> Result
|
||||
Keywords --> Result
|
||||
Scope --> Result
|
||||
```
|
||||
|
||||
## 7. 模块输出
|
||||
|
||||
Validation 主要对外输出两类数据：
|
||||
|
||||
- `ValidationResponse`
|
||||
提供给校验页和 Cleaner 页
|
||||
- `CleanerData`
|
||||
提供给 Cleaner 执行前的数据准备
|
||||
|
||||
## 8. 最近的结构优化
|
||||
|
||||
这一块已经从早期的大 `validation-handler` 中拆分出来：
|
||||
|
||||
- `shared-production-ids-store`
|
||||
- `validation-database`
|
||||
- `production-input-service`
|
||||
- `validation-application-service`
|
||||
|
||||
这样之后：
|
||||
|
||||
- handler 只做 IPC 壳
|
||||
- 共享状态有独立归属
|
||||
- 数据库方言差异有独立封装
|
||||
|
||||
## 9. 常见改动点
|
||||
|
||||
- 改共享订单号逻辑：`shared-production-ids-store.ts`
|
||||
- 改输入识别：`production-input-service.ts`
|
||||
- 改数据库差异：`validation-database.ts`
|
||||
- 改校验结果富化：`validation-application-service.ts`
|
||||
- 改 renderer 侧调用：`useValidation.ts`
|
||||
|
||||
## 10. 修改建议
|
||||
|
||||
- 不要再把共享状态放回 handler
|
||||
- 数据库分支优先收敛在 `validation-database`
|
||||
- 校验结果组装逻辑尽量集中在 application service
|
||||
- 跨模块共享数据要保持单向来源清晰
|
||||
Reference in New Issue
Block a user