时间分析系列大纲

2026-10-23 更新。时间系列第 17—21 章已按 Launcher 0.1.38 / CLI 0.1.25 整体复审待阅。#158～#161 复测通过，空值输出与诊断说明同步；教学端口 40 次 CLI 查询执行、2 次 HTTP 执行及 3 项预期拒绝通过，见升级与验证。旧版初验与故障证据保留。

主线与篇幅

从“按日期计算”，走向“让 AI 理解业务中的时间”：选对日期、确定期间、解释缺失，区分流量与存量，再分析业务耗时和客户随时间的变化。常用规则尽量固化到语义模型，让 AI 选择范围和指标，不必每次重新推导。

按 四章重点实操，加一章选讲 组织，正式占第 17—21 章。按用户最新要求，同期群也在本批完成，正文只交代最小必要的阶段计算，不提前展开整套 Compose/CTE 接口。

专题二的第十八章正文使用 Chinook 加教学日历、模拟入库时间，未切换 WWI；初验在 Launcher 0.1.36 改用普通日期属性声明角色，14 项执行和 1 项拒绝通过；当前 0.1.38 代表回归也已核对，见实操记录。WWI 留给后续确有业务数据需要的专题，不为更换案例先铺整套环境。

一：期间比较与窗口计算

保留第十七章的同比、环比、YTD/MTD、LAG、calendar/observed 滚动，不再扩写为时间需求大全。

• 重点仍是当前期与历史输入、跨年/月重置、上一行与上一自然期、自然日与实际数据桶。
• 简要说明滚动 SUM、桶均值与明细均值的区别；0.1.36 已另测两种模式的 SUM/AVG/COUNT/MIN/MAX 共 10 项，正文补 AVG/COUNT，未扩展到其他数据库或所有空值组合。
• 不在本章展开财务日历、补齐时间轴、部分期间同比和留存；只留下后续专题入口。
• 已有 0.1.35 的 24 项执行、2 项预期拒绝及补充 observed 证据保留，不因扩充系列重新执行全部旧用例。

二：业务日期、日历与可比期间

主问题：“截至某日，本月比上月同期怎样？”用同一个问题串起日期选择、统计截止和期间对齐。

1. 先选业务日期。 区分下单、开票、付款与系统更新时间；通过字段说明、时间角色和实际样例告诉 AI 各自用途。多个日期角色引用同一日期表时，公开名称要明确。复用第十一章知识，不重讲基本年月建模。
2. 把日历写成数据。 示例以完整日期表和一个明确的教学工作日规则为主，定义日期、年月、周起点、是否工作日。没有交易的日期不等于零；补齐时保留“确认无业务”和“数据未知”的区别。
3. 对齐可比期间。 区分整月、截至同日、相同已过天数、相同工作日数；选一种作主例，其余解释差异。期间边界、月底短月与闰日策略须先确认；不默认按天数推算整月，也不把当前不支持的部分期间塞进 timeWindow。
4. 固定统计截止。 “今天”与“数据更新到昨天”不同；示例固定查询基准日期及已知数据截止。“最近七天”不等于“本周”，相对日期须展开成可解释的边界。源码已有 now、-7D 等日期表达式解析，但具体入口和时区行为待实测；历史样例不能拿机器当天直接当业务当前日。

引擎落点： 日期维度、多个日期关联、普通 slice/groupBy、固定计算字段；业务日切点可评估固定的计算日期轴，不能只改字段描述。先验证日历为主表的关联方案，必要时在准备层形成完整日序列，再通过 TM/QM 查询。自定义工作日和财年属于建模规则，不宣称有一个通用 timeWindow 开关。

带一下： ISO 周与跨年周、财年/财季、营业日切点、时区及夏令时；星期/月份的简单周期分布可作短例，不展开季节性分解。跨时区先明确源时间含义和转换规则，不让 AI 猜。

验收： 日期轴不串用；补齐前后金额一致；零值与未知不混淆；跨月/跨年/短月边界符合约定；两期覆盖长度及截止可解释。新的周历或部分期间能力逐项验证，不能由月同比通过推断。

三：存量、快照与历史时点

主问题：“本月发生多少”和“月底还剩多少”，为什么不能用同一个 SUM？

1. 先区分流量与存量。 销售额可跨日累计；每日余额不能再跨日相加。说明实体、日期与快照粒度，选库存或应收余额中的一个作为主例，不同时铺开多个行业。
2. 取期末状态。 区分截止日有完整快照、每个对象最近一次有效记录、由期初加变动重建三条路径。不能用 MAX(balance) 代替最新余额，也不能只取全表最大的日期就认为覆盖了所有对象。
3. 算平均存量。 连续日快照的日均与仅有变动日记录的平均不同；后者需要确认状态延续规则，再按有效时长加权。先讲一个可手工核对的小例子。
4. 交代历史依据。 缺少期初或历史变更就不能恢复任意时点。当前归属与当时归属、事后补录后的重算与原发布值，作为短节说明；完整慢变维和双时间模型另留扩展。

引擎落点： 日期筛选、聚合及 TM/QM；0.1.38 已验证“每对象 MAX 日期 → 对应记录 → 目录 LEFT JOIN”的完整嵌套路径，以及日快照和日均。不会因有 LAG、MAX 或窗口函数就宣称存在通用的期末值/历史查询算子。

验收： 期初＋变动＝期末；对象无当日记录时处理正确；缺期初明确报告；不跨日期累加余额；加权平均可逐段复算。没有真实历史的数据不冒充 WWI 原始快照。

四：业务耗时、逾期与时效

主问题：“处理通常要几天？哪些仍未完成或已经逾期？”

1. 确定起止事件。 区分下单至开票、开票至付款等不同周期；不因字段名像日期就随便相减。主例只选一个有证据的业务过程。
2. 分别处理完成和未完成。 已完成看实际耗时，未完成看截至固定日期的等待时长；未完成记录不能直接丢掉，也不能混作已完成耗时。
3. 固化耗时和逾期规则。 自然日为主例；条件聚合得到超时数和占比，讲清截止时点、阈值和分母。“截至当时逾期”与“后来最终超时”分开。
4. 给出有用的分布。 除均值外，用简单时长分段找出长尾，不把 SQL 分位数等未验能力列为必备功能。

引擎落点： 文档中的日期差、条件表达式、固定/临时计算字段、slice/having 与条件聚合。日期差单位、跨日取整、空值和实际方言必须先测；完成后的常用口径进入 TM/QM，查询端仅选范围和分组。

带一下： 工作时长扣除周末/假期需要业务日历；单位营业/运行时长的效率指标必须有可靠时长分母。复杂暂停恢复、多次返工和完整事件漏斗留后续组合分析，不在这里堆接口。

验收： 同日、跨日、缺结束时间、恰好达到阈值、结束早于开始；已完成与未完成分母正确；固定参考日期后结果可复现。观察尚未结束的对象不与已观察完整周期的对象直接比较最终表现。

五：同期群、复购与留存（选讲，现第二十一章）

主问题：“不同月份首次购买的客户，之后的复购表现怎样？”

• 先得到每位客户的首次可见购买月份，再按购买后第 0、1、2…个月组织活动；区分自然月与客户进入后的相对时间。
• 主例只做“按月购买同期群＋次月再次购买比例”；观察窗口不足的格子标未到观察期，不补成零。
• 去重到客户；分母是已确认的同期群人数，不能每个月换成当月活跃人数。
• 历史不完整时只能称“样本内首次购买”，不能据此断言真实新客。不得为了限定展示期间先裁掉确定首次购买所需的历史。
• 流失与回流只解释活跃定义、阈值和窗口；不把“未再购买”擅自解释成客户永久流失。

引擎落点： MIN、客户—月去重与固定月份属性，加上 Compose 分阶段聚合/关联；0.1.36 已实际验证。引擎返回同期群规模及实际购买人数，结果整理脚本按固定观察截止补零/空并计算比例；不是原生留存 DSL，也没有在准备层预先计算首购结果。

验收： 手工选择少量客户追踪；每客户每月只计一次；月偏移正确；人数、分母和未到观察期一致；不越过用户可见历史追查隐藏数据。

常见需求的取舍

能力依据与待验证项

主要参考：

• 0.1.35 复测记录及验收结果。
• DSL 语法参考：表达式、聚合、窗口；其中旧的粒度兼容表不替代当前发行版实测。
• TM 日期与维度定义：独立日期维及多个日期角色。
• 时间窗口设计及比较期合同：本轮核对到 0.1.35 对应提交 189b8b5617c724193a1943e65a849806628a28e1，新场景尚未实测。
• 相对日期解析源码：作为后续入口验证线索，不替代公开 CLI 验收。
• DSL_CTE 白皮书：仅承诺窄合同；不把白皮书模板、Runtime Compose 与任意 SQL CTE 当成同一套接口。

写作顺序与交付

第 17—21 章按“一 → 二 → 三 → 四 → 五”阅读，本轮已按 0.1.38 更新并整体自审，交用户统一审阅。旧故障与替代方案转入历史记录，正文采用已验证的新用法。旧 18/19 语义 SQL 草稿文件未覆盖，仍为历史素材编号。

各章仍按“业务问题 → 确认口径与数据 → 创建/修改模型 → 查询 → 独立核对”推进，创建与查询分步，提示词保持简短。查询 Markdown 由引擎实时生成，结束列出本章 Foggy 知识点。WWI 是否有适用字段和历史先探查，教学补充数据保留来源与生成规则；不为演示虚构源库事实。

本轮自审：第十七章负责计算，专题二负责期间定义，三负责存量，四负责耗时，五负责对象随时间变化；共同的权限、元数据和回归方法引用前文，不重复介绍。新增专题都标出数据前提与验收，未将设计文档或 capability 标记当作新场景已通过。