设计:UI 操作按钮与 enable.apiMethods 白名单的前后端一致性契约

[baozhoutao]

问题

console 列表页无条件渲染 Import/Export 按钮,不读对象的 enable.apiMethods;后端 REST 数据面却按 ADR-0049 严格执行该白名单——不在白名单的操作直接 405(OBJECT_API_METHOD_NOT_ALLOWED)。

结果就是"前端放行、后端拒绝":用户看得见按钮,点了才报错(首例:#3025 业务单元导入)。

需要设计的契约

1. 一致性规则:UI 是否应按对象元数据里的 apiMethods 隐藏/禁用 Import、Export(以及其它操作入口)?还是约定"平台对象默认放开这些操作、白名单只用于显式收紧"?两边必须取其一,不能各自为政。

2. 白名单语义:import 本质是批量 create/upsert,export 本质是批量 read。是让它们隐含跟随 create+update / list,还是保持独立操作、要求逐对象显式声明(现状)?现状下所有平台对象的白名单都是样板 CRUD 五件套,全仓库没有任何对象声明过 import/export——说明显式声明模式在实践中会被普遍遗漏。

3. 缺口盘点:ApiMethod 枚举里 upsert / bulk / aggregate / history / search / restore / purge 同样不在样板白名单里,而对象上却开着对应能力开关(trash: true 但无 restore/purge、searchable: true 但无 search、trackHistory: true 但无 history)。能力开关与 API 白名单的组合是否自洽,需要整体过一遍。

4. 逐对象决策:契约定下来后,哪些 sys_* 对象开放数据可携带性操作(如 sys_business_unit HRIS 组织树场景)、哪些必须继续封死(token / jwks / oauth-consent 类),给出清单。

关联

• 业务单元需要支持导入:列表页导入按钮 405(apiMethods 白名单缺 import/export) #3025 业务单元导入 405(本设计的首个触发案例,点状修复可先行)
• ADR-0049(no unenforced security properties —— apiMethods 强制执行的出处)

[os-zhuang]

收尾:本设计的四个问题已全部定稿并落地

本 issue 提的是设计问题,定稿后由 #3391 接手分阶段落地,落地过程分散在多个 PR/issue 里,这里做一次逐条对账,然后关闭。

定稿契约(一句话)

服务端是唯一裁决者:每个对象的有效操作集由 spec 里唯一一张派生映射表从 6 个原语(get/list/create/update/delete/bulk)白名单解析(undefined=全开、[]=全禁、子集=收紧);REST gate、dispatcher gate、D3 调和、D4 clamp 全部消费同一张表;前端只渲染下发的 effective 结果,不读原始 apiMethods、不自行派生;派生动词不可独立声明。

逐条对账

本 issue 的问题	结论	落地位置
① 一致性规则:UI 按 apiMethods 隐藏,还是约定默认放开?	都不是 —— 改为「服务端唯一裁决 + 前端只消费下发的 effective」。前端不读原始白名单是契约点(全仓 grep 零违例)	hono-plugin.ts annotateEffectiveApiOperations 经 /me/permissions 下发 apiOperations;objectui#2823 消费
② 白名单语义:import/export 隐含跟随,还是逐对象显式声明?	隐含派生。import 按 writeMode 派生(insert→create、update→update、upsert→create∧update),export→list;派生动词不可独立声明	packages/spec/src/data/api-derivation.ts(唯一真源)、#3498
③ 缺口盘点:upsert/bulk/aggregate/history/search/restore/purge 与能力开关是否自洽?	8 个 legacy 动词全部进派生表并绑能力旗标:search←list∧searchable、history←get∧trackHistory、restore/purge←delete∧trash(trash 已随 #2377 退役,故恒 false,待 #1893 真回收站落地再启用)	API_METHOD_DERIVATION
④ 逐对象决策:哪些开放数据可携带性、哪些封死?	等价全开的直接删声明;真收紧的保留(['get','list']、[] 等)。token/jwks/oauth-consent 类保持 apiMethods: [] 作纵深防御	#3392、#3394 的全仓盘点表 + #3581 的 P2 审计

本 issue 正文里「所有平台对象的白名单都是样板 CRUD 五件套、全仓库没有任何对象声明过 import/export」的实证,正是否掉显式声明模式的依据 —— 显式声明在实践中 100% 会被遗漏,所以改成派生。

落地清单(全部已合并)

• P0 点状修复:fix(platform-objects): allow import/export on sys_business_unit (#3025) #3392、fix(platform-objects): allow import/export on sys_business_unit_member (#3025 / #3391 P0) #3394(BU/BUM 白名单)+ objectui#2823(ImportWizard 405 独立文案,区别于 404 回退)
• P1 契约:feat: single-source API-method derivation contract (#3391 P1) #3498(spec 派生真源 + runtime/rest/hono 三门禁 + /me/permissions 下发)/ objectui#2823(前端只消费 effective)
• P2 枚举收缩:P2:ApiMethod 枚举收缩至 6 原语(breaking,独立版本) #3543 → feat(spec)!: shrink ApiMethod enum to the six primitives (#3543, P2 of #3391) #3581(ApiMethod 收至 6 原语、ApiOperation 类型分家、stripLegacyApiMethods 永久兼容层 + codemod)
• follow-up:用户级 export 权限轴(接入 P1 预留的 userExportAllowed 槽) #3544/feat(security): 让用户级 export 权限轴真正在服务端生效 (#3544) #3709(用户级 export 权限轴真正执法)、元数据不可解析时的 fail-open 残余风险评估(api-exposure / rest-server) #3545(fail-open 残余风险)、detail/form 面的 edit/delete 按钮接入服务端 effective 操作集 #3546(detail/form 面接 effective)、security 服务 getReadableFields 查询面(export 列投影的长期正解) #3547(getReadableFields)、定时报表的 CSV 附件绕过用户级 export 权限轴(#3544 的第二道出数据的门) #3710(定时报表 CSV 侧门)

最后一处缺口 → #3745(in flight)

对账时发现 P1 的一个配套修复没扫全:P1 把 bulk 门禁改成 bulk ∧ derived(child) 后,「给还留着显式白名单的对象补 bulk 原语」只在 platform-objects 包内做了。另外 3 个包里的 8 个对象仍是 CRUD 五件套样板、缺 bulk,导致 /batch 与 createMany/updateMany/deleteMany 返回 405,而单条写完全开放(data-objectstack 对该 405 直接 rethrow,Setup 网格多选删除会硬报错):

sys_capability、sys_permission_set、sys_position、sys_position_permission_set、sys_user_permission_set、sys_user_position(plugin-security);sys_approval_delegation(plugin-approvals);sys_view_definition(metadata-core)。

这属于落地遗漏而非设计问题,已在 #3745 修复(先红后绿,三包测试全绿)。本 issue 的设计契约本身已完整交付,先关闭。

---

Generated by Claude Code