enforce-or-remove: DashboardWidgetSchema 的 5 个 dead 键(#4956 下钻首次给出裁决)

[xuyushun441-sys]

#4956 给 dashboard.widgets 补上了 children 下钻,22 个 widget 级键第一次拿到逐键裁决(证据取自 objectui@91757a7 与本仓库 HEAD,2026-08-03 手工闭合调用图)。其中 16 个 live,6 个 dead。

responsive 已经在 #4876 / PR #4995 退休(tombstone),不在本单范围。剩下 5 个 dead 键是 ADR-0049 enforce-or-remove 的工作项:

键	裁决依据	备选出路
widgets[].colorVariant	没有任何渲染路径读顶层键。读它的全是编写期界面(WidgetConfigPanel、plugin-designer/DashboardEditor、metadata-admin 的 DashboardWidgetInspector、DashboardWithConfig 的配置草稿)。DashboardRenderer 构造 metric / object-metric 组件 schema 时是显式拼装的({ type: 'metric', ...options, label, value }),所以只有 options.colorVariant 能到达 MetricWidget;dataset 路径(DatasetWidget)则完全没有配色能力	enforce(渲染器改读顶层键)或 remove(让作者写进 options)。注意本仓库自己的 packages/platform-objects/src/apps/dashboards/system_overview.dashboard.ts 就写了 7 次 —— 直接删键会改动平台自带看板
widgets[].actionUrl	没有任何渲染器画「每个 widget 的操作按钮」。DashboardRenderer 里 14 处 actionUrl 全部限定在 schema.header.actions[](那是 DashboardHeaderAction,另一个 schema)	remove,或真的实现 widget 级按钮
widgets[].actionType	同上;唯一读它的是下面那条 lint,用来挑选对 actionUrl 套哪条解析规则	同上
widgets[].actionIcon	两个仓库里除 schema 声明和一行 objectui 类型注释外零引用,连 lint 都不看它	同上
widgets[].aria	两仓库均无 widget.aria 消费者(DashboardRenderer / DatasetWidget 里的 aria-* 是渲染器自己的 DOM 属性;objectui 唯一的 .aria 读取在 plugin-view/ObjectView.tsx:989,那是 view 的)。与 17.0.0 里被删掉的看板级 aria 是同一种「假合规」	remove(与看板级 aria 一致)

值得单独指出的二阶成本

packages/lint/src/validate-dashboard-action-refs.ts 对 widgets[].actionUrl 做引用完整性强校验:目标解析不到就 ERROR、构建失败。它的 docblock 写着自己「mirrors the objectui runtime dispatch」、把这个键称作 "the per-widget button" —— 而那个按钮并不存在。也就是说,今天一个作者可能因为一个永远不会渲染的按钮指向不存在的 action 而被卡住构建。删键时这条规则的 widget 分支要一并处理。

现状与不做什么

• liveness: DashboardWidgetSchema 的 ~22 个 widget 级键从未被台账分类,而 dashboard.json 的 _note 声称它们已分类 #4956 只记录裁决,不动任何键;5 个键都已带 authorWarn + authorHint,objectstack build / lint 会在编写期提示(liveness: DashboardWidgetSchema 的 ~22 个 widget 级键从未被台账分类,而 dashboard.json 的 _note 声称它们已分类 #4956 同时把 dashboard 注册进 CLI lint 的 TYPE_COLLECTIONS,否则台账正确但无人收到)。
• 走 remove 路线请照 .claude/skills/spec-property-retirement/SKILL.md:DashboardWidgetSchema 是 .strict(),两条路线(retiredKey tombstone vs 严格删除)对台账行的处置相反。

台账证据:packages/spec/liveness/dashboard.json → props.widgets.children。

---

Generated by Claude Code