docs: add developer architecture handbook
This commit is contained in:
Misaka
326
docs/developer/architecture/decision-log.md
Normal file
326
docs/developer/architecture/decision-log.md
Normal file
@@ -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. 相关文件
|
||||
|
||||
建议记录的场景包括：
|
||||
|
||||
- 新增跨层通信机制
|
||||
- 重构核心模块边界
|
||||
- 修改更新、认证、校验、清理主链路
|
||||
- 引入新的状态管理或测试策略
|
||||
Reference in New Issue
Block a user