AppNavInspector 编辑 off-spec 的 nav path/kind(运行期不生效)——应改为 type + 分类型目标选择器

[os-zhuang]

背景

来源:UX eval #5(picker-first / 消除手敲标识符)。审计原本把 AppNavInspector 的 nav path 列为「低复杂度:把自由文本 InspectorTextField 换成按 kind 联动的 combobox」。但深入排查后发现 path/kind 本身是 off-spec 的、运行期不生效 —— 仅美化这个字段会产出一个「运行期忽略、且被兄弟编辑器主动删除」的键,违反本仓 contract-first 原则。据此开 issue 记录正确修法。

注:同一批审计里的另一项 lookup dependsOn 早已在 #1937(2026-06-24)修好(选中字段渲染为可删 chip + InspectorComboField(allowCustom={false}) over host fields),无需再做。本 issue 只针对 nav path。

现象 / 根因:inspector 编辑的字段不在 spec 里,运行期也不读

AppNavInspector 编辑 kind + path,但 App 导航的 spec 契约 是一个按 type 的判别联合,各类型有各自的 typed 目标字段,根本没有 path、没有 kind:

• spec:packages/spec/src/ui/app.zod.ts(framework)
  • ObjectNavItem → type:'object' + objectName(+ viewName/recordId)
  • DashboardNavItem → type:'dashboard' + dashboardName
  • PageNavItem → type:'page' + pageName(+ params)
  • ReportNavItem → type:'report' + reportName
  • UrlNavItem → type:'url' + url(+ target)
  • ComponentNavItem → type:'component' + componentRef
  • GroupNavItem → type:'group' + children
  • BaseNavItem 要求 snake_case id
• 运行期只认 typed 字段:packages/layout/src/NavigationRenderer.tsx:382 的 resolveHref 全程 switch(item.type) 读 objectName/pageName/dashboardName/reportName/url/componentRef;packages/layout/src/AppSchemaRenderer.tsx:218-221 同理。从不读 path/kind。
• 没有任何 normalizer 把 path→pageName 或 kind→type(objectui 与 framework 两仓均已 grep 确认)。

因此:在 AppNavInspector 里给 object/page/dashboard/report 类型写 path,导航不会生效(resolveHref 拿不到 typed 字段 → # 或空)。这是 declared ≠ enforced 的典型(Prime Directive #10)。

相关位置:

• off-spec 编辑:packages/app-shell/src/views/metadata-admin/inspectors/AppNavInspector.tsx:179-181(path = InspectorTextField;kind = InspectorSelectField,KINDS 在 line 44)
• canvas 新建即写 off-spec:packages/app-shell/src/views/metadata-admin/previews/AppNavCanvas.tsx:180({ label, path: '' },无 type/id)
• 注册可达:inspectors/index.ts:32 registerMetadataInspector('app', AppNavInspector)(泛用 metadata-admin 里编辑 app 时的 inspector)

已有的「正确」先例(但只覆盖 object)

StudioDesignSurface.tsx 的 StudioNavItemInspector(line 691)已经按 spec 写:

• 绑定对象 → patch({ id, type:'object', objectName, object:undefined, path:undefined, label })(line 757-764)
• 解绑 → patch({ type:undefined, objectName:undefined, object:undefined })(line 749)
• 注释(line 752-756)明确:「nav 是 type 判别联合、BaseNavItem 需要 snake_case id;object/path 被清掉以免残留无效键」

即:现有代码已把 path 当作会导致 navigation.0: Invalid input 的「无效残留键」主动删除。若再把 path 做成 picker 去写它,等于跟这个既有正确实现对着干。但 StudioNavItemInspector 只是一个对象 <select>,不支持 page/dashboard/report/url/component。

为什么「仅把 path 变成 picker」是错的

• 违反 spec-strict / contract-first(objectui AGENTS.md #0、#0.1;framework Prime Directive [WIP] Enhance UI components for forms and layouts #12):path/kind 不是 spec 属性。
• 违反 Prime Directive [WIP] Enhance every detail of the designer #10:会 demo 一个运行期不兑现的能力(写了 path,点了不跳转)。
• 与既有 StudioNavItemInspector 冲突:它把 path 当无效键删。

建议修复(契约正确 · 泛化 StudioNavItemInspector)

把 AppNavInspector 的目标编辑从 kind+path 改为 type + 分类型 typed-target 选择器:

1. kind 选择器 → type 选择器,选项取 spec 类型:object / page / dashboard / report / url / component / group(action 可后续)。
2. path 文本 → kind-aware typed-target 选择器(可编辑 combobox,降级为自由文本,mirror FlowReferenceField/ReferenceCombobox + InspectorComboField):
   • object → 写 objectName,选项 client.list('object')
   • page → 写 pageName,选项 client.list('page')
   • dashboard → 写 dashboardName,选项 client.list('dashboard')
   • report → 写 reportName,选项 client.list('report')
   • url → 写 url(自由文本,外链)
   • component → 写 componentRef(已知组件列表或自由文本)
   • group → 无目标(只有 children)
3. 切换 type 时:set type、清除其它 typed 字段 + legacy path/kind、保证 snake_case id(参照 StudioNavItemInspector)。
4. 读回向后兼容:显示时兼容旧的 kind/path 与 typed 字段;任意编辑都归一化为 spec 形状(edit 即迁移)。
5. 抽出纯解析逻辑 type → { targetKey, metaType }(哪个 typed 字段 + 拉哪个 metadata list),加单测。
6. 收敛:让 StudioNavItemInspector 复用这套泛化后的 picker(或反过来),避免两套 nav 编辑器长期分叉。

验收标准

• 在 AppNavInspector 里编辑 object/page/dashboard/report/url 项,产出 spec 合法的判别联合项(过 NavigationItemSchema/AppSchema 校验),不再出现 path/kind 键,且带合法 id。
• 运行期 resolveHref 能据此产出正确 href(点击真正跳转)。
• type→target 解析器有单测。
• 补齐 i18n key(en + zh-CN)。
• AppNavCanvas.addItem 新建项不再只写 {label, path:''}(至少带 type/id,或走同一归一化)。

备注

• 影响面:泛用 metadata-admin 里对 app 的导航编辑;Studio Interfaces pillar 已用 StudioNavItemInspector(object 正确),但其余类型仍会落到本 inspector。
• 关联:UX eval Implement component reordering via drag-and-drop in designer canvas #5 picker-first;flow-node connector-action picker(feat(studio): pick a connector action from the chosen connector (no hand-typed action ids) #2244)、lookup dependsOn(fix(studio): localize lookup picker config + keep published org objects editable #1937)为同族已完成项。

[os-zhuang]

设计补充(讨论结论):原方案的「object → 写 objectName」不完整——type:'object' 的目标编辑是四种互斥落点,须与 resolveHref 的优先级 recordId → filters → viewName 严格对应(filters//data 表面来自 #2251 / ADR-0055,spec 已于 framework#2626 合入):

落点模式	写入字段	运行期路由	UI 控件
默认视图(工作台)	仅 objectName	/:objectName	无额外控件
具名视图	+ viewName	/:objectName/view/:viewId	视图 picker,选项按对象过滤(objectDef.listViews 键 + client.list('view') 中 <object>. 前缀项)
记录深链	+ recordId(+ recordMode)	/:objectName/record/:id	文本框 + 模板变量提示,view/edit 开关
参数化切面	+ filters	/:objectName/data?filter[...]	key-value 行编辑器:字段 picker(过字段级权限)+ 值文本(支持 {current_user_id})

设计决策:

1. 模式不落库——从字段存在性按优先级推导,不新增 spec 字段;切换模式显式清掉其它三组字段(延续 StudioNavItemInspector 的清键纪律,防残留 recordId 劫持优先级)。
2. 实时 URL 预览——inspector 底部用导出的 resolveHref 渲染当前配置的真实落点,把「declared ≠ enforced」变成编辑期可见。
3. 模式辅助文案引用 app-composition 指南(least-power:一次性切面用 filters,值得沉淀才建视图)。

纯解析器相应扩展为 type → { modes },object 返回四模式描述;单测覆盖模式推导与清键。验收标准在原文基础上追加:四模式互斥切换无残留键、URL 预览与 resolveHref 一致、filters 项经保存后过 NavigationItemSchema 校验。

---

Generated by Claude Code