@aiao/rxdb-plugin-tree 0.0.0-stage → 0.0.28

package/src/query/tree-helper.ts

@@ -0,0 +1,342 @@
+import { EntityType, getEntityId, RxDBEntityId, UpdateDataCache } from '@aiao/rxdb';
+import { get_tree_parent_id } from './query-tree.utils.js';
+
+/**
+ * 目标实体的祖先 id 集合，{@link TreeHelper.collectAncestorIdsForCount} 的产物
+ */
+export interface TreeAncestorIdSet {
+  /** 自目标向上、`maxLevel` 以内解析到的全部祖先 id */
+  ids: ReadonlySet<RxDBEntityId>;
+  /**
+   * 父链是否走到了尽头。
+   *
+   * `false` 表示中途有一环取不到实体 —— 集合**之外**的候选无从判定，只能回 SQL；
+   * 集合**之内**的候选仍是确定的 `true`（走链在断点之前就已经经过它）。
+   */
+  complete: boolean;
+}
+
+/**
+ * 用预先收集的祖先集合判定单个候选实体（`count` 口径）
+ *
+ * @param ancestors {@link TreeHelper.collectAncestorIdsForCount} 的结果
+ * @param candidateEntity 候选祖先实体
+ * @returns true=是祖先, false=不是祖先, undefined=无法确定（调用方回 SQL 重算）
+ */
+export const resolveAncestorForCount = <T extends EntityType>(
+  ancestors: TreeAncestorIdSet,
+  candidateEntity: InstanceType<T> | null | undefined
+): boolean | undefined => {
+  const candidateId = getEntityId(candidateEntity);
+  if (candidateId === undefined) {
+    return undefined; // 候选实体ID不存在
+  }
+  if (ancestors.ids.has(candidateId)) {
+    return true;
+  }
+  return ancestors.complete ? false : undefined;
+};
+
+/**
+ * 树形结构辅助函数管理器
+ *
+ * 提供树形查询所需的核心功能：
+ * - 解析父实体引用
+ * - 判断后代/祖先关系（普通 + count 专用变体）
+ * - 支持层级限制和循环检测
+ *
+ * @template T 实体类型
+ *
+ * @internal 由 merge-update-tree.ts 的 handle*Update 函数使用
+ */
+export class TreeHelper<T extends EntityType> {
+  constructor(
+    private cache: UpdateDataCache<T>,
+    private oldResultMap: Map<RxDBEntityId, InstanceType<T>>
+  ) {}
+
+  /**
+   * 解析父实体
+   *
+   * 从更新缓存或旧结果集中获取父实体，避免重复查询数据库
+   *
+   * @param id 父实体ID
+   * @returns 父实体实例，如果不存在则返回 undefined
+   *
+   * @remarks
+   * **更新缓存优先，旧结果集兜后**。`oldResultMap` 是本批事件**之前**的快照；
+   * 同一批里父节点自己也被移动时（`Y.parentId A→null` 与 `M.parentId Z→Y` 同批到达），
+   * 先读旧结果集会顺着过期的 `parentId` 往上走，把已经移出子树的节点判成仍在子树内。
+   * `cache.getSerializedUpdate` 给的是本批应用后的状态，与 `merge-update-tree.ts`
+   * 孤儿复查里的 `resolveParent` 同口径。
+   */
+  resolveParentEntity(id: RxDBEntityId): InstanceType<T> | undefined {
+    // 本批更新后的状态优先
+    const serialized = this.cache.getSerializedUpdate(id);
+    if (serialized) {
+      this.oldResultMap.set(id, serialized);
+      return serialized;
+    }
+    // 未被本批更新：回旧结果集取已序列化的实体
+    return this.oldResultMap.get(id);
+  }
+
+  /**
+   * 检查实体是否是目标实体的后代
+   *
+   * 从实体向上遍历父级链，检查是否能到达目标实体
+   * 包含循环检测，防止无限递归
+   *
+   * @param entity 要检查的实体
+   * @param targetEntityId 目标实体ID (潜在的祖先)，为 null 或 undefined 时表示查找所有树（所有节点都有效）
+   * @returns 包含是否为后代和层级深度的对象
+   */
+  isEntityDescendant(
+    entity: InstanceType<T>,
+    targetEntityId: RxDBEntityId | null | undefined
+  ): { isDescendant: boolean; level: number } {
+    // 特殊情况：当 targetEntityId 为 null 或 undefined 时，表示查询所有树
+    // 此时所有节点都是有效的（包括根节点和子节点）
+    if (targetEntityId === null || targetEntityId === undefined) {
+      // 计算层级：根节点层级为 0，子节点层级根据到根节点的距离计算
+      let currentParentId = get_tree_parent_id<RxDBEntityId>(entity);
+      let level = 0;
+      const visited = new Set<RxDBEntityId>();
+
+      while (currentParentId !== null && !visited.has(currentParentId)) {
+        level++;
+        visited.add(currentParentId);
+        const parent = this.resolveParentEntity(currentParentId);
+        if (parent) {
+          currentParentId = get_tree_parent_id<RxDBEntityId>(parent);
+        } else {
+          break;
+        }
+      }
+
+      return { isDescendant: true, level };
+    }
+
+    let currentParentId = get_tree_parent_id<RxDBEntityId>(entity);
+    const visited = new Set<RxDBEntityId>(); // 防止循环引用
+    let currentLevel = 0;
+
+    // 向上遍历父级链
+    while (currentParentId !== null && !visited.has(currentParentId)) {
+      currentLevel++;
+      // 找到目标实体，确认是后代
+      if (currentParentId === targetEntityId) {
+        return { isDescendant: true, level: currentLevel };
+      }
+      visited.add(currentParentId);
+
+      // 解析并继续向上查找
+      const parent = this.resolveParentEntity(currentParentId);
+      if (parent) {
+        currentParentId = get_tree_parent_id<RxDBEntityId>(parent);
+      } else {
+        break; // 父实体不存在，停止遍历
+      }
+    }
+    return { isDescendant: false, level: 0 };
+  }
+
+  /**
+   * 检查实体是否是目标的祖先
+   *
+   * 从目标实体向上遍历父级链，检查是否能到达候选实体
+   *
+   * @param targetEntity 目标实体 (要查找其祖先)
+   * @param candidateEntity 候选祖先实体
+   * @param maxLevel 层级上限，口径同 `FindTreeOptions.level`：目标自身为 0、父节点为 1。
+   *   `undefined` 表示不限层级。
+   * @returns true 表示候选实体是目标的祖先
+   *
+   * @remarks
+   * `maxLevel` 不是可选的性能优化，而是正确性要求：调用方给了 `level` 时，
+   * 适配器的递归成员带 `c.__level < level`，`__level` 超出上限的祖先 SQL 根本不会返回；
+   * 这里不跟着截断就会把深处的祖先并进增量结果，与全量刷新分叉。
+   * 调用方没给 `level`（不限深度）时传 `undefined`，两边都走到根。
+   */
+  isEntityAncestor(targetEntity: InstanceType<T>, candidateEntity: InstanceType<T>, maxLevel?: number): boolean {
+    const candidateId = getEntityId(candidateEntity);
+    if (candidateId === undefined) {
+      return false;
+    }
+
+    // 实体不是自己的祖先
+    if (candidateId === getEntityId(targetEntity)) {
+      return false;
+    }
+
+    let currentParentId = get_tree_parent_id<RxDBEntityId>(targetEntity);
+    const visited = new Set<RxDBEntityId>(); // 防止循环引用
+    let level = 0; // 距目标实体的跳数：父节点为 1
+
+    // 从目标实体向上遍历
+    while (currentParentId !== null && !visited.has(currentParentId)) {
+      level++;
+      // 超出层级上限：再往上的节点 SQL 都不会返回，无需继续遍历
+      if (maxLevel !== undefined && level > maxLevel) {
+        return false;
+      }
+      // 找到候选实体，确认是祖先
+      if (currentParentId === candidateId) {
+        return true;
+      }
+      visited.add(currentParentId);
+
+      // 解析并继续向上查找
+      const parent = this.resolveParentEntity(currentParentId);
+      if (parent) {
+        currentParentId = get_tree_parent_id<RxDBEntityId>(parent);
+      } else {
+        break; // 父实体不存在，停止遍历
+      }
+    }
+
+    return false; // 未找到候选实体
+  }
+
+  /**
+   * 检查实体是否是目标的后代 (用于 count 查询)
+   *
+   * 与 isEntityDescendant 类似，但返回 undefined 表示无法确定
+   * 当父实体链中有实体不在更新数据中时，无法继续追踪，返回 undefined
+   * 此时需要触发 SQL 刷新以获取准确结果
+   *
+   * @param entity 要检查的实体
+   * @param targetEntityId 目标实体ID，为 null 或 undefined 时表示查找所有树（所有节点都有效）
+   * @returns true=是后代, false=不是后代, undefined=无法确定
+   */
+  isEntityDescendantForCount(
+    entity: InstanceType<T> | null | undefined,
+    targetEntityId: RxDBEntityId | null | undefined
+  ): boolean | undefined {
+    if (!entity) {
+      return undefined; // 实体不存在，无法判断
+    }
+
+    // 特殊情况：当 targetEntityId 为 null 或 undefined 时，表示查询所有树
+    // 此时所有节点都是有效的（包括根节点和子节点）
+    if (targetEntityId === null || targetEntityId === undefined) {
+      return true;
+    }
+
+    let currentParentId = get_tree_parent_id<RxDBEntityId>(entity);
+    const visited = new Set<RxDBEntityId>(); // 防止循环引用
+
+    while (currentParentId !== null && !visited.has(currentParentId)) {
+      // 找到目标实体，确认是后代
+      if (currentParentId === targetEntityId) {
+        return true;
+      }
+      visited.add(currentParentId);
+
+      // 尝试从更新数据中获取父实体
+      const parentEntity = this.cache.getSerializedUpdate(currentParentId);
+      if (parentEntity) {
+        currentParentId = get_tree_parent_id<RxDBEntityId>(parentEntity);
+      } else {
+        // 父实体不在更新数据中，无法继续追踪，返回 undefined
+        return undefined;
+      }
+    }
+
+    return false; // 到达根节点仍未找到目标实体
+  }
+
+  /**
+   * 计算实体相对目标实体的后代深度 (用于 count 查询)
+   *
+   * @param entity 要检查的实体
+   * @param targetEntityId 目标实体ID；为 null 或 undefined 时表示查询所有树，深度从根节点算起
+   * @returns `{ isDescendant, depth }`；无法确定时返回 `undefined`
+   *
+   * @remarks
+   * {@link isEntityDescendantForCount} 只回答「是不是后代」，答不出「隔了几层」，
+   * 于是 `countDescendants` 的 `level` 限制在增量合并里整个缺席：`{ entityId, level: 0 }`
+   * （只数目标节点自己，后代一个都不算）会被一个直接子节点的 where 翻转加成 1。
+   *
+   * 深度口径与 `FindTreeOptions.level` 一致：给了 `entityId` 时目标节点自身深度为 0、
+   * 直接子节点为 1；没给 `entityId` 时根节点深度为 0。调用方用 `depth <= level` 过滤。
+   *
+   * 与 {@link isEntityDescendantForCount} 一样，父链上任何一环取不到就返回 `undefined`
+   * 让调用方回 SQL 重算 —— 深度算不准时不能猜。
+   */
+  descendantDepthForCount(
+    entity: InstanceType<T> | null | undefined,
+    targetEntityId: RxDBEntityId | null | undefined
+  ): { isDescendant: boolean; depth: number } | undefined {
+    if (!entity) {
+      return undefined; // 实体不存在，无法判断
+    }
+
+    const findsWholeTree = targetEntityId === null || targetEntityId === undefined;
+    let currentParentId = get_tree_parent_id<RxDBEntityId>(entity);
+    const visited = new Set<RxDBEntityId>(); // 防止循环引用
+    let depth = 0;
+
+    while (currentParentId !== null && !visited.has(currentParentId)) {
+      depth++;
+      if (!findsWholeTree && currentParentId === targetEntityId) {
+        return { isDescendant: true, depth };
+      }
+      visited.add(currentParentId);
+
+      // 尝试从更新数据中获取父实体
+      const parentEntity = this.cache.getSerializedUpdate(currentParentId);
+      if (!parentEntity) {
+        return undefined; // 父实体不在更新数据中，深度无从算起
+      }
+      currentParentId = get_tree_parent_id<RxDBEntityId>(parentEntity);
+    }
+
+    // 走到根节点：查全树时任何节点都算命中，深度即到根的距离；限定了目标则说明不是它的后代
+    return findsWholeTree ? { isDescendant: true, depth } : { isDescendant: false, depth };
+  }
+
+  /**
+   * 收集目标实体的祖先 id 集合 (用于 count 查询)
+   *
+   * @param targetEntity 目标实体（要查找其祖先）
+   * @param maxLevel 层级上限，口径同 {@link isEntityAncestor}；`undefined` 表示不限层级。
+   * @returns 祖先 id 集合 + 「父链是否完整」标记，交给 {@link resolveAncestorForCount} 判定候选
+   *
+   * @remarks
+   * `countAncestors` 的目标祖先链在一批事件内是**不变**的（目标自己改父会被调用方
+   * 提前 `refresh()` 拦掉），而这条链只取决于起点的 `parentId` 加逐跳的
+   * `cache.getSerializedUpdate` —— 对批内每个候选各走一遍是 O(N×depth) 的逐字节重复。
+   * 走一次建 Set，候选判定降到 O(1)。
+   *
+   * 与 {@link isEntityAncestor} 同因，`maxLevel` 不是性能优化而是正确性要求：
+   * `countAncestors` 数的是 `__level <= level` 的祖先，不带上限会把超深祖先也计进去。
+   * 超出 `maxLevel` 时停止收集并标记 `complete: true` —— 更上方的祖先 SQL 不会返回，
+   * 「不是祖先」是能确定的答案，不必为此回一次 SQL。只有父链中途取不到实体
+   * 才标记 `complete: false`。环由 `ids` 自身兜住，无需额外的跳数上限。
+   */
+  collectAncestorIdsForCount(targetEntity: InstanceType<T>, maxLevel?: number): TreeAncestorIdSet {
+    // `ids` 同时充当 visited：祖先链上的节点两种身份完全重合，环用它一并兜住
+    const ids = new Set<RxDBEntityId>();
+    let currentParentId = get_tree_parent_id<RxDBEntityId>(targetEntity);
+    let level = 0; // 距目标实体的跳数：父节点为 1
+
+    while (currentParentId !== null && !ids.has(currentParentId)) {
+      level++;
+      // 超出层级上限：SQL 不会返回更上方的祖先，链到此为止即可
+      if (maxLevel !== undefined && level > maxLevel) {
+        return { ids, complete: true };
+      }
+      ids.add(currentParentId);
+
+      // 尝试从更新数据中获取父实体
+      const parentEntity = this.cache.getSerializedUpdate(currentParentId);
+      if (!parentEntity) {
+        return { ids, complete: false }; // 父实体不在更新数据中，无法继续追踪
+      }
+      currentParentId = get_tree_parent_id<RxDBEntityId>(parentEntity);
+    }
+
+    return { ids, complete: true }; // 走到根节点，或被环截断
+  }
+}

package/src/query/tree-query.interface.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview 树查询任务类型
+ *
+ * 四个查询任务经 `RepositoryQueryExtensions` 的模块扩展并进核心的 `QueryOptions` 联合：
+ * 那是插件往闭合联合里加支的唯一入口。不装本插件的应用，`QueryOptions` 上没有这四支，
+ * `QueryTask.type` 也不会出现树类型 —— 这正是 US-025 阶段 E 要的「核心不内置树」。
+ */
+import { EntityType } from '@aiao/rxdb';
+import type { TreeQueryType } from '../constants.js';
+import { FindTreeOptions } from '../repository/tree-repository.interface.js';
+
+/**
+ * FindDescendants 查询任务
+ * 查找指定实体的所有后代节点
+ */
+export interface FindDescendantsQuery<T extends EntityType> {
+  type: Extract<TreeQueryType, 'findDescendants'>;
+  options: FindTreeOptions<T>;
+}
+
+/**
+ * FindAncestors 查询任务
+ * 查找指定实体的所有祖先节点
+ */
+export interface FindAncestorsQuery<T extends EntityType> {
+  type: Extract<TreeQueryType, 'findAncestors'>;
+  options: FindTreeOptions<T>;
+}
+
+/**
+ * CountDescendants 查询任务
+ * 统计指定实体的后代节点数量
+ */
+export interface CountDescendantsQuery<T extends EntityType> {
+  type: Extract<TreeQueryType, 'countDescendants'>;
+  options: FindTreeOptions<T>;
+}
+
+/**
+ * CountAncestors 查询任务
+ * 统计指定实体的祖先节点数量
+ */
+export interface CountAncestorsQuery<T extends EntityType> {
+  type: Extract<TreeQueryType, 'countAncestors'>;
+  options: FindTreeOptions<T>;
+}
+
+/**
+ * 四支树查询任务的联合。
+ *
+ * @remarks
+ * 与 {@link TreeQueryType} 的双向一致性由
+ * `__tests__/contracts/tree-query-type-parity.spec.ts` 钉死：这里加一支而
+ * {@link TREE_QUERY_TYPE_LIST} 没加（或反过来），那条断言编译失败。
+ */
+export type TreeQuery<T extends EntityType> =
+  FindDescendantsQuery<T> | FindAncestorsQuery<T> | CountDescendantsQuery<T> | CountAncestorsQuery<T>;
+
+declare module '@aiao/rxdb' {
+  interface RepositoryQueryExtensions<T extends EntityType> {
+    treeFindDescendants: FindDescendantsQuery<T>;
+    treeFindAncestors: FindAncestorsQuery<T>;
+    treeCountDescendants: CountDescendantsQuery<T>;
+    treeCountAncestors: CountAncestorsQuery<T>;
+  }
+}

