基础功能覆盖审查

本文保留补充前的审查意见。最新结果：第九章文字/排除/空值、第十章条件聚合、第十二章去重/小计已实测补入；字典独立为第十五章，维护顺延第十六章。详见基础功能补充记录。

2026-10-21。审查第 1—13 章正文，对照本地技术白皮书与语法、实施文档。第十三章已获用户确认；本轮审查及后续编排不开始下一章实操，不改模型或运行查询，也不把文档中列出的能力标为教材现场已验收。

结论

基础主线已完整：接入数据 → 确认业务含义 → 建立 TM/QM → 实时获取元数据 → 筛选、聚合与计算 → 时间分析 → 成员、关联与下钻 → 权限。

还值得补充的常用功能主要是：文字搜索与空值筛选、字典映射、原生合计与去重，以及简单条件指标。QM JOIN 与聚合 JOIN 已明确补入基础篇；累计和滚动随同比/环比、LAG 集中到高级篇。模型维护与回归已规划，属于尚未写完，不是遗漏。无需为每个参数新增一章。

已讲到什么

范围	已覆盖	评价
第 1—5 章：通用原理	Text-to-SQL 的实现与限制、可执行语义层、查询上下文、DSL、方案选择与职责	保持稳定，不追加产品参数
第 6—7 章：接入与理解数据	Skill/CLI/服务、数据源与 Namespace、结构与实际值探查、粒度、日期、金额口径和独立基线	已覆盖基础准备
第 8 章：建模与首次查询	TM/QM 源码、属性/维度/度量、关联、校验加载、实时 Markdown、排名和分类汇总	已覆盖最小闭环
第 9 章：筛选	日期区间、等值、数值比较、in、AND/OR、slice/having、空结果	已有逐张账单查询，不能再算作“缺少明细查询”
第 10 章：计算	SUM/COUNT/去重计数/AVG/MIN/MAX、临时计算、QM 固定指标、零分母和占比分母	覆盖主要聚合；尚未示范条件分组/指标
第 11 章：日期汇总	日期自维度、年月属性、月度汇总与跨年分组	比较与 LAG 已迁高级素材，累计与滚动也在高级篇统一讲
第 12 章：成员与关联	成员目录与成交成员、多级维度、具体列 name/alias、稳定排序、分页/总数、下钻	尚未讲原生合计；DISTINCT 的修复证据不等于正文已讲解
第 13 章：权限	模型/字段/行/成员范围、可信身份、失败拒绝、聚合和分页范围核对	已覆盖本地教学边界，不追加生产 IAM

建议补充的内容

1. 文字搜索、排除与空值：补第九章

这是最值得先补的日常功能。已有示例主要查询日期、国家与金额，读者还会问“名称里带某个词”“排除某类”“哪些记录没填某个字段”。

补一个文字包含查询，以及 not in 的简短变体。
补 is null / is not null，区分 NULL、空字符串、0，以及完全没有符合条件的记录。
不列全部操作符；字段必须先由实时元数据确认。选用原始 Chinook 中确有空值的字段；未公开时先建模，再查询。
验证文字匹配的大小写和通配符行为，不能将某个数据库的行为说成所有数据库都相同。

2. 字典与业务名称：放进第十五章的模型完善示例

第九章已发现“美国”与 USA 的取值差异，但目前由 AI 查询取值后理解。文档提供 dictRef，值得说明如何把稳定的编码含义放进语义模型，减少每次猜测。

可以从已存在的国家代码与中文名称做小例子；不要给 Chinook 凭空添加订单状态。先验证字典是否进入实时元数据、返回的键与标签是什么，以及筛选到底使用哪个值。字典标签不能直接视作可提交的筛选值。

这与第十二章不同：维度成员来自关联表，字典通常用于有限编码映射。常用名称、字段描述、单位说明也在这里一起完善；代码与语义说明变更后，再进入校验、刷新和回归，衔接自然。

3. 分页、去重与合计：补第十二章

正文已经区分本页 5 条、119 个分组和全年金额，但全年金额是另行核对的，尚未介绍原生汇总输出。

用一个去重列表说明 distinct 与第十章 count_distinct 的区别：一个返回不同的值，一个返回数量。去重不会修复错误关联造成的金额重复。
对照 returnTotal、原生汇总返回和 withSubtotals，验证当前 CLI 实际支持的组合与响应位置，再决定保留哪个最小例子。
重点讲本页、全范围、分组总数与金额合计；平均值和比例不能直接累加。
不展开多层 ROLLUP、透视轴或复杂小计规则。若当前版本不支持目标组合，就说明边界，保留独立汇总查询，不能手工拼接后称为引擎原生输出。

4. 时间比较、累计与滚动：集中高级篇

用户已确认统一到高级篇“时间分析”大章，第十一章只保留日期字段、年月分组与范围。累计、滚动属于常见需求；本次后移是为了集中讲清期间与窗口口径，不代表它们只适合高级用户。既有同比/环比、LAG 素材与证据保留，新增累计/滚动待验证。

5. 简单条件计算：第十章可选补充

除算平均和占比，日常还会把账单按已确认金额门槛分组，或只累计某一类记录。可选一个固定的金额分档示例，先临时表达，再说明高频定义应固化。

文档中的条件表达式能力存在不同执行路径和受治理子集。不能据此宣称任意 CASE/函数都支持；按当前引擎验证一种最小写法即可。不要扩展到 CTE、复杂分群或跨模型计算。

6. 一个 QM 中 JOIN 多个 TM：第十四章

用户已纠正：基础篇讲 QM 内关联多个 TM，以及模型中先聚合再 JOIN；不是运行时 Compose 组合多个 QM。当前已用账单/明细两个 TM 的普通 JOIN 与聚合 relation 实测重做。查询端仍为一个 QM 加普通 DSL。先前的 Compose 素材和真实证据迁往高级篇，不能继续把其问题或用例数算在基础章上。

已在计划内，无须重复增加

第十五章继续讲“模型改了，旧问题还能不能答对”：

完善一处真实的业务描述或字典映射；先修改，不查询。
校验、更新与刷新，区分文件保存、校验通过和实际加载。
实时获取元数据，确认 AI 使用了新定义。
用少量旧问题回归，覆盖正常结果、空结果、无效字段与身份范围。
遇到失败时根据诊断定位模型、请求或执行问题；核对当前加载版本，不反复加提示词。

查询证据各章已经在用，第十五章归纳其读法即可。解释/重新编译的 SQL 与实际执行日志要分清；完整发布、回滚、制品治理留作运维或高级内容。

QM 默认排序、预定义条件可顺带说明。conds 是条件定义，不能直接当作强制业务过滤或权限条件。无需为默认值单独开章。

仍放高级篇与在线篇

CTE、复杂多阶段聚合、跨源 Memory Grid 与多来源对齐。基础篇纳入单 QM 的多 TM 关联和聚合 relation；动态 Compose、CTE 组合保留高级。
复杂层级、透视、透视派生指标、漏斗和归因。
语义 SQL、统一计划、向量、缓存与预聚合、性能调优。
Recipe 注册治理、完整 authoring/release/promotion/rollback 流程。
Console/FAP、图表和导出放在线接入时讲，不把它们遗漏于基础 DSL 等同于基础概念缺失。

普通“国家 × 月份”交叉表在业务上很常见，但用户已约定多维分析进入高级篇，本轮不改变这个安排。

补写顺序与验收

建议先补第九章的文字/空值、第十二章的结果去重与合计；第十章条件指标按篇幅选补。再写第十四章 QM 内多 TM JOIN（含聚合 relation），第十五章模型维护与回归。第十一章不再补累计，基础完成后再规划高级系列。各章原稿保持精练，完整证据进 lab。

新增用例均按“实时元数据 → validate → execute → 原始数据独立核对”验收。模型变更与查询分开，提示词只描述业务任务。当前会话调用 CLI 的验证，与另开干净会话仅凭短提示词的读者复现，继续分别记录。

本审查随后已按用户要求同步编排：收紧第十一章，基础篇新增第十四章 JOIN、维护顺延第十五章。未执行新增能力；具体变更见当前总大纲。

参考与文档差异

本次读取本地文档仓库，HEAD 为 08bef58，工作树无改动；这是本地文档快照，不代表已核对远端最新版本。教材既有实操基线是 Launcher 0.1.30 / CLI 0.1.25。白皮书版本号与 Launcher 发行号不是同一版本体系。

v1.0 技术白皮书：基础建模、查询契约、权限和证据。
v2.0 技术白皮书：分阶段、Memory Grid、Pivot 等复杂能力及签收边界。
v3.0 草案：明确 DRAFT / NOT FROZEN，不能把候选合同当作稳定功能补进教材。
DSL 参考：timeWindow、distinct、withSubtotals 与查询范围。
TM 语法：字典与属性；QM 语法：默认排序、计算字段与预定义条件。
查询 DSL、查询工具、模型生命周期。

两处应在后续实操时核对：查询 DSL 手册称 left_like 自动加前置 %，查询工具页却将其写为前缀匹配；旧 HTTP 响应文档描述 returnTotal 返回 totalData，白皮书则不承诺具体结果包络。不能把旧 HTTP 响应直接套到当前 CLI，更不能仅凭这两处描述提交引擎缺陷。