SAG / ARCHITECTURE NOTE

为什么 JSON 分析契约需要版本和验证

这是一种为 JSON 观测与报告资料定义字段含义、版本和验证规则的设计。即使可以轻松接入新引擎，只要字段含义发生变化，历史资料就可能失真。存储灵活并不意味着无需验证。

SAG编辑 · 2026-10-08 · 更新 2026-10-08

什么是分析数据契约？

这是一种为 JSON 观测与报告资料定义字段含义、版本和验证规则的设计。 本说明将分析数据契约视为输入、转换和输出各自承担的职责，而非某个功能的名称。要信任分析结果，就必须能够追溯输入了哪些资料、进行了哪些检查，以及结论能够得出到什么程度。

即使可以轻松接入新引擎，只要字段含义发生变化，历史资料就可能失真。存储灵活并不意味着无需验证。

在输入时验证类型、大小、必填值、时间段和版本。区分原始数据与用于汇总的转换版本，并保留旧版本中的缺失值。

原始输入 → 版本与字段验证 → 月度汇总契约

每个阶段都不应把前一阶段的成功说成下一阶段的成果。连续记录资料的标识符、时间段和验证状态，就能找到遗漏或错误发生的位置，并确定需要重新检查的范围。

SAG 按照模式、时间段和对象标准读取已存储的月度报告与观测数据。只有存在完整性标记和原始数据时，才会汇总引用。

SAG 的运营价值在于将这些关系连接到页面、问题、比较结果和改进工作。客户不必只看数字，还可以一并检查需要补充的对象和判断依据。对于需要额外应用的模式，应依据相应段落的范围进行解读。

如果说明性旧资料没有 citations，却将其转换为空数组，那么“未确认”就会变成“没有引用”。按版本进行的转换必须保留“未知”状态。

上述示例用于说明结构和计算，并非某家特定客户的实测成果。实际报告应关联所选的时间段、对象、观测条件和原始记录，才能重新核验相同的判断。

请确认在空资料、重复资料和条件不同的资料中，含义是否仍然一致，而不仅限于正常输入。将验证项目纳入工作完成标准，有助于缩小功能说明与实际运营之间的差距。

仅靠 JSON 存储并不能完成契约。还需要读取端验证、迁移资料和回归资料。

外部资料为上述设计主题提供背景，并不代表对 SAG 所有实现或客户成果的认证。本说明中的应用解读和说明性示例依据 SAG 的运营架构整理。资料核查日期：2026-10-06。