certflow.services.report_fill_service module¶

报告填充服务（批次4 / B4-3+B4-7 集成层）。

把报告生成从「读 xlsx 数据源」改为「读 certflow.db（SalePlan / Certificate）」，复用已迁入 certflow.services.report_migration 的泛型填充引擎，并接下游 ReportOutputService 完成双存根(xlsx+pdf) / 印章 / 文件夹命名 / 报告目录。

数据流：

SalePlan(+关联 Certificate): → build_product_records() → list[ProductRecord] → ReportFillEngine.fill() 填充 12 模板之一（openpyxl，分页） → ReportOutputService.emit() 落盘到 VBA 同款项目文件夹

材质块优先取 Certificate 的阀体/阀杆/启闭件材质；缺失时按生产令号查 BOM 兜底牌号（配置 report.material_bom_fallback，默认开启），仍缺则留空（绝不把型号当牌号回填）。试压压力优先取 Certificate 已算值；缺失则经 PressureCalcService 计算。

报告的名称/型号/规格/编号/标准号一律取「合格证打印信息」（非合同值）：优先 Certificate 打印列 → 其次 SalePlan.cert_product_*（合格证打印列） → 最后兜底合同列 product_*（仅 legacy 缺打印列时）。

certflow.services.report_fill_service.resolve_spec_key(report_kind, language='zh', records_per_page=6)[源代码]¶

根据 UI 选择（报告类型 + 语言 + 每页记录数）解析出模板 spec key。

参数:

report_kind (str) -- quality / pressure / material。
language (str) -- zh / en。
records_per_page (int) -- UI 微调框值，用于挑选模板变体（行数/双语）。

返回:

_SPEC_FACTORIES 中的 key。

返回类型:

str

certflow.services.report_fill_service.spec_for_key(key)[源代码]¶

返回对应模板的 ZhiBaoShuSpec 实例。

参数:: key (str)

certflow.services.report_fill_service.build_product_records(session, sale_plan_ids, report_kind='quality', spec=None)[源代码]¶

从 certflow.db 构建报告所需的产品记录列表。

名称/型号/规格/编号/标准号一律取合格证打印信息（详见 _resolve_print）。

参数:

session (Session) -- SQLAlchemy 会话。
sale_plan_ids (list[int]) -- 选中的销售计划 ID 列表。
report_kind (str) -- quality / pressure / ``material``（影响材质块取舍）。

返回:

填充引擎可直接消费的记录列表。

返回类型:

list[ProductRecord]

certflow.services.report_fill_service.generate(session, sale_plan_ids, report_kind='quality', language='zh', records_per_page=6, report_date=None, export_pdf=None, spec_key=None, variant='', plan_date=None)[源代码]¶

生成一份报告：填充 12 模板之一并落盘到 VBA 同款项目文件夹。

参数:

session (Session) -- SQLAlchemy 会话。
sale_plan_ids (list[int]) -- 选中的销售计划 ID 列表。
report_kind (str) -- quality / pressure / material。
language (str) -- zh / en。
records_per_page (int) -- 用于挑选模板变体（行数/双语）。
report_date (date | str | None) -- 报告日期（默认今天）。
export_pdf (bool | None) -- 是否同时派生 PDF（None→读配置，默认 False）。
spec_key (str | None) -- 直接指定模板 spec key（覆盖 report_kind/language/records_per_page 的自动解析）。用于「一次性跑全部 12 个模板」等场景。
variant (str)
plan_date (date | str | None)

返回:

含 success / folder / xlsx / pdf / sealed 等键。

返回类型:

dict

certflow.services.report_fill_service.report_readiness(session, report_kind='quality', limit=50)[源代码]¶

诊断 sale_plans 中能支撑指定类型报告的完备度。

仅统计「已可进入报告流程」的销售计划（有生产令号，作为可报告数据的最小门槛）。返回聚合统计与少量缺失样例，便于定位需要补全的字段。

对 quality / material 报告，额外判定合格证各零件材质能否在 material_grades 查到化学成分+力学性能（供材质块/RandBetween 实测值使用）。

参数:

session (Session) -- SQLAlchemy 会话。
report_kind (str) -- quality / pressure / material。
limit (int) -- 返回缺失样例的最大条数。

返回:

含 total / ready / missing_field_counts / samples。

返回类型:

dict

certflow.services.report_fill_service.check_report_readiness(session, sale_plan_ids, report_kind='quality')[源代码]¶

报告生成前的完整性预检（阻断式闸门的数据来源）。

按 report.required_fields[report_kind]``（配置驱动，对齐 ``output.targets.scan.required_fields 契约）逐条核对所选 SalePlan 的必检字段； quality/material 报告额外校验材质牌号能否在 material_grades 查表。

参数:

session (Session) -- SQLAlchemy 会话。
sale_plan_ids (list[int]) -- 待生成报告的销售计划 ID 列表。
report_kind (str) -- quality / pressure / material。

返回:

{"passed": bool, "missing": list[dict]}， missing 每项含 id / product_model / ``fields``（缺失字段列表）。

返回类型:

dict