第十六章实操记录：模型维护与回归（原第十五章）

编排说明：维护章现顺延第十六章。本记录及 chapter-15 脚本、查询和证据目录保留原编号，对应字典与州字段补充前的维护阶段；不能用其中的全文件摘要断言验收后续已授权的模型变更。当前补充回归另见 basic-supplements-notes.md。

2026-10-21。当前 Codex 会话真实调用项目内 CLI，维护已登记的账单 QM，并运行修改前、修改后及复跑三阶段题库。未另开干净 Codex 会话验证短提示词或回答行为。

环境与最终变更

http://127.0.0.1:18067，Namespace chinook，命名数据源 chinook-sqlite，公开 Chinook v1.4.5 SQLite。实际运行进程核对 Launcher 0.1.30 JAR，SHA256 c11af04b990b8a351c0c1330031ca854fe3237ee58c3167724e9d3e5a2ed4374；CLI 0.1.25，Python 3.11.5，Java 17，本地 none-dev-test-only。未重启、升级或更换数据源。

最终仅修改 lab/models/query/ChinookInvoiceQueryModel.qm 的 averageAmount：

• caption 从“平均账单金额”改为“平均每张账单金额”。
• description 明确按账单数计算，区别于按购买客户数的人均消费；含糊术语先确认分母，无账单时为空。
• name、formula、type 与其他字段保持原样。formula 仍为 sum(invoiceAmount) / nullif(count(invoiceId), 0)。

其他九个模型文件及 SQLite 摘要未变，主目录仍为十个文件。快照：修改前、修改后、差异。只改说明，不将期望数值变化作为目标。

实际操作

1. 保存主目录与数据摘要、原 QM、模型说明和 Bundle 登记。核对 capabilities、Namespace 绑定和所用三个 QM 的字段。
2. 建立小题库，修改前运行七项正常查询，一项拼写错误在 validate 阶段拒绝；另两项回答审阅题不执行。
3. 在未登记候选目录模拟 invoice.invoiceDateTypo，models validate 返回 MODEL_VALIDATE_FAILED、phase=models.validate、catalogState=ACTIVE。原 QM 的字段说明未变；改回 invoiceDate 后，候选校验通过，校验前后 catalog generation 相同。候选从未登记或刷新。
4. 修改正式 QM，校验现有十个文件，显式 models refresh --model ChinookInvoiceQueryModel，再 describe / describe --format markdown，确认新说明。
5. 运行相同题库，保存每题 validate / execute；拒绝请求不 execute。用只读 SQLite 原行和 Decimal 独立核对，比较修改前后 items。
6. 使用交付的回归入口再执行一次，验证复跑入口与一致性；没有改变题目、日期或预期以求通过。

临时尝试过在 billingCountry 的 QM ref 上覆盖 description，但该说明未出现在 describe 中，仍沿用 TM 描述；这项额外修改已撤回，最终不把它记为生效的维护。完整中间响应保留，不推断所有字段说明都能在同一层覆盖；本章只演示已验证的计算字段标题和说明。未提交新的 GitHub issue。

真实观察，不预填生命周期结论

• 登记项 watch=false，但保存后第一次 describe 已显示新标题。不能把“只有显式 refresh 后才可能生效”写成所有入口的行为，也不根据这一现象推断自动更新的内部原因。
• 单独 models validate 的 before/afterCatalogGeneration 相同；本次候选校验没有发布目录变化。
• 指定一个 QM refresh，实际返回 refreshedCount=6。按实际返回核对元数据与代表查询，不将它称为只刷新一个 QM 的验收。这个现象本轮只记录，没有判定为引擎缺陷。
• 新旧公开字段名集合相同，averageAmount 标题和说明已变化；Markdown 来自实时模型说明，不手写修改。

原始记录：保存后首次 describe、最终校验、最终刷新、最终实时 Markdown。候选错误下层 message 在本机输出中存在文字编码异常，保留原始响应，以 code/phase/target 与错误字段引用定位，正文未编造更完善的诊断文案。

回归范围和结果

七项正常查询每阶段均通过：总额/账单数/购买客户数；固定平均值；USA 账单 21 行；20 国分组均额；12 个月汇总；第十四章聚合 JOIN 汇总；无账单期间的空均额。三个阶段各自做原行独立核对，items 前后完全相同。

2012 年金额 477.53，账单数 83，购买客户数 47；平均账单金额约 5.75，按购买客户数平均约 10.16。后一个数由相同基线相除说明，不是修改了原固定指标。

错误字段 averageAmout 三阶段均 FIELD_NOT_FOUND，提示 averageAmount，均未执行。模型候选错误也按预期拒绝并修正。

题库共十题：七项执行、一项预期查询拒绝、两项待回答审阅。两项手动审阅涉及含糊的“客单价”和缺少成本的“利润”，未向独立 AI 会话发送，不计为 AI 澄清/拒答已通过。没有重做第十三章身份服务或权限全量测试；本次权限配置未修改。

复跑

只读运行题库，不修改模型、不刷新或登记：

python -u .\lab\checks\run-chapter-15-regression.py

仅核对已保存的前后响应、源码差异和原行基线：

python .\lab\checks\verify-chapter-15.py

本章记录的是一次已明确范围的修改。后续真改口径或数据时，先确认新预期、保存新快照，再调整回归依据。前章证明“那一轮没有修改原模型”的哈希记录属于当时证据，不应被解释为永远禁止维护；持续回归重点是明确允许改动和验证业务/接口兼容。

题库、验收摘要、真实命令与退出码、环境。未做生成正确率基准、性能测试、ETL、Console/FAP 或正式发布。