docs: add developer guides
This commit is contained in:
Misaka
114
docs/developer/guides/README.md
Normal file
114
docs/developer/guides/README.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 开发指南索引
|
||||
|
||||
本目录收录“开发者实际做事时会用到的指南文档”。
|
||||
|
||||
如果 `architecture/` 负责解释系统是什么，`modules/` 负责解释模块怎么工作，那么 `guides/` 负责回答：
|
||||
|
||||
- 本地怎么启动
|
||||
- 出问题怎么调试
|
||||
- 怎么新增或修改 IPC
|
||||
- 怎么开发 renderer
|
||||
- 怎么构建和发布
|
||||
|
||||
## 阅读建议
|
||||
|
||||
如果你是第一次参与这个项目的开发，推荐按下面顺序阅读：
|
||||
|
||||
1. `local-development.md`
|
||||
2. `debugging.md`
|
||||
3. `renderer-development.md`
|
||||
4. `ipc-development.md`
|
||||
5. `release-process.md`
|
||||
|
||||
## 指南地图
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Guides[guides/]
|
||||
Local[local-development]
|
||||
Debug[debugging]
|
||||
Renderer[renderer-development]
|
||||
IPC[ipc-development]
|
||||
Release[release-process]
|
||||
|
||||
Guides --> Local
|
||||
Guides --> Debug
|
||||
Guides --> Renderer
|
||||
Guides --> IPC
|
||||
Guides --> Release
|
||||
```
|
||||
|
||||
## 按任务查阅
|
||||
|
||||
你可以按当前任务来选文档：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Task[当前任务]
|
||||
Start[启动项目]
|
||||
Fix[排查问题]
|
||||
UI[修改前端]
|
||||
Bridge[修改 IPC]
|
||||
Ship[构建 / 发布]
|
||||
|
||||
Task --> Start
|
||||
Task --> Fix
|
||||
Task --> UI
|
||||
Task --> Bridge
|
||||
Task --> Ship
|
||||
|
||||
Start --> LocalDoc[local-development.md]
|
||||
Fix --> DebugDoc[debugging.md]
|
||||
UI --> RendererDoc[renderer-development.md]
|
||||
Bridge --> IPCDoc[ipc-development.md]
|
||||
Ship --> ReleaseDoc[release-process.md]
|
||||
```
|
||||
|
||||
## 当前文档一览
|
||||
|
||||
| 文档 | 主要内容 |
|
||||
| --- | --- |
|
||||
| `local-development.md` | 环境准备、启动、构建、常用命令、本地验证 |
|
||||
| `debugging.md` | 分层调试思路、调试入口、主链路定位方法 |
|
||||
| `renderer-development.md` | React 渲染层开发方式、页面/hook/组件边界 |
|
||||
| `ipc-development.md` | 新增或修改 IPC 能力的推荐实现路径 |
|
||||
| `release-process.md` | 构建、发布、更新产物与上传流程 |
|
||||
|
||||
## 与其他文档目录的关系
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Architecture[architecture/]
|
||||
Modules[modules/]
|
||||
Guides[guides/]
|
||||
|
||||
Architecture --> Modules
|
||||
Modules --> Guides
|
||||
```
|
||||
|
||||
理解方式：
|
||||
|
||||
- 先看 `architecture/`
|
||||
建立系统级认知
|
||||
- 再看 `modules/`
|
||||
理解业务边界
|
||||
- 最后看 `guides/`
|
||||
落到具体开发动作
|
||||
|
||||
## 使用建议
|
||||
|
||||
- 改代码前，先看对应模块文档，再看对应 guide
|
||||
- 如果是跨层改动，优先先看 `ipc-development.md`
|
||||
- 如果是页面交互问题，优先结合 `renderer-development.md` 与模块文档一起看
|
||||
- 如果是运行时问题，优先从 `debugging.md` 开始
|
||||
|
||||
## 后续可继续补充的指南
|
||||
|
||||
随着文档继续完善，后续可以考虑新增：
|
||||
|
||||
- `testing.md`
|
||||
- `database-development.md`
|
||||
- `erp-automation.md`
|
||||
- `config-management.md`
|
||||
|
||||
后续新增指南时，建议同步更新这份索引页，让它持续作为 `guides/` 的入口文档。
|
||||
189
docs/developer/guides/debugging.md
Normal file
189
docs/developer/guides/debugging.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 调试指南
|
||||
|
||||
本文档说明项目里最常见的调试入口、日志观察方式和问题定位路径。
|
||||
|
||||
## 1. 调试总览
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Problem[出现问题]
|
||||
Area{问题在哪一层}
|
||||
Renderer[Renderer]
|
||||
Preload[Preload / IPC]
|
||||
Main[Main / Services]
|
||||
External[ERP / DB / Update]
|
||||
|
||||
Problem --> Area
|
||||
Area --> Renderer
|
||||
Area --> Preload
|
||||
Area --> Main
|
||||
Area --> External
|
||||
```
|
||||
|
||||
## 2. 常见调试入口
|
||||
|
||||
项目里当前有几个现成的调试入口：
|
||||
|
||||
```bash
|
||||
npm run debug:erp-login
|
||||
npm run debug:config-path
|
||||
npm run test:rustfs
|
||||
```
|
||||
|
||||
对应文件：
|
||||
|
||||
- `src/main/tools/erp-login-debug.ts`
|
||||
- `src/main/tools/config-path-debug.ts`
|
||||
- `src/main/tools/rustfs-test.ts`
|
||||
|
||||
## 3. 调试分层思路
|
||||
|
||||
### 3.1 Renderer 问题
|
||||
|
||||
适合从这里开始：
|
||||
|
||||
- `src/renderer/src/App.tsx`
|
||||
- `src/renderer/src/pages/*`
|
||||
- `src/renderer/src/hooks/*`
|
||||
|
||||
常见现象：
|
||||
|
||||
- 页面不更新
|
||||
- 弹窗打不开
|
||||
- 表单状态异常
|
||||
- 请求重复触发
|
||||
|
||||
### 3.2 Preload / IPC 问题
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Renderer --> Preload
|
||||
Preload --> Handler
|
||||
Handler --> Service
|
||||
```
|
||||
|
||||
定位顺序建议：
|
||||
|
||||
1. renderer 是否正确调用 `window.electron.xxx`
|
||||
2. preload facade 是否暴露了正确接口
|
||||
3. handler 是否已注册
|
||||
4. service 是否返回了预期结构
|
||||
|
||||
### 3.3 Main 进程问题
|
||||
|
||||
适合从这里开始：
|
||||
|
||||
- `src/main/index.ts`
|
||||
- `src/main/bootstrap/*`
|
||||
- `src/main/ipc/*`
|
||||
- `src/main/services/*`
|
||||
|
||||
常见现象：
|
||||
|
||||
- 启动失败
|
||||
- 数据库连接失败
|
||||
- ERP 登录失败
|
||||
- 更新检查失败
|
||||
|
||||
## 4. Cleaner 调试路径
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CleanerIssue[Cleaner 问题]
|
||||
UI[CleanerPage / useCleaner]
|
||||
Validation[validation-handler / service]
|
||||
Handler[cleaner-handler]
|
||||
AppSvc[cleaner-application-service]
|
||||
ERP[erp/cleaner.ts]
|
||||
Report[report / rustfs]
|
||||
|
||||
CleanerIssue --> UI
|
||||
UI --> Validation
|
||||
Validation --> Handler
|
||||
Handler --> AppSvc
|
||||
AppSvc --> ERP
|
||||
ERP --> Report
|
||||
```
|
||||
|
||||
## 5. Extractor 调试路径
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
ExtractorIssue[Extractor 问题]
|
||||
Input[ExtractorPage / OrderNumberInput]
|
||||
Hook[useExtractor]
|
||||
Shared[useSharedProductionIds]
|
||||
Handler[extractor-handler]
|
||||
Service[erp/extractor.ts]
|
||||
|
||||
ExtractorIssue --> Input
|
||||
Input --> Hook
|
||||
Input --> Shared
|
||||
Hook --> Handler
|
||||
Handler --> Service
|
||||
```
|
||||
|
||||
## 6. Update 调试路径
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
UpdateIssue[Update 问题]
|
||||
Hook[useAppBootstrap]
|
||||
Dialog[UpdateDialog / useUpdateDialogState]
|
||||
Handler[update-handler]
|
||||
Service[UpdateService]
|
||||
Catalog[UpdateCatalogService]
|
||||
Installer[UpdateInstaller]
|
||||
Storage[UpdateStorageClient]
|
||||
|
||||
UpdateIssue --> Hook
|
||||
UpdateIssue --> Dialog
|
||||
Hook --> Handler
|
||||
Dialog --> Handler
|
||||
Handler --> Service
|
||||
Service --> Catalog
|
||||
Service --> Installer
|
||||
Service --> Storage
|
||||
```
|
||||
|
||||
## 7. 认证调试路径
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as useAppBootstrap
|
||||
participant Auth as auth-handler
|
||||
participant AppSvc as auth-application-service
|
||||
participant Session as session-manager
|
||||
|
||||
App->>Auth: silentLogin / login / switchUser
|
||||
Auth->>AppSvc: application service
|
||||
AppSvc->>Session: user resolution
|
||||
Session-->>AppSvc: session result
|
||||
AppSvc-->>Auth: response
|
||||
Auth-->>App: auth state
|
||||
```
|
||||
|
||||
## 8. 日志观察建议
|
||||
|
||||
调试时优先关注：
|
||||
|
||||
- renderer 控制台输出
|
||||
- main 进程日志
|
||||
- 关键 application service 的 logger 输出
|
||||
- audit log（如果问题涉及登录、清理等操作记录）
|
||||
|
||||
## 9. 定位建议
|
||||
|
||||
出现问题时，建议优先回答这几个问题：
|
||||
|
||||
1. 问题发生在哪一层
|
||||
2. 是状态流问题还是外部依赖问题
|
||||
3. 是请求没发出、没到 handler，还是 service 失败
|
||||
4. 是同步返回问题，还是事件推送问题
|
||||
|
||||
## 10. 调试原则
|
||||
|
||||
- 先缩小层级，再深入代码
|
||||
- 先看入口与边界，再看实现细节
|
||||
- 能复现就尽量用最小路径复现
|
||||
- 复杂主链路优先画调用链再改代码
|
||||
159
docs/developer/guides/ipc-development.md
Normal file
159
docs/developer/guides/ipc-development.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# IPC 开发指南
|
||||
|
||||
本文档说明在项目中新增或修改一个 IPC 能力时，推荐的实现路径和注意事项。
|
||||
|
||||
## 1. IPC 开发原则
|
||||
|
||||
当前项目的 IPC 目标结构是：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Renderer[Renderer]
|
||||
Preload[Preload Facade]
|
||||
Handler[IPC Handler]
|
||||
AppService[Application Service]
|
||||
Domain[Domain Service / DAO]
|
||||
|
||||
Renderer --> Preload --> Handler --> AppService --> Domain
|
||||
```
|
||||
|
||||
原则：
|
||||
|
||||
- renderer 不直接感知 IPC channel 细节
|
||||
- preload 负责 facade 化
|
||||
- handler 保持薄壳
|
||||
- 业务逻辑尽量放到 application service 或 domain service
|
||||
|
||||
## 2. 新增一个 IPC 能力的推荐步骤
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Need[需要新增能力]
|
||||
Types[定义类型]
|
||||
Service[实现 service]
|
||||
Handler[注册 handler]
|
||||
Preload[暴露 preload API]
|
||||
Renderer[接入 renderer]
|
||||
Test[补测试]
|
||||
|
||||
Need --> Types --> Service --> Handler --> Preload --> Renderer --> Test
|
||||
```
|
||||
|
||||
## 3. 第一步：定义类型
|
||||
|
||||
优先在稳定类型层定义：
|
||||
|
||||
- request 类型
|
||||
- response 类型
|
||||
- preload 暴露面类型
|
||||
|
||||
常见位置：
|
||||
|
||||
- `src/main/types/`
|
||||
- `src/preload/index.d.ts`
|
||||
|
||||
## 4. 第二步：实现 service
|
||||
|
||||
如果能力有实际业务逻辑，优先先写 service。
|
||||
|
||||
不要直接把逻辑堆到 handler 里。
|
||||
|
||||
示意结构：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Request[Request]
|
||||
Handler[Handler]
|
||||
Service[Application Service]
|
||||
Repo[Repository / DAO]
|
||||
Response[Response]
|
||||
|
||||
Request --> Handler
|
||||
Handler --> Service
|
||||
Service --> Repo
|
||||
Repo --> Service
|
||||
Service --> Handler
|
||||
Handler --> Response
|
||||
```
|
||||
|
||||
## 5. 第三步：注册 handler
|
||||
|
||||
常见位置：
|
||||
|
||||
- `src/main/ipc/<module>-handler.ts`
|
||||
- `src/main/ipc/index.ts`
|
||||
|
||||
handler 里建议只做：
|
||||
|
||||
- 接收参数
|
||||
- 转发给 service
|
||||
- 用统一错误包装返回 `IpcResult`
|
||||
|
||||
## 6. 第四步：接到 preload
|
||||
|
||||
常见位置：
|
||||
|
||||
- `src/preload/api/<module>.ts`
|
||||
- `src/preload/api/index.ts`
|
||||
- `src/preload/index.d.ts`
|
||||
|
||||
preload 的职责是把主进程能力变成 renderer 可调用的 facade，而不是承载业务判断。
|
||||
|
||||
## 7. 第五步：接到 renderer
|
||||
|
||||
renderer 侧通常有两种接法：
|
||||
|
||||
- 直接在页面 hook 中调用
|
||||
- 先落一层 hook / helper，再被页面使用
|
||||
|
||||
建议优先把复杂调用路径集中到 hook。
|
||||
|
||||
## 8. 典型示例路径
|
||||
|
||||
以一个校验相关能力为例：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as useCleaner / useValidation
|
||||
participant Preload as preload.validation
|
||||
participant Handler as validation-handler
|
||||
participant AppSvc as validation-application-service
|
||||
|
||||
UI->>Preload: validate(request)
|
||||
Preload->>Handler: invoke
|
||||
Handler->>AppSvc: validate(...)
|
||||
AppSvc-->>Handler: response
|
||||
Handler-->>Preload: IpcResult
|
||||
Preload-->>UI: normalized result
|
||||
```
|
||||
|
||||
## 9. 修改 IPC 时优先检查的文件
|
||||
|
||||
- `src/main/ipc/index.ts`
|
||||
- `src/main/ipc/<module>-handler.ts`
|
||||
- `src/main/services/<module>/...`
|
||||
- `src/preload/api/<module>.ts`
|
||||
- `src/preload/api/index.ts`
|
||||
- `src/preload/index.d.ts`
|
||||
- renderer 对应 hook / page
|
||||
|
||||
## 10. 测试建议
|
||||
|
||||
如果是新增 IPC 能力，建议至少补：
|
||||
|
||||
- handler 单测
|
||||
- application service 单测
|
||||
- preload surface 或 renderer 状态测试（视复杂度而定）
|
||||
|
||||
## 11. 常见反模式
|
||||
|
||||
- 直接在页面里拼 IPC channel
|
||||
- handler 里写完整业务流程
|
||||
- preload 里堆业务分支
|
||||
- 改了主进程返回结构但不更新 renderer 类型
|
||||
|
||||
## 12. 实践建议
|
||||
|
||||
- 优先复用现有领域模块
|
||||
- 先想边界，再写调用
|
||||
- 先让主进程能力清晰，再接 renderer
|
||||
193
docs/developer/guides/local-development.md
Normal file
193
docs/developer/guides/local-development.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# 本地开发指南
|
||||
|
||||
本文档说明如何在本地启动、检查、构建和验证项目。
|
||||
|
||||
## 1. 开发环境概览
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Clone[拉取代码]
|
||||
Install[安装依赖]
|
||||
Config[准备配置]
|
||||
Dev[启动开发环境]
|
||||
Verify[类型检查 / lint / 测试]
|
||||
|
||||
Clone --> Install --> Config --> Dev --> Verify
|
||||
```
|
||||
|
||||
## 2. 基础要求
|
||||
|
||||
- Node.js >= 18
|
||||
- npm >= 9
|
||||
- 本地可访问 ERP 系统
|
||||
- 可访问 MySQL 或 SQL Server
|
||||
|
||||
## 3. 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## 4. 准备配置
|
||||
|
||||
项目使用 `config.yaml` 作为主配置文件。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Config[config.yaml]
|
||||
ERP[ERP URL]
|
||||
DB[数据库配置]
|
||||
Update[更新配置]
|
||||
Paths[路径配置]
|
||||
|
||||
Config --> ERP
|
||||
Config --> DB
|
||||
Config --> Update
|
||||
Config --> Paths
|
||||
```
|
||||
|
||||
至少要确认这些配置可用：
|
||||
|
||||
- ERP URL
|
||||
- 当前使用的数据库类型
|
||||
- 数据库连接信息
|
||||
|
||||
说明：
|
||||
|
||||
- ERP 用户名和密码不是放在 `config.yaml`
|
||||
- 这部分在应用设置页中按用户存储
|
||||
|
||||
## 5. 启动开发环境
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
开发启动链路如下：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Dev as npm run dev
|
||||
participant Vite as electron-vite
|
||||
participant Main as main process
|
||||
participant Preload as preload build
|
||||
participant Renderer as renderer dev server
|
||||
|
||||
Dev->>Vite: electron-vite dev
|
||||
Vite->>Main: build main
|
||||
Vite->>Preload: build preload
|
||||
Vite->>Renderer: start renderer dev server
|
||||
Vite->>Main: launch electron
|
||||
```
|
||||
|
||||
## 6. 常用开发命令
|
||||
|
||||
```bash
|
||||
# 启动开发环境
|
||||
npm run dev
|
||||
|
||||
# 类型检查
|
||||
npm run typecheck
|
||||
|
||||
# 代码格式化
|
||||
npm run format
|
||||
|
||||
# lint
|
||||
npm run lint
|
||||
|
||||
# 单测
|
||||
npm run test:run
|
||||
|
||||
# E2E
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## 7. 构建命令
|
||||
|
||||
当前正式维护的是 Windows 构建链路。
|
||||
|
||||
```bash
|
||||
# 常规构建
|
||||
npm run build
|
||||
|
||||
# Windows 安装版
|
||||
npm run build:win
|
||||
|
||||
# 仅生成 unpack 目录
|
||||
npm run build:unpack
|
||||
```
|
||||
|
||||
构建路径如下：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Build[build]
|
||||
Typecheck[typecheck]
|
||||
ElectronVite[electron-vite build]
|
||||
Updater[build:updater]
|
||||
Builder[electron-builder]
|
||||
|
||||
Build --> Typecheck
|
||||
Build --> ElectronVite
|
||||
Build --> Updater
|
||||
Build --> Builder
|
||||
```
|
||||
|
||||
## 8. 日常验证建议
|
||||
|
||||
修改代码后，建议至少跑：
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npx eslint <changed files>
|
||||
```
|
||||
|
||||
如果改到关键主链路，再补：
|
||||
|
||||
```bash
|
||||
npx vitest run <related tests>
|
||||
```
|
||||
|
||||
## 9. 常见本地问题
|
||||
|
||||
### 9.1 `npm run dev` 无法启动
|
||||
|
||||
优先检查：
|
||||
|
||||
- `config.yaml` 是否存在
|
||||
- 数据库配置是否正确
|
||||
- 当前终端里是否残留异常环境变量
|
||||
|
||||
### 9.2 类型检查失败
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
TypeError[类型错误]
|
||||
Main{node 还是 web}
|
||||
Node[node tsconfig]
|
||||
Web[web tsconfig]
|
||||
Fix[修正类型引用边界]
|
||||
|
||||
TypeError --> Main
|
||||
Main --> Node
|
||||
Main --> Web
|
||||
Node --> Fix
|
||||
Web --> Fix
|
||||
```
|
||||
|
||||
### 9.3 ERP 登录相关问题
|
||||
|
||||
优先检查：
|
||||
|
||||
- 设置页中的 ERP 账号密码
|
||||
- ERP URL
|
||||
- 网络可达性
|
||||
- 是否可用调试脚本复现
|
||||
|
||||
## 10. 相关文件
|
||||
|
||||
- `package.json`
|
||||
- `config.yaml`
|
||||
- `src/main/index.ts`
|
||||
- `src/main/bootstrap/runtime.ts`
|
||||
- `electron-builder.yml`
|
||||
138
docs/developer/guides/release-process.md
Normal file
138
docs/developer/guides/release-process.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# 发布流程指南
|
||||
|
||||
本文档说明当前项目的构建、发布和上传链路。
|
||||
|
||||
当前正式维护的是 Windows 发布流程。
|
||||
|
||||
## 1. 发布链路总览
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Prepare[release:prepare]
|
||||
Build[build / build:win]
|
||||
Updater[build:updater]
|
||||
Publish[release:publish]
|
||||
Upload[release:upload]
|
||||
|
||||
Prepare --> Build
|
||||
Build --> Updater
|
||||
Updater --> Publish
|
||||
Publish --> Upload
|
||||
```
|
||||
|
||||
## 2. 当前相关命令
|
||||
|
||||
```bash
|
||||
npm run release:prepare
|
||||
npm run build:win
|
||||
npm run release:publish
|
||||
npm run release:upload
|
||||
```
|
||||
|
||||
以及构建相关命令：
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run build:updater
|
||||
npm run build:unpack
|
||||
```
|
||||
|
||||
## 3. 相关脚本
|
||||
|
||||
当前发布链路涉及这些脚本：
|
||||
|
||||
- `scripts/prepare-release.js`
|
||||
- `scripts/publish-release.js`
|
||||
- `scripts/upload-release.js`
|
||||
- `scripts/compile-updater.js`
|
||||
|
||||
## 4. 构建阶段
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Prebuild[prebuild]
|
||||
Typecheck[typecheck]
|
||||
Vite[electron-vite build]
|
||||
Updater[compile-updater]
|
||||
Builder[electron-builder --win]
|
||||
|
||||
Prebuild --> Typecheck --> Vite --> Updater --> Builder
|
||||
```
|
||||
|
||||
这一阶段大致会完成：
|
||||
|
||||
- 清理旧产物
|
||||
- 类型检查
|
||||
- 构建 main / preload / renderer
|
||||
- 构建更新相关产物
|
||||
- 生成 Windows 安装包
|
||||
|
||||
## 5. 发布前建议检查
|
||||
|
||||
发布前建议确认：
|
||||
|
||||
- `npm run typecheck` 通过
|
||||
- 关键测试通过
|
||||
- `config.yaml` / 发布配置没有误改
|
||||
- 更新目录与版本号符合预期
|
||||
- release 文案、构建产物和上传目标一致
|
||||
|
||||
## 6. 更新链路关系
|
||||
|
||||
发布流程和 update 模块关系很强：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Release[发布脚本]
|
||||
Artifact[构建产物]
|
||||
Storage[对象存储 / 发布目录]
|
||||
Update[UpdateService]
|
||||
Client[客户端 UpdateDialog]
|
||||
|
||||
Release --> Artifact
|
||||
Artifact --> Storage
|
||||
Storage --> Update
|
||||
Update --> Client
|
||||
```
|
||||
|
||||
也就是说，发布流程最终会直接影响：
|
||||
|
||||
- `UpdateCatalogService`
|
||||
- `UpdateDialog`
|
||||
- 客户端是否能正确检测与安装更新
|
||||
|
||||
## 7. 常见问题
|
||||
|
||||
### 7.1 构建失败
|
||||
|
||||
优先检查：
|
||||
|
||||
- `npm run typecheck`
|
||||
- 更新编译脚本是否正常
|
||||
- Windows 构建配置是否被误改
|
||||
|
||||
### 7.2 发布后客户端看不到更新
|
||||
|
||||
优先检查：
|
||||
|
||||
- 发布目录是否正确上传
|
||||
- 版本号与 channel 是否正确
|
||||
- update catalog 是否包含该版本
|
||||
- 客户端 `UpdateService` 是否成功拉取目录
|
||||
|
||||
### 7.3 上传成功但安装失败
|
||||
|
||||
优先检查：
|
||||
|
||||
- `UpdateInstaller` 的下载与校验逻辑
|
||||
- 产物哈希是否正确
|
||||
- 客户端本地下载路径与安装流程
|
||||
|
||||
## 8. 相关文件
|
||||
|
||||
- `package.json`
|
||||
- `electron-builder.yml`
|
||||
- `scripts/prepare-release.js`
|
||||
- `scripts/publish-release.js`
|
||||
- `scripts/upload-release.js`
|
||||
- `src/main/services/update/*`
|
||||
164
docs/developer/guides/renderer-development.md
Normal file
164
docs/developer/guides/renderer-development.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Renderer 开发指南
|
||||
|
||||
本文档说明在当前项目里开发 React 渲染层时，推荐的组织方式和常见改动路径。
|
||||
|
||||
## 1. 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
|
||||
```
|
||||
|
||||
## 2. 开发原则
|
||||
|
||||
当前 renderer 层推荐遵循这些边界：
|
||||
|
||||
- 页面组件优先作为组装层
|
||||
- 复杂流程优先下沉到 hook
|
||||
- 纯逻辑优先抽到 helper / lib
|
||||
- 非首屏重型弹窗优先考虑懒加载
|
||||
- bridge 调用优先放在 hook，不直接散落在组件树中
|
||||
|
||||
## 3. 页面开发路径
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Feature[新增或修改页面功能]
|
||||
Page[页面容器]
|
||||
Hook[页面 Hook]
|
||||
Components[子组件]
|
||||
Helpers[helper / lib]
|
||||
Preload[window.electron facade]
|
||||
|
||||
Feature --> Page
|
||||
Page --> Hook
|
||||
Page --> Components
|
||||
Hook --> Helpers
|
||||
Hook --> Preload
|
||||
```
|
||||
|
||||
## 4. 当前页面入口
|
||||
|
||||
主要页面：
|
||||
|
||||
- `ExtractorPage.tsx`
|
||||
- `CleanerPage.tsx`
|
||||
- `SettingsPage.tsx`
|
||||
|
||||
主壳层：
|
||||
|
||||
- `App.tsx`
|
||||
- `AuthenticatedAppShell.tsx`
|
||||
- `UnauthenticatedApp.tsx`
|
||||
|
||||
## 5. Hook 组织建议
|
||||
|
||||
推荐把 hook 分成几类：
|
||||
|
||||
- 页面启动/编排 hook
|
||||
例如 `useAppBootstrap`
|
||||
- 业务流程 hook
|
||||
例如 `useCleaner`、`useExtractor`
|
||||
- 辅助状态 hook
|
||||
例如 `usePersistentTextState`、`useSharedProductionIds`
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Page[Page]
|
||||
Bootstrap[Bootstrap Hook]
|
||||
Domain[Domain Hook]
|
||||
Helper[Helper Hook]
|
||||
|
||||
Page --> Bootstrap
|
||||
Page --> Domain
|
||||
Domain --> Helper
|
||||
```
|
||||
|
||||
## 6. 当前推荐风格
|
||||
|
||||
结合近期重构，当前 renderer 更推荐：
|
||||
|
||||
- `App.tsx` 保持薄入口
|
||||
- `CleanerPage` 保持页面布局和弹窗编排
|
||||
- 重型局部区域拆成子组件
|
||||
- 异步状态收敛到 hook
|
||||
|
||||
## 7. 状态更新建议
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Input[用户输入]
|
||||
Local[局部 state]
|
||||
Derived[派生状态]
|
||||
Async[异步请求]
|
||||
UI[UI 更新]
|
||||
|
||||
Input --> Local
|
||||
Local --> Derived
|
||||
Local --> Async
|
||||
Derived --> UI
|
||||
Async --> UI
|
||||
```
|
||||
|
||||
建议：
|
||||
|
||||
- 能派生的状态尽量派生，不额外存储
|
||||
- 输入态不要直接挂太多高频副作用
|
||||
- 非紧急 UI 更新可考虑 `startTransition`
|
||||
|
||||
## 8. 弹窗开发建议
|
||||
|
||||
当前项目弹窗较多，建议遵循：
|
||||
|
||||
- 非首屏关键弹窗优先懒加载
|
||||
- 弹窗状态尽量放在页面或页面 hook 中统一管理
|
||||
- 弹窗本身专注展示和内部交互
|
||||
|
||||
## 9. 典型改动路径
|
||||
|
||||
### 改 Cleaner 页面
|
||||
|
||||
- `CleanerPage.tsx`
|
||||
- `components/cleaner/*`
|
||||
- `useCleaner.ts`
|
||||
- `hooks/cleaner/*`
|
||||
|
||||
### 改 Extractor 页面
|
||||
|
||||
- `ExtractorPage.tsx`
|
||||
- `useExtractor.ts`
|
||||
- `useSharedProductionIds.ts`
|
||||
|
||||
### 改更新弹窗
|
||||
|
||||
- `UpdateDialog.tsx`
|
||||
- `useUpdateDialogState.ts`
|
||||
- `useAppBootstrap.ts`
|
||||
|
||||
## 10. 测试建议
|
||||
|
||||
当前 renderer 测试更适合先从：
|
||||
|
||||
- 状态 helper
|
||||
- hook 决策逻辑
|
||||
- 与 preload 调用边界有关的轻量测试
|
||||
|
||||
开始补，而不是一上来就做全量 UI 集成测试。
|
||||
|
||||
## 11. 常见反模式
|
||||
|
||||
- 页面组件同时承载过多副作用
|
||||
- 在组件中直接散布大量 `window.electron.xxx`
|
||||
- 一个 hook 同时管理初始化、交互、请求、持久化和对话框
|
||||
- 非首屏重型组件全部静态导入
|
||||
Reference in New Issue
Block a user