Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Repository navigation
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

data-objectstack 的 queryDataset 返回类型漏掉 fields[].percentScale,而 #3136 明令渲染端必须按它缩放 #3752

Closed
#3817
Closed
data-objectstack 的 queryDataset 返回类型漏掉 fields[].percentScale,而 #3136 明令渲染端必须按它缩放#3752
#3817
Assignees
yinlianghui
Labels
pm:dispatchedpm:queue

Description

@yinlianghui
yinlianghui
opened on Aug 8, 2026

在 #3613(把 selection 参数换成 spec 的 DatasetSelection)时发现的同族、但在返回值一侧的漂移,按 PD #10 单开、不并入那个 PR。

现状

packages/data-objectstack/src/index.ts 的 queryDataset 返回类型手写了 fields 元素的形状:

fields: Array< { name: string; type: string; label?: string; format?: string; currency?: string } >;

其 JSDoc 逐项列举了它以为服务端会送的东西("a display label…, and a measure's numeral format + declared currency")。而 pin 的 @objectstack/spec@17.0.0-rc.5 里 AnalyticsResult.fields[](contracts)除这几项外还有 percentScale?: PercentScale(以及 sql? 在结果顶层)。spec 注释写明:

The column's percent SCALE, when it is a percentage: fraction for a 0–1 ratio (1 ⇒ "100%"), whole for percentage points… renderers that receive it must scale by it instead of guessing from the value (objectui#3136).

为什么这不是纸面问题

percentScale 在本仓是重度消费的,三个包都在读 queryDataset 结果里的这个字段:

  • packages/plugin-dashboard/src/DatasetWidget.tsx:625,707,824
  • packages/plugin-report/src/DatasetReportRenderer.tsx:470,485,710,932,943,957,967
  • packages/app-shell/src/views/metadata-admin/previews/DatasetPreview.tsx:228

它们全都靠自己本地的 DatasetResultField 之类的类型(packages/core/src/utils/dataset-format.ts:34 声明了 percentScale)读到它,因此今天不报错。但任何按 adapter 返回类型取值的作者会得到编译错误——声明在说"这一列没有 percentScale",而这恰好把作者推向 #3136 明确禁止的"按数值大小猜百分比刻度"。与 #3613 同一个 declared≠contract 形状,只是方向在返回值上。

根因与建议

和 #3613 一样:手写重述一份别人拥有的契约,就是给同一契约开第二份方言,漂移只是时间问题——这份 fields 形状就是停在了写它那天的 spec 上。

但不能简单换成 AnalyticsResult:adapter 的返回是 REST 信封,它比 AnalyticsResult 多 object / dimensionFields / drillRawRows(ADR-0021 D2 钻取),又不含 sql。所以这里需要一个判断,而不是机械替换。两个方向:

  • A:返回类型改成 AnalyticsResult 与信封增量的交叉(AnalyticsResult & { object?: …; dimensionFields?: …; drillRawRows?: … }),fields 由此直接来自 spec、再不会漏项。前提是确认服务端在这条路由上确实回全 AnalyticsResult(含 sql)。
  • B:只把 fields 元素一项换成 AnalyticsResult['fields'][number],其余信封字段保持本地声明。改动最小,且不对 sql 是否回传做任何断言。

倾向 B:它精确消灭了这一处方言(fields 的列元信息本就是 spec 拥有的概念),又不需要先证明整条路由与 AnalyticsResult 等同——A 的那个前提没查证前就是在替服务端下断言。若维护者能确认路由确实回全 AnalyticsResult,A 更彻底。

顺带:REST 路由的实际回包形状需要在 framework/spec 侧确认一次,所以这条可能要跨仓看一眼再动手。

Activity

  1. os-zhuang
    added
    pm:queue
    on Aug 8, 2026

  2. os-zhuang commented on Aug 8, 2026

    @os-zhuang
    os-zhuang
    on Aug 8, 2026 – with Claude
    Contributor

    Triage: pm:queue (objectui in-repo card — the fix lands in packages/data-objectstack; the framework/spec side is a read-only confirmation, so no transfer).

    Classification rationale. Concrete declared-vs-contract drift with a named location and a minimal fix direction: the hand-written fields element type omits percentScale, which spec explicitly tells renderers to consume (objectui#3136). Three in-repo packages already read the field through local types, so the adapter's return type is actively steering external authors toward the guess-by-value behaviour #3136 bans. The body's direction B (replace only the fields element with the spec-owned type) is self-contained and does not assert anything about the rest of the envelope — dispatch with B as the default; A only if the dev verifies the route returns the full AnalyticsResult.

    Anchor verification (objectui origin/main @ b1204af): packages/data-objectstack/src/index.ts:3213 still declares the five-key fields element without percentScale; packages/core/src/utils/dataset-format.ts:34 still carries the local percentScale?: PercentScale the consumers use instead. Facts live.

    Dedup: #3613 is the same drift family on the parameter side (selection) and is referenced as the provenance; this card is the return-value side, filed separately per PD #10. No open duplicate.

    本评论来自分诊座位 Routine（#5474 试点），不构成认领。

    Generated by Claude Code

  3. yinlianghui
    added
    pm:dispatched
    on Aug 8, 2026
  4. yinlianghui
    self-assigned this
    on Aug 8, 2026

  5. yinlianghui commented on Aug 8, 2026

    @yinlianghui
    yinlianghui
    on Aug 8, 2026 – with Claude
    ContributorAuthor

    🔒 认领(objectui 分片 PM,session_01GTRjn8xBqp75dk7kFupVRt)

    即将派发 os-dev 实施。

    Generated by Claude Code

  6. yinlianghui
    closed this as completedin #3817on Aug 8, 2026
  7. akarma-synetal
    added 3 commits that reference this issue on Aug 10, 2026

    fix(data-objectstack): type queryDataset(selection) as the spec Datas…

    5f08c05

    fix(data-objectstack): type queryDataset result fields as the spec An…

    d83f6b3

    fix(data-objectstack): pass the server drillRanges sidecar through qu…

    3765678
  8. akarma-synetal
    added a commit that references this issue on Aug 17, 2026

    refactor(core): derive DatasetResultField from spec AnalyticsResult.f…

    e901131
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

pm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions