# Electron 最佳实践优化计划

本文档基于 `$electron-best-practices` 对当前项目的审查结果整理而成，目标不是一次性重构整个 Electron 应用，而是按照“低风险、可验证、逐步收敛”的方式，分阶段提升主进程、preload、IPC、更新模块和工程配置的可维护性。

## 1. 计划背景

当前项目已经具备了较好的 Electron 基础结构：

- 主进程、preload、renderer 三层已分离
- Renderer 通过 `contextBridge` 暴露能力
- IPC 统一采用 `invoke/handle` 模式
- 大部分主进程能力已经模块化到 `ipc/` 与 `services/`

但从长期维护角度看，项目仍存在几个明显问题：

- `src/main/index.ts` 入口文件承担职责过多
- 部分 IPC handler 仍然是“厚编排层”
- `src/preload/index.ts` 更像“接口总表”，不是按领域划分的 facade
- 更新链路实现较重，边界尚不清晰
- 打包配置存在模板残留，容易误导维护者
- Electron 边界层测试尚未系统化

## 2. 优化目标

本轮优化聚焦以下目标：

- 让主进程入口只负责启动顺序，不承载业务细节
- 让 IPC handler 回归“薄壳”，把编排逻辑下沉到应用服务层
- 让 preload API 按业务领域组织，而不是按主进程实现镜像
- 收敛更新模块的职责边界，降低后续维护复杂度
- 清理打包与发布配置中的模板残留
- 为 Electron 边界补足更稳定的测试支撑

## 3. 优化范围

本计划优先处理 Electron 工程化与可维护性问题，不把安全性作为唯一优先目标，但会顺带处理那些同时影响可维护性的边界设计问题。

本次计划重点覆盖：

- 主进程启动与应用初始化
- IPC handler 与 application service 分层
- preload API 结构
- 更新模块
- 打包配置
- Electron 边界层测试

暂不作为本轮首要目标：

- 大规模 UI 重构
- 业务流程重写
- ERP 自动化细节重构

## 4. 当前问题总览

```mermaid
graph TD
    MainIndex[src/main/index.ts]
    IPC[IPC Handlers]
    Preload[src/preload/index.ts]
    Update[update-service.ts]
    Builder[electron-builder.yml]
    Tests[tests/unit]

    MainIndex -->|启动逻辑过重| Maintainability[维护成本上升]
    IPC -->|编排过厚| Maintainability
    Preload -->|API 面过大| Maintainability
    Update -->|职责边界不清| Maintainability
    Builder -->|模板残留| Maintainability
    Tests -->|边界覆盖不足| Maintainability
```

## 5. 分阶段执行计划

### Phase 1: 收敛主进程入口

目标：

- 让 `src/main/index.ts` 只表达启动顺序
- 把运行时检查、窗口创建、异常守卫、模块初始化拆到独立函数或模块

建议涉及文件：

- `src/main/index.ts`
- `src/main/bootstrap/` 下新增或调整模块

建议拆分方向：

- `bootstrapApp()`
- `createMainWindow()`
- `setupProcessGuards()`
- `verifyPlaywrightRuntime()`
- `initializeAppServices()`

预期收益：

- 降低入口文件修改风险
- 提高启动问题排查效率
- 为多窗口、多实例策略预留更清晰的扩展点

风险等级：

- 低到中

验证方式：

- 应用冷启动成功
- 窗口创建与关闭流程正常
- 异常日志、更新初始化、IPC 注册行为不回归

### Phase 2: 让 IPC Handler 回归薄壳

目标：

- 把 `cleaner-handler`、`auth-handler` 这类厚编排层下沉到应用服务
- 明确 handler、application service、infrastructure service 的职责边界

建议涉及文件：

- `src/main/ipc/cleaner-handler.ts`
- `src/main/ipc/auth-handler.ts`
- `src/main/ipc/update-handler.ts`
- `src/main/services/`

建议拆分方向：

- `CleanerApplicationService`
- `AuthApplicationService`
- `UpdateApplicationService`

handler 只负责：

- 接收请求
- 调用 service
- 映射返回结构
- 统一错误包装

预期收益：

- 提升主进程业务编排的可测试性
- 降低 handler 文件复杂度
- 让业务流程更容易被复用和替换

风险等级：

- 中

验证方式：

- 关键 IPC 流程回归测试
- 原有 renderer 调用协议保持不变
- 清理、登录、更新等主流程手动验收通过

### Phase 3: 重组 Preload API

目标：

- 把 `src/preload/index.ts` 从“大总表”改造成“按领域组织的 facade”
- 稳定 renderer 对 Electron 能力的访问边界

建议涉及文件：

- `src/preload/index.ts`
- `src/preload/index.d.ts`
- `src/main/types/`

建议拆分方向：

- `authApi`
- `cleanerApi`
- `updateApi`
- `reportApi`
- `fileApi`

建议原则：

