fix(service-analytics): 编译期拒绝 dataset 的跨 datasource JOIN (#5115)

[claude]

Fixes #5115

按维护者在 issue 里的拍板,本 PR 只做第 1 步:compileDataset 在编译期拒绝跨 datasource 的 join。

做了什么

compileDataset 新增一个可选的 DatasetCompileOptions(第三个参数),里面是两个早已存在于 AnalyticsServiceConfig 上的探针:getObjectDatasource(#5033 为诊断文案引入)和 isExternalObject(ADR-0062 D6)。AnalyticsService.registerDataset —— 启动预注册、保存、Studio 草稿预览都要走的那一道门 —— 把它们交给编译器,于是被证明的冲突在任何 SQL 被构造之前就被拒绝。

判定接在既有的 include 解析链路上:resolveHop 每解析出一个 join 目标就判一次,没有另起一套关系解析。多跳路径的每一跳都是同一条语句里的 join,所以每一跳都判(不只是最后一段)。

错误文案点名两个对象、两个 datasource、出问题的 include 路径,以及两条出路:

[dataset-compiler] dataset "revenue_by_region" declares a JOIN that crosses datasources:
its base object "opportunity" is on datasource "billing_db", but the joined object
"crm_account" — reached via the `include` path "account" — is on datasource "crm_db".
A dataset JOIN cannot cross datasources: the whole dataset is executed as ONE statement
on the base object's datasource, so "crm_account" is simply not there. Fix it by binding
both objects to the same datasource, or by dropping "account" from the dataset's
`include` (and every dimension/measure that references it).

与 #5033 查询期那句同源(同样的「不能跨库 + 两条修法」),不会读成两个 bug。

分级放行的判据(这是本 PR 最需要评审的部分)

拒绝只在元数据自己能证明冲突时发生:基对象与某个 join 目标各自显式声明了 object.datasource,且两个名字不同(大小写不敏感比较)。以下一律放行,由 #5033 的查询期防线兜底:

1. 宿主没接探针(无 data engine)—— 编译行为与改动前完全一致。有专门的测试钉住:不传 options、传 {}、以及用 new AnalyticsService({ relationshipResolver }) 直接注册,三种都照常编译。
2. 探针答不上来(对基对象或对某个 join 目标返回 undefined)。基对象答不上来时不判任何 join —— 不能因为「问不出基对象」就拒绝所有 join。
3. 任意一侧停在 'default'。这条是本 PR 唯一一处需要判断力的地方,理由写在代码注释里:ObjectQL.getDriver 的解析顺序是「显式非 'default' 的 object.datasource → datasourceMapping 规则 → ADR-0057 §3.6 生命周期分流(audit/telemetry/event → telemetry)→ package 的 defaultDatasource → 全局默认」。也就是说 'default' 是 schema 的默认值(ObjectSchema.datasource 带 .default('default')),不是一个路由决定;声明 'default' 的对象仍然可能被 mapping 规则或生命周期分流落到别的库,甚至正好落到对面那个库。把 'default' 当成「主库」会误拒这类今天能正常工作的 dataset,还会让判定取决于该对象是否恰好被 Zod parse 过(parse 才会把默认值物化出来)。误放行的代价是一条已经存在的响亮运行时错误;误拒绝的代价是升级后看板直接变白 —— 所以这里选了「证明不了就不拒绝」。
4. 任意一侧是 federated(external)对象。NativeSQLStrategy.canHandle 本就 decline 这种 cube(base 或 join 目标为 external),查询由 ObjectQL FK-expand 路径(两段读 + 内存 join)承接,那条路径天然跨库。在这里拒绝会打断今天能工作的路径。

明确不在范围

• 第 2 步(换策略)不做:让跨库看板真正能工作(NativeSQLStrategy.canHandle 在 join 跨库时 decline + 两段读内存 join)完全不在本 PR 内,也没有为它预埋任何抽象。顺带记录一个对第 2 步有用的现场事实:那条路径的机制已经存在 —— ObjectQLStrategy 的 executeCrossObject(FK-expand,analytics/objectql: 跨对象(点号 lookup)维度聚合在 ObjectQL 路径上静默塌成 (null) 桶 / native SQL 报错 #3654)就是「按 FK 分组 + 单独读关联对象」,每一段各自按对象路由,因此天然跨库;第 2 步大概率是让 NativeSQLStrategy 在跨库时 decline,而不是新写一条路径。
• 不碰 packages/spec/**、packages/lint/**;content/docs/releases/** 未触碰,变更记录只走 .changeset/。

发布闸门(publish-time lint)落点的调研结论 —— 只调研,不实现

维护者要求本单只做注册期拒绝,发布闸门另立单。调研结论如下,供开那一单时直接用:

• 落点:packages/lint,进 reference-integrity-suite.ts 那一族(「metadata 里写下的名字能不能解析到东西」),新增一条形如 dataset-cross-datasource-join 的规则,由 suite 统一接到 os validate / os lint / os compile 三个入口(该文件的存在意义就是让新规则的接线是一行编辑,避免三处漂移)。
• 需要的输入,发布期比运行期更全:StackSchema 同时持有 objects(每个带 datasource)、datasources、datasourceMapping 和 datasets。也就是说 lint 规则能把 getDriver 五步里的前两步(显式绑定 + mapping 规则)都算出来,而运行期的 compileDataset 只能通过探针一次问一个对象、且看不见 mapping。发布闸门天生能比本 PR 判得更准,而不只是更早。
• 仍然算不出的部分:package defaultDatasource(跨 package 安装时才确定)与「telemetry datasource 是否真的注册」属于部署事实,规则应对这两类保持同样的「证明不了就不拒绝」姿态。
• 一个前置缺口(已单独记账:analytics 的 getObjectDatasource 报告的是「声明值」而非「有效 datasource」:#5033 的诊断会点错库,#5115 的编译期闸门看不见隐式路由的对象 #5288):运行期没有权威的「对象的有效 datasource」访问器,getObjectDatasource 只报告声明值。所以 service-analytics 的 executeRawSql 自动桥接丢弃 objectName —— dataset 原始 SQL 永远打在默认 datasource 上,凡被路由到非默认 datasource 的对象一律读成 0 #5033 催生本单的那个真实场景(sys_audit_log 靠 lifecycle.class: 'audit' 被分流到 telemetry,而不是靠显式字段)对本 PR 的闸门是不可见的 —— 补上那个访问器,本 PR 的判据可以在不引入误拒的前提下扩到隐式路由的对象。

STALE-PREMISE 核对(issue 基于 c272e48be,已对最新 origin/main 重核)

• ✅ getObjectDatasource 在 AnalyticsServiceConfig 上,plugin 侧从 engine.getObject(name).datasource 接出 —— 仍然成立。
• ✅ compileDataset 已校验 include 关系是否存在于基对象上,并已通过 relationshipResolver 拿到 join 目标对象名 —— 仍然成立,新判定就接在这条链上。
• ✅ service-analytics 的 executeRawSql 自动桥接丢弃 objectName —— dataset 原始 SQL 永远打在默认 datasource 上,凡被路由到非默认 datasource 的对象一律读成 0 #5033 的查询期响亮失败文案仍在 analytics-service.ts 的 missing-source 分诊里,措辞未变。
• ⚠️ 一处补正:issue 说「只需要问每个参与对象绑定在哪个 datasource 上」。现场比这句更微妙 —— 'default' 不是一个绑定答案,而是「没有绑定」;真正的路由还要经过 mapping / 生命周期分流 / package 默认值。本 PR 因此把判据收窄到「双方都显式声明且不同」,并把理由写进代码注释与 changeset。

行为变更(收紧)

原本能编译通过、要到查询期才失败的跨库 dataset,现在在注册期就被拒。启动时预注册的 dataset 走既有的 per-dataset try/catch:记一条点名冲突的 WARN 并跳过,同一宿主里其它 dataset 照常注册,不会因此起不来。changeset 里写清了受影响面。

验证

• pnpm --filter @objectstack/service-analytics test —— 42 个文件 / 555 个用例全绿(新增 17 个:dataset-compiler.test.ts 里 11 个判定与放行用例,dataset-cross-datasource-registration.test.ts 里 6 个接线用例)。
• tsc --noEmit -p packages/services/service-analytics/tsconfig.json —— 与改动前同样的 13 行既有报错(全部在我未触碰的测试文件里:analytics-service.test.ts、measure-source-field-gate.test.ts、objectql-timedimension-projection.test.ts),没有新增。改动前后各跑一次对比确认。
• eslint --no-inline-config packages/services/service-analytics/src/ —— 干净;测试里没有 as any。
• pnpm --filter @objectstack/service-analytics build —— 通过(含 DTS)。

顺手记的账(不在本 PR 修)

• analytics 的 getObjectDatasource 报告的是「声明值」而非「有效 datasource」:#5033 的诊断会点错库,#5115 的编译期闸门看不见隐式路由的对象 #5288 —— getObjectDatasource 报告的是声明值而非有效 datasource(getDriver 五步里它只覆盖第 1 步)。两个后果:service-analytics 的 executeRawSql 自动桥接丢弃 objectName —— dataset 原始 SQL 永远打在默认 datasource 上,凡被路由到非默认 datasource 的对象一律读成 0 #5033 的查询期文案对靠生命周期分流跨库的对象(比如 sys_audit_log)会点错库;本 PR 的闸门因此只能收窄到「双方都显式声明」。已按未分配、无标签提交 PM 分诊,本 PR 不依赖它。

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 3:52pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-analytics.

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

• content/docs/api/data-api.mdx (via @objectstack/service-analytics)
• content/docs/api/index.mdx (via @objectstack/service-analytics)
• content/docs/kernel/services-checklist.mdx (via @objectstack/service-analytics)
• content/docs/permissions/sharing-rules.mdx (via @objectstack/service-analytics)
• content/docs/plugins/packages.mdx (via @objectstack/service-analytics)
• content/docs/releases/implementation-status.mdx (via @objectstack/service-analytics)
• content/docs/releases/v17.mdx (via @objectstack/service-analytics)
• content/docs/releases/v9.mdx (via @objectstack/service-analytics)

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.