流水平衡不等于证据充分：为奖励声明建立可追溯引用约束

摘要：积分流水的加减正确，只能回答数字是否一致。奖励声明还需要说明引用了哪条流水、标识是否唯一，以及证据能支持到哪一步。本文依据一个离线核对工具的源码、测试和历史日志，讨论如何分别表达账本一致性与声明的证据状态。

看到“期初加收入减支出等于期末”，容易顺手写下“奖励已确认”。这一步跨过了证据边界：相同的总额，可以来自不同事件；声明里的状态文字，也可能只是输入者填写的标签。

先让每一步余额说得通

以下数字和标识全部为合成示例：期初为100，流水A增加10，余额110；流水B减少5，余额105；期末为105。核对时既要计算总变动，也要按输入顺序检查每行余额。

如果A的余额误填111，期末仍填105，总额关系依然成立，中间记录却有错误。现有测试专门覆盖了“中间错误、最终相等”。实现不通过排序或改数替输入解围，而是报告不一致。

这里的earned是正向变动总和，spent是负向变动的绝对值总和。后者可能包含冲正，不能单凭字段名解释为消费；同样，正向变动也不能直接等同于某项活动的奖励。

声明必须有可定位的引用

工具将奖励声明称为claim。它包含声明ID、状态文字，以及可选的ledger_id。claim不参与余额加总，避免把“声称获得”再算成一笔收入。

沿用上面的合成账本，可以手工推演三种声明：

approved不会让缺失的引用自动成立。代码检查状态是非空字符串，并将其保留到结果中；它没有向外部审核系统查询。真正改变supported的，是引用是否能定位到唯一的流水ID。

因此，账本的ok=true与声明的supported=false可以同时出现。warnings本身不影响ok：ok回答数字和标识是否一致，warnings提示声明缺少可用引用。只在汇总里显示一个绿色“通过”，会遮住这层差别。

去重不能替重复证据作决定

再构造一组数据：期初100，第一行ID为A、增加10、余额110；第二行仍叫A、变动0、余额110；期末110。每步余额和最终总额都吻合，但A已经无法唯一定位一条记录。

如果只检查“A是否出现过”，引用A的claim就可能被错误支持。当前实现先收集重复ID，再判断声明引用；引用重复ID时，supported为false，并给出warning。重复ID也使账本ok为false。

这里没有自动删掉第二行。程序仍按原始行计算总额，并明确标为仅供诊断。去重需要依据业务规则判断两行究竟是重复导出、不同事件误用了标识，还是其他问题。核对工具没有足够信息替使用者选定一行，更不能把去重后的数字包装为奖励确认。

把证据范围写进结论

supported为true只说明引用的ID在输入账本中唯一存在。它不验证流水来源真实性，也不校验该行是否为正向变动、金额是否对应某项奖励。当前实现还允许多个claim引用同一个唯一ID，因此不能据此证明多项奖励分别到账。

supported也不依赖整个账本的ok：某个引用可以唯一存在，同时其他行出现余额错误。阅读报告时，应同时检查账本问题、每条声明的引用和警告，随后再依据外部凭证判断业务事实。

2026年10月25日留存的失败日志记录了两处实际问题：重复ID引用被支持，以及缺少引用时没有可见警告；对应回归测试检查了这两个行为。最终历史日志记录53项测试通过。本文只分析源码、测试和既有记录，未于今日重新运行测试，也未进行生产验收。

可追溯的声明，应让读者沿着“声明—唯一流水—外部凭证”逐步复查。离线核对完成的是其中明确的一段；结论写到哪里，证据就必须能跟到哪里。