04e 报告生成流程

状态：✅ 已实现（主路径）；🟡 迁移草稿区待并入 | ⚙️ 配置驱动

1. 操作入口

方式

入口

GUI

导航「报告生成」→ ReportView

CLI

certflow report-gen [options]

支持三类报告：质保书、试压报告、材质报告。

2. 涉及配置

配置文件

关键字段

说明

config/report.yaml

模板 / 命名规则

报告文件名占位符

config/templates/

报告模板

三类报告模板

config/test_report.yaml

试压标准

试压报告参数

3. 涉及代码文件

层

文件

职责

View

views/report_view.py

报告生成页面

Controller

controllers/report_controller.py

编排

Service

services/report_fill_service.py

报告填充（主实现 ✅）

Service

services/report_output_service.py

报告输出与命名

Service

services/report_bom_enricher.py

BOM 富化

Service

services/bom_material_service.py

BOM 零件牌号

Service

services/bom_part_classifier.py

零件分类

Handler

handlers/report_generator.py

报告生成处理器

Model

models/report_template.py

报告模板表

Draft (🟡)

services/report_migration/material_provider.py

草稿，抛 NotImplementedError

Draft (🟡)

services/report_migration/report_fill_engine.py

草稿

4. 逐步流程

4.1 选择数据

  1. 导航「报告生成」

  2. 选择提取方式：

    • 随机/指定抽取（report-gen 支持 --sample / --plan-no）

    • 按销售计划记录生成

  3. ReportView 展示可生成的报告类型（质保书/试压/材质）

4.2 生成报告

  1. 选择报告类型与范围

  2. ReportController → ReportFillService

  3. ReportBomEnricher 通过 BomMaterialService + BomPartClassifier 匹配 BOM 零件牌号

  4. ReportFillService 填充模板字段

  5. ReportOutputService 按 report.yaml 命名规则输出文件

CLI：

certflow report-gen --type warranty --sample 10
certflow report-gen --type pressure --plan-no CF2026080001

4.3 命名规则

config/report.yaml 定义文件名自动命名格式（占位符见 ReportOutputService._build_filename），支持计划日期/制作日期等占位符。工作表标签名同文件名占位符规则。

5. 迁移草稿区（🟡 TODO）

services/report_migration/ 为下一路线的草稿实现：

  • material_provider.py 的抽象方法抛 NotImplementedError（L45, L166）

  • report_fill_engine.py、report_data_builder.py 也已豁免 C901（见 pyproject.toml:210-213）

待办：将草稿并入 src/certflow/services/，重写 material_provider 实现，移除 NotImplementedError。当前日常使用走 report_fill_service.py（已实现），草稿区不阻塞使用。详见 08-todo.md T0-2。

6. 常见问题

  • BOM 牌号缺失：检查基础字典「BOM 物料」是否维护该零件

  • 报告命名异常：检查 report.yaml 占位符配置