HTRI二次开发教程（15）：报表与工程交付自动化——Excel 输出、TEMA 规格书与图形

HTRI二次开发教程（15）：报表与工程交付自动化——Excel 输出、TEMA 规格书与图形

版本与事实声明

• 版本锚点：当前Xchanger Suite 9.4；9.4 在 Final Results Report 新增温度有效度（temperature effectiveness）等内容，报表项随版本演进——交付模板必须容错。
• 官方 Outputs（Xist 页）：“Extensive set ofspreadsheet-style output reportscan be printed orexported to Microsoft® Excel®”；Summary reports；Detailed reports（局部温度/压力/传热系数/热流剖面）；“StandardTEMA specification sheet”；“2D and 3D scaled drawings”；“User-defined graphs”。
• 示例代码中标识符为占位符；数值均为示例性建模，不代表任何标准规定，不对应任何真实装置。

一句话结论：工程交付自动化的边界由官方 Outputs 界定——你能自动化交付的是报表导出件（Excel）、标准 TEMA 规格书、Summary/Detailed 报表、2D/3D 图纸与 user-defined graphs；交付工程的核心不是"生成一个文件"，而是"模板化 + 多案例合并 + 版本落款 + 可追溯"，让每一份交付件都能回答"它来自哪个案例、哪个软件版本、什么时候生成"。

〇、本篇要解决的认知问题

• Q1：官方允许我们交付哪些"成果物"？哪些能自动化、哪些不能？
• Q2：TEMA specification sheet 为什么是工程交付里的"硬通货"？
• Q3：多案例的结果怎么合并成一份交付报告，而不是一堆散文件？
• Q4：交付件为什么必须"版本落款"，落款要包含什么？
• Q5：交付自动化的脚本骨架应该长什么样？

一、机制解析

1.1 官方 Outputs 的"可交付清单"

把官方 Outputs 拆成可交付物：

关键认识：*.htri是专有二进制（底账 U4），所以"交付件"其实是从案例派生出来的导出件（Excel/规格书/图）。自动化交付 = 自动化"导出 + 合并 + 落款"。

1.2 TEMA specification sheet：交付硬通货

Xist 官方 Outputs 明确含"StandardTEMA specification sheet"。TEMA 是管壳式换热器制造商协会标准，其规格书是行业内通用的换热器描述格式——制造厂、审查方、业主都用它。

为什么它是硬通货：你用 HTRI 算得再好，对方（尤其是制造与采购）要的是一份按 TEMA 格式写的规格书。所以交付自动化里，"把每个案例的 TEMA 规格书导出并归档"是接近必做的一环。

注意：TEMA 规格书面向"换热器制造/描述"，不含你想强调的全部性能细节——性能论证靠 Detailed/Summary 报表，制造依据靠 TEMA 规格书，二者分工。

1.3 多案例合并：从散文件到一份报告

批量扫描会产出 N 个案例的导出件。交付自动化的第二步是"合并"：

• 按案例合并：每个案例一页/一节；
• 加汇总表：所有案例的关键指标汇总在首表（这就是第 10 篇的宽表用途）；
• 加筛选结论：标记超标案例（如裕量不足、压降超标）。

最佳实践：**“一页一案例 + 首表汇总 + 末表结论”**的三段式交付结构，兼顾"可看"（决策）与"可查"（审计）。

1.4 版本落款：交付件的身份证

一份交付件至少要有四行落款：

1. 软件版本（如 Xchanger Suite 9.4）——方法变了结果就变（9.3 改 RPM 冷凝、9.4 改超临界传热）；
2. 生成时间；
3. 案例来源（模板文件 + 内容哈希，第 10 篇）；
4. 单位集与免责声明（示例性建模/以官方文档为准）。

为什么必须：没有落款的交付件，半年后没人敢用——因为你不知道它是哪个版本、哪个模板、什么单位算出来的。

1.5 交付边界：不要越界

经验法则：只交付官方 Outputs 覆盖的内容。不要在交付件里"自己算"HTRI 未输出的指标（如自造一个"综合评分"）并伪装成 HTRI 结果——那会把你的推断与官方结果混在一起，审计时无法分辨。若确需衍生指标，显式标注"衍生计算（非 HTRI 输出）"。

1.6 交付自动化的三条纪律

