certflow.services.report_migration.material_provider module

质保书/报告中「主要零件名称 + 零件牌号」的可插拔解析器。

设计取向（来自用户，已记入长期记忆）： - 主键 = 生产令号（公司通用追踪 ID）。 - 权威来源 = 钉钉在线表「加工进度跟踪单」（复合键 生产令号+型号+规格），

每条记录自带 零件名称 / 材质（及尺寸等）。

• 完工产品的记录会被从钉钉源表剪切走，故 provider 必须「自学习即时 DB 化」： 按生产令号查询后把结果落库缓存，保证已完工令号仍可回溯。

• 优先级：低于报告填充引擎主线，列为后续任务。短期用静态 material_grades 兜底。

class certflow.services.report_migration.material_provider.MaterialPart(零件名称='', 材料='', 化学成分=<factory>, 力学性能=<factory>, 结果='合格', 来源='cert', is_virtual=True, 表头外元素=<factory>, 来源令号='')

基类：object

一个产品的一个主要零件的材质信息（写入质保书材质块）。

参数:

• 零件名称 (str)

• 材料 (str)

• 化学成分 (dict[str, float])

• 力学性能 (dict[str, float])

• 结果 (str)

• 来源 (str)

• is_virtual (bool)

• 表头外元素 (dict[str, float])

• 来源令号 (str)

零件名称: str = ''

材料: str = ''

化学成分: dict[str, float]

力学性能: dict[str, float]

结果: str = '合格'

来源: str = 'cert'

is_virtual: bool = True

表头外元素: dict[str, float]

来源令号: str = ''

class certflow.services.report_migration.material_provider.MaterialProvider

基类：ABC

按生产令号解析该产品的主要零件 + 牌号列表。

abstractmethod resolve(生产令号, *, 型号='', 规格='')

返回该产品的主要零件材质列表（按报告所需顺序）。

参数:

• 生产令号 (str)

• 型号 (str)

• 规格 (str)

返回类型:

list[MaterialPart]

class certflow.services.report_migration.material_provider.StaticMaterialProvider(material_grade_service=None)

基类：MaterialProvider

短期兜底：无真实数据源时的「留空」策略（绝不伪造）。

设计原则（report_fill_service._resolve_materials 注释）：型号本身不是材质 牌号，绝不把型号填进材质块。当前没有可靠的「型号→牌号」查表，故无真实牌号时 一律返回空列表，交由填充引擎在该组写「以下空白」，而不是把型号当牌号回填。

resolve(生产令号, *, 型号='', 规格='', 零件数=1)

返回该产品的主要零件材质列表（按报告所需顺序）。

参数:

• 生产令号 (str)

• 型号 (str)

• 规格 (str)

• 零件数 (int)

返回类型:

list[MaterialPart]

class certflow.services.report_migration.material_provider.XlsxMaterialProvider(xlsx_path, sheet='加工进度跟踪单')

基类：MaterialProvider

（短期真实来源）直接读取「材料进度跟踪单」xlsx 按生产令号解析主要零件+牌号。

对标用户指定的 reports_migration/scratch/一个钉钉文档在线表格的酷应用.js 的 读取逻辑（源表 '加工进度跟踪单'，复合键 生产令号+型号+规格）。本类用离线 xlsx 替代钉钉实时接口，作为 DingTalkMaterialProvider 落地前的真实数据源： - 精确匹配 生产令号；未命中则退化按 (型号, 规格) 查。 - 返回 MaterialPart 列表（零件名称 + 材料=材质）；质保书材质块只写首零件。 - 未命中返回空列表（引擎留空，绝不伪造）。

参数:

• xlsx_path (str)

• sheet (str)

resolve(生产令号, *, 型号='', 规格='', 零件数=1)

返回该产品的主要零件材质列表（按报告所需顺序）。

参数:

• 生产令号 (str)

• 型号 (str)

• 规格 (str)

• 零件数 (int)

返回类型:

list[MaterialPart]

class certflow.services.report_migration.material_provider.DingTalkMaterialProvider(db_session=None, dingtalk_client=None)

基类：MaterialProvider

（后续任务，低优先级）钉钉生产进度表驱动 + 自学习 DB 化。

实现要点： 1. 用 reports_migration/scratch/一个钉钉文档在线表格的酷应用.js 的读取逻辑

（源表 '加工进度跟踪单'，COMPOSITE_KEY=['生产令号','型号','规格']）查询某 生产令号；

2. 提取每个零件的 零件名称 + 材质（及尺寸等），构成 MaterialPart 列表；

3. 首次查询后写入本地 DB（按 生产令号 缓存），已完工被剪切的记录仍可回溯；

4. 后续查询优先命中本地缓存，未命中再走钉钉实时查并回写。 当前为桩，调用即抛 NotImplementedError。

resolve(生产令号, *, 型号='', 规格='')

返回该产品的主要零件材质列表（按报告所需顺序）。

参数:

• 生产令号 (str)

• 型号 (str)

• 规格 (str)

返回类型:

list[MaterialPart]

certflow.services.report_migration.material_provider.register_material_function(name, func)

注册一个具名材质解析函数，供配置 report.material_provider: function:<name> 调用。

参数:

• name (str)

• func (Callable)

返回类型:

None

certflow.services.report_migration.material_provider.get_material_function(name)

按名取回已注册的材质解析函数；未注册返回 None。

参数:

name (str)

返回类型:

Callable | None

certflow.services.report_migration.material_provider.random_material_resolver(生产令号, *, 型号='', 规格='', 零件数=1)

返回随机真实牌号的材质零件列表（仅用于排版压测，不入正式报告）。

每个零件名取自 阀体/阀杆/启闭件（超过 3 个则补 零件N），牌号随机选取。

参数:

• 生产令号 (str)

• 型号 (str)

• 规格 (str)

• 零件数 (int)

返回类型:

list[MaterialPart]

class certflow.services.report_migration.material_provider.FunctionMaterialProvider(func)

基类：MaterialProvider

把任意已注册/传入的 callable 当作材质解析器（可返回随机/计算值）。

用于「附加自定义函数动态驱动材质块」：例如 random_material_resolver 或用户自注册的 function:<name>。

参数:

func (Callable)

resolve(生产令号, *, 型号='', 规格='', 零件数=1)

返回该产品的主要零件材质列表（按报告所需顺序）。

参数:

• 生产令号 (str)

• 型号 (str)

• 规格 (str)

• 零件数 (int)

返回类型:

list[MaterialPart]