返回正文目录

第十二章实操：维度成员与多级关联

日期：2026-10-20。正文：从艺术家查到专辑。当前 Codex 会话实际调用公开 CLI，没有另开干净会话只发送正文短提示词。

环境与模型修改

2026-10-21 最新复测： Launcher 0.1.30 / CLI 0.1.25 的 #148/#149 均通过。正式教学入口已升级；在原 Namespace 完成 QM 具体列改名、6/6 校验、刷新、实时元数据和 11 项查询，成员接口也返回正确目录。正文已同步、自审，待用户审阅。见当前实操记录；以下 0.1.29 及之前段落保留历史过程。

2026-10-21 最新状态： 教学入口已升级 0.1.29。#146 具体列 name/alias、#145 DISTINCT 排序通过；候选别名稿 11 项查询通过，但同 Namespace 的已登记目录再次校验报资源重复，正式教学 QM 暂未改名。专用 members 接口在新进程仍异常。详见0.1.29 实操复测与下一步规划。下文保留各轮原始环境与结果。

实时元数据公开名是 album$id、album$caption、artist$id、artist$caption，不是直接照搬源码的 track.album.artist 路径。models describe --format markdown 返回内容已原样提取为实时 Markdown 快照，仅供证据留档，不要求读者预先生成或维护。

后续命名核对（2026-10-20）：根据用户追问，在原 0.1.25 教学服务上分别使用 artist$id/artist$caption 与 track_album_artist$id/track_album_artist$caption，同步替换 columns、groupBy、orderBy，再分别增加 ID=90 的筛选。四项请求均先校验后执行通过；完整结果都是 119 组，筛选结果均为 Iron Maiden 的一组、34 条明细，统一结果键名后数据和 total 一致。证据见 dimension-name-check/verification.json，脚本为 checks/check-chapter-12-dimension-names.py。这只证明当前 QM 两套名称可解析，未验证同名嵌套维度的消歧或跨版本行为；不将短名当作 QM 默认丢弃父路径的通用规则。

先前 TM 别名试验（2026-10-20，保留历史证据）：在独立示例 TM 的 artist 维度设置 alias: 'albumArtist'，QM 继续通过 line.track.album.artist 引用。使用不同模型名 ChinookInvoiceLineAliasModel、ChinookInvoiceLineAliasQueryModel 和临时 Bundle，不修改原六个模型。两个示例文件先校验通过，再登记、刷新并读取实时 JSON/Markdown，均公开 albumArtist$id、albumArtist$caption；DSL 筛选 ID=90、分组并计数，返回 Iron Maiden、34 条明细。之后核对所属路径并移除临时 Bundle，确认原 QM 可用，原模型和数据哈希未变，没有重启服务或更改数据源绑定。用户后续明确要 QM 别名，故这段试验不再作为正文方案。

示例代码在 examples/chapter-12-dimension-alias/models，脚本为 checks/check-chapter-12-dimension-alias.py，结果见别名验证和清理记录。示例文件保留供复核，未登记为日常教学模型。此方案是 TM 的维度 alias，不是给 QM 的整个维度 ref 添加输出 alias。

QM 别名核对（2026-10-20，用户澄清后）：在独立的 TM 副本中保留所有维度配置，仅用不同模型名隔离；建立三个 QM，对照整维度引用设置 alias: 'albumArtist'、ID/caption 分别设置列 alias、ID/caption 同时设置 name/alias。四个模型文件校验通过后，临时登记、刷新并实时读取 JSON/Markdown。三者元数据仍公开 artist$id 等原名称，分别以 albumArtist$id 或 albumArtistId 查询均在 query.validate 返回 FIELD_NOT_FOUND，未执行任何已拒绝请求。此结果不能将别名写法作为当前可用步骤，也不证明其他版本和所有普通属性 alias 都不可用。

源文件和请求在 examples/chapter-12-qm-alias/models，结果与精确诊断见 qm-alias-check/verification.json，脚本为 checks/check-chapter-12-qm-alias.py。已核对临时 Bundle 路径并移除，主模型仍可读取，原六个模型和数据哈希未变，见清理记录。该轮使用 0.1.25，未改产品代码或重启教学服务。

0.1.26 复测（2026-10-20）： 使用官方发行脚本在独立 18068 实例重做三个原请求，并缩减为具体 ID/caption 列同时配置 name/alias 的一对 TM/QM。模型校验通过，JSON/Markdown 仍是原名称，新名称均在查询校验阶段被拒绝；每个同 QM 原名称对照均返回 Iron Maiden、34 条、33.66。已提交 #146，说明元数据/字段解析问题及不支持配置应提前拒绝的要求。第十二章不迁移到失败别名。测试实例已停止，原教学 0.1.25 服务未动；安装身份、操作、日志及清理见完整复测记录。

模型版本：本次 TM 快照、本次 QM 快照。第八章的旧明细 TM/QM 另存到 evidence/chapter-08，与当时源码一致；旧章链接改指向快照，内嵌代码未变。

查询与独立核对

所有成功用例对相同 payload 先 validate 再 execute。结果以 Chinook 原件只读表行核对：Python 分别读取 Invoice、InvoiceLine、Track、Album、Artist、Genre，以主键字典连接和 Decimal 计算，不复用引擎生成的 JOIN SQL。

用例 已核对结果
01-artists-all 2012 年完整排名 119 组，合计 477.53、数量 447，每位金额和数量逐项匹配
02-artists-first-page start=0、limit=5、total=119，与完整排名前五项一致；本页合计 136.75
03-artists-second-page start=5，第二页从 Lost 开始，无前页重复，total 仍为 119
04-artists-last-page start=115，末页四项与完整排名一致，hasNext=false
05-sale-artist-members DISTINCT 得到当年有成交的 119 位 ID/名称集合；只验收成员集合，不验收此请求的顺序
05b-sale-artist-members-grouped 按 ID、名称分组并计明细数；119 位及各自条数匹配，ID 升序正确；这是正文采用的成员发现方式
06-selected-artist-albums 从完整排名第一位获取 Iron Maiden / ID 90，再按专辑分组；19 张有当年成交的专辑，合计 33.66、数量 34
07-selected-album-tracks 从上步第一张 Powerslave / ID 107 获取曲目；5 首，合计 4.95、数量 5
08-plain-totals 无新增维度分组的原明细合计仍是 477.53、447 条、数量 447，与完整艺术家分组一致
09-empty-period 1990 年该艺术家专辑分析返回空列表
10-category-regression 第八章原分类请求逐分类金额、数量与原件匹配

合计 11 项语义查询通过；每个聚合值容许误差 1E-12，展示金额才保留两位。SQLite 使用浮点求和，排序按实际未舍入金额核对，金额完全相同时核对 ID 次序；没有把显示两位相同的值强行当作原始值相同。

returnTotal: true 在本章分组分页中返回总组数 119；pagination.returned 是页内条数，金额通过独立汇总核对。普通未请求总数的响应不拿 total 判断金额或完整性。最初整体汇总 limit=1 时返回一行并提示“可能还有更多”；采集脚本按完整性检查停止，随后仅将该用例改为 limit=2，重新校验执行并确认没有下一页。此行为没有误记成金额错误。

专用成员接口异常：未计为通过

本章加载嵌套 album/artist 后，CLI 0.1.24 的 members list 探查出现以下结果：

dimension 参数 实际表现
artist 响应 code=200，但返回 Track 名称和 ID，total=3503；CLI 退出 2，缺少标准 Runtime success 信封
artist$id code=500：query model slot/name mismatch: ChinookInvoiceLineQueryModel#album
album$id code=200，但仍返回 Track 列表、total=3503；CLI 退出 2
track_album_artist、track.album.artist 及带 $id 写法 code=500：cannot resolve synthetic member-QM from fieldName

调用参数、退出码、完整响应与关键日志见member-diagnostics.json和运行日志节选。安装的 CLI 源码显示该命令使用公开 /jdbc-model/dimension/v2/... 路径；返回信封与 CLI 的标准成功判定不一致，同时存在返回对象错误和服务端 slot/name mismatch，不能仅因 code=200 就当成功。

另一个只读探查中，distinct 请求的 normalized orderBy 保留 artist$id 升序，但生成 SQL 没有 ORDER BY，实际也未按 ID 排序。本章因此只验证 DISTINCT 的集合；正文改用已验证排序的分组查询。探查编译响应保存于 *-members-query-explain.json。

这些是本轮新发现的未解决行为，不属于已通过的 #139–#142 时间分析复测。尚未做干净进程隔离来确定缓存、嵌套模型与接口解析各自的作用，未修改产品代码。

2026-10-20 按用户要求，DISTINCT 查询丢失 ORDER BY 已提交 #145，包含发行身份、完整 TM/QM、payload、预期/实际结果、执行与 explain SQL、分组对照和回归建议。已回读核对远端正文，提交记录位于 evidence/chapter-12/github-issues/distinct-order-submission.json。专用 members 接口异常未混入此 issue，尚未另行提交。

后续状态更新：用户告知 #145 已解决，已核对维护者的修复发布说明，修复已随 Launcher 0.1.26 发布。本教学环境尚未复测，以上 0.1.25 失败证据保留历史语境；不能据此声称新版仍失败，也不能把成员接口异常当作一并解决。下一步见当前规划。

正文使用现有公开 QM 分组查询发现 2012 年有成交记录的艺术家，没有退回原始 SQL 来回答问题，也不把该结果称为完整艺术家目录或成员接口修复。

证据与复跑

目录：evidence/chapter-12。主要入口：查询清单、独立基线、验收摘要、所选成员。原件与副本 SHA256 保持 bdf635be69850bd3be09c9a2dbeef7ddfb80036bd3ef3381383cd03b61e4a61a，六个模型中只有明细 TM/QM 发生预期修改。

模型已加载时，在 lab 目录执行：

python -X utf8 .\checks\collect-chapter-12.py
python -X utf8 .\checks\verify-chapter-12.py

采集脚本每次检查能力、绑定、连接与实时字段，按实际排名结果选择艺术家和专辑。只读核对可单独运行第二条。--resume 仅用于本次采集中断后复用相同 payload 的已保存成功结果，不会重放已通过请求。

需要重新发布修改后的模型时，先运行 chapter12_cli.py 探查，再运行 publish-chapter-12.py；后者只操作已确认的教学 Bundle，校验失败不继续发布。当前无需重新建模或发布。

本样例没有缺失专辑/艺术家关联，未构造异常关联样例；未验证并发数据变更时的跨页一致性、完整艺术家目录、生产权限、Console/FAP 或独立干净会话短提示词。未执行用户暂缓的 Text-to-SQL 多次生成对比。正文待审阅，第十三章未开始。