package/src/repository/TreeRepository.ts

@@ -0,0 +1,133 @@
+import { EntityType, getFingerprintByEntities, getFingerprintPrimitive, Repository, RxDB } from '@aiao/rxdb';
+import { Observable, switchMap, tap } from 'rxjs';
+import { TREE_QUERY_TYPE_LIST, TREE_QUERY_TYPES } from '../constants.js';
+import { ITreeEntity } from '../entity/tree-entity.interface.js';
+import { merge_create } from '../query/merge_create.js';
+import { merge_remove } from '../query/merge_remove.js';
+import { merge_update } from '../query/merge_update.js';
+import { assertTreeLevel } from './tree-level.utils.js';
+import { FindTreeOptions, ITreeRepository } from './tree-repository.interface.js';
+
+/**
+ * 树结构实体仓库
+ * 根据配置决策实体的具体操作
+ *
+ * @template T - 必须是实现 ITreeEntity 接口的实体类型（通常继承 TreeAdjacencyListEntityBase）
+ *
+ * @example
+ * ```typescript
+ * // ✅ 正确：继承 TreeAdjacencyListEntityBase
+ * // 不必写 repository：`repository: 'TreeRepository'` 与 `features.tree` 都由基类声明，
+ * // 沿原型链继承下来（要覆盖就在自己的 @Entity 里显式声明）
+ * @Entity({ name: 'Category' })
+ * class Category extends TreeAdjacencyListEntityBase {
+ *   name!: string;
+ * }
+ *
+ * // 可以使用树查询方法
+ * Category.findDescendants({ entityId: 'root-id' });
+ * Category.findAncestors({ entityId: 'leaf-id' });
+ *
+ * // ❌ 错误：只继承 EntityBase，没有实现 ITreeEntity
+ * @Entity({ name: 'User' })
+ * class User extends EntityBase {
+ *   name!: string;
+ * }
+ *
+ * // 编译错误：User 不满足 TreeRepository 的类型约束
+ * // User.findDescendants({ entityId: 'id' }); // TypeScript 错误
+ * ```
+ */
+
+export class TreeRepository<
+  T extends EntityType & (new (...args: never[]) => ITreeEntity),
+  RepositoryType extends ITreeRepository<T> = ITreeRepository<T>
+> extends Repository<T, RepositoryType> {
+  // 直接摊开单一来源：挂到实体上的静态方法名与 merge 登记的 task 类型本就是同一批，
+  // 各写一份时漏掉这里 = 实体上根本没有这个查询方法。
+  protected static override _STATIC_METHODS = [...super._STATIC_METHODS, ...TREE_QUERY_TYPE_LIST];
+
+  constructor(rxdb: RxDB, EntityType: T) {
+    super(rxdb, EntityType);
+    // 四个树 task 类型各自登记增量 merge。核心的默认 merge 已不认识树类型，
+    // 这三行是树查询拿到增量行为的唯一入口；未登记的类型（findAll / count 等）
+    // 仍走核心默认实现。
+    TREE_QUERY_TYPES.forEach(type => {
+      this.queryManager.registerMergeCreateFn(type, merge_create);
+      this.queryManager.registerMergeUpdateFn(type, merge_update);
+      this.queryManager.registerMergeRemoveFn(type, merge_remove);
+    });
+  }
+
+  /**
+   * 查询子孙
+   */
+  findDescendants(options: FindTreeOptions<T>): Observable<InstanceType<T>[]> {
+    options = this.#normalizeOptions(options);
+    const runner = () =>
+      this.primary$.pipe(
+        switchMap(local => local.findDescendants(options)),
+        tap(this._setLocals)
+      );
+    return this.queryManager.createTask({
+      options: { type: 'findDescendants', options },
+      runner,
+      getFingerprint: getFingerprintByEntities
+    }).result$;
+  }
+
+  /**
+   * 查询子孙数量
+   */
+  countDescendants(options: FindTreeOptions<T>): Observable<number> {
+    options = this.#normalizeOptions(options);
+    const runner = () => this.primary$.pipe(switchMap(local => local.countDescendants(options)));
+    return this.queryManager.createTask({
+      options: { type: 'countDescendants', options },
+      runner,
+      getFingerprint: getFingerprintPrimitive
+    }).result$;
+  }
+
+  /**
+   * 查询祖先
+   */
+  findAncestors(options: FindTreeOptions<T>): Observable<InstanceType<T>[]> {
+    options = this.#normalizeOptions(options);
+    const runner = () =>
+      this.primary$.pipe(
+        switchMap(local => local.findAncestors(options)),
+        tap(this._setLocals)
+      );
+    return this.queryManager.createTask({
+      options: { type: 'findAncestors', options },
+      runner,
+      getFingerprint: getFingerprintByEntities
+    }).result$;
+  }
+
+  /**
+   * 查询祖先数量
+   */
+  countAncestors(options: FindTreeOptions<T>): Observable<number> {
+    options = this.#normalizeOptions(options);
+    const runner = () => this.primary$.pipe(switchMap(local => local.countAncestors(options)));
+    return this.queryManager.createTask({
+      options: { type: 'countAncestors', options },
+      runner,
+      getFingerprint: getFingerprintPrimitive
+    }).result$;
+  }
+
+  /**
+   * 归一查询选项。
+   *
+   * 两件事：`entityId` 的 `undefined` 与 `null` 在树语义里都表示「查全树」，统一成 `null`；
+   * `level` 交给 {@link assertTreeLevel} 校验后原样透传 —— 不传就是 `undefined`（不限深度），
+   * 非法值直接抛错。这里**不做裁剪**：把越界值悄悄改成边界值，只会让调用方拿到一份
+   * 自己没要过的结果，且掩盖掉注入探针。
+   */
+  #normalizeOptions(options: FindTreeOptions<T>): FindTreeOptions<T> {
+    return { ...options, level: assertTreeLevel(options.level), entityId: options.entityId ?? null };
+  }
+}

