feat(client): 类型化 data.batchTransaction() —— master-detail 保存统一走原子跨对象批量(#1604 / ADR-0034 item 4)

[os-zhuang]

背景

承接 #1604 与 ADR-0034 item 4:服务端原子跨对象批量端点(POST {basePath}/batch,单引擎事务、{ $ref: <opIndex> } 批内父引用、逐对象 API 曝光鉴权)已落地,但 @objectstack/client SDK 没有对应的类型化方法——objectui 的 masterDetailTx 适配器要走原子路径只能手写 fetch。本 PR 补上 framework 侧缺口,让原子 batchTransaction 成为 master-detail 保存的一等公民 SDK API。

改动

• packages/client/src/index.ts:新增 client.data.batchTransaction(operations) 与环境作用域镜像 client.project(id).data.batchTransaction(operations)。
  • 复用并 re-export spec 契约类型 CrossObjectBatchOperation/Request/Response(@objectstack/spec/api)。
  • 恒原子、不暴露 atomic 参数——类型上无法表达非原子请求(服务端对 atomic:false 也会 400 BATCH_NOT_ATOMIC)。非原子 per-object 批量保留在 data.batch()/createMany/updateMany;best-effort 回退只能隔离在调用方(ObjectUI masterDetailTx)适配器里,SDK 不承载——这是"非原子回退隔离进适配器"的类型化表达。
  • URL 推导:端点按构造挂在 data 前缀的父级(${basePath}/batch),客户端从 getRoute('data') 去末段推导,兼容 discovery 覆写的自定义路由;不给 ApiRoutesSchema 加 key(避免 3+ 个 discovery 生产方同步、declared-but-unpopulated 路由)。
• 测试:
  • 单测 6 例(client.test.ts):URL/payload、$ref 透传、裸/信封双响应形态解包、discovery 路由推导、错误整形(code/httpStatus)、scoped 镜像。
  • 端到端 4 例(新文件 client.batch-transaction.test.ts,LiteKernel + Hono 真实服务):父+子 $ref 落库且 FK 等于父 id、scoped 路由、BATCH_UNRESOLVED_REF 全链路错误映射、atomic:false → 400 BATCH_NOT_ATOMIC 契约 pin。文件头注明 InMemoryDriver 事务为 passthrough,回滚原子性由 engine-ambient-transaction.test.ts / rest-batch-endpoint.test.ts 覆盖。
• 文档:content/docs/api/client-sdk.mdx 增加原子跨对象批量示例并互链 http-protocol.mdx Batch Operations;ADR-0034 §4 补状态注(framework 侧完成)。
• Changeset:@objectstack/client minor。

验证

• pnpm --filter @objectstack/client build ✅(DTS 通过)
• pnpm --filter @objectstack/client test ✅ 4 files / 109 tests(含新增 10 例)
• pnpm --filter @objectstack/rest test ✅ 19 files / 323 tests(相邻回归)

跨仓库 follow-up(不在本 PR)

objectui 仓库:masterDetailTx / data-objectstack 适配器改为调用 client.data.batchTransaction(以 $ref 组 operations),删除客户端 best-effort 清理;非原子顺序回退(面向无该端点的旧服务器,按 error.httpStatus === 404 特性探测)只保留在该适配器内部。

注:任务标题所引 #2679 在 framework 为不相关 issue(userFilters),应为 objectui 侧编号;本 PR 按 #1604 / ADR-0034 item 4 的实质内容执行。

🤖 Generated with Claude Code

https://claude.ai/code/session_01QCrTB7b5qFX2yyHJEGB5xa

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 19, 2026 11:58am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/client.

12 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx(via packages/client)
• content/docs/api/client-sdk.mdx(via @objectstack/client)
• content/docs/api/data-flow.mdx(via @objectstack/client)
• content/docs/api/environment-routing.mdx(via @objectstack/client)
• content/docs/api/error-catalog.mdx(via @objectstack/client)
• content/docs/getting-started/your-first-project.mdx(via @objectstack/client)
• content/docs/kernel/runtime-services/data-service.mdx(via packages/client)
• content/docs/kernel/runtime-services/index.mdx(via packages/client)
• content/docs/permissions/authentication.mdx(via @objectstack/client)
• content/docs/plugins/packages.mdx(via @objectstack/client)
• content/docs/protocol/kernel/realtime-protocol.mdx(via @objectstack/client)
• content/docs/releases/implementation-status.mdx(via @objectstack/client)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.