vent_agent_2.0/algorithms/airflow_review

矿井风量研判

「数据接入 → 规则复算 → 交叉核验 → 风险判定 → 证据追溯 → 报告生成」一体化的 确定性引擎。本目录不导入 api、agents、extensions；Agent 侧由 extensions/vent_airflow 注册工具调用这里的函数（见 独立算法约定）。

目录

algorithms/airflow_review/
  contracts.py        枚举、常量、单位换算、时间窗口等公共契约
  evidence.py         证据登记表（evidence_id → 文件/位置/值）
  parsers/
    measurement_report.py   测风报表 xlsx → 研判数据集（工具 1）
    plan_preprocess.py      配风计划文档 → 清洗文本/章节/表格/提取模板（工具 3a）
    plan_extraction.py      提取结果校验与规范化（工具 3b）
  rules/
    airflow-rules-2026.1.json  版本化规则库：公式、系数表、验算式、阈值、条款引用
    master_data.json           主数据：地点分类、别名、回风系统标识
    loader.py                  规则加载、变体选择、参数派生与留痕
  engine/
    expression.py  白名单 AST 求值器（公式不落 eval）
    recalc.py      需风量复算（用风地点 → 回风系统 → 矿井总需风量）
    hierarchy.py   层级校验（遗漏/重复归属、循环引用、重复汇总、单一回风系统等值）
    verify.py      配风计划核验与权威需风量提取（工具 4）
    compare.py     实际 vs 需风量比对与阈值分级（工具 6）
    reconcile.py   多源交叉校核与冲突判定（工具 5）
    matching.py    地点名称匹配（计划 ↔ 实测）
    dedupe.py      问题去重与单一回风系统复用去重
    trace.py       证据链追溯（工具 7）
    findings.py    问题记录构造与统计
  report/render.py  审查报告渲染（md + docx，工具 8）

关键设计

两条核验线同时进行。 每个对象既要"独立复算"（用规则库公式 + 计划参数，检验公式 适用性与参数取值），也要"自洽核验"（用计划写出的代入值按该公式重算，检验计划自己 有没有算错）。两种失败的含义不同，报告里分列。

参数口径决定公式变体。 真实计划里 Q采1=60×11.3×1.0×1.2×1.5=1221——公式文字写了 70% 有效断面系数，代入的 11.3 却已经是有效断面积。规则库为此支持 variants：按 section_area_basis 选公式，避免对同一物理量重复套系数（否则真实计划会满屏假阳性）。

汇总校验用子项计划值。 父级的正确性 = 它的声称值是否等于子项声称值的汇总（这正是 "漏算/重复计算/算错"的检验）；子项各自的复算值另走一路，完整时给出 propagation_value_m3_min 观察误差是否向上传播。这样 89 个地点缺参数也不会把父级误判为"依据不足"。

依据不足与计算错误分开处置。 只有计算错误沿层级向上阻断（错误会污染父级汇总 值）；依据不足的对象只是自身不进入权威集，不牵连父级。层级归属缺失则把计划整体判为 manual_review。

阈值由规则库按对象类型给。 矿井总进风/总回风与回风系统 threshold_ratio=1.0， 采掘工作面 0.75，不重复建比较逻辑。

规则库

rules/airflow-rules-*.json 版本化，每次计算都记录 rule_version。公式写成表达式字符串， 由 engine/expression.py 用白名单 AST 求值——公式与参数分离、可版本化、可复现， 也不用开放 eval。

参数的派生同样留痕：derive_params 返回逐项来源（哪张表、按哪个事实、命中哪一行）， 写进计算链。

表定义里的 bounds 显式声明区间字段名（如 min_temp / max_temp），因为"按什么字段 匹配"与"区间边界字段叫什么"常常不同名。

用法

from algorithms.airflow_review.parsers.measurement_report import parse_measurement_report
from algorithms.airflow_review.rules.loader import load_rules
from algorithms.airflow_review.engine.verify import verify_plan
from algorithms.airflow_review.engine.compare import compare_targets

dataset = parse_measurement_report("测风报表.xlsx", mine_id="BLT", report_period="2026-05")
rules = load_rules()                       # 或 load_rules("AIR-RULE-2026.1")
verification = verify_plan(plan, rules)     # → verified_items / blocked_items / findings
comparison = compare_targets(targets, rules)

限制

• 配风计划解析分两步：preprocess_plan_document 只做确定性预处理（含按坐标重建视觉行序、 识别表格行与公式行、生成提取模板），数值由模型按模板全量提取后经 validate_plan_extraction 校验。PDF 依赖 pdfminer.six（MIT）；扫描件与图片型 PDF 本轮不支持。
• 测风报表解析针对"计划风量 / 入风 / 回风"三组并排的分块表，按表头语义定位而非固定 单元格；判不出地点类型的测点进待复核，不静默丢弃。
• 安全监控无真实数据源时返回 data_insufficient 并转人工复核，绝不用测风报表顶替。
• 规则库只承载复算与阈值规则；形式审查、红线清单、云知识库法定条款判定不在范围内。