先说结论
Odoo Digest 真正解决的问题，不是“把若干数字塞进一封邮件”，而是：同一套管理摘要，如何在不同周期下稳定取数、比较上一周期，并给出下一次该何时发送。看懂这一层，你才知道为什么 Digest 改错一个周期字段，结果会连带影响 KPI 的语义。
第一层：为什么 Digest 先算时间窗，再算指标
在 _compute_timeframes() 里，官方不是先去读 KPI，而是先根据公司时区构造三组时间窗：最近 24 小时、最近 7 天、最近 30 天，并且每组都同时带上“当前区间”和“上一段对照区间”。这说明 Digest 的核心不是某个单点数值，而是“同口径下的对比”。如果没有这一层，后面的增长率、下降率就没有讨论基础。
第二层：KPI 汇总为什么依赖上下文而不是写死 SQL
Digest 通过 with_context(start_datetime=..., end_datetime=...) 来驱动每个 kpi_*_value 字段的重新计算，然后再让 _calculate_company_based_kpi() 去按公司和时间范围做 _read_group。这种设计的好处是：Digest 不需要知道所有业务模型的细节，它只需要提供一套统一上下文，具体 KPI 自己按这个上下文取数。也因此，Studio 自定义 KPI 和原生 KPI 才能共存。
第三层：环比 margin 为什么不是“这期减上期”这么简单
_get_margin_value() 明确在两个值都非零时才计算百分比变化，这是一种很务实的产品判断。因为很多管理摘要里的问题并不是“有没有变化”，而是“变化是否具有可解释性”。当上一期为零时，直接算百分比往往会得到误导性的巨大数值，所以源码宁愿返回 0，也不去制造漂亮但虚假的涨幅。
第四层：为什么 next run 要独立计算
_get_next_run_date() 没有把发送时间混进 KPI 计算里，而是单独根据 periodicity 推导下一次日期。这样做的好处是非常清楚：一封 Digest 的“内容时间窗”与“调度节奏”是相关但不同的两件事。你可以今天手动发送一次，但不一定就要打乱后续自动发送的节奏。
第五层：这套机制最适合解决什么场景
当公司想让管理层每天、每周或每月收到固定口径摘要时，Digest 比手工报表更可靠，因为它把时间窗、指标口径、环比与调度拆成了清晰的层次。你不是在维护一封邮件，而是在维护一套重复执行的管理观察规则。
最容易误解的三个点
- 误区一：Digest 只是一个邮件模板。实际上模板只是最外层，核心是时间窗和 KPI 取数上下文。
- 误区二：周期改成 weekly 就只是少发几封。实际上它会改变 next run 节奏，也会影响管理者对摘要节奏的预期。
- 误区三：环比数字天然可信。没有先统一时间窗，任何环比都可能是错位比较。
实战上怎么用更稳
- 新增 KPI 时，先确认它是否支持按上下文时间范围安全取数。
- 多公司环境下，不要偷懒直接查全库，优先沿用公司维度聚合逻辑。
- 如果业务方质疑摘要数字，第一步先核对时间窗，而不是先怀疑模板。
最后总结
Digest 的本质，是把“时间窗、指标、比较、调度”四件事捏成一条链。只有按这条链理解它，你才不会把管理摘要误做成一封好看但口径混乱的邮件。
DISCUSSION
评论区