写路径 validate-only(dry-run)模式:把「提交前反馈」的 UX 用单实现的方式补回来(objectui#3110)

[os-zhuang]

背景

objectui 刚拍板(objectui#3110):客户端不再镜像对象级校验规则 —— 规则是 enforcement,enforcement 单实现在服务端 objectql/src/validation/rule-validator.ts。objectui 的 ObjectValidationEngine 已标 @deprecated,并加了 tripwire 测试防止再被接进生产路径。

拍板过程里唯一被牺牲掉的东西是 UX:用户现在只能提交之后才吃到 rule_violation。这个 issue 就是把那份 UX 用不产生第二个求值器的方式补回来。

促成拍板的实证:objectui#3103 逐条对着本仓 rule-validator 源码做了一轮认真收敛(8 个 mutation-test 闸门),仍然留了一处分歧 —— ADR-0113 的 legacy-violation 豁免(仅当合并后状态违规且本次写入使其恶化时才拒)客户端没有实现。一轮认真收敛尚且留尾巴,说明跨仓镜像 parity 是结构性不可靠。

诉求:写路径的 validate-only(dry-run)模式

跑真正的 rule-validator、不落库、返回 violations 列表。

• 零 parity 风险:同一份代码路径,不存在第二个实现可漂移。
• 覆盖客户端永远做不到的两类:unique(要查库,而且客户端做 SELECT-then-check 本身就是 TOCTOU 竞态 —— 正是 spec 有意移除 unique 规则类型的理由)、json_schema(ajv 在服务端)。
• ADR-0113 语义自动正确:豁免逻辑就在那条路径上,不需要任何一侧去"记得"实现它。
• 也顺带能服务非 UI 消费者(CLI 校验、导入预检、AI 生成记录的自检)。

需要设计的点(非结论,列出来供讨论)

1. 接口形态:insert/update 带 dryRun: true 选项,还是独立端点?倾向前者——同一入口保证走同一段代码,独立端点容易长出自己的分支。
2. previous 的取法:update 的 dry-run 要不要真去读 prior record(state_machine、跨字段谓词、ADR-0113 都需要它)?读了才准,但就有一次读的成本。
3. 权限:dry-run 必须走与真实写入相同的权限判定,否则会变成一个探测器(用报错差异反推他人数据是否存在/字段值)。
4. 副作用边界:明确 lifecycle hooks(beforeInsert 等)在 dry-run 下不执行——只跑声明式规则。否则 dry-run 自己就成了副作用来源。
5. 返回形状:直接复用现有的 FieldValidationError[](field/code/message/label),console 已经会渲染,不需要新契约。

排期建议

不建议现在就做。 objectui 侧的弃用已经落地,现状(服务端拒绝 + 结构化报错渲染)是可用的。这个 issue 先作为决策记录存在,等产品确认「提交前反馈」是真需求时再排期。先记下来是为了:objectui#3110 的结论明确指向这里,没有这个 issue,下一个 agent 会重新发明客户端预检。

关联

• objectui#3110 —— 拍板与理由(含为什么选 B 而不是接线)
• objectui#3103 / objectui#3107 —— 语义收敛,以及留下的 ADR-0113 分歧
• ADR-0020(规则求值器)、ADR-0113(legacy-violation 豁免)

另:未来若 objectui 需要离线写入

OfflineConfig 一旦进路线图,客户端求值器会从"冗余"变成"必需"(离线时没有服务端可问)。届时的前置条件应该是 @objectstack/spec 携带 conformance fixtures —— golden 的「规则 + 记录 + 判定」三元组,两仓 CI 各跑同一套。那是唯一能把跨仓行为 parity 从约定变成机制的办法。这不是本 issue 的范围,但值得在这里留个指针。

[os-zhuang]

产品评估结论:关闭(not planned)—— 无当前业务价值

本 issue 自己预设了排期条件:「等产品确认『提交前反馈』是真需求时再排期」。评估已做,结论是否定分支:从平台长远合理性看,现在没有业务价值,不排期,关闭。 依据逐条如下(两仓代码均已核实)。

逐条评估

1. 「提交前反馈」UX(核心动机)——增量为零或存疑。
   • 提交点自动预检:objectui 对预检和真写渲染的是同一条链(form.tsx 的服务端拒绝分支 → announceFieldErrors:字段级 setError、tab 切换、reveal + toast)。dry-run-then-write 与直接 write 的用户体验完全相同,只是每次成功提交多一个 round trip。
   • 显式「校验」按钮:无需求证据;单记录表单失败成本低(直接提交即可)。objectui#3110 决策评论已指出 Salesforce 同样是 save 时服务端评估、无客户端预检——没有行业压力。ImportWizard 的校验按钮场景不同(批量、失败昂贵),且 import 已有自己的 dryRun。
   • 编辑中实时校验:成本高(高频请求 + update dry-run 每次要读 prior record),而 required/min/max/pattern 等字段形状校验客户端本就有(buildValidationRules)。
2. 非 UI 消费者(CLI 校验/导入预检/AI 自检)——皆非当下。 导入预检已存在且可用(import-runner.ts 自带 dryRun);CLI/AI 自检是推测性需求,今天没有一个具体消费者。
3. 零 parity / ADR-0113 自动正确:这是实现方式的优点,不是做这件事的理由。
4. 离线场景:dry-run 帮不上离线(离线 = 没有服务端可问);离线路线的前置(spec conformance fixtures)在 objectui#3110 的 tripwire 里另有记录,与本 issue 正交。

长远合理性恰恰反对现在做

没有消费者的写路径 data-safety flag 是本仓最忌惮的死面(PD #10 declared ≠ enforced、#4115 台账)。本仓已有一模一样的前车之鉴:BatchOptionsSchema.validateOnly(#4052 墓碑)——声明了 dry-run、没人读、validateOnly: true 照样落库。而要把新 flag 做到「不说谎」,代价是持久的:spec request/response schema、engine 选项键闸门(还得先堵上 insert 未知选项被静默忽略的洞,否则新客户端对旧服务端发 dry-run 会静默真写——版本偏移下的 #4052 重演)、client SDK 两个镜像 surface、objectui DataSource 契约 + feature-detect、conformance/ledger/docs/i18n。为零个现有消费者背这笔永久税,不成立。

现状是健康的:服务端拒绝已结构化(field/code/message/label),console 渲染良好。

不变式重申(关闭不改变它)

客户端预检仍然不做。 决策在 objectui#3110,tripwire(validation-engine-stays-unwired.test.ts)继续有效。今天的正确路径 = 提交,渲染服务端结构化拒绝。本 issue 关闭后仍是反发明指针:下一个想做预检的 agent,顺着 tripwire 文案会落到这里,读到的答案是「机制上服务端 dry-run 是对的形态,但产品上现在不做」。

重开条件

1. 产品拿到具体的预提交反馈需求(如长向导表单重填成本高)→ 按本 issue 正文的 5 个设计要点实现为 insert/update 的 flag(必须留在 middleware 链内,权限判定与真写一致);
2. 出现第二个真实非 UI 消费者——最可能的是 import-runner 下次需要语义规则时,把它对字段形状检查的二实现收编到 engine 级 dry-run;
3. AI 生成记录自检成为真实工作流。

顺手修正

packages/client/README.md 至今还在把已退役的 validateOnly 当可用 dry-run 来文档化(文档版的 declared ≠ enforced),已在 claude/validate-only-mode-ux-q2hslo 分支修正为指向 upgrade-guide 墓碑。

---

Generated by Claude Code