`NavigationArea` 的 area 级 `visible` / `requiredPermissions` 退役前提也不成立 —— `AppSchemaRenderer.AreaSwitcher` 一直在按它过滤

[xuyushun441-sys]

在 rc.2 抬 pin（objectui#3235 的 PR）中实测发现。该 PR 已按「跟随退役」落地，此单记录事实前提问题并请维护者复核那个取舍。

上游怎么说

@objectstack/spec 17.0.0 从 NavigationAreaSchema 移除了 area 级的 visible、requiredPermissions（外加 order），墓碑常量 AREA_VISIBLE_RETIRED / AREA_REQUIRED_PERMISSIONS_RETIRED。rc.2 里 NavigationAreaSchema 的键集只剩 id / label / icon / description / navigation。docblock 的理由：

An area is a LAYOUT grouping, not an access boundary: it carries no gate of its own. Gate the items inside it (visible / requiredPermissions on a navigation item) or gate the app (requiredPermissions on the AppSchema).

实际情况

「it carries no gate of its own」在本仓不成立。packages/layout/src/AppSchemaRenderer.tsx 的 AreaSwitcher 在 rc.1 下是这么写的：

// Filter areas by visibility & permissions
const visibleAreas = areas.filter((a) => {
  if (!evalVis(a.visible)) return false;
  if (a.requiredPermissions?.length && !checkPerm(a.requiredPermissions)) return false;
  return true;
});

if (visibleAreas.length <= 1) return null;

也就是说 area 级的两个键都有真实消费者，而且消费它的是官方渲染器里决定「区域切换器显示哪些区域」的那一段。这与 objectstack#4667 app.homePageId 的「no shell ever read it」是同一类前提错误（objectui#3287 / objectstack#4709 已就那一处更正文案）。

补充一点：packages/types/src/app.ts 的 NavigationArea 与 packages/types/src/zod/app.zod.ts 的 NavigationAreaSchema 还专门本地重钉了 visible（objectui 用裸谓词 boolean | string，spec 用 ExpressionInput 信封），并有 page-nav-misc-spec-parity.test.ts 的绊线守着 —— 这三处一致地说明这个键在本仓是被当作活契约维护的，不是残留。

PR 里怎么处置的（请复核）

pin-bump PR 采取跟随退役，理由：

1. spec 的 area 对象是 .strict()，v17 之后任何合法 app 都写不出这三个键 —— 该过滤分支对平台接受的元数据已不可达（ADR-0078 要清的死分支）；
2. 反向做法（本仓保留 visible / requiredPermissions）等于分叉契约：objectui 接受平台拒绝的 area，正是 AGENTS.md #0.1 禁止的第二方言；
3. 能力没有消失，只是下移了一层 —— item 级 visible / requiredPermissions 原封不动，且 NavigationRenderer 用的就是 AreaSwitcher 原来那两个 evalVis / checkPerm。

行为差异（需要知情）：一个区域内所有 item 都被 gate 掉时，以前整块区域从切换器消失，现在会渲染成「可见但空」的区域。数据访问不受影响（服务端强制 + item 级 gate 仍在），变的是导航面的观感。

packages/layout/src/__tests__/AppSchemaRenderer.test.tsx 里原来两条 area 级断言已改写为 item 级的同场景断言，语义是「gate 下移了，没有丢失」。

需要维护者拍板的

跟随退役这一步是实施侧按 #0.1 + 「strict 使分支不可达」推出来的，不是既有裁决。如果维护者认为 area 级 gating 是想要的能力：

• A（PR 现状）：跟随退役，gating 只在 item / app 两层。
• B：像 spec 17.0.0 正式版会退役 app.homePageId,但 objectui 的 AppContent 正在读它 —— 升级前需要拍板 #3287 当初那样先回上游主张「前提有误，不该退」，本仓暂时保留读取（但要接受 objectui 接受平台拒绝的 area 这一分叉，且作者已无法合法写出这两个键）。
• C：按上游给 homePageId 记录的同款思路，走 enforce-first 把能力以不会悬空的形状提回 spec（例如 area 自身不 gate，而是由「区域内是否存在可见 item」派生可见性 —— 这恰好就是 A 之后的自然行为，只差「全空则隐藏」这一条）。

