“把 Excel 里的数据填进 Word”听起来像一个很小的自动化任务。真正上线后，问题却往往出在写入之前：同一指标有三种字段名，金额列混入文本，空值被当成 0，页面看到的统计和文档里的统计还不一样。
因此，稳定的报表自动化不应从 Word 模板开始，而应从统一数据契约开始。
先把字段名变成稳定接口
外部 Excel 的列名会变，内部计算使用的字段名不应跟着变。可以在导入层建立一张显式映射表：
COLUMN_ALIASES = {
"交易日期": "date",
"记账日期": "date",
"收入金额": "income",
"贷方发生额": "income",
"支出金额": "expense",
"借方发生额": "expense",
}映射的价值不只是兼容更多文件。它还把“外部格式变化”限制在导入层，避免分析、页面和 Word 生成各自维护一套判断。
区分空值、0 和解析失败
这三种情况在业务上含义不同：
- 空值：原文件没有提供。
- 0：原文件明确表示为零。
- 解析失败：原值存在，但系统无法转换。
如果一律使用 fillna(0)，一些数据质量问题就会被隐藏。更安全的做法是先记录转换状态，再由明确的业务规则决定哪些空值可以当作 0。
让统计结果只计算一次
同一个“支出合计”，不应在页面、AI 提示词和 Word 生成器里分别计算。一个统一的 summary 对象应该服务所有输出：
summary = {
"income_total": income_total,
"expense_total": expense_total,
"monthly": monthly_stats,
"scope": "operating_transactions",
}其中 scope 尤其重要。它说明这些数字究竟统计了全部流水，还是只统计了经营性交易。没有口径的数字，往往比没有数字更容易误导。
Word 模板是视图，不是数据库
Word 生成层的职责应该尽量单一：把已经校验过的结构化结果呈现出来。它可以处理分页、表格样式和字体，但不应再做一轮业务分类或金额计算。
这个边界让测试变得更简单：
- 数据层测试字段映射和数值转换。
- 分析层测试统计口径和规则。
- 报表层测试某个已知数据对象能否生成正确文档。
一份可执行的回归清单
- 同一指标在页面和 Word 中是否来自同一数据字段？
- 只有一条数据时，比例和分母是否正确？
- 数据为空、为 0、为负数时，文档是否仍可读？
- 表格行数增加后，页眉、分页和表头是否正常？
- 生成后的 DOCX 能否重新打开，ZIP 结构是否完整？
报表自动化的成熟度，最终体现在“数据只有一种含义”。当字段、口径和输出共享同一个真实数据源时，才能放心把重复工作交给程序。