fix(service-analytics): lower the where before seeding an ad-hoc cube's dimensions (#5353)

[os-zhuang]

Fixes #5353

前提重验(对 origin/main,fce4c7385)

立单前提仍然成立,逐条核过:

• analytics-service.ts:1577 上 !Array.isArray(query.where) 守卫在位,一字未改。
• 同文件 1446-1455 行还留着 PR fix(service-analytics): where 源字段闸门 —— 点名不存在字段的筛选答 400 INVALID_FIELD 而非驱动 500 (#5669) #5740 写下的说明,明确记着这个 skip 属于 observation: inferCube 仍把数组 where 当「不是筛选」跳过 —— #5334 之后这个 !Array.isArray 守卫已经过时 #5353、本次不动。
• filter-normalizer.ts 的 normalizeAnalyticsFilterTree 自 analytics 是 #5158 拍板 C 漏掉的第五道门:where 为数组(FilterArray 糖)时被 normalizeAnalyticsFilterTree 静默丢弃,图表画全表 #5334 起对数组 where 走 isFilterAST → parseFilterAST 下沉,所以「数组 where 是真筛选」也成立。

改了什么

inferCubeFromQuery 的 where 臂先下沉再取键。下沉复用 #5334 那一次,不是新接一份:normalizeAnalyticsFilterTree 里的数组分支抽成 lowerAnalyticsWhere(返回下沉后的 canonical FilterCondition),normalizeAnalyticsFilterTree 变成「这次下沉 + buildNode」。全仓只有一处 isFilterAST/parseFilterAST 调用,两处读者(闸门读树的叶子,铸造读条件的键)看同一次下沉的两种视图。

取键走新的 conjunctFieldKeys,它下钻 $and、不下钻 $or / $not。下钻 $and 不是顺手加的:下沉本身会引入 $and —— 平铺数组 [[a,…],[b,…]] 是对象 {a…, b…} 的数组写法,parseFilterAST 把它降成 {$and: [{a…},{b…}]}。只读下沉后对象自己的顶层键的话,答案是「只有 $and」即什么都没有,两种写法照旧铸出两个 cube。连带效果:对象写法的显式 {$and: […]} 现在也会铸出其 conjunct 的键(以前不会),这与 {a…, b…} 拉平,属同一个缺陷类。

$or / $not 两种写法今天都不贡献键,保持不变。

刻意不用 collectFilterLeaves:叶子回答「编出的谓词绑了哪些 member」,这个 bag 回答「调用方可以命名什么」,两者真的不同 —— {stage: {$in: []}} 降成布尔常量 FALSE,不绑任何 member,却仍然命名了 stage。

判定不变性(实测,不是推断)

两种写法修前就编出逐字相同的谓词,这也是本单属 observation 而非缺陷的原因:resolveFieldSql 对未声明 member 回落裸列名,而 qualifyAndRegisterJoin 只在 cube 声明了 joins 时才加限定 —— 即席 cube 从不声明。所以新铸的 dimension 只是把这些 member 从「未声明裸列」分支挪到「已声明 dimension」分支,两分支得出同一列。

• 编译语句:逐字一致(用例断言 WHERE stage = 且 不含 "deal"."stage")。
• 引擎 filter:逐字一致。
• analytics: where 里点名不存在的字段仍然一路到驱动 —— #4437(measure)/ #5520(dimension)之后,filter 面是同一个缺陷剩下的第三个 param #5669 闸门判定:不变。它读的是筛选叶子而非 cube.dimensions,所以本单改不动它 —— 实测确认。变的是拒收消息里的 Valid filter members: 建议表,方向正是本闸门家族要消除的分叉:同一份筛选,两种写法,现在读到同一条消息。

一处没有统一的:点号 where 键

{'owner.region': 'NA'} 铸出剥尾后的基表列 region;数组写法 [['owner.region','=','NA']] 什么都不铸,编出关系穿越。两个方向都不是本单能选的,实测:

① where: {'owner.region': 'NA'}       dims ["deal.region"]  → 400 INVALID_FIELD 'region'
② where: [['owner.region','=','NA']]  dims []               → LEFT JOIN "owner" ON …
                                                               WHERE "owner"."region" = $1

• 把误铸传播给数组写法(对所有 conjunct key 一律 stripPrefix)是回归:② 从能跑的穿越变成 WHERE region = $1(基表有同名列时静默筛错列),基表无该列时变成 400。
• 从对象写法撤掉误铸会劈开一条 fix(service-analytics): where 源字段闸门 —— 点名不存在字段的筛选答 400 INVALID_FIELD 而非驱动 500 (#5669) #5740 刻意钉住的不变量:点号 member 在 where 与 dimensions 两个请求键上共用 resolveMemberSource、逐字同答,且「一旦这个读法被判定为错,两个键必须同时改」。只在 where 一侧撤会让两键分叉。

所以点号键原样保留各自写法今天的答案(残留循环逐字复刻 origin/main 的对象顶层键 + stripPrefix),归 #5739 裁定 —— 该单已带 needs-user-decision,实测与两个子选项的代价已评论上去。#5353 自己的范围(过时的 !Array.isArray 守卫)是完整交付的:守卫已删,数组走下沉。

测试

新增 infer-cube-where-spelling-parity.test.ts(23 例)。平价表直接取 #5334 自己的 EQUIVALENT_SPELLINGS,让两个文件不会对「同一份筛选的两种写法」各说各话 —— #5334 断言两者选出同样的行,这里断言两者铸出同样的cube。每例都断言「精确期望集合」而不只是「两边相等」:只比两边的表会在两边都空时同样通过,而那正是缺陷本身。

• pnpm --filter @objectstack/service-analytics test → 56 files / 1008 tests 全绿(含 fix(service-analytics): where 源字段闸门 —— 点名不存在字段的筛选答 400 INVALID_FIELD 而非驱动 500 (#5669) #5740 的 31 例、analytics 是 #5158 拍板 C 漏掉的第五道门:where 为数组(FilterArray 糖)时被 normalizeAnalyticsFilterTree 静默丢弃,图表画全表 #5334 等价性用例零回归)。
• pnpm --filter @objectstack/rest test → 55 files / 778 tests 全绿。
• tsc --noEmit:本包在 type-check 覆盖率账本里带 DEBT 条目(无 typecheck 脚本)。直接跑:改动前后同为 7 条既有报错,我的三个文件零报错。
• 门:check:nul-bytes OK(5648 文件);对三个改动文件另做了越过门盲区的自查 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' → 无命中;eslint 三个文件零输出。改动只在 packages/services/service-analytics/src/,不碰 spec/docs/i18n,故 spec 生成物与 i18n 门无关。
• 消费半径已扫:normalizeAnalyticsFilterTree 等导出在本包外无消费者;依赖本包的 rest/cli/verify/qa-dogfood 中无数组 where、无点号 where 的 analytics fixture。

反向验证(先预测方向,再跑)

恢复 !Array.isArray(query.where) 守卫。预测 13 红 / 10 绿,并预先点名红的集合:平价表 13 例中降成合取且至少命名一个字段的 11 例、seeds the where keys ALONGSIDE …、以及 bare keys reach parity even when a dotted key rides along。实测恰好这 13 例。

两处绿是刻意的,写在用例头里而不留给下一位读者去踩:

• $or 根的两例(prefix OR group、nested group — OR of an AND)修前修后都绿 —— 两种写法经由析取都不贡献键,那里本来就没有不对称可修。把表读成「13 例全红」是错的。
• 第 3 组(点号残留)修前修后都绿,这是围栏而不是修复的一部分:它让日后改用 collectFilterLeaves 的重构(会把 {owner: {region: 'NA'}} 拉平成叶子 owner.region 并重新铸出 region)响亮地失败,而不是悄悄改掉一条 fix(service-analytics): where 源字段闸门 —— 点名不存在字段的筛选答 400 INVALID_FIELD 而非驱动 500 (#5669) #5740 与 dimensions 请求键共享的判定。

---

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 6, 2026 4:15am

[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.