certflow.services.print_history_service module

历史回填兜底服务（docs/PRINT_BLUEPRINT.md §11.2 / §11.8 阶段1·2）。

阶段1（本文件当前范围）：仅实现 HistoryBackfillService.candidates()， 读 PrintLog 聚合「同型号上次实际打印值」，供统一护栏的 ④ 差异确认闸 （reconfirm_on_diff）使用。复用 PrintLog（51 字段/每产品一条）作历史源，零新表。

阶段2 待扩展：backfill``（仅补缺、易变字段不兜底）+ ``record_after_generate （打印成功后写入 PrintLog，§10.8 不可事后改写）。

注意：``check_standard``（检验标准）不在 PrintLog 的 51 字段中，故差异闸对该字段 暂取不到历史值、自动跳过差异确认（仍走 required/reconfirm 逻辑）。后续如需覆盖， 可在阶段2 扩展其他历史源。

certflow.services.print_history_service.backfill(data, history_last, fields=None)

历史自动补缺（护栏 stage ①）：用同型号上次实际值预填 data 中**缺失**的字段。

仅对 fields 白名单内、且当前为空的字段生效；用户已填值、历史缺失、或不在 白名单的字段一律不动。返回更新后的 ``data``（不污染入参）。

参数:

• data (dict[str, Any]) -- 当前合格证字段字典。

• history_last (dict[str, str] | None) -- 同型号上次实际值（cert_field -> value），缺省跳过。

• fields (tuple[str, ...] | None) -- 允许补缺的字段白名单，缺省用 BACKFILL_FIELDS。

返回类型:

dict[str, Any]

class certflow.services.print_history_service.HistoryBackfillService(session)

基类：object

历史回填兜底服务：读 PrintLog 聚合历史 / 构造并写入 PrintLog（§11.8 阶段1·2）。

参数:

session (Session)

candidates(model, spec=None)

按产品型号取最近一条成功打印记录的实际值（作历史候选）。

参数:

• model (str | None) -- 产品型号（product_model）。

• spec (str | None) -- 规格（预留；§11.2 归并键 key: [product_model, product_spec]， 阶段2 起按 型号+规格 进一步归并，当前仅按型号）。

返回:

字典 {cert_field: value}``（如 ``{"temperature": "≤200℃", ...}）； 无历史记录返回 None。

返回类型:

dict[str, str] | None

assemble_print_log(*, certificate_id, fields)

单一 PrintLog 构造器：由调用方解析好的字段字典组装 ``PrintLog``（不提交）。

各打印路径（GUI / CLI-batch）保留各自的 SN/KKS/温度/PN 派生逻辑， 仅在此处统一落库构造，杜绝运行期重复写与字段不一致。

参数:

• certificate_id (int) -- 关联合格证批次 ID。

• fields (dict[str, Any]) -- 已解析的 PrintLog 字段字典（键为 PrintLog 列名）。

返回类型:

PrintLog

record_after_generate(*, certificate_id, fields, status='success', error_message=None, content_summary=None, now=None)

打印成功后写入一条 PrintLog（统一写点，逐条提交）。

取代旧 CertificatePrintService.record_print_log 的内联构造+提交； CLI/batch 路径经此单点写库。GUI 路径因批量单提交语义走 assemble_print_log() + 外部统一提交，不调用本方法。

§10.8：PrintLog 不可事后改写，故本方法仅新增、不更新既有记录。

返回:

成功返回 PrintLog，异常返回 None。

参数:

• certificate_id (int)

• fields (dict[str, Any])

• status (str)

• error_message (str | None)

• content_summary (str | None)

• now (datetime | None)

返回类型:

PrintLog | None