- renderer 只拿到业务语义接口
- preload 不原样映射主进程实现细节
- 类型定义集中管理，避免 renderer 和 main 双边漂移

预期收益：

- 降低渲染层对 IPC 细节的耦合
- 提高 preload 的可读性和可扩展性
- 为后续做 runtime schema 校验打基础

风险等级：

- 中

验证方式：

- `npm run typecheck`
- preload surface 测试通过
- 主要页面功能回归正常

### Phase 4: 收敛更新模块边界

目标：

- 把更新服务中的下载、状态管理、安装协调、日志处理边界进一步明确
- 降低自定义更新链路的维护成本

建议涉及文件：

- `src/main/services/update/update-service.ts`
- `src/main/ipc/update-handler.ts`
- `src/main/types/`

建议拆分方向：

- `UpdateStateMachine`
- `UpdateDownloadService`
- `UpdateInstallCoordinator`
- `UpdateEventBridge`

预期收益：

- 更新问题更容易定位
- 状态流转更容易测试
- 后续切换更新策略时影响面更小

风险等级：

- 中到高

验证方式：

- 更新检查、下载、安装提示链路验证
- 状态事件顺序测试
- 失败重试与异常日志验证

### Phase 5: 清理打包与发布配置

目标：

- 让构建配置更贴近当前项目实际维护范围
- 清理无效、模板化或误导性的配置项

建议涉及文件：

- `electron-builder.yml`
- `package.json`
- `scripts/` 下发布相关脚本
- `docs/releases/` 与构建说明文档

重点检查项：

- 实际支持的平台范围
- 发布目标与渠道
- 无关权限说明
- Windows 优先配置是否清晰

预期收益：

- 降低发版配置理解成本
- 减少“看似支持、实际无人维护”的伪能力
- 让发布文档与配置保持一致

风险等级：

- 低

验证方式：

- 本地构建通过
- 发布脚本执行链路无回归
- 文档与配置一致性核对完成

### Phase 6: 补强 Electron 边界层测试

目标：

- 让最容易劣化的 Electron 边界层拥有稳定回归保护

建议涉及文件：

- `tests/unit/preload-surface.test.ts`
- `tests/unit/ipc-index.test.ts`
- 新增 `tests/unit/update-service.*`
- 新增 `tests/unit/cleaner-handler.*`
- 新增 `tests/unit/auth-handler.*`

优先补测内容：

- 主进程启动编排
- preload surface 稳定性
- IPC 返回包装与错误路径
- update service 状态迁移
- handler 与 service 交互边界

预期收益：

- 降低后续拆分时的回归风险
- 提升主进程重构信心
- 让 Electron 工程层而非仅业务工具层获得测试保护

风险等级：

- 低

验证方式：

- 单元测试通过
- 关键流程 smoke test 通过

## 6. 推荐执行顺序

```mermaid
graph LR
    A[Phase 1 主进程入口收敛]
    B[Phase 2 IPC Handler 薄壳化]
    C[Phase 3 Preload API 重组]
    D[Phase 4 更新模块收敛]
    E[Phase 5 构建配置清理]
    F[Phase 6 Electron 边界测试补强]

    A --> B
    B --> C
    C --> D
    D --> E
    B --> F
    C --> F
    D --> F
```

建议优先顺序：

1. 先做主进程入口收敛
2. 再做 IPC handler 薄壳化
3. 然后重组 preload API
4. 再处理更新模块
5. 清理打包配置
6. 在每一阶段同步补强测试

说明：

- `Phase 1` 与 `Phase 2` 性价比最高
- `Phase 3` 适合在 handler 边界稳定后推进
- `Phase 4` 风险相对更高，应放在前面边界清晰后再处理
- `Phase 6` 不应完全放到最后，建议伴随每阶段一起推进

## 7. 每阶段完成标准

每一阶段建议采用统一完成标准：

- 相关模块职责边界变清晰
- 对外接口保持兼容或完成显式迁移
- `npm run lint` 通过
- `npm run typecheck` 通过
- 相关单元测试通过
- 关键手工路径验证完成
- 对应文档同步更新

## 8. 本计划与现有重构工作的衔接

当前已经完成的两轮重构：

- `validation-handler` 第一阶段拆分
- `useCleaner` 第一阶段拆分

它们为本计划提供了两个基础：

- 团队已经验证“先拆超大文件，再保持对外行为不变”的策略可行
- 后续继续拆 `cleaner-handler`、`preload`、`App` 时，可以沿用相同方法论

因此，Electron 向优化建议优先从主进程和边界层继续推进，而不是立刻进入更深的 UI 重构。

## 9. 后续建议

建议后续执行方式如下：

1. 先按本计划完成 `Phase 1`
2. 每完成一个阶段，单独补一份重构说明文档
3. 每个阶段单独提交，避免一次性大改
4. 每阶段结束后重新运行 `lint`、`typecheck` 和对应测试

如果后续决定正式执行，本计划可作为 Electron 工程化重构的主索引文档持续维护。