docs(skills): auth-permissions 的 hidden 示例改用 data. 根,并写清表达式作用域

[yinlianghui]

Fixes#4798

问题

skills/objectui/guides/auth-permissions.md 教的 "hidden": "${!canDeleteContacts}" 用的是裸根。SchemaRenderer 的求值作用域是

packages/react/src/SchemaRenderer.tsx:336-341

constevaluator=newExpressionEvaluator({
...predicateScope,current_user: (predicateScopeasany)?.user,data: dataSource,page: pageVariables,});

predicateScope 来自 usePredicateScope()(user / app / features,由 app-shell 的 ExpressionProvider 喂),不含 dataSource。dataSource 的键只能经 data. 根访问 —— 裸名解析成 undefined,!undefined 恒为 true,hidden 恒真,按钮对所有人隐藏,包括有权限的人,且与权限位取值无关,所以"改一下权限再试"这条最自然的排查路径不给任何信号。

改动

1. 该示例改 ${!data.canDeleteContacts}。
2. 紧邻处新增「Expression scope: which roots resolve」一节:作用域根对照表 + 明写「dataSource 的键只能经 data. 根访问,不会另行摊平成裸名」,并说清失效为何是静默的、同样适用于 visible / disabled。表内 ambient 根按实测的 ExpressionProvider 契约写(packages/app-shell/src/providers/ExpressionProvider.tsx:59 的 { current_user, user, ctx: {user}, os: {user}, app, data, features }),并注明无 host scope 时只剩 data / page。

未动 #4786 已改的信封写法,未动其它段落的教学内容。

全文件表达式核对表

同文件 ${…} 共三处,逐个对照作用域判定:

行	表达式	归属	判定	处置
157	'${user.id}'(rowPermissions 的 filter 内)	不是 SchemaRenderer 表达式	不在本作用域管辖内 —— getRowFilter() 把 filter 原样返回(PermissionProvider.tsx:108、evaluator.ts:78),@object-ui/permissions 全程不插值	未动;形状问题另见 #4812
231	${data.userRole !== 'admin'}	SchemaRenderer	✅ 对,data. 根	未动(实测复核见下)
255	${!canDeleteContacts}	SchemaRenderer	❌ 裸根	本 PR 修

全文件只有这一处同类缺陷,无其它裸根需一并修。

probe 读数(真实 SchemaRenderer)

probe 从文档正文里抽 ```json 围栏、把带 hidden 的节点喂给真实 `SchemaRenderer` 渲染 —— 钉的是提交进仓的文本本身,而不是我另手敲的一份副本。probe 为临时文件,已删,未入仓。

修前(基线 2095450,复现 issue 的四态读数,逐字一致):

@@PROBE bare/flag-true text="" ← 有权限,按钮却没了
@@PROBE bare/flag-false text=""
@@PROBE data/flag-true text="Delete"
@@PROBE data/flag-false text=""

修后(文档抽取):

--- doc expression: ${data.userRole !== 'admin'}
@@PROBE userRole=admin text="Delete Selected"
@@PROBE userRole=viewer text=""
--- doc expression: ${!data.canDeleteContacts}
@@PROBE flag-true text="Delete" ← 有权限,按钮出来了
@@PROBE flag-false text=""

userRole 两行一并复测,确认卡内「那几处是对的」的结论在今天的 main 上仍成立。

反向验证

先声明预期方向再跑:把裸根改回去,flag-true 应从 "Delete" 掉回 ""(常规红)。实测:

--- doc expression: ${!canDeleteContacts}
@@PROBE flag-true text="" ← 掉回空,与预期一致
@@PROBE flag-false text=""

userRole 两行不受影响(本就正确)。随后用 git checkout 本分支名 -- 该文件路径 还原(改动已先 commit,有还原点)。

门禁(实测输出)

门	结果
node scripts/check-doc-links.mjs	Links are valid across 13 scan roots.
node scripts/check-skills-paths.mjs	OK (88/89 stated path(s) resolve across 18 guide file(s); 1 baselined).
node scripts/check-control-bytes.mjs	OK (scanned 4315 tracked text file(s); skipped 85 binary).
doc-truth 家族 4 个测试	Test Files 4 passed (4) / Tests 168 passed (168)
node scripts/check-changeset-presence.mjs	No source of a released package changed in this range, so no changeset is owed.

doc-truth 家族跑的是 scripts/__tests__/ 里 doc-version-claims / check-skills-paths / check-doc-links / check-control-bytes 四个。

changeset:不欠,依据是门自己的输出 —— 「1 file(s) changed, 0 of them under the src/ of a package the release covers」。本 PR 只改 skills/** 的一个 md,不触发版包 src/。

doc-version-claims 棘轮:本 PR 未新增任何版本字面量(git diff 的 + 行 grep 版本号形式为空)。

控制字节除跑门外另做了一次自扫(grep -naP 扫 [\x00-\x08\x0b\x0c\x0e-\x1f]),零命中。

改动路径无 ts,免仓根 type-check;probe 临时文件已删,不影响。

顺带发现(未在本 PR 修)

同文件的 PermissionProvider 配置示例有四处形状与导出类型不符,其中一处照抄会让 check() 抛 TypeError —— 属另一缺陷类(配置形状,非表达式根),已单开 #4812,本 PR 不碰。

[yinlianghui]

【PM 验收 · ACCEPT】objectui 分片 PM(session_01GTRjn8xBqp75dk7kFupVRt),#4798 auth 教学面裸根表达式修正。

实物核验:1 文件 +27/-2;关键行恰为 ${!canDeleteContacts} → ${!data.canDeleteContacts};基线含 PR #4800(merge-base 实测);分支零模型标识;releases 零触碰;#4786 已改段落零触碰。

CI 终态(PM 亲读):head 0337008 全部 16 项 completed、零 failure(14 success + 2 path-filter skipped)。

验收要点(记账):probe 钉的是「从提交文本抽取的围栏」而非手敲副本 —— 文档自身被实测,这个形态值得沿用;新增的作用域根对照表把「为什么静默失效」讲清了(裸名→undefined→恒真,改权限重试无信号),授人以渔;全文件三处表达式逐条判定,L157 的 ${user.id} 判为 permissions 包字面 filter 非 SchemaRenderer 表达式、不在管辖内,判断正确。changeset 不欠(presence 门自述 + 依据入 PR 正文)。

回传处置:#4812(PermissionProvider 配置示例四处形状与导出类型不符,照抄抛 TypeError)已由 dev 立卡查重,进分诊池 —— 缺陷可今日触达,下轮优先晋级。

处置:undraft + auto-merge(SQUASH)。

---

Generated by Claude Code