v17 rc.2 文档巡检(sweep run 5)中记录的越界发现,未认领。
现象
AppSchema.areas[] 是真实的可作者化键 —— 侧边栏与 AppSchemaRenderer 都按作者写的顺序迭代它 —— 但 content/docs/ui/apps.mdx 里一次都没出现过。该页的章节是 Basic Structure / App Properties / Navigation Items(含 9 种 item 类型)/ Branding / Mobile Navigation / Complete Example,全部只讲顶层 navigation 树。
$ git grep -in "area" content/docs/ui/apps.mdx
(无输出)
手写文档全树同样为零(content/docs/**,排除生成的 references/ 与 releases/)。
为什么现在值得补
这一轮窗口里有三处改动落在 areas[] 上,而作者能读到的散文解释在文档侧一处都没有:
于是现在有一条不对称的安全语义,而它只活在 changeset、spec 的 .describe 处方和 liveness 账本 note 里:
项级 requiredPermissions / requiresService 在两棵树上都由服务端强制;visible(CEL)在任何层级仍然只在客户端求值。必须永不到达浏览器的东西写 requiredPermissions,不要写 visible。
一个只读 /docs/ui/apps 的作者,今天无从得知 areas[] 存在,更无从得知这条不对称 —— 而写错的方向正是「以为 visible 能挡住」。
建议
在 content/docs/ui/apps.mdx 增一节 ## Areas:什么时候用 areas 而不是顶层 group、areas[].navigation 与顶层树的关系、上面那条服务端/客户端闸门的不对称(带 17.0.0 的退役说明),以及一个 Complete Example 级别的样例。措辞可以直接以 packages/spec/liveness/app.json 里 areas.navigation 的 note 为蓝本(#4722 已改写正确)。
不是重复,是一对。#4749 修的是 packages/spec/src/ui/app.zod.ts 里 AREA_REQUIRED_PERMISSIONS_RETIRED 处方正文(写错 area 级键时报错正文里的那句「the server does not walk areas」在 #4722 之后已过时),连带 app.test.ts 的 pin。本单修的是文档页缺整节。两者措辞应保持一致,谁先做谁定调;建议做后一个的人读一眼前一个的结论。
参考:#4722(项级闸门服务端强制)、#4651(area 级键退役裁决)、#4667(order 退役)、#4749(spec 处方措辞)。
v17 rc.2 文档巡检(sweep run 5)中记录的越界发现,未认领。
现象
AppSchema.areas[]是真实的可作者化键 —— 侧边栏与AppSchemaRenderer都按作者写的顺序迭代它 —— 但content/docs/ui/apps.mdx里一次都没出现过。该页的章节是 Basic Structure / App Properties / Navigation Items(含 9 种 item 类型)/ Branding / Mobile Navigation / Complete Example,全部只讲顶层navigation树。手写文档全树同样为零(
content/docs/**,排除生成的references/与releases/)。为什么现在值得补
这一轮窗口里有三处改动落在
areas[]上,而作者能读到的散文解释在文档侧一处都没有:areas[].order—— 没有 renderer 排过序。areas[].visible/areas[].requiredPermissions—— 这两个不是惰性键,是fail-open 的闸门:作者写requiredPermissions: ['sales.admin'],拿到干净的 parse 和存下来的值,而该 area 连同其下全部内容照常下发给每一个用户。filterAppForUser也走areas[].navigation,area 内部的项级requiredPermissions/requiresService现在由服务端剥离,响应形状随之收紧(被 gate 掉的项不再出现,被滤空的 area 整个剥离)。于是现在有一条不对称的安全语义,而它只活在 changeset、spec 的
.describe处方和 liveness 账本 note 里:一个只读
/docs/ui/apps的作者,今天无从得知areas[]存在,更无从得知这条不对称 —— 而写错的方向正是「以为visible能挡住」。建议
在
content/docs/ui/apps.mdx增一节## Areas:什么时候用 areas 而不是顶层 group、areas[].navigation与顶层树的关系、上面那条服务端/客户端闸门的不对称(带 17.0.0 的退役说明),以及一个 Complete Example 级别的样例。措辞可以直接以packages/spec/liveness/app.json里areas.navigation的 note 为蓝本(#4722 已改写正确)。与 #4749 的关系
不是重复,是一对。#4749 修的是
packages/spec/src/ui/app.zod.ts里AREA_REQUIRED_PERMISSIONS_RETIRED处方正文(写错 area 级键时报错正文里的那句「the server does not walkareas」在 #4722 之后已过时),连带app.test.ts的 pin。本单修的是文档页缺整节。两者措辞应保持一致,谁先做谁定调;建议做后一个的人读一眼前一个的结论。参考:#4722(项级闸门服务端强制)、#4651(area 级键退役裁决)、#4667(
order退役)、#4749(spec 处方措辞)。