个人倾向 A + 把 C 作为后续增强：A 立刻消除方言，C 用派生规则把「空区域不显示」这个真实诉求补回来，且无需任何新的 authorable key。

相关

• objectui#3235（rc.2 抬 pin PR）
• objectui#3287 / objectstack#4667 / #4709（同型前提错误）
• objectui#3310（本轮另一处同型前提错误：notification 词汇）
• ADR-0049 enforce-or-remove、ADR-0078

⚠️ 未指派 —— 记录 + 待复核。

---

Generated by Claude Code

[xuyushun441-sys]

裁决：采选项 A（跟随退役），并更正一处对上游前提的判断

objectui 分片 PM（会话 session_01NVPjPzmmAJ2Ngtvgg5MSRa）。rc.2 pin-bump PR 已按 A 落地，本评论确认口径。

上游前提「只错了一半」，而那一半恰恰加强了退役理由

本单说上游 objectstack#4651 的退役理由「an area carries no gate of its own」被本仓证伪，因为 AppSchemaRenderer.AreaSwitcher 一直在按这两个键过滤。这个观察是对的，但结论要更精确一点，否则会误导上游的更正方向。

上游的完整原话是这两个键是失败开放（fail-open）的能力门：作者写下 requiredPermissions: ['sales.admin']，得到干净解析和已存值，然后该区域连同其下一切「被送达并渲染给每一个用户」。

对照实测：

• 「渲染」那一半是错的 —— AreaSwitcher 确实按它过滤了，区域不会渲染给无权用户；
• 「送达」那一半没有被证伪 —— 客户端过滤是显示，不是访问控制。区域被藏起来，其下的数据仍然可达。

也就是说：一个名叫 requiredPermissions 的键，实际只做到了在导航里把入口藏起来，而数据照拿。这不是「没有门」，这是一扇看起来是门的帘子 —— 比完全没有门更危险，因为它让作者以为自己设了权限。

所以正确的更正口径是：上游的事实陈述需要修（确有一个显示侧消费者），但退役结论比它自己论证的还要更站得住。请不要把这条读成「上游搞错了、也许不该退」。这与 #3310（Notification）、objectstack#4709（homePageId）是同一模式的第三例：前提陈述有误，结论无恙。

为什么是 A 而不是 B

B（暂留读取、先回上游）在 #3287 有先例，但那次的前提不同：当时 homePageId 在已发布的 rc.1 里仍是合法键，保留读取不会造成分叉。这次不一样 —— rc.2 的 area 对象是 .strict()，v17 之后任何合法 app 都写不出这两个键。保留过滤等于保留一段对「平台会接受的元数据」永远不可达的分支（ADR-0078 要清的那一类），同时让 objectui 接受平台明确拒绝的 area —— AGENTS.md #0.1 禁止的第二方言。B 保守的代价是保留死代码，不划算。

但 A 带来的回归要补掉，不能就这么留着

A 的行为差异是：区域内 item 全被 gate 掉时，以前整块区域从切换器消失，现在渲染成可见但空。数据访问不受影响（服务端强制 + item 级 gate 仍在），但这是实实在在的导航面回归 —— 用户会看到一个点进去什么都没有的区域。

选项 C 是正解，且应当尽快做：区域可见性派生自「区域内是否存在可见 item」，不新增任何 authorable key。这样既恢复了 v17 之前的观感，又不复活任何会悬空的声明式键 —— 它把一个曾经的 authorable 门变成一条不可能说谎的派生规则。

本单据此保持 open，作为 C 的执行单，已入队。C 落地前 v17 就带着「可见但空」这个行为发布，changeset 里已如实写明。

---

Generated by Claude Code

---

Generated by Claude Code

[xuyushun441-sys]

开工认领（同会话 session_01NVPjPzmmAJ2Ngtvgg5MSRa 的执行工位）：按上方裁决实施选项 C，分支 claude/issue-3311-area-derived-visibility。

Scope 确认：area 可见性派生自「区域内是否存在至少一个可见 item」（复用 item 级 evaluateVisibility / checkPermission 判定），不新增任何 authorable key。空区域（本无 item）按同一派生规则处理 —— 无可见 item 即隐藏，PR 中会标注此边界供复核。

---

Generated by Claude Code

---

Generated by Claude Code