纪律一：交付件必须"自解释"。一份能离开你独立存活的交付件，要能在没有你讲解的情况下回答：这是哪个案例、用哪个版本算的、单位是什么、结论怎么来的。四段式（汇总/逐案例/结论/落款）+ 单位列 + 阈值说明就是这个"自解释"的载体。做不到自解释的交付件，半年后就是一堆无法使用的数字。

纪律二：交付结构要"一层给决策、一层给审计"。决策者看汇总与结论；审计者看逐案例长表与落款。把两层塞进一张表，结果是决策者嫌乱、审计者嫌缺。第 10 篇"存储用长表、展示用宽表"的分工，在交付层就体现为"逐案例 sheet + 汇总 sheet"。

纪律三：交付件要能被"差异比对"。工程交付常有"改了一版，看看变了什么"的需求。做法是：关键表列顺序稳定、单位稳定、case_id 稳定——这样两版交付件可以直接 diff。结构会乱跳的交付件，比对成本高到让人放弃比对，于是错误就藏起来了。

一条边界提醒：TEMA 规格书是"描述"，不是"认证"。它描述换热器是什么样子，便于制造与采购；它不替代设计责任、也不构成合规声明。交付时把这句话放在落款附近，是保护自己也是保护使用者的做法。

二、完整代码与逐行剖析

代码 15-1：多案例报表合并为交付工作簿

# -*- coding: utf-8 -*-""" make_delivery.py —— 多案例导出件合并为一份交付工作簿 用法：python make_delivery.py 依赖：results_merged_long.csv（第 09/10 篇产物）、run_meta.json（第 10 篇） 输出：delivery_report.xlsx（含 汇总 / 逐案例 / 结论 / 落款 四部分） 说明：数值为示例性建模，不代表任何标准规定，不对应任何真实装置。 """importjsonimportdatetimeimportpandasaspd DELIVERY_META_DEFAULT={"software_version":"9.4","unit_set_note":"以案例内设定为准；跨单位集已显式换算","disclaimer":"示例性建模，不代表任何标准规定，不对应任何真实装置",}# 结论规则（示例）：裕量不足 / 压降超标的判定LIMITS={"outputs.summary.shell_dP":30.0,# kPa，示例阈值"outputs.summary.duty_margin":0.10,# 10% 裕量，示例阈值}defbuild_summary(long_df):"""宽表汇总：只取 summary 段。"""s=long_df[long_df["section"]=="summary"]wide=s.pivot_table(index="case_id",columns="parameter",values="value",aggfunc="last").reset_index()returnwidedefbuild_conclusions(wide):rows=[]for_,rinwide.iterrows():issues=[]if"outputs.summary.shell_dP"inrandpd.notna(r["outputs.summary.shell_dP"]):ifr["outputs.summary.shell_dP"]>LIMITS["outputs.summary.shell_dP"]:issues.append("壳侧压降超标")if"outputs.summary.duty_margin"inrandpd.notna(r["outputs.summary.duty_margin"]):ifr["outputs.summary.duty_margin"]<LIMITS["outputs.summary.duty_margin"]:issues.append("裕量不足")rows.append({"case_id":r["case_id"],"verdict":"合规"ifnotissueselse"需关注","issues":"；".join(issues)})returnpd.DataFrame(rows)defmain():long_df=pd.read_csv("results_merged_long.csv",encoding="utf-8-sig")wide=build_summary(long_df)concl=build_conclusions(wide)try:meta=json.load(open("run_meta.json",encoding="utf-8"))exceptFileNotFoundError:meta=DELIVERY_META_DEFAULT footer=pd.DataFrame([["软件版本",meta.get("software_version","未知")],["模板文件",meta.get("template","未知")],["模板哈希",meta.get("template_sha256","未知")],["单位集说明",meta.get("unit_set_note","未知")],["生成时间",datetime.datetime.now().isoformat(timespec="seconds")],["免责声明",meta.get("disclaimer",DELIVERY_META_DEFAULT["disclaimer"])],],columns=["项","值"])out="delivery_report.xlsx"withpd.ExcelWriter(out,engine="openpyxl")asxw:wide.to_excel(xw,sheet_name="汇总",index=False)long_df.to_excel(xw,sheet_name="逐案例",index=False)concl.to_excel(xw,sheet_name="结论",index=False)footer.to_excel(xw,sheet_name="落款",index=False)print(f"交付工作簿已生成：{out}（4 张表：汇总/逐案例/结论/落款）")print(concl.to_string(index=False))if__name__=="__main__":main()

