# 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：

```bash
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`](./08-todo.md) T0-2。

## 6. 常见问题

- **BOM 牌号缺失**：检查基础字典「BOM 物料」是否维护该零件
- **报告命名异常**：检查 `report.yaml` 占位符配置