package/src/repository/tree-level.utils.ts

@@ -0,0 +1,14 @@
+import { assertOptionalNonNegativeSafeInteger } from '@aiao/rxdb';
+
+/**
+ * 校验树查询深度，未提供时保留不限深度的语义。
+ *
+ * @param level - 查询深度
+ * @returns 非负安全整数；未提供时返回 `undefined`
+ * @throws 当深度不是非负安全整数时抛出 `RxDBError`
+ */
+export const assertTreeLevel = (level: number | undefined): number | undefined =>
+  assertOptionalNonNegativeSafeInteger(
+    level,
+    `tree query 'level' must be a non-negative integer, received: ${String(level)}`
+  );

package/src/repository/tree-repository.interface.ts

@@ -0,0 +1,76 @@
+import { EntityStaticType, EntityType, IRepository, RuleGroup } from '@aiao/rxdb';
+
+/**
+ * 树结构查询配置
+ */
+export interface FindTreeOptions<T extends EntityType = EntityType, WhereType = RuleGroup<InstanceType<T>>> {
+  /**
+   * 查询的根实体 ID
+   */
+  entityId?: EntityStaticType<T, 'idType'> | null;
+
+  /**
+   * 查询条件
+   */
+  where?: WhereType;
+
+  /**
+   * 查询深度（层级数包含当前节点本身）
+   *
+   * - 不传：**不限深度** —— `findDescendants` 返回整棵子树、`findAncestors` 返回整条祖先链
+   * - `0`：仅当前节点（`entityId` 为空时即所有根节点）
+   * - `1`：当前节点 + 直接子节点
+   * - `n`：查询到第 n 层深度
+   *
+   * @defaultValue `undefined`（不限深度）
+   *
+   * @remarks
+   * 不裁剪、不兜底：非负整数以外的值（负数、小数、`NaN`、字符串）一律抛 `RxDBError`。
+   * `level` 是树查询里唯一被直接插值进递归 CTE 比较式的选项，悄悄改写它等于把注入
+   * 变成一次静默的错误查询。插件的 `assertTreeLevel` 与各适配器复用核心的通用数值校验，
+   * 绕过 Repository 直接调适配器时同样抛错。
+   *
+   * 不传时递归深度由各 SQL 适配器内部的失控保护常量兜底（防脏数据把 `parentId` 连成环），
+   * 那是实现细节而非查询语义：正常树不会触到。
+   */
+  level?: number;
+}
+
+/**
+ * 树结构仓库接口
+ */
+export interface ITreeRepository<T extends EntityType> extends IRepository<T> {
+  /**
+   * 查询子孙实体
+   *
+   * @remarks
+   * - 指定 entityId 时：包含当前节点 + 子孙节点
+   * - 不指定 entityId 时：返回所有根节点及其子孙
+   */
+  findDescendants(options: FindTreeOptions<T>): Promise<InstanceType<T>[]>;
+
+  /**
+   * 查询子孙实体数量
+   *
+   * @remarks
+   * - 指定 entityId 时：**不包含当前节点**，只统计后代数量
+   * - 不指定 entityId 时：统计所有根节点及其后代的总数
+   */
+  countDescendants(options: FindTreeOptions<T>): Promise<number>;
+
+  /**
+   * 查询祖先节点
+   *
+   * @remarks
+   * 指定 entityId 时：包含当前节点 + 祖先节点
+   */
+  findAncestors(options: FindTreeOptions<T>): Promise<InstanceType<T>[]>;
+
+  /**
+   * 查询祖先节点数量
+   *
+   * @remarks
+   * 指定 entityId 时：**不包含当前节点**，只统计祖先数量
+   */
+  countAncestors(options: FindTreeOptions<T>): Promise<number>;
+}