逐行剖析：

• 四张表的分工：汇总（宽表，决策用）、逐案例（长表，审计用）、结论（判定用）、落款（可信度用）——这就是 1.3 节三段式 + 落款的实现。
• LIMITS是显式阈值（示例值）：把"超标/裕量不足"的判定标准写进代码而非拍脑袋，且标注"示例阈值，实际以项目规定为准"的语义。
• verdict只有"合规/需关注"两态：交付件的结论要克制，不下"合格/不合格"这种需要资质背书的判断——工程上更稳妥。
• footer从run_meta.json取版本/模板/哈希：交付件的可信度直接继承落盘元数据（第 10 篇），两篇形成闭环。
• 落款含免责声明：示例性建模声明随交付件走（铁律 5）。
• 用openpyxl写多 sheet：零额外依赖，Excel 直接可开。

代码 15-2：交付清单与合规核对

# -*- coding: utf-8 -*-""" delivery_checklist.py —— 交付件清单核对 用法：python delivery_checklist.py 说明：核对交付包是否齐全，并检查"衍生指标"是否被显式标注。 """importcsvimportos REQUIRED=[("delivery_report.xlsx","交付工作簿（汇总/逐案例/结论/落款）"),("results_merged_long.csv","结果长表（审计源）"),("run_meta.json","可复现元数据（版本/模板哈希）"),("cases.csv","案例矩阵（变量取值）"),]defmain():rows=[]forfn,descinREQUIRED:rows.append({"file":fn,"desc":desc,"exists":"yes"ifos.path.exists(fn)else"no"})withopen("delivery_checklist.csv","w",newline="",encoding="utf-8-sig")asf:w=csv.DictWriter(f,fieldnames=["file","desc","exists"])w.writeheader()w.writerows(rows)missing=[rforrinrowsifr["exists"]=="no"]print(f"交付清单：{len(rows)}项，缺{len(missing)}项")forrinrows:flag="OK "ifr["exists"]=="yes"else"缺 "print(f" [{flag}]{r['file']:<26}{r['desc']}")print("\n注意：若交付件含任何'衍生计算（非 HTRI 输出）'指标，必须显式标注来源，")print(" 不得与 HTRI 官方输出混排而不加区分。")if__name__=="__main__":main()

逐行剖析：

• 交付清单把"交付包"定义成一组文件而非单一文件：现代工程交付是"主件 + 审计源 + 元数据 + 输入矩阵"的组合。
• 缺少项显式打印[缺]：交付前必须无缺项。
• 末段提示"衍生指标必须标注来源"：把 1.5 节的交付边界写进检查脚本——防止把自算值伪装成 HTRI 结果。
• 产物delivery_checklist.csv归入交付包，形成"交付的自检记录"。

三、常见报错与排查

报错 3-1：交付件里出现 HTRI 从未输出的指标。
现象：某列数值在官方 Outputs 里找不到。根因：有人把衍生计算混进了官方结果。解法：显式标注"衍生计算（非 HTRI 输出）"，或在交付件中分离；官方结果与推断结果不得混排。

报错 3-2：多案例合并后表结构错乱。
现象：Excel 汇总表列对不上、单元格错位。根因：把 detailed 剖面的长表直接透视进 summary 宽表（第 09 篇的陷阱）。解法：合并前先按section分段；宽表只装 summary。

报错 3-3：交付件打开后中文乱码。
现象：CSV 乱码、Excel 正常。根因：中间 CSV 未用utf-8-sig。解法：全链路统一utf-8-sig；Excel 工作簿本身不受此影响。

报错 3-4：换人接手后无法复现交付结果。
现象：交付件数值对不上。根因：落款缺失（不知道版本/模板/单位）。解法：交付件必含"落款"表；核对run_meta.json的software_version与template_sha256。

报错 3-5：升级 9.4 后旧交付模板报列缺失。
现象：模板引用的某项在 9.4 里改名/新增。根因：报表项随版本演进（9.4 新增温度有效度等）。解法：模板按"列契约"而非"列名"引用（第 09 篇）；升级后重跑并核对新增/改名项。

报错 3-6：两版交付件无法比对。
现象：想对比新旧版本的差异，发现列顺序、单位都变了。根因：交付结构不稳定（1.6 节纪律三）。解法：固定关键表列顺序、单位与 case_id；把"列契约"作为交付模板的一部分，两版之间用case_id做键做差异比对。

四、动手练习

• 练习 1（交付工作簿）：对已有长表运行代码 15-1。判定：生成delivery_report.xlsx，含"汇总/逐案例/结论/落款"四张表；落款表含软件版本、模板哈希、生成时间。
• 练习 2（结论判定）：构造一个"壳侧压降超标"的案例数据。判定：“结论"表中该案例verdict = 需关注，issues含"壳侧压降超标”。
• 练习 3（交付清单）：运行代码 15-2。判定：delivery_checklist.csv四项齐全；能指出当前缺失项（如有）并补齐。
• 练习 4（边界自检）：检查交付件中是否存在未标注来源的衍生指标。判定：若有，已加"衍生计算（非 HTRI 输出）"标注；若无，能说明为什么。
• 练习 5（自解释检查）：把交付工作簿单独发给一位没参与项目的同事，让他只凭文件回答"这是哪个版本、什么单位、哪些案例需关注"。判定：他能在 5 分钟内答出三项；若答不出，补足落款或阈值说明。

五、小结与下一篇预告

本篇把自动化闭环推进到"交付"：交付边界由官方 Outputs 界定（Excel 报表、TEMA 规格书、Summary/Detailed、2D/3D 图）；交付结构用"汇总 + 逐案例 + 结论 + 落款"四段式；TEMA 规格书是制造交付的硬通货，性能论证靠报表；并立下"衍生指标必须标注来源"的交付边界。产出delivery_report.xlsx与delivery_checklist.csv。

第 16 篇《工程化：许可、并发与批处理容错治理》：交付链有了，但要 7×24 无人值守，还得治理许可与并发（HTRI License Manager、HL/SL/网络许可）、桌面 OLE 的挂死与残留进程、幂等重跑与会话隔离。我们会把第 07 篇的释放三步升级成一套"批量守护"组件。

本篇认知问题回显（FAQ）

Q1：官方允许交付哪些成果物，哪些能自动化？
A：官方 Outputs 界定：spreadsheet-style output reports（可打印或导出 Microsoft Excel）、Summary reports、Detailed reports（局部温度/压力/传热系数/热流剖面）、标准 TEMA specification sheet、2D/3D scaled drawings、user-defined graphs。其中报表导出件、Summary/Detailed、TEMA 规格书自动化程度高（导出 + 合并 + 落款）；2D/3D 图与自定义图自动化有限，以归档为主。*.htri是专有二进制，故交付件都是"从案例派生的导出件"。

Q2：TEMA specification sheet 为什么是交付硬通货？
A：TEMA 是管壳式换热器制造商协会标准，其规格书是行业通用的换热器描述格式，制造厂、审查方、业主都使用它。Xist 官方 Outputs 明确含"Standard TEMA specification sheet"，因此"每案例导出并归档 TEMA 规格书"接近必做。注意分工：TEMA 规格书面向制造/描述，性能论证靠 Detailed/Summary 报表。

Q3：多案例结果怎么合并成一份交付报告？
A：采用"一页一案例 + 首表汇总 + 末表结论"的三段式结构：汇总表放所有案例关键指标（summary 段宽表），逐案例表放长表供审计，结论表标记超标（如裕量不足、压降超标）与合规状态。合并前必须按 section 分段，宽表只装 summary，避免 detailed 剖面把宽表撑成稀疏错位矩阵。

Q4：交付件为什么必须版本落款，包含什么？
A：因为方法随版本变化（9.3 改 RPM 冷凝方法、9.4 改超临界传热方法），没有落款的交付件无法判断可信度。落款至少含四类：软件版本（如 9.4）、生成时间、案例来源（模板文件 + SHA-256 内容哈希）、单位集与免责声明（示例性建模/以官方文档为准）。

Q5：交付自动化的脚本骨架是什么样？
A：读取第 09/10 篇的结果长表 → 生成 summary 段宽表汇总 → 按阈值规则生成结论表（verdict 合规/需关注，只做提示不做资质判定）→ 从 run_meta.json 生成落款表 → 用 openpyxl 写多 sheet 交付工作簿 → 用交付清单脚本核对"主件 + 审计长表 + 元数据 + 案例矩阵"是否齐全，并检查衍生指标是否标注来源。核心是"模板化 + 多案例合并 + 版本落款 + 可追溯"。