BIPMaterialManager/docs/plans/2026-04-13-cleaner-db-persistence-design.md

Cleaner 数据库持久化设计

背景

Cleaner 当前使用 Markdown 文件做执行记录持久化，通过 RustFS 上传存储。存在以下问题：

• 报告是非结构化文本，无法程序化查询和统计
• 历史记录无法按用户、时间、状态筛选
• 重试时依赖文件名去重，覆盖了首次执行的崩溃信息
• 前端需要通过 RustFS 下载报告再解析展示，链路长且脆弱

Extractor 已有成熟的数据库持久化模式（ExtractorOperationHistory 表 + DAO + 前端弹窗），Cleaner 应复用相同模式。

设计决策

决策项	选择	理由
表结构	独立建表，不与 Extractor 共用	Cleaner 数据结构差异大（双层、物料级详情），独立更清晰
记录粒度	执行 + 订单 + 物料三层	执行表存全局信息，订单表存订单汇总，物料表存操作明细
批次标识	BatchId（UUID），与 Extractor 一致	标准、简洁，不需要嵌入时间戳
重试记录	不覆盖，每次尝试独立写入，用 AttemptNumber 区分	保留完整审计链，为后续智能跳过提供数据基础
报告文件	移除 Markdown 报告和 RustFS 上传	数据库完全替代，报告相关代码（CleanerReportGenerator、generateAndUploadReport）删除
前端历史	独立 CleanerOperationHistoryModal，复用 Extractor 的 UI 模式	放在 CleanerPage 上，与 Extractor 的"操作历史"按钮对齐

数据库表结构

所有表的 schema 为 ERPAuto。

1. CleanerExecution（执行级）

全限定名：ERPAuto.CleanerExecution

一次清理操作（含重试）的全局信息。每次尝试一行记录。

列名	类型	说明
ID	INT IDENTITY	自增主键
BatchId	UNIQUEIDENTIFIER	批次 ID，一次清理操作（含重试）共享
AttemptNumber	INT	第几次尝试（1=首次，2=外层重试）
UserId	INT	操作用户 ID
Username	NVARCHAR(255)	操作用户名
OperationTime	DATETIME	操作时间
EndTime	DATETIME	结束时间
Status	NVARCHAR(50)	pending / success / failed / partial / crashed
IsDryRun	BIT	是否模拟运行
TotalOrders	INT	订单总数
OrdersProcessed	INT	已处理订单数
TotalMaterialsDeleted	INT	总删除物料数
TotalMaterialsSkipped	INT	总跳过物料数
TotalMaterialsFailed	INT	总失败物料数
TotalUncertainDeletions	INT	总不确定删除数
ErrorMessage	NVARCHAR(MAX)	全局错误信息（如外层崩溃原因）
AppVersion	NVARCHAR(20)	应用版本号

2. CleanerOrderHistory（订单级）

全限定名：ERPAuto.CleanerOrderHistory

每个订单在每次尝试中的执行结果。每个订单每次尝试一行记录。

列名	类型	说明
ID	INT IDENTITY	自增主键
BatchId	UNIQUEIDENTIFIER	关联执行表 BatchId
AttemptNumber	INT	关联执行表 AttemptNumber
OrderNumber	NVARCHAR(255)	订单号
Status	NVARCHAR(50)	pending / success / failed
MaterialsDeleted	INT	删除物料数
MaterialsSkipped	INT	跳过物料数
MaterialsFailed	INT	删除失败物料数
UncertainDeletions	INT	不确定删除数
RetryCount	INT	内层重试次数
RetrySuccess	BIT	内层重试是否成功
ErrorMessage	NVARCHAR(MAX)	错误信息

关联方式：BatchId + AttemptNumber 关联执行表。

3. CleanerMaterialDetail（物料级）

全限定名：ERPAuto.CleanerMaterialDetail

每个物料在每次尝试中的操作明细。

列名	类型	说明
ID	INT IDENTITY	自增主键
BatchId	UNIQUEIDENTIFIER	关联执行表 BatchId
AttemptNumber	INT	关联执行表 AttemptNumber
OrderNumber	NVARCHAR(255)	所属订单号
MaterialCode	NVARCHAR(255)	物料代码
MaterialName	NVARCHAR(255)	物料名称
RowNumber	INT	行号
Result	NVARCHAR(50)	deleted / skipped / failed / uncertain
Reason	NVARCHAR(MAX)	跳过/失败原因
AttemptCount	INT	删除尝试次数
FinalErrorCategory	NVARCHAR(50)	最终错误分类

关联方式：BatchId + AttemptNumber + OrderNumber 关联订单表。

数据示例

首次执行到第 80 个订单时崩溃，外层重试成功完成全部 211 个订单：

CleanerExecution

BatchId=uuid-1, Attempt=1, Status=crashed,  TotalOrders=211, Processed=80,  ...
BatchId=uuid-1, Attempt=2, Status=success,  TotalOrders=211, Processed=211, ...

CleanerOrderHistory（Attempt=1 中部分记录）

BatchId=uuid-1, Attempt=1, Order=SC001, Status=success, Deleted=5, Skipped=1
BatchId=uuid-1, Attempt=1, Order=SC080, Status=crashed, Error=查询超时

CleanerOrderHistory（Attempt=2 中部分记录）

BatchId=uuid-1, Attempt=2, Order=SC001, Status=success, Deleted=5, Skipped=1
BatchId=uuid-1, Attempt=2, Order=SC080, Status=success, Deleted=3, Skipped=0
BatchId=uuid-1, Attempt=2, Order=SC211, Status=success, Deleted=2, Skipped=0

CleanerMaterialDetail（SC080 在 Attempt=2 中的物料）

BatchId=uuid-1, Attempt=2, Order=SC080, Material=MAT-001, Result=deleted
BatchId=uuid-1, Attempt=2, Order=SC080, Material=MAT-002, Result=skipped, Reason=不可删除

写入时机

用户点击"执行清理"
  → IPC: cleaner:run
    → cleaner-handler.ts
      → ① BatchId = randomUUID()
      → ② 插入 CleanerExecution（Status=pending）
      → ③ 插入 CleanerOrderHistory（所有订单，Status=pending）
      → ④ 执行清理（CleanerApplicationService.runCleaner）
      → ⑤ 更新 CleanerExecution（Status=success/failed/partial/crashed）
      → ⑥ 更新 CleanerOrderHistory（每个订单的结果）
      → ⑦ 插入 CleanerMaterialDetail（每个物料的操作明细）
      → ⑧ 如果 crashed → 外层重试
         → 插入新的 CleanerExecution（AttemptNumber=2, Status=pending）
         → 插入新的 CleanerOrderHistory（AttemptNumber=2, Status=pending）
         → 重新执行
         → 更新执行表和订单表状态
         → 插入物料明细

• 步骤 ②③：在 cleaner-handler.ts 中，执行前写入，记录操作人、全局配置、待处理订单
• 步骤 ⑤⑥⑦：在 CleanerApplicationService 中，执行完成后回调 DAO 写入结果
• 步骤 ⑧：外层重试时，三张表都新增 AttemptNumber=2 的记录，首次尝试的数据完整保留

变更清单

新增文件

1. src/main/services/database/cleaner-operation-history-dao.ts

   • CleanerOperationHistoryDAO 类
   • 执行表操作：insertExecution、updateExecutionStatus
   • 订单表操作：insertOrderRecords、updateOrderStatus
   • 物料表操作：insertMaterialDetails
   • 查询操作：getBatches、getBatchDetails（含订单+物料）、deleteBatch
   • 参考 ExtractorOperationHistoryDAO 的模式，表名使用 ERPAuto.CleanerExecution、ERPAuto.CleanerOrderHistory、ERPAuto.CleanerMaterialDetail

2. src/main/types/cleaner-history.types.ts

   • CleanerExecutionRecord、CleanerOrderRecord、CleanerMaterialRecord
   • CleanerBatchStats、InsertCleanerExecutionInput、InsertOrderInput、InsertMaterialDetailInput

3. src/renderer/src/components/CleanerOperationHistoryModal.tsx

   • 操作历史弹窗，复用 ExtractorOperationHistoryModal 的 UI 模式
   • 批次列表（按 BatchId 聚合，显示操作时间、用户、状态、成功/失败数，区分多次尝试）
   • 展开明细（订单列表，每订单的删除/跳过/失败数）
   • 物料级详情（第二层展开，显示每个物料的操作结果）
   • 管理员可按用户筛选、可删除批次

修改文件

4. src/main/ipc/cleaner-handler.ts

   • CLEANER_RUN handler 中：执行前插入 execution + order 的 pending 记录，执行后更新结果
   • 新增 IPC handlers：CLEANER_HISTORY_BATCHES、CLEANER_HISTORY_DETAILS、CLEANER_HISTORY_DELETE

5. src/main/services/cleaner/cleaner-application-service.ts

   • runCleaner 接收 batchId 参数
   • 移除 generateExecutionId() 函数
   • 移除 generateAndUploadReport() 方法
   • 移除 executionId 相关逻辑
   • 外层重试时，通过 DAO 写入 AttemptNumber=2 的执行记录和订单记录，不覆盖首次尝试
   • 执行完成后回调 DAO 写入订单结果和物料明细

6. src/main/ipc/index.ts

   • 注册新的 cleaner history IPC handlers

7. src/preload/api/cleaner.ts

   • 新增 IPC 调用方法：getBatches、getBatchDetails、deleteBatch

8. src/preload/index.d.ts

   • CleanerAPI 接口新增 getBatches、getBatchDetails、deleteBatch 类型声明

9. src/renderer/src/pages/CleanerPage.tsx

   • 新增"操作历史"按钮
   • 引入 CleanerOperationHistoryModal

删除文件

10. src/main/services/report/cleaner-report-generator.ts
    • 整个文件删除，报告生成逻辑不再需要

可选清理

11. src/renderer/src/components/ReportViewerDialog.tsx

    • 基于 RustFS 文件的报告查看器，Cleaner 不再使用
    • 如果 Extractor 不共用此组件，可删除

12. src/renderer/src/components/ReportAnalysisDialog.tsx

    • 基于报告文件的分析，Cleaner 不再使用
    • 后续可基于数据库重新实现统计分析

移除的概念

概念	原因
ExecutionId（CLN-时间戳-随机）	为文件名设计，数据库用 UUID
generateExecutionId()	随 ExecutionId 一起移除
CleanerReportGenerator	Markdown 报告生成器，被数据库替代
generateAndUploadReport()	RustFS 上传链路，被数据库写入替代
报告文件名去重	数据库 UUID 天然唯一
重试覆盖旧报告	数据库保留所有尝试记录

不涉及的部分

• Extractor 的持久化逻辑不变
• 数据库 schema 迁移（需 DBA 创建表，应用层只做 CRUD）
• 后续智能跳过功能（基于已有 success 记录跳过已成功的订单）
• 内层重试逻辑（订单级/物料级）不变