BIPMaterialManager/docs/features/use-cleaner-refactor-overview.md

useCleaner 重构说明

本文档记录 src/renderer/src/hooks/useCleaner.ts 的第一阶段重构工作。目标不是一次性把整个 Cleaner 页面完全组件化，而是优先拆出共享类型、纯函数和 IPC 编排逻辑，让 useCleaner 从“大而全逻辑容器”逐步收敛为“组合层”。

1. 重构背景

重构前，useCleaner.ts 同时负责：

• 页面初始化
• 权限判断
• sessionStorage 持久化
• 校验请求
• 结果筛选
• 勾选状态处理
• 删除计划构建
• 保存物料变更
• Cleaner 执行编排
• 导出编排
• 弹窗确认
• 报告状态维护

这导致它虽然名义上是一个 hook，但实际上已经接近一个“前端页面服务总线”。

2. 重构目标

本次重构目标是：

• 提取共享类型，消除重复定义
• 提取纯函数，隔离无副作用逻辑
• 提取 IPC / 异步编排，隔离对 window.electron 的直接调用
• 保持 useCleaner() 返回值和 CleanerPage.tsx 使用方式不变

3. 重构后结构

graph TD
    Page[CleanerPage.tsx]
    Hook[useCleaner.ts]

    subgraph CleanerHookModules[Cleaner Hook Modules]
        Types[hooks/cleaner/types.ts]
        Helpers[hooks/cleaner/helpers.ts]
        Api[hooks/cleaner/api.ts]
    end

    subgraph ExternalDeps[External Dependencies]
        Electron[window.electron]
        Store[useAppStore / Toast]
        Dialog[ConfirmDialog]
    end

    Page --> Hook
    Hook --> Types
    Hook --> Helpers
    Hook --> Api
    Hook --> Store
    Hook --> Dialog
    Api --> Electron

4. 本次拆分内容

4.1 共享类型

新增：

• src/renderer/src/hooks/cleaner/types.ts

统一收敛了以下类型：

• ValidationRequest
• ValidationResult
• ValidationStats
• ValidationResponsePayload
• CleanerProgress
• CleanerReportData
• CleanerInitializationResult
• CleanerConfigResult

这一步解决了原来多个文件重复定义同类类型的问题，比如：

• useCleaner.ts
• useValidation.ts
• ExecutionReportDialog.tsx

4.2 纯函数与数据构造

新增：

• src/renderer/src/hooks/cleaner/helpers.ts

提取出的纯函数包括：

• getStoredBoolean()
• getStoredValidationMode()
• filterValidationResults()
• buildDeletionPlan()
• buildExportItems()

这些逻辑之前都散落在 useCleaner.ts 的 useMemo 或事件处理函数里，现在可以单独测试。

4.3 IPC 与异步编排

新增：

• src/renderer/src/hooks/cleaner/api.ts

提取出的异步编排包括：

• initializeCleanerPage()
• loadCleanerConfig()
• runValidationRequest()
• saveDeletionPlan()
• reloadManagers()
• runCleanerExecution()
• exportCleanerResults()

这样做之后，useCleaner.ts 不再需要在每个 handler 里直接拼接 window.electron.xxx 调用细节。

5. useCleaner 的角色变化

flowchart LR
    subgraph Before[重构前]
        A[useCleaner.ts]
        A --> A1[本地状态]
        A --> A2[筛选逻辑]
        A --> A3[删除计划构建]
        A --> A4[执行清理请求]
        A --> A5[导出请求]
        A --> A6[初始化请求]
        A --> A7[共享类型定义]
    end

    subgraph After[重构后]
        B[useCleaner.ts]
        B --> B1[组合状态]
        B --> B2[调用 helpers]
        B --> B3[调用 api]

        C[helpers.ts]
        D[api.ts]
        E[types.ts]

        B --> C
        B --> D
        B --> E
    end

重构后，useCleaner.ts 更接近“组合层”：

• 管理 React state
• 串联用户交互流程
• 调用 helpers 和 api
• 将最终能力暴露给页面

6. 受影响的文件

6.1 主体修改

• src/renderer/src/hooks/useCleaner.ts
• src/renderer/src/hooks/useValidation.ts
• src/renderer/src/components/ExecutionReportDialog.tsx

6.2 新增模块

• src/renderer/src/hooks/cleaner/types.ts
• src/renderer/src/hooks/cleaner/helpers.ts
• src/renderer/src/hooks/cleaner/api.ts

6.3 新增测试

• tests/unit/cleaner-helpers.test.ts

7. 具体收益

7.1 类型一致性提升

之前 ValidationResult、CleanerProgress 在多个文件重复定义，修改字段时容易遗漏。
现在统一从 hooks/cleaner/types.ts 引用，降低了类型漂移风险。

7.2 可测试性提升

原先删除计划构建、筛选和导出映射逻辑只能通过 hook 间接覆盖。
现在这些逻辑已经被抽成纯函数，可以直接做单测。

7.3 Hook 复杂度下降

虽然 useCleaner.ts 还没有变成一个很小的文件，但其中的“细节密度”已经明显下降：

• 数据变换逻辑外提
• API 编排逻辑外提
• 重复类型移除

7.4 为下一步组件拆分做准备

后续如果要拆 CleanerPage.tsx：

• 左侧筛选区
• 表格工具栏
• 底部执行区

这些组件就可以直接消费已经整理好的 hook 能力，而不是继续把逻辑往页面里塞。

8. 验证方式

本次重构后执行了以下验证：

• npm run typecheck:node
• tests/unit/cleaner-helpers.test.ts
• tests/unit/cleaner.test.ts

9. 新增测试覆盖点

tests/unit/cleaner-helpers.test.ts 覆盖了：

• 非管理员筛选逻辑
• 删除计划构建逻辑
• 导出数据构建逻辑

10. 仍然保留在 useCleaner 中的内容

为了控制改动风险，这次没有继续下沉以下能力：

• ConfirmDialog 的 Promise 封装
• 编辑状态 editingCell / editValue
• isRunning / isExecuting / isReportDialogOpen 等 UI 状态
• 页面层直接依赖的完整返回对象

这些能力仍然保留在 useCleaner.ts，因为它们和当前页面交互绑定较深。

11. 下一步建议

基于目前的结构，建议下一阶段继续做：

1. 拆 CleanerPage.tsx 为“左侧筛选区”和“右侧结果与执行区”两个子组件。
2. 将 showConfirmDialog() 封装为独立 hook，例如 useConfirmDialogController()。
3. 将 inline edit 相关逻辑提取到更专门的 manager-assignment controller。
4. 视情况把 Cleaner 相关状态进一步收敛到专门 store 或 domain hook 中。

12. 总结

这次 useCleaner 重构的核心价值，不是“让文件立刻变得很小”，而是先把最容易复用、最适合测试、最不应继续堆在 hook 里的部分拆出来。

它为接下来的页面组件拆分提供了一个更稳的基础，也让 Cleaner 模块开始从“页面驱动逻辑”向“模块化前端能力”转变。