`drillDown` 是 objectui 读的活能力,却不是 spec 声明的任何键 —— #3752 的迁移处方曾指向它

[xuyushun441-sys]

从 #4001 批 15 中分离出来,未指派。批 15 已就地修正了错误的处方文本(否则会把它提升成一条带平台权威的报错),但底下的缺口是独立的一件事。

发现

packages/spec/src/ui/chart.zod.ts 里 #3752 写下的迁移说明是:

clickAction — … Migration: drillDown, or handle it in React.

批 15 要把这句话提升进 ChartInteractionSchema 的 strict 拒绝信息时,先按惯例核了处方指向的键是否存在。不存在:

• grep -rn "drillDown" packages/spec/src/ui/*.zod.ts → 只有这段注释本身;
• DashboardWidgetSchema 没有任何 drill 相关键;
• ReportSchema 有的是 drilldown(全小写,ADR-0021 D2,布尔,默认 true);
• objectui 侧则是 packages/plugin-charts/src/ObjectChart.tsx:602 的 const drillDown = (schema as any).drillDown; —— 一个未类型化的读取,后面真的驱动了 drill drawer、computeDrillFilter、drillDown.target / .maxRows / .columns。

即:渲染器实现了一套 drill 配置,协议里没有它的声明,而 spec 的注释在教作者写它。

为什么这是个问题,而不只是注释错字

如果批 15 照抄那句话,一个把 clickAction 改对的作者会被告知写 drillDown,然后被同一个刚加上的闸门再拒一次 —— 账本记过两次的 finding 7(「本战役自己的修复,给人指向了它本要消灭的失效模式」)的第三次。批 15 因此把处方改成只点名确实存在的东西(onSegmentClick / ReportSchema.drilldown / dashboard widget 的 options 袋),并留了一条测试钉死「永不出现 drillDown」。

但那只是让错误信息不再说谎。真实缺口仍在:

1. drillDown 走的是 options(DashboardWidgetOptionsSchema,故意 passthrough)还是别处?今天没有声明,所以两种写法都「能跑」,取决于渲染器拿到的扁平化 schema 长什么样 —— 这是 Prime Directive chore: version packages #10 的 declared ≠ delivered,方向相反的一种:delivered 但 never declared。
2. ReportSchema.drilldown 与 objectui 的 drillDown 拼写不同、语义不同(前者是布尔开关,后者是 { target, maxRows, columns, mode } 配置对象),名字却几乎一样。这正是本战役反复付学费的那类近似键。

建议

按 contract-first 择一:

• 声明它 —— 给 chart drill 配置一个 Zod 形状({ enabled, mode, target, maxRows, columns },从 ObjectChart.tsx 的实际读取点反推),挂在 widget options 或 chart config 上,再让渲染器读声明后的键;顺便决定与 ReportSchema.drilldown 的关系(是否统一拼写)。
• 或明确它是渲染器私有 —— 那就在 DashboardWidgetOptionsSchema 的文档里点名 drillDown 属于「渲染器自有、协议不建模」的那一类(该 schema 已有这段话,只是没列它),并保持 (schema as any) 的读取方式,但不要在 spec 注释里把它当作可授权键推荐。

参考

• ChartConfig 剩余的 declared ≠ delivered 属性：stepSize / clickAction / zoom / description / height（#3729 收尾） #3752(移除 zoom / clickAction 的那次改动,处方文本的来源)
• 未知键静默剥离仍是全仓默认:把 #3405 的 strict 收紧从一个 schema 推广到整个可授权面(ADR-0078 完整性闸门) #4001 批 15(修正处方 + 测试钉;账本 ui/chart.zod.ts 行记录了这条更正)
• ADR-0021 D2(ReportSchema.drilldown)
• packages/spec/src/ui/dashboard.zod.ts DashboardWidgetOptionsSchema(声明的渲染器逃生口)

[xuyushun441-sys]

维护者裁决(2026-08-04):A,且改动不大就整件进 v17(含拼写关系收口,不再拆两步)

执行定调:

1. 声明 drill 形状:按 ObjectChart.tsx 实际读取点反推({ enabled?, mode?, target, maxRows?, columns? } 以实测为准),strict(战役标准)。落点与拼写的最小改动路径:直接声明渲染器已在读的 drillDown(objectui 零改动),挂 chart config(可发现性优于 options 袋)。
2. 拼写关系收口(v17 内完成):ReportSchema.drilldown(布尔开关)与 chart drillDown(配置对象)是两个概念,强行统一命名反而合并语义——默认走双向点名消歧:两个 schema 的 strict 门各带对方拼写的 guidance(在 report 上写 drillDown → 点名「这是 chart 的配置对象,报表开关是 drilldown」,反向同理)。若 dev 实测重命名的爆炸半径确实微小且语义可清晰分离,可提议重命名方案,量大即回落双向消歧,不阻塞。
3. spec 注释里 ChartConfig 剩余的 declared ≠ delivered 属性：stepSize / clickAction / zoom / description / height（#3729 收尾） #3752 处方的历史错误已由批 15 修正;本单落地后把「渲染器读声明键」的 objectui 跟改立为跨分片 follow-up 单(unassigned)。
4. changeset:additive 为主(minor);若含重命名则 major。窗口开工先核 .changeset/pre.json。

needs-user-decision 摘除,target:v18 → target:v17,入队(T2 序,量小顺手)。

---

Generated by Claude Code