Skip to content

docs: data-engine.mdx 的 IDataEngine 代码块漏掉四个读方法的 options 参数——漏的正是 #4251 修的那个 #4486

Description

@os-zhuang

文件content/docs/kernel/contracts/data-engine.mdx(手写文档,非自动生成)
发现于:核对 #4419 时(PR #4459)。文档漂移先于该 PR 存在,当时没混进一个破坏性 PR。
核实基线main @ ec975f1

摘要

文档里的 IDataEngine 代码块把四个读方法都写成两个参数,漏掉了尾部的
options?: BaseEngineOptions。真实契约四个都有。

漏掉的恰恰是 #4251 修复的那个参数——当初正因为它缺失而出过 bug。

现状对照

content/docs/kernel/contracts/data-engine.mdx:33-38

export interface IDataEngine {
  // Query
  find(objectName: string, query?: EngineQueryOptions): Promise<any[]>;
  findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
  count(objectName: string, query?: EngineCountOptions): Promise<number>;
  aggregate(objectName: string, query: EngineAggregateOptions): Promise<any[]>;

真实契约 packages/spec/src/contracts/data-engine.ts:70 / 85 / 89 / 90

  find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any[]>;
  findOne(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any>;
  count(objectName: string, query?: EngineCountOptions, options?: BaseEngineOptions): Promise<number>;
  aggregate(objectName: string, query: EngineAggregateOptions, options?: BaseEngineOptions): Promise<any[]>;

同一代码块里的写方法(insert / update / delete)都带着各自的 options
所以读者看到的是「写方法有 options、读方法没有」——这正是 #4251 之前那个错误认知。

为什么值得单独修

这个尾参不是可有可无的细节。契约里它自己的 TSDoc 记着它的来历:

同一个 { context } 对象作为 insert 的第 3 参是正确的,作为 find 的第 3 参却被
静默丢弃,于是一个本意为 isSystem 的绕过凭空消失(控制面读取在 org-scoping hook
落地后开始返回空)。契约当时只保留了 query.context,所以每个传尾参的调用方——
包括当前用户端点的 permission-set 加载器——都得靠 any 去够它。

也就是说:文档漏掉的,正是「当初因为缺失而出 bug、后来专门补上」的那个参数。
一个照着这段文档写代码的人(或 agent)会被引回旧写法。

修法

把那四行补齐即可,纯文档:

  find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any[]>;
  findOne(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any>;
  count(objectName: string, query?: EngineCountOptions, options?: BaseEngineOptions): Promise<number>;
  aggregate(objectName: string, query: EngineAggregateOptions, options?: BaseEngineOptions): Promise<any[]>;

顺带值得加一句:query.contextoptions.context 同时给出时,后者胜(契约原文如此)。

content/docs/kernel/contracts/ 不在自动生成范围内(只有 content/docs/references/ 是),
所以这是手改,不需要跑生成器。

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions