第 4 章读者视角自审记录

自审日期：2026 年 10 月 15 日。正文：自然语言到 DSL 再到 SQL。待用户统一审阅。

• 沿用六月前三名，先给当前模型的字段，再给 DSL，读者不必猜语义字段与原表的对应关系。
• 用 SUM(salesAmount) 和客户 ID、名称分组明确汇总；不暗示仅列出金额字段就自动完成聚合。
• 区分模型固定的有效状态、单位换算与本次查询的日期、排序；limit 明确为调用层分页参数。
• 用同一章节内的对照表说明 AI 工作量怎样变化，权限在两条路线中均由系统落实，不把直接 SQL 描述成只能依靠提示词。
• 不编造错误码与响应 JSON，字段错误按诊断过程解释。

核对依据：JSON Query DSL 参考、v1.0 白皮书第 3、4 节、Runtime API 示例。物理 SQL 在独立 SQLite 内存库执行，客户、排名、金额与第一章查询完全一致：5500、4200、3000 元。

DSL 基于本章约定的教学模型，未在 Foggy Runtime 加载和执行；物理 SQL 是等价教学示意，正文已明确区分。模型配置和真实编译证据在应用篇补齐。

按用户意见，第三章改为产品无关的概念章后，本章在首次发现模型前简要介绍 Foggy 的 TM/QM 分工，并就地解释 DSL。对照 TM/QM 定义总览核对，未改动请求示例、物理 SQL 或结果。

按前序概念讲解定位重写（2026-10-17）

本轮按用户纠正，以“前序继续讲通用概念与机制”为准，替代此前在第四章引入 Foggy 与 TM/QM 的安排；具体产品配置与调用留到应用篇。

• 删除 Foggy、TM/QM、专有客户字段、产品分页参数分类和专用语法参考，沿用第三章的 customerId、customerName、invoiceDate、salesAmount。
• 明确约定产品无关的教学 DSL，增加 model 标识，说明 JSON 只是载体，键名、区间、排序等需要通过查询协议交付 LLM，不冒充标准 DSL 或实际产品 API。
• 以同一问题说明元数据选择、请求构造、字段和权限校验、业务规则展开及 SQL 执行；指出 SQL 中哪些部分来自语义模型，哪些来自本次请求。
• 错误字段改为 clientName，保留 customerName 为合法字段；区分结构校验拒绝与选错业务指标的语义问题。
• 读者视角复审：与第三章同一组名称和口径，不提前讲引擎配置；对照表承认直接 SQL 可以封装视图，权限两条路线均由系统执行；模型均明确指语义模型。
• 同步第五、六章的共享字段与相关表述，移出尚未进入实践的私有引擎术语；写作方案和总纲同步记录范围，避免后续再次提前引入产品。
• 实际复跑当时的核对脚本（现名 verify-query-equivalence.py）：SQLite 中第一章基线、第四章等价物理 SQL 与第五章临时视图教学 SQL 一致，前三名仍为 5500、4200、3000 元。请求 JSON 可解析；未运行真实语义引擎的 DSL 校验、权限或编译。
• 已读回第四章全文，核对正文 JSON/SQL 与配套文件一致；合订稿同步第四至六章，其他章节正文保持原样。

补充 DSL 使用熟悉格式的说明（2026-10-17）

在 JSON 示例后补充读者容易理解的说明：DSL 可以借助 JSON、YAML 等熟悉的格式组织领域含义，不必从零发明陌生语法。用第三章 YAML 定义语义模型、本章 JSON 描述查询的区别举例，不把 YAML 建模文件误称为查询协议。合并原有载体说明，保留具体键名、操作符和含义仍需通过协议学习的要点。已读回并同步合订稿，示例代码未改。

对照第三章精简并补充目标用户选择（2026-10-17）

• 从读者角度通读第三、四章：第三章负责语义层概念、收益与代价，第四章负责具体查询意图如何写成 DSL、展开为物理 SQL，以及字段错误怎样修正。
• 删除第四章小结中重复的 SQL/DSL 分工表，压缩重复的产品无关说明、模型规则提醒和执行后回答说明。保留短字段表，便于对照下方 DSL，不要求读者反复翻回第三章。
• 小结按目标用户说明选择：熟悉业务库、日常使用 SQL 且能复核结果的技术或分析人员，可从直接 Text-to-SQL 起步；非技术业务用户更适合通过语义层围绕业务概念问数。技术人员反复使用的指标也可沉淀，避免按职业作绝对划分。
• 使用 SQL 客户端与已确认口径的报表作类比，随后说明语义层仍可支持范围内的灵活提问与追问，避免将语义层等同于固定报表。
• 结尾衔接第五章的语义 SQL 入口；未引入具体产品。正文的 JSON、SQL、结果未修改，未重复运行数据库；已读回全文并同步合订稿，其他章节保持原样。

章节调整与样例入口更新（2026-10-17）

语义 SQL 与统一执行计划专题迁入第十九、二十章。上文历史记录中的第五、六章对应新章号；核对脚本现为 verify-query-equivalence.py，输出为 query-equivalence-results.json。本次复跑通过，仍仅验证 SQLite SQL 等价性与 JSON 解析，不验证实际语义编译、DSL 执行或权限。

第四章结尾改接新的方案分工概览。按用户要求，本章暂定，未将此状态改为正式审阅通过。

补充字段值对应与筛选阶段（2026-10-17）

• 在 DSL 请求前补充业务别名、枚举或维度值、相对日期，强调从已定义映射或当前用户可见的维度成员确认值。
• 地区作为扩展情形举例，不给原销售语义模型虚构地区字段；日期说明沿用已指定的 2025 年六月。
• 对照单张发票筛选与客户汇总金额筛选；说明当前 slice 只支持聚合前筛选，聚合后筛选取决于查询协议能力，不编造新 DSL 属性。
• 引擎校验加入字段组合，与第三章的粒度约束衔接；保留原 JSON 和物理 SQL，不把教学示意变成真实编译证据。
• 整体通读后，第三章只解释协议适配门槛，具体字段值和过滤阶段集中在第四章。补充稿已自审，待用户审阅。

路线选择移至第五章（2026-10-17）

• 将目标用户判断、指标复用取舍和 SQL 客户端与报表的类比移到第五章。
• 第四章小结只归纳 LLM、语义引擎和数据库的职责，并引出方案选择，不再提前展开选型。
• 通读第三章结尾、第四章全文与第五章后，查询流程和路线选择各有落点；本章 JSON、SQL 与样例结果未改。
• 调整稿已自审，待用户审阅。

实战篇合并后的对应关系（2026-10-17）

原第六、七章合并为现第六章《认识 Foggy，准备第一个问数项目》；原第八至二十二章顺移为第七至二十一章。语义 SQL 与统一执行计划现为第十八、十九章。上文保留当时的审阅记录，现行结构以总大纲 v7 为准；未开展环境搭建。