`ObjectMapSchema`(types)声明的键几乎与 ObjectMap 实际读的键无交集:`map` 块整体未建模,组件 props 类型写的是 `ObjectGridSchema`,每处 map 读取都走 `as any`

[yinlianghui]

发现于 #5002 的实施(plugin-map README 重写)。Filed unassigned, not claiming.

现象

object-map 这一个组件有三份互不一致的"形状":

1. 声明面 —— packages/types/src/objectql.ts:1811-1826 与 packages/types/src/zod/objectql.zod.ts:536-542 的 ObjectMapSchema,一共四个键:

type: 'object-map', objectName(必填), locationField?, titleField?, mapStyle?

2. 实际读取面 —— packages/plugin-map/src/ObjectMap.tsx 读的是:objectName / staticData / data(getDataConfig,:103-123)、filter / sort(:467-468)、map 块的 8 个键(MapConfigSchema,:41-50:latitudeField、longitudeField、locationField、titleField、descriptionField、zoom、center、style)、顶层同名的 5 个字段键 + zoom / center(:202-213)、enableClustering(:570)、navigation(:554)、style / mapStyle(:199)。

3. 组件 props 类型 —— ObjectMapProps.schema 声明成 ObjectGridSchema(ObjectMap.tsx:61),不是 ObjectMapSchema。于是全部 map 专有读取都得绕过类型:(schema as any).map、(schema as any).enableClustering、(schema as any).navigation、(schema as any).style、(schema as any).mapStyle。

结果:map: { … } 这个注册时声明的输入(src/index.tsx:68 / :78,{ name: 'map', type: 'object' })在类型面上完全不存在。一个 TS 作者按 ObjectMapSchema 写地图,写不出 map 块;按文档(content/docs/plugins/plugin-map.mdx)写 map 块,则拿不到任何类型检查 —— 拼错 latitudeField 为 latitudeFieId 没有任何一层会说话,渲染出的是一张"记录坐标无效"的空地图。

这正是 AI 生成的 metadata 最容易藏错的形状:声明面松、消费面 as any、错了不响。

与 #5002 的关系

#5002 只修 README(已按现码重写,教 map 块这一个拼法)。本单是它下面那一层:README 现在教的形状,类型面并不承认。两者不相交,但 #5002 的 PR 把这个落差看得很清楚,所以在这里记账。

可能的修法(供分诊定向,未实施)

1. ObjectMapSchema 补齐:staticData / data / filter / sort / map: MapConfigSchema / enableClustering / navigation,并把 MapConfigSchema 从 plugin-map 抬到 types(它今天是包内私有的 zod,ObjectMap.tsx:41),让声明面与运行时校验共用同一个 schema;ObjectMapProps.schema 改成 ObjectMapSchema,删掉 as any。
2. 只抬 MapConfigSchema 到 types 并让 ObjectMapSchema.map 引用它,先解决 map 块无类型这一半。
3. 顺带需要裁一刀的:顶层字段拼法(:202-213)与 map 块两条路并存,顶层优先且静默胜出 —— 两个拼法同时写,map 块整块被忽略。这条 gate 里有钉子(ObjectMap.filterConfig.test.tsx:164),但没有任何文档教它,ObjectView.tsx:770-776 又正是把 view options 摊平成顶层拼法的生产者。是要把顶层收为内部形态,还是把它也声明出来,是本单真正的裁决点。

分级

交 PM 分诊。若认为 3 是独立裁决,可拆子单。

[os-zhuang]

Triage: needs-user-decision, type Bug. This is the map component's contract-shape fork: three authorities (declared ObjectMapSchema = 4 keys; runtime reads ~15 keys via as any; props typed as ObjectGridSchema), plus the card's item 3 — top-level spellings vs map block, with top-level silently winning. Choosing the canonical shape expands/reshapes the declared public face ⇒ human floor, not auto-adjudicable.

Four-facet block:

1. Platform long-term coherence: today's shape is three truths for one component; any ruling (model the map block in types, or canonicalize top-level) shrinks special cases. Doing nothing grows them — every new map key will be born untyped.
2. Measured business pull: real — docs (post-plugin-map README teaches an API the package does not implement — every snippet in it renders an empty map #5002) now teach the map block, showcase uses maps today, and a typo'd latitudeFieId currently renders a silent empty map. This is not speculative surface; it is the typed face for behavior that already ships.
3. AI-agent error-resistance: strongest axis. Declared-loose + consumed-via-as any + silent-wrong is exactly the shape where AI-authored metadata hides errors. A closed MapConfigSchema lifted to types with the props type corrected makes the wrong spelling unrepresentable at authoring time.
4. Startup scope discipline: option 2 (lift MapConfigSchema to types, wire ObjectMapSchema.map to it, fix the props type) is alignment of declaration with existing behavior, not new capability. The item-3 precedence question should be ruled narrow: pick one canonical authoring shape, keep the other as internal/deprecated — do not declare both.

Recommendation: option 2 as the core (declare what is consumed; smallest true fix), with item 3 ruled "map block is canonical; top-level spellings become internal (ObjectView flattening) and undocumented, refused or warned on direct authoring". Option 1's full key-by-key modeling can follow as mechanical work once the shape is ruled. Related cards: #5017 (the style collision leg — dispatchable now, its pin survives either ruling), #5003/#5020 (findings, same component).

This comment is from the triage seat Routine — session session_01CNcg2rhY7jLn5g5TEbhK4Z.

---

Generated by Claude Code

[yinlianghui]

标签半状态修复(objectui 分片 PM,session session_01GTRjn8xBqp75dk7kFupVRt):分诊席 2026-08-17 15:47Z 的评论已裁「三份形状真相 + 顶层/map 块静默优先级 = 公开契约收束,human floor」并宣布 needs-user-decision,但标签半边未落、卡仍挂 pm:queue —— 批次 22 选席时差点按可派态误读。已按分诊裁定补齐:pm:queue → needs-user-decision。裁决点与推荐方案见上一条分诊评论(推荐:修法 2 为核,item 3 收窄为「map 块为规范拼法,顶层拼法降为内部形态」)。待维护者裁定后再入队。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — maintainer, 2026-08-17, batch acceptance of the PM decision-inbox recommendations, verbatim: 「同意」. Four-dimension analysis delivered in-session; provenance: PM session session_01NYgmGheCzM6NrHZN436Cxf.

Ruled: full alignment (direction 1), with point 3 decided as follows:

• ObjectMapSchema gains the keys the renderer actually reads: staticData / data / filter / sort / map: MapConfigSchema / enableClustering / navigation; MapConfigSchema is lifted from plugin-map into types so the declared face and the runtime validation share one schema; ObjectMapProps.schema becomes ObjectMapSchema and every as any map read goes.
• The map block is the author face. The top-level flat spelling is an internal form (the ObjectView flatten product) — it stays out of ObjectMapSchema and out of the docs. When both are present, the map block wins, with a dev-mode warning naming the shadowed top-level keys — what the author wrote outranks what internal flattening produced. The existing pin at ObjectMap.filterConfig.test.tsx:164 records the OLD precedence; it flips with this ruling (the implementer cites this comment in the pin's history note). If a constraint surfaces that makes the flip unsafe for ObjectView's producer path, stop and report — do not silently keep the old precedence.

Label needs-user-decision → pm:queue in the same stroke.

---

Generated by Claude Code