@zucker-framework/crud 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1334 @@
+import { Term, DatabaseAdapter, GenericEntity, TreeSortSupportEntity, TreePathStrategy, TransactionAwareDatabaseAdapter, ModelOperations, ValidationSchema } from '@zucker-framework/core';
+export { DATABASE_ADAPTER } from '@zucker-framework/core';
+import { Logger, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { TopicEventBus, EntityEventType, EntityEventPhase, EntityEvent } from '@zucker-framework/event';
+import { ICache } from '@zucker-framework/cache';
+
+type FilterOperatorType = 'eq' | 'neq' | 'like' | 'notLike' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'isNull' | 'isNotNull' | 'between' | 'has' | 'hasSome' | 'empty' | 'notEmpty';
+interface IFilterOperator {
+    readonly operatorType: FilterOperatorType;
+    apply(field: string, value: unknown): Record<string, unknown> | null;
+}
+declare const FILTER_OPERATORS = "FILTER_OPERATORS";
+declare class EqualsOperator implements IFilterOperator {
+    readonly operatorType: "eq";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class NotEqualsOperator implements IFilterOperator {
+    readonly operatorType: "neq";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class LikeOperator implements IFilterOperator {
+    readonly operatorType: "like";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class ContainsOperator implements IFilterOperator {
+    readonly operatorType: "contains";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class GtOperator implements IFilterOperator {
+    readonly operatorType: "gt";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class GteOperator implements IFilterOperator {
+    readonly operatorType: "gte";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class LtOperator implements IFilterOperator {
+    readonly operatorType: "lt";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class LteOperator implements IFilterOperator {
+    readonly operatorType: "lte";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class InOperator implements IFilterOperator {
+    readonly operatorType: "in";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class NotInOperator implements IFilterOperator {
+    readonly operatorType: "notIn";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class IsNullOperator implements IFilterOperator {
+    readonly operatorType: "isNull";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class BetweenOperator implements IFilterOperator {
+    readonly operatorType: "between";
+    apply(field: string, value: unknown): Record<string, unknown> | null;
+}
+declare class HasOperator implements IFilterOperator {
+    readonly operatorType: "has";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class HasSomeOperator implements IFilterOperator {
+    readonly operatorType: "hasSome";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class NotLikeOperator implements IFilterOperator {
+    readonly operatorType: "notLike";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class StartsWithOperator implements IFilterOperator {
+    readonly operatorType: "startsWith";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class EndsWithOperator implements IFilterOperator {
+    readonly operatorType: "endsWith";
+    apply(field: string, value: unknown): Record<string, unknown>;
+}
+declare class IsNotNullOperator implements IFilterOperator {
+    readonly operatorType: "isNotNull";
+    apply(field: string, _value: unknown): Record<string, unknown>;
+}
+declare class EmptyOperator implements IFilterOperator {
+    readonly operatorType: "empty";
+    apply(field: string, _value: unknown): Record<string, unknown>;
+}
+declare class NotEmptyOperator implements IFilterOperator {
+    readonly operatorType: "notEmpty";
+    apply(field: string, _value: unknown): Record<string, unknown>;
+}
+declare const ALL_OPERATORS: (typeof EqualsOperator | typeof NotEqualsOperator | typeof LikeOperator | typeof ContainsOperator | typeof GtOperator | typeof GteOperator | typeof LtOperator | typeof LteOperator | typeof InOperator | typeof NotInOperator | typeof IsNullOperator | typeof BetweenOperator | typeof HasOperator | typeof HasSomeOperator | typeof NotLikeOperator | typeof StartsWithOperator | typeof EndsWithOperator | typeof IsNotNullOperator | typeof EmptyOperator | typeof NotEmptyOperator)[];
+declare class FilterOperatorFactory {
+    private readonly operators;
+    private readonly logger;
+    private readonly operatorMap;
+    constructor(operators: IFilterOperator[]);
+    /** Normalize hyphen-style aliases (e.g. 'is-null' → 'isNull') to camelCase keys */
+    private normalizeType;
+    getOperator(operatorType: string): IFilterOperator | null;
+    applyFilter(field: string, operatorType: string, value: unknown): Record<string, unknown> | null;
+    getSupportedOperators(): FilterOperatorType[];
+    isOperatorSupported(operatorType: string): boolean;
+}
+
+/**
+ * 将 WHERE 表达式解析为 Term[]
+ * 支持: =, !=, >, <, >=, <=, like, not-like, in, not-in, is-null, is-not-null
+ * 支持: and, or 连接
+ * 支持: 字符串值用单引号包裹
+ *
+ * 例: "name = '张三' and age > 16"
+ */
+declare function parseExpression(expression: string): Term[];
+/**
+ * 将 {"field$operator": value} 格式解析为 Term[]
+ * 如 {"name$like": "张"} -> [{column: "name", termType: "like", value: "张"}]
+ * 没有 $ 的 key 默认 eq 操作符
+ * $or$ 前缀表示 or 连接
+ * $nest / $orNest 前缀表示嵌套条件
+ */
+declare function parseFilterMap(filterMap: Record<string, unknown>): Term[];
+
+/**
+ * 完整的 SQL-like 表达式解析器
+ * 支持运算符：=, !=, >, >=, <, <=, like, in, not in, between, is null, is not null
+ * 支持 AND/OR 组合和括号嵌套
+ *
+ * 示例: "name = '张三' and (age > 16 or status in ('active', 'pending'))"
+ */
+declare class TermExpressionParser {
+    private tokens;
+    private pos;
+    /**
+     * 解析排序表达式
+     * 例: "age asc,score desc"
+     * @returns 排序数组 [{name: 'age', order: 'asc'}, {name: 'score', order: 'desc'}]
+     */
+    static parseOrder(expression: string): Array<{
+        name: string;
+        order: 'asc' | 'desc';
+    }>;
+    /**
+     * 解析 Map 为 Term[]
+     *
+     * 格式:
+     * - {"name$like": "张三"} -> column=name, termType=like, value=张三
+     * - {"$or$status$in": [1,2,3]} -> or 连接, column=status, termType=in
+     * - {"$nest": {"age$gt": 10}} -> 嵌套条件
+     * - {"$orNest": {"age$gt": 10}} -> or 嵌套条件
+     */
+    static parseMap(map: Record<string, unknown>): Term[];
+    /**
+     * 解析 SQL-like 表达式为 Term[]
+     */
+    parse(expression: string): Term[];
+    /** 解析 OR 层级 */
+    private parseOrExpression;
+    /** 解析 AND 层级 */
+    private parseAndExpression;
+    /** 解析基本表达式：括号分组或单个条件 */
+    private parsePrimary;
+    /** 解析单个条件表达式 */
+    private parseCondition;
+    /** 解析括号包裹的值列表: ('a', 'b', 'c') */
+    private parseValueList;
+    /** 解析单个标量值 */
+    private parseScalarValue;
+    private matchKeyword;
+    private expectKeyword;
+    private match;
+    private expect;
+    private expectToken;
+    private expectValue;
+    private peek;
+    private nextToken;
+    private error;
+    private convertOperator;
+    private tokenize;
+    private isIdentStart;
+    private isIdentPart;
+}
+
+/**
+ * Pagination utilities for dynamic query results.
+ */
+
+/**
+ * Paginated query result containing data and pagination metadata.
+ * @template T - The type of each data item
+ */
+interface PaginatedResult<T> {
+    /** The data items for the current page */
+    data: T[];
+    /** Total number of matching records */
+    total: number;
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of pages */
+    totalPages: number;
+    /**
+     * 0-based page index, equal to page - 1.
+     */
+    pageIndex: number;
+}
+/**
+ * SaveResult
+ * Represents the outcome of a batch save (upsert) operation.
+ */
+interface SaveResult {
+    /** Number of newly created records */
+    created: number;
+    /** Number of updated records */
+    updated: number;
+    /** Total number of affected records (created + updated) */
+    total: number;
+}
+/**
+ * Create an empty PaginatedResult.
+ */
+declare function emptyPagerResult<T>(): PaginatedResult<T>;
+/**
+ * Merge two SaveResults.
+ */
+declare function mergeSaveResult(a: SaveResult, b: SaveResult): SaveResult;
+/**
+ * Adjust pagination parameters based on total count.
+ * If the current page exceeds total pages, automatically adjusts to the last page.
+ * @param queryParam - The original query parameters
+ * @param totalCount - The total number of matching records
+ * @returns Adjusted query parameters with corrected page number
+ */
+declare function rePaging(queryParam: DynamicQueryParam, totalCount: number): DynamicQueryParam;
+/**
+ * Create a query parameter with pagination disabled.
+ * @param queryParam - Optional base query parameters
+ * @returns Query parameters with page and pageSize set to undefined
+ */
+declare function noPaging(queryParam?: DynamicQueryParam): DynamicQueryParam;
+/**
+ * Check whether the query parameters have pagination enabled.
+ * @param queryParam - The query parameters to check
+ * @returns True if both page and pageSize are defined
+ */
+declare function isPaged(queryParam: DynamicQueryParam): boolean;
+/**
+ * Build a PaginatedResult from raw data and pagination metadata.
+ * @param data - The data items for the current page
+ * @param total - Total number of matching records
+ * @param page - Current page number (1-based)
+ * @param pageSize - Number of items per page
+ * @returns A complete PaginatedResult
+ */
+declare function toPaginatedResult<T>(data: T[], total: number, page: number, pageSize: number): PaginatedResult<T>;
+/**
+ * Calculate the total number of pages.
+ * @param total - Total number of records
+ * @param pageSize - Number of items per page
+ * @returns The total number of pages
+ */
+declare function calculateTotalPages(total: number, pageSize: number): number;
+
+/**
+ * Dynamic query parameter — describes filter, sort, pagination, and field selection
+ * for dynamic queries.
+ *
+ * @example
+ * ```ts
+ * const query: DynamicQueryParam = {
+ *   filters: '{"name$like":"Alice"}',
+ *   orderBy: 'createdAt desc',
+ *   page: 1,
+ *   pageSize: 20,
+ * };
+ * ```
+ */
+interface DynamicQueryParam {
+    /** JSON-encoded filter map (e.g., '{"name$like":"value"}') */
+    filters?: string;
+    /** Raw where clause string */
+    where?: string;
+    /** Structured filter object */
+    filter?: Record<string, unknown>;
+    /** Sort expression (e.g., 'createdAt desc,name asc') */
+    orderBy?: string;
+    /** Page number (1-based) */
+    page?: number;
+    /** Page index (0-based), 与 page 二选一，pageIndex 优先级高于 page */
+    pageIndex?: number;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Pre-computed total count (skips COUNT query when provided) */
+    total?: number;
+    /** Fields to include in the result */
+    includes?: string[];
+    /** Fields to exclude from the result */
+    excludes?: string[];
+    /** Whether to run COUNT and SELECT queries in parallel */
+    parallelPager?: boolean;
+    /** Structured Term conditions  */
+    terms?: Term[];
+}
+/**
+ * Service for parsing dynamic query parameters into Prisma-compatible query arguments.
+ * Handles filter maps, sort expressions, pagination, and field selection.
+ */
+declare class DynamicQueryParamService {
+    private readonly operatorFactory;
+    private readonly logger;
+    constructor(operatorFactory: FilterOperatorFactory);
+    /**
+     * 解析查询条件（filter map 格式: {"name$like": "张三"}）
+     *
+     * 支持：
+     * - 普通字段：{ "name$like": "张三" } → AND 条件
+     * - OR 前缀：{ "$or$role": "admin" } → OR 条件（与同级其他条件 OR）
+     * - 嵌套 AND 组：{ "$nest": { ... } } → 递归解析，AND 到外层
+     * - 嵌套 OR 组：{ "$orNest": { ... } } → 递归解析，OR 到外层
+     */
+    parseFilters(filters?: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * 解析排序
+     * @param orderBy 排序字符串，格式：'field1 desc,field2 asc'
+     * @param defaultField 默认排序字段
+     */
+    parseOrderBy(orderBy?: string, defaultField?: string): Record<string, string>[];
+    /**
+     * 解析分页参数
+     */
+    parsePagination(page?: number, pageSize?: number): {
+        skip: number;
+        take: number;
+    };
+    /**
+     * 解析字段选择
+     */
+    parseSelect(includes?: string[], excludes?: string[]): Record<string, boolean> | undefined;
+    /**
+     * 将 DataAccess Term[] 转换为 Prisma WHERE 条件
+     *
+     * Term 是 Zucker 统一的过滤条件格式（column + termType + value），
+     * 由 DataAccessHandler 生成，需注入到查询中以实现行级数据权限。
+     *
+     * @param terms DataAccess 产生的过滤条件
+     * @returns Prisma 兼容的 WHERE 条件对象
+     */
+    termsToWhere(terms: Term[]): Record<string, unknown>;
+}
+/**
+ * Service for executing dynamic queries with automatic filter parsing,
+ * sorting, pagination, and field selection. Supports parallel paging
+ * and total count reuse for optimized queries.
+ */
+declare class DynamicQueryService {
+    private readonly db;
+    private readonly dynamicQueryParam;
+    private readonly logger;
+    constructor(db: DatabaseAdapter, dynamicQueryParam: DynamicQueryParamService);
+    /**
+     * 通用分页查询
+     * @param model 模型名称
+     * @param queryParam 查询参数
+     * @param defaultOrderField 默认排序字段
+     * @param dataAccessTerms DataAccess 产生的过滤条件（由 DataPermissionGuard 注入）
+     * @param denyFields DataAccess 产生的禁止字段列表
+     * @returns 分页查询结果
+     */
+    findMany<T = unknown>(model: string, queryParam: DynamicQueryParam, defaultOrderField?: string, dataAccessTerms?: Term[], denyFields?: string[]): Promise<PaginatedResult<T>>;
+    /**
+     * 查询单条记录
+     */
+    findOne(model: string, id: string, includes?: string[], excludes?: string[]): Promise<unknown>;
+}
+
+/**
+ * DynamicQueryParam 的增强封装类
+ * - 静态工厂方法: of(), newQuery()
+ * - 链式操作: noPaging(), doNotSort(), clone(), rePaging(total)
+ * - 嵌套查询转换: toNestQuery()
+ * - DSL 构建: and(), or()
+ *
+ * 内部以 terms 为唯一权威表示，where/filter/filters 只是输入或序列化形式。
+ */
+declare class QueryParamEntity implements DynamicQueryParam {
+    private _filters?;
+    private _where?;
+    private _filter?;
+    orderBy?: string;
+    page?: number;
+    pageSize?: number;
+    total?: number;
+    includes?: string[];
+    excludes?: string[];
+    parallelPager?: boolean;
+    private _terms;
+    private _termsInitialized;
+    private _noPaging;
+    private _noSort;
+    constructor(param?: DynamicQueryParam);
+    get filters(): string | undefined;
+    set filters(value: string | undefined);
+    get where(): string | undefined;
+    set where(value: string | undefined);
+    get filter(): Record<string, unknown> | undefined;
+    set filter(value: Record<string, unknown> | undefined);
+    get terms(): Term[] | undefined;
+    set terms(value: Term[] | undefined);
+    /**
+     * 创建一个空的查询参数实体
+     */
+    static of(): QueryParamEntity;
+    /**
+     * 基于已有参数创建查询参数实体
+     */
+    static of(param: DynamicQueryParam): QueryParamEntity;
+    /**
+     * 创建带单个 eq 条件的查询参数
+     */
+    static of(field: string, value: unknown): QueryParamEntity;
+    /**
+     * 创建新的链式查询构建器
+     */
+    static newQuery(): QueryParamEntity;
+    /**
+     * 添加 AND 条件
+     * @param column 字段名
+     * @param termType 操作符 (eq, like, gt, in, etc.)
+     * @param value 值
+     */
+    and(column: string, termType: string, value: unknown): this;
+    /**
+     * 添加 OR 条件
+     */
+    or(column: string, termType: string, value: unknown): this;
+    /**
+     * 将已有条件包装到嵌套条件里，并返回自身用于继续添加外层条件。
+     */
+    toNestQuery(): this;
+    /** 禁用分页，查询全部数据 */
+    noPaging(): this;
+    /** 禁用排序 */
+    doNotSort(): this;
+    /** 深拷贝当前查询参数 */
+    clone(): QueryParamEntity;
+    /**
+     * 根据总数重新计算分页
+     * 根据总数重新分页：
+     * - 缓存 total 到实例，后续分页查询跳过 count
+     * - 如果当前页超过总页数，自动跳转到最后一页
+     */
+    rePaging(total: number): this;
+    /** 设置分页参数 */
+    withPage(page: number, pageSize?: number): this;
+    /** 设置排序 */
+    withOrderBy(orderBy: string): this;
+    /** 添加过滤条件 */
+    withFilter(key: string, value: unknown): this;
+    /** 设置 includes（要查询的列） */
+    withIncludes(...fields: string[]): this;
+    /** 设置 excludes（不查询的列） */
+    withExcludes(...fields: string[]): this;
+    /** 是否禁用分页 */
+    get isPagingDisabled(): boolean;
+    /** 是否禁用排序 */
+    get isSortDisabled(): boolean;
+    /**
+     * 获取 0 基索引的页码（用于 PagerResult）
+     */
+    getThinkPageIndex(): number;
+    getTerms(): Term[];
+    private ensureTermsInitialized;
+    /** 将 _terms 同步到 filter map 格式 */
+    private syncFilterFromTerms;
+    private serializeTermsToFilterMap;
+    private cloneTerm;
+    private cloneValue;
+}
+
+/**
+ * 链式查询构建器接口
+ */
+interface IQueryBuilder<T extends GenericEntity> {
+    where<K extends string & keyof T>(field: K, op: string, value: unknown): IQueryBuilder<T>;
+    whereEq<K extends string & keyof T>(field: K, value: T[K]): IQueryBuilder<T>;
+    in<K extends string & keyof T>(field: K, values: unknown[]): IQueryBuilder<T>;
+    notIn<K extends string & keyof T>(field: K, values: unknown[]): IQueryBuilder<T>;
+    like<K extends string & keyof T>(field: K, value: string): IQueryBuilder<T>;
+    notLike<K extends string & keyof T>(field: K, value: string): IQueryBuilder<T>;
+    startsWith<K extends string & keyof T>(field: K, value: string): IQueryBuilder<T>;
+    endsWith<K extends string & keyof T>(field: K, value: string): IQueryBuilder<T>;
+    isNull<K extends string & keyof T>(field: K): IQueryBuilder<T>;
+    isNotNull<K extends string & keyof T>(field: K): IQueryBuilder<T>;
+    between<K extends string & keyof T>(field: K, low: unknown, high: unknown): IQueryBuilder<T>;
+    and(fn: (q: IQueryBuilder<T>) => IQueryBuilder<T>): IQueryBuilder<T>;
+    or(fn: (q: IQueryBuilder<T>) => IQueryBuilder<T>): IQueryBuilder<T>;
+    orderBy<K extends string & keyof T>(field: K, direction?: 'asc' | 'desc'): IQueryBuilder<T>;
+    select(...fields: Array<string & keyof T>): IQueryBuilder<T>;
+    distinct(...fields: Array<string & keyof T>): IQueryBuilder<T>;
+    groupBy(...fields: Array<string & keyof T>): IQueryBuilder<T>;
+    having(field: string, op: string, value: unknown): IQueryBuilder<T>;
+    exists(relation: string, fn?: (q: IQueryBuilder<any>) => IQueryBuilder<any>): IQueryBuilder<T>;
+    notExists(relation: string, fn?: (q: IQueryBuilder<any>) => IQueryBuilder<any>): IQueryBuilder<T>;
+    limit(n: number): IQueryBuilder<T>;
+    offset(n: number): IQueryBuilder<T>;
+    include(relation: string): IQueryBuilder<T>;
+    join(model: string): IJoinClause<T>;
+    fetch(): Promise<T[]>;
+    fetchOne(): Promise<T | null>;
+    count(): Promise<number>;
+    aggregate(args: AggregateQueryArgs): Promise<any>;
+    fetchGroupBy(args: GroupByQueryArgs): Promise<any[]>;
+}
+/** 聚合查询参数 */
+interface AggregateQueryArgs {
+    _count?: Record<string, boolean> | boolean;
+    _sum?: Record<string, boolean>;
+    _avg?: Record<string, boolean>;
+    _min?: Record<string, boolean>;
+    _max?: Record<string, boolean>;
+}
+/** groupBy 查询参数 */
+interface GroupByQueryArgs {
+    by: string[];
+    _count?: Record<string, boolean> | boolean;
+    _sum?: Record<string, boolean>;
+    _avg?: Record<string, boolean>;
+    _min?: Record<string, boolean>;
+    _max?: Record<string, boolean>;
+}
+/** JOIN 子句接口 */
+interface IJoinClause<T extends GenericEntity> {
+    on(localField: string, foreignField: string): IQueryBuilder<T>;
+}
+/**
+ * 链式查询构建器实现
+ * 通过 DatabaseAdapter 执行查询，将链式 API 转换为 Prisma 兼容的查询参数
+ */
+declare class QueryBuilder<T extends GenericEntity> implements IQueryBuilder<T> {
+    private readonly db;
+    private readonly modelName;
+    private _conditions;
+    private _orderBy;
+    private _selectFields;
+    private _distinctFields;
+    private _groupByFields;
+    private _havingConditions;
+    private _existsConditions;
+    private _limit?;
+    private _offset?;
+    private _includes;
+    private _joins;
+    constructor(db: DatabaseAdapter, modelName: string);
+    where<K extends string & keyof T>(field: K, op: string, value: unknown): this;
+    whereEq<K extends string & keyof T>(field: K, value: T[K]): this;
+    in<K extends string & keyof T>(field: K, values: unknown[]): this;
+    notIn<K extends string & keyof T>(field: K, values: unknown[]): this;
+    like<K extends string & keyof T>(field: K, value: string): this;
+    notLike<K extends string & keyof T>(field: K, value: string): this;
+    startsWith<K extends string & keyof T>(field: K, value: string): this;
+    endsWith<K extends string & keyof T>(field: K, value: string): this;
+    isNull<K extends string & keyof T>(field: K): this;
+    isNotNull<K extends string & keyof T>(field: K): this;
+    between<K extends string & keyof T>(field: K, low: unknown, high: unknown): this;
+    and(fn: (q: IQueryBuilder<T>) => IQueryBuilder<T>): this;
+    or(fn: (q: IQueryBuilder<T>) => IQueryBuilder<T>): this;
+    orderBy<K extends string & keyof T>(field: K, direction?: 'asc' | 'desc'): this;
+    select(...fields: Array<string & keyof T>): this;
+    distinct(...fields: Array<string & keyof T>): this;
+    groupBy(...fields: Array<string & keyof T>): this;
+    having(field: string, op: string, value: unknown): this;
+    exists(relation: string, fn?: (q: IQueryBuilder<any>) => IQueryBuilder<any>): this;
+    notExists(relation: string, fn?: (q: IQueryBuilder<any>) => IQueryBuilder<any>): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    include(relation: string): this;
+    join(model: string): IJoinClause<T>;
+    /** leftJoin 便捷方法 */
+    leftJoin(model: string): IJoinClause<T>;
+    /** innerJoin 便捷方法 */
+    innerJoin(model: string): IJoinClause<T>;
+    /** 执行查询，返回结果列表 */
+    fetch(): Promise<T[]>;
+    /** 执行查询，返回单条结果 */
+    fetchOne(): Promise<T | null>;
+    /** 执行计数查询 */
+    count(): Promise<number>;
+    /** 执行聚合查询 */
+    aggregate(args: AggregateQueryArgs): Promise<any>;
+    /** 执行 groupBy 查询 */
+    fetchGroupBy(args: GroupByQueryArgs): Promise<any[]>;
+    /** 构建完整的查询参数 */
+    private buildQueryArgs;
+    /** 将条件组转换为 Prisma where 对象 */
+    private buildWhere;
+    /** Allowed Prisma operators — prevents arbitrary operator injection */
+    private static readonly ALLOWED_OPS;
+    /** 将单个条件转换为 Prisma 条件 */
+    private buildCondition;
+    /** 构建含 exists 子查询的 WHERE 条件 */
+    private buildWhereWithExists;
+    /** 构建 HAVING 条件（用于 groupBy） */
+    private buildHaving;
+    /** 构建 include 对象（将 JOIN 和 include 合并） */
+    private buildInclude;
+}
+
+/**
+ * Abstract base service providing standard CRUD operations with entity event support.
+ *
+ * Subclasses should provide the model name and optionally customize the default order field.
+ *
+ * @template T - The entity type, must extend GenericEntity
+ */
+declare abstract class BaseService<T extends GenericEntity> {
+    protected readonly db: DatabaseAdapter;
+    protected readonly dynamicQuery: DynamicQueryService;
+    protected readonly eventBus?: TopicEventBus | undefined;
+    protected readonly logger: Logger;
+    protected readonly modelName: string;
+    protected readonly defaultOrderField: string;
+    constructor(db: DatabaseAdapter, dynamicQuery: DynamicQueryService, modelName: string, eventBus?: TopicEventBus | undefined, options?: {
+        defaultOrderField?: string;
+    });
+    /**
+     * 创建记录
+     * @param data 实体数据
+     * @returns 创建后的完整实体
+     */
+    create(data: Partial<T>): Promise<T>;
+    /**
+     * 根据 ID 更新记录
+     * @param id 记录 ID
+     * @param data 要更新的字段
+     * @returns 更新后的完整实体
+     * @throws NotFoundException 记录不存在时
+     */
+    update(id: string, data: Partial<T>): Promise<T>;
+    /**
+     * 保存或更新单条记录 — 有 ID 则 update，无 ID 则 create
+     * 发送保存操作的实体生命周期事件
+     * @param data 实体数据
+     * @returns 保存后的完整实体
+     */
+    saveOrUpdate(data: Partial<T>): Promise<T>;
+    /**
+     * 根据 ID 删除记录
+     * @param id 记录 ID
+     * @returns 被删除的实体
+     * @throws NotFoundException 记录不存在时
+     */
+    delete(id: string): Promise<T>;
+    /**
+     * 根据 ID 查询单条记录
+     * @param id 记录 ID
+     * @returns 查询到的实体
+     * @throws NotFoundException 记录不存在时
+     */
+    findOne(id: string): Promise<T>;
+    /**
+     * 动态条件查询（带分页）
+     * @param query 动态查询参数
+     * @returns 分页查询结果
+     */
+    findAll(query: DynamicQueryParam): Promise<PaginatedResult<T>>;
+    /**
+     * 根据 ID 查询，返回 null 而不抛异常
+     * 记录不存在时返回空值
+     * @param id 记录 ID
+     * @returns 实体或 null（不存在时返回 null）
+     */
+    findByIdOptional(id: string): Promise<T | null>;
+    /**
+     * 根据 ID 列表批量查询
+     */
+    findByIds(ids: string[]): Promise<T[]>;
+    /**
+     * 查询总数
+     */
+    count(where?: Record<string, unknown>): Promise<number>;
+    /**
+     * 根据动态查询参数查询总数
+     */
+    countByQuery(query: DynamicQueryParam): Promise<number>;
+    /**
+     * 判断数据是否存在
+     */
+    exists(query: DynamicQueryParam): Promise<boolean>;
+    /**
+     * 分页查询
+     * - 如果 param.total 已设置（前端传入），跳过 count 查询
+     * - count 为 0 时直接返回空结果
+     * - 自动调用 rePaging 修正越界页码
+     */
+    queryPager(param: DynamicQueryParam): Promise<PaginatedResult<T>>;
+    /**
+     * 批量保存（upsert 语义）
+     * 有 ID 则 update，无 ID 则 create
+     * 发出 SAVE 类型事件（EntityBeforeSaveEvent / EntitySavedEvent）
+     * @returns SaveResult { created: number, updated: number, total: number }
+     */
+    save(entities: Partial<T>[]): Promise<{
+        created: number;
+        updated: number;
+        total: number;
+    }>;
+    /**
+     * 批量创建记录（不触发事件）
+     * @param data 实体数据数组
+     * @returns 创建数量
+     */
+    createMany(data: Partial<T>[]): Promise<{
+        count: number;
+    }>;
+    /**
+     * 按条件批量更新记录
+     * @param where 过滤条件
+     * @param data 要更新的字段
+     * @returns 更新数量
+     */
+    updateMany(where: Record<string, unknown>, data: Partial<T>): Promise<{
+        count: number;
+    }>;
+    /**
+     * 按条件批量删除记录
+     * @param where 过滤条件
+     * @returns 删除数量
+     */
+    deleteMany(where: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    /**
+     * 软删除（设置 deletedAt 字段）
+     * @param id 记录 ID
+     * @returns 更新后的实体
+     */
+    softDelete(id: string): Promise<T>;
+    /**
+     * 恢复软删除的记录（清除 deletedAt 字段）
+     * @param id 记录 ID
+     * @returns 恢复后的实体
+     */
+    restore(id: string): Promise<T>;
+    /** 创建链式查询构建器 */
+    createQuery(): IQueryBuilder<T>;
+    /**
+     * 乐观锁批量更新
+     * 使用 updatedAt 作为版本号，只有 updatedAt 匹配时才执行更新
+     * @param items 待更新的记录数组，每条记录必须包含 id 和 updatedAt
+     * @returns { count: 成功更新数, failed: 冲突记录数组 }
+     */
+    updateManyWithOptimisticLock(items: Array<Partial<T> & {
+        id: string;
+        updatedAt: Date;
+    }>): Promise<{
+        count: number;
+        failed: T[];
+    }>;
+    /**
+     * 批量创建（带事件）
+     */
+    createBatch(items: Partial<T>[], options?: {
+        skipEvents?: boolean;
+    }): Promise<T[]>;
+    /**
+     * 批量更新（带事件）
+     */
+    updateBatch(items: (Partial<T> & {
+        id: string;
+    })[], options?: {
+        skipEvents?: boolean;
+    }): Promise<T[]>;
+    /**
+     * 批量删除（带事件）
+     */
+    deleteBatch(ids: string[], options?: {
+        skipEvents?: boolean;
+    }): Promise<number>;
+    /**
+     * 执行事务
+     * @param fn 事务回调函数
+     * @returns 事务执行结果
+     */
+    transaction<R>(fn: (db: DatabaseAdapter) => Promise<R>): Promise<R>;
+    protected emitEvent(type: EntityEventType, phase: EntityEventPhase, entity: unknown): Promise<EntityEvent>;
+    /**
+     * 发出 BEFORE 阶段事件并检查是否被取消
+     * 如果事件被取消，抛出 OperationCancelledException
+     */
+    protected emitEventWithCancelCheck(type: EntityEventType, entity: unknown): Promise<void>;
+}
+
+declare class BaseControllerHost<T extends GenericEntity> {
+    protected readonly service: BaseService<T>;
+    create(..._args: unknown[]): Promise<T>;
+    findOne(..._args: unknown[]): Promise<T>;
+    findAll(..._args: unknown[]): Promise<unknown>;
+    saveOrUpdate(..._args: unknown[]): Promise<T>;
+    update(..._args: unknown[]): Promise<T>;
+    delete(..._args: unknown[]): Promise<T>;
+    save(..._args: unknown[]): Promise<{
+        created: number;
+        updated: number;
+        total: number;
+    }>;
+    createMany(..._args: unknown[]): Promise<{
+        count: number;
+    }>;
+    updateMany(..._args: unknown[]): Promise<{
+        count: number;
+    }>;
+    deleteMany(..._args: unknown[]): Promise<{
+        count: number;
+    }>;
+    queryNoPaging(..._args: unknown[]): Promise<T[]>;
+    queryNoPagingPost(..._args: unknown[]): Promise<T[]>;
+    queryPager(..._args: unknown[]): Promise<unknown>;
+    queryPagerPost(..._args: unknown[]): Promise<unknown>;
+    count(..._args: unknown[]): Promise<{
+        total: number;
+    }>;
+    countPost(..._args: unknown[]): Promise<{
+        total: number;
+    }>;
+    exists(..._args: unknown[]): Promise<{
+        exists: boolean;
+    }>;
+    existsPost(..._args: unknown[]): Promise<{
+        exists: boolean;
+    }>;
+}
+declare function BaseController<T extends GenericEntity>(EntityClass: Type<T>): Type<BaseControllerHost<T>>;
+
+interface CacheEnabledServiceOptions {
+    /** 缓存 TTL（毫秒） */
+    ttlMs?: number;
+    /** 默认排序字段 */
+    defaultOrderField?: string;
+}
+/**
+ * 带缓存的 CRUD 服务
+ * - findOne/findById 自动读缓存、写缓存（带 TTL）
+ * - update/delete 自动失效缓存，发布缓存清除事件
+ */
+declare abstract class CacheEnabledService<T extends GenericEntity> extends BaseService<T> {
+    protected readonly cache: ICache;
+    protected readonly cacheLogger: Logger;
+    protected readonly ttlMs: number;
+    constructor(db: DatabaseAdapter, dynamicQuery: DynamicQueryService, modelName: string, cache: ICache, eventBus?: TopicEventBus, options?: CacheEnabledServiceOptions);
+    /**
+     * 获取缓存名称
+     */
+    getCacheName(): string;
+    /** 生成缓存键 */
+    protected getCacheKey(id: string): string;
+    /** 全量缓存键 */
+    protected getAllCacheKey(): string;
+    /**
+     * 获取全量数据（优先走缓存）
+     * 适用于数据量较小的配置表、字典表等
+     */
+    getCacheAll(): Promise<T[]>;
+    /**
+     * 创建后失效全量缓存
+     */
+    create(data: Partial<T>): Promise<T>;
+    /**
+     * 批量保存后失效缓存
+     */
+    save(entities: Partial<T>[]): Promise<{
+        created: number;
+        updated: number;
+        total: number;
+    }>;
+    /** 读取时优先走缓存 */
+    findOne(id: string): Promise<T>;
+    /** 更新后失效缓存 */
+    update(id: string, data: Partial<T>): Promise<T>;
+    /** 删除后失效缓存 */
+    delete(id: string): Promise<T>;
+    /** 软删除后失效缓存 */
+    softDelete(id: string): Promise<T>;
+    /**
+     * 批量创建后失效全量缓存
+     */
+    createMany(data: Partial<T>[]): Promise<{
+        count: number;
+    }>;
+    /**
+     * 批量更新后失效全量缓存
+     */
+    updateMany(where: Record<string, unknown>, data: Partial<T>): Promise<{
+        count: number;
+    }>;
+    /**
+     * 批量删除后失效全量缓存
+     */
+    deleteMany(where: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    /**
+     * 失效指定 ID 的缓存，并发布缓存清除事件
+     *
+     * 事务感知行为：
+     * - 有事务上下文时：注册 afterCommit 回调，commit 后才真正失效缓存
+     *   这样如果事务回滚，缓存不会被错误清除
+     * - 无事务上下文时：立即执行缓存失效
+     */
+    protected invalidateCache(id: string): Promise<void>;
+    /**
+     * 批量删除后失效缓存
+     */
+    deleteBatch(ids: string[], options?: {
+        skipEvents?: boolean;
+    }): Promise<number>;
+    /** 批量失效缓存 */
+    protected invalidateCacheMany(ids: string[]): Promise<void>;
+}
+/**
+ * @Cacheable() 方法装饰器
+ * 为任意方法添加缓存能力，使用方法的第一个参数作为缓存键的一部分
+ */
+declare function Cacheable(options?: {
+    ttlMs?: number;
+    keyPrefix?: string;
+}): MethodDecorator;
+
+/** 支持软删除的实体接口 */
+interface SoftDeletableEntity extends GenericEntity {
+    deletedAt?: Date | null;
+}
+/** 软删除查询选项 */
+interface SoftDeleteQueryOptions {
+    includeDeleted?: boolean;
+}
+/**
+ * 软删除服务
+ * - 所有查询自动加 WHERE deletedAt IS NULL 条件
+ * - delete() 执行软删除而非物理删除
+ * - 通过 options.includeDeleted 参数临时包含已删除记录
+ * - restore(id) 恢复已删除记录
+ */
+declare abstract class SoftDeleteService<T extends SoftDeletableEntity> extends BaseService<T> {
+    constructor(db: DatabaseAdapter, dynamicQuery: DynamicQueryService, modelName: string, eventBus?: TopicEventBus, options?: {
+        defaultOrderField?: string;
+    });
+    /** 查询单条记录（自动排除已删除） */
+    findOne(id: string, options?: SoftDeleteQueryOptions): Promise<T>;
+    /** 分页查询（自动排除已删除） */
+    findAll(query: DynamicQueryParam, options?: SoftDeleteQueryOptions): Promise<PaginatedResult<T>>;
+    /**
+     * 执行软删除（设置 deletedAt）
+     * BEFORE 阶段检查取消标志，支持监听器取消删除操作
+     */
+    delete(id: string): Promise<T>;
+    /** 批量软删除 */
+    deleteMany(where: Record<string, unknown>, options?: SoftDeleteQueryOptions): Promise<{
+        count: number;
+    }>;
+    /** 恢复已删除记录 */
+    restore(id: string): Promise<T>;
+    /**
+     * @deprecated Use `findAll(query, { includeDeleted: true })` or
+     * `findOne(id, { includeDeleted: true })` instead.
+     * This method uses Object.create(this) which causes shared mutable state bugs.
+     */
+    withDeleted(): this;
+    /**
+     * 物理删除（真正从数据库删除）
+     */
+    forceDelete(id: string): Promise<T>;
+    /** 在查询参数中注入软删除过滤条件 */
+    private injectSoftDeleteFilter;
+}
+
+/**
+ * Abstract service for tree-structured entities with automatic path/level management.
+ * Extends BaseService with tree-specific operations: findAsTree, moveNode, rebuildPath, etc.
+ *
+ * @template T - The entity type, must extend TreeSortSupportEntity
+ */
+declare abstract class TreeService<T extends TreeSortSupportEntity> extends BaseService<T> {
+    protected readonly treeLogger: Logger;
+    protected readonly pathStrategy?: TreePathStrategy;
+    /**
+     * 获取批量操作的缓冲大小
+     */
+    getBufferSize(): number;
+    /**
+     * 设置子节点
+     */
+    setChildren(entity: T, children: T[]): void;
+    /**
+     * 获取子节点
+     */
+    getChildren(entity: T): T[];
+    /**
+     * 查询所有数据并组装为树形结构
+     */
+    findAsTree(): Promise<T[]>;
+    /**
+     * 查询指定父节点下的所有子节点（直接子节点）
+     */
+    findChildren(parentId: string): Promise<T[]>;
+    /**
+     * 查询节点及其所有后代（利用 path 前缀匹配）
+     */
+    findWithChildren(id: string): Promise<T[]>;
+    /**
+     * 创建节点时自动计算 path、level 和 sortIndex
+     */
+    create(data: Partial<T>): Promise<T>;
+    /**
+     * 重建所有节点的 path 和 level 字段
+     */
+    rebuildPath(): Promise<void>;
+    /**
+     * 查询指定 ID 的实体及其所有后代节点
+     * 使用 path 前缀匹配，并自动去重
+     */
+    queryIncludeChildren(ids: string[]): Promise<T[]>;
+    /**
+     * 根据查询参数查询数据，并包含所有匹配节点的子节点
+     * 保留 includes/excludes 字段选择
+     */
+    queryIncludeChildrenByQuery(queryParam: DynamicQueryParam): Promise<T[]>;
+    /**
+     * 查询节点及所有后代（通过 path 前缀匹配）
+     * @deprecated 使用 queryIncludeChildren() 代替
+     */
+    findByTreeChild(parentIds: string[]): Promise<T[]>;
+    /**
+     * 向上查找所有祖先节点
+     */
+    findParents(childId: string): Promise<T[]>;
+    /**
+     * 查找同级节点
+     */
+    findSiblings(nodeId: string): Promise<T[]>;
+    /**
+     * 查询指定 ID 节点的所有父/祖先节点（通过 path 反向匹配）
+     */
+    queryIncludeParent(ids: string[]): Promise<T[]>;
+    /**
+     * 删除节点及其所有后代（通过 path 前缀匹配级联删除）
+     * 通过路径前缀匹配级联删除子节点
+     */
+    delete(id: string): Promise<T>;
+    /**
+     * 批量删除节点及其后代
+     */
+    deleteBatch(ids: string[], options?: {
+        skipEvents?: boolean;
+    }): Promise<number>;
+    /**
+     * 保存/更新时自动处理树属性
+     * - 校验循环依赖
+     * - 展开子节点
+     * - 自动分配 path, level, sortIndex
+     */
+    save(entities: Partial<T>[]): Promise<SaveResult>;
+    /**
+     * 查询并返回树形结构（使用查询参数）
+     */
+    queryResultToTree(queryParam?: DynamicQueryParam): Promise<T[]>;
+    /**
+     * 查询符合条件的数据及其所有子节点，组装为树
+     */
+    queryIncludeChildrenTree(queryParam: DynamicQueryParam): Promise<T[]>;
+    /**
+     * 校验循环依赖
+     * 防止将节点的父节点设置为自己的子节点
+     */
+    checkCyclicDependency(nodeId: string, newParentId: string | null): Promise<void>;
+    /**
+     * 判断节点是否为根节点
+     */
+    isRootNode(entity: T): boolean;
+    /**
+     * 移动节点到新的父节点下
+     */
+    moveNode(id: string, newParentId: string | null): Promise<T>;
+    /**
+     * 获取同级节点的下一个 sortIndex
+     */
+    protected getNextSortIndex(parentId: string | null): Promise<number>;
+    /**
+     * 展开树形输入数据为扁平列表
+     * 递归遍历 children 字段，将嵌套树结构展平
+     */
+    private expandTreeToList;
+    private buildTree;
+    /**
+     * 通过向上遍历祖先链计算 path 和 level，避免加载全表。
+     */
+    private computePathByAncestors;
+    private computePath;
+}
+
+declare class TreeControllerHost<T extends TreeSortSupportEntity> {
+    protected readonly service: TreeService<T>;
+    findAllTree(..._args: unknown[]): Promise<T[]>;
+    findAllChildren(..._args: unknown[]): Promise<T[]>;
+    findAllChildrenTree(..._args: unknown[]): Promise<T[]>;
+}
+/**
+ * 树形结构控制器工厂
+ * 提供树形查询和树节点 CRUD 路由
+ *
+ * 路由:
+ * - GET  /_query/tree          动态查询并返回树形结构
+ * - POST /_query/tree          POST方式动态查询并返回树形结构
+ * - GET  /_query/_children     动态查询并返回子节点数据(扁平)
+ * - POST /_query/_children     POST方式动态查询并返回子节点数据(扁平)
+ * - GET  /_query/_children/tree  动态查询并返回子节点树形结构
+ * - POST /_query/_children/tree  POST方式动态查询并返回子节点树形结构
+ * - DELETE /{id}               删除节点及其所有子节点
+ */
+declare function TreeController<T extends TreeSortSupportEntity>(EntityClass: Type<T>): Type<TreeControllerHost<T>>;
+
+/** Minimal interface for a Prisma-like client */
+interface PrismaLikeClient extends Record<string, unknown> {
+    $transaction<T>(fn: (tx: Record<string, unknown>) => Promise<T>): Promise<T>;
+}
+interface PrismaAdapterOptions {
+    /** 项目级别的额外模型名别名（业务侧覆盖 framework 默认） */
+    modelAliases?: Record<string, string>;
+}
+declare class PrismaAdapter extends TransactionAwareDatabaseAdapter {
+    private readonly prisma;
+    private readonly aliases;
+    constructor(prisma: PrismaLikeClient, options?: PrismaAdapterOptions);
+    model(name: string): ModelOperations;
+    protected doTransaction<R>(fn: (adapter: DatabaseAdapter) => Promise<R>): Promise<R>;
+}
+
+interface PrismaDatabaseAdapterModuleOptions {
+    /** 项目侧 PrismaService class（构造时会被作为 inject token） */
+    prismaService: Type<unknown>;
+    /** 项目侧 PrismaModule（含 PrismaService）。
+     *  通常需要传入，否则在 forRoot 模块作用域内拿不到 PrismaService。 */
+    prismaModule?: Type<unknown> | DynamicModule;
+    /**
+     * 业务侧扩展模型名别名。会与框架默认别名 merge。
+     * 例：{ aiModels: 'aIModel' }（Prisma client AIModel → aIModel）
+     */
+    modelAliases?: Record<string, string>;
+    /** 是否注册为 @Global()。默认 true（@zucker-framework/ai 等需全局可见 DATABASE_ADAPTER） */
+    global?: boolean;
+}
+/**
+ * 现成的 Nest dynamic module：把 PrismaService 包装成 `DATABASE_ADAPTER`
+ * provider，让 @zucker-framework/ai 的 AIConfigService、PromptManager 等开箱使用。
+ *
+ * 比 ZuckerCrudModule.forRootAsync 更轻量：不带 dynamic-query / 操作符 /
+ * BaseService 等 CRUD 周边，仅注册 DATABASE_ADAPTER + PrismaAdapter 实例。
+ *
+ * 用法（项目 AppModule）：
+ * ```ts
+ * import { PrismaModule, PrismaService } from '@/prisma';
+ *
+ * @Module({
+ *   imports: [
+ *     PrismaDatabaseAdapterModule.forRoot({
+ *       prismaService: PrismaService,
+ *       prismaModule: PrismaModule,
+ *       modelAliases: { aiModels: 'aIModel' },
+ *     }),
+ *     ZuckerAIModule.forRoot({ ... }),
+ *   ],
+ * })
+ * ```
+ */
+declare class PrismaDatabaseAdapterModule {
+    static forRoot(options: PrismaDatabaseAdapterModuleOptions): DynamicModule;
+}
+
+/**
+ * InMemoryAdapter — development / testing database adapter.
+ *
+ * Stores all data in a plain JS Map<model, Map<id, record>>.
+ * Supports simple Prisma-style where-clauses (equality only) and
+ * auto-generates string IDs when missing.
+ *
+ * NOT suitable for production — data is lost on restart.
+ *
+ * Usage:
+ * ```typescript
+ * ZuckerCrudModule.forRoot({ adapterClass: InMemoryAdapter })
+ * ```
+ */
+declare class InMemoryAdapter extends TransactionAwareDatabaseAdapter {
+    /** Shared store across all model instances */
+    private readonly store;
+    private getStore;
+    model(name: string): ModelOperations;
+    protected doTransaction<T>(fn: (adapter: DatabaseAdapter) => Promise<T>): Promise<T>;
+}
+
+interface CurrentUserProvider {
+    getCurrentUserId(): string | undefined;
+    getCurrentUserName(): string | undefined;
+}
+declare const CURRENT_USER_PROVIDER = "CURRENT_USER_PROVIDER";
+declare class CreatorEventListener {
+    private readonly userProvider?;
+    private readonly eventBus?;
+    constructor(userProvider?: CurrentUserProvider | undefined, eventBus?: TopicEventBus | undefined);
+    private registerListeners;
+    private handleCreate;
+    private handleUpdate;
+}
+
+/**
+ * 实体验证规则注册表
+ * 使用方通过 registerSchema() 注册实体的验证规则
+ */
+interface EntityValidationRegistry {
+    /**
+     * 获取指定实体类型的验证规则
+     * @param entityType 实体模型名称
+     * @param group 验证分组 ('create' | 'update')
+     * @returns 验证规则，如果没有注册规则则返回 undefined
+     */
+    getSchema(entityType: string, group: string): ValidationSchema | undefined;
+}
+declare const ENTITY_VALIDATION_REGISTRY = "ENTITY_VALIDATION_REGISTRY";
+declare class ValidateEventListener {
+    private readonly registry?;
+    private readonly eventBus?;
+    private readonly logger;
+    constructor(registry?: EntityValidationRegistry | undefined, eventBus?: TopicEventBus | undefined);
+    private registerListeners;
+    private handleValidation;
+}
+/**
+ * 简单的内存验证规则注册表实现
+ */
+declare class SimpleEntityValidationRegistry implements EntityValidationRegistry {
+    private readonly schemas;
+    /**
+     * 注册实体验证规则
+     * @param entityType 实体模型名称
+     * @param group 验证分组 ('create' | 'update')
+     * @param schema 验证规则
+     */
+    registerSchema(entityType: string, group: string, schema: ValidationSchema): void;
+    getSchema(entityType: string, group: string): ValidationSchema | undefined;
+}
+
+/**
+ * QueryAnalyzer — 查询分析优化
+ */
+
+interface OptimizedQuery {
+    /** 优化后的查询参数 */
+    query: DynamicQueryParam;
+    /** 用于 count 的查询（去掉 orderBy 和 select） */
+    countQuery: DynamicQueryParam;
+    /** 检测到的潜在问题 */
+    warnings: string[];
+}
+declare class QueryAnalyzer {
+    /**
+     * 分析查询参数并返回优化后的查询
+     */
+    static analyze(queryParam: DynamicQueryParam): OptimizedQuery;
+}
+
+interface CrudModuleAsyncOptions {
+    imports?: Array<Type | DynamicModule>;
+    useFactory?: (...args: unknown[]) => DatabaseAdapter | Promise<DatabaseAdapter>;
+    useClass?: Type<DatabaseAdapter>;
+    useExisting?: InjectionToken;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+declare class ZuckerCrudModule {
+    static forRoot(options: {
+        adapterClass: Type<DatabaseAdapter>;
+    }): DynamicModule;
+    static forRootAsync(options: CrudModuleAsyncOptions): DynamicModule;
+    private static createAdapterProvider;
+}
+
+/**
+ * CRUD 自动生成装饰器 — 对标 Claude Code Tool 统一注册模式
+ *
+ * 将重复的 CRUD Controller 代码抽象为声明式配置。
+ * 生成标准端点: POST /_query, GET /:id, POST /, PUT /:id, DELETE /:id
+ *
+ * 注意: 这是元数据标记 + mixin 模式，需配合 CrudControllerFactory 使用。
+ *
+ * 用法:
+ * ```ts
+ * @Controller('admin/users')
+ * class UsersController extends CrudControllerFactory(UserService, {
+ *   routes: {
+ *     query: { decorators: [Permissions('user:query')] },
+ *     create: { decorators: [Permissions('user:add')] },
+ *   },
+ * }) {
+ *   // 自动拥有 query/findOne/create/update/delete 方法
+ *   // 只需手写非标准端点
+ * }
+ * ```
+ */
+declare const CRUD_METADATA: unique symbol;
+interface CrudRouteConfig {
+    /** 额外的装饰器（如权限控制） */
+    decorators?: MethodDecorator[];
+    /** 是否启用此路由（默认 true） */
+    enabled?: boolean;
+}
+interface CrudOptions {
+    routes?: {
+        query?: CrudRouteConfig;
+        findOne?: CrudRouteConfig;
+        create?: CrudRouteConfig;
+        update?: CrudRouteConfig;
+        delete?: CrudRouteConfig;
+    };
+    /** 软删除模式（delete 时调用 softDelete 而非 delete） */
+    softDelete?: boolean;
+}
+/**
+ * CRUD Controller 工厂
+ *
+ * 生成一个带标准 CRUD 方法的基类，子类可以覆写或扩展。
+ */
+declare function CrudControllerFactory<T>(serviceToken: new (...args: unknown[]) => T, options?: CrudOptions): new (...args: unknown[]) => object;
+
+export { ALL_OPERATORS, type AggregateQueryArgs, BaseController, BaseControllerHost, BaseService, BetweenOperator, CRUD_METADATA, CURRENT_USER_PROVIDER, CacheEnabledService, type CacheEnabledServiceOptions, Cacheable, ContainsOperator, CreatorEventListener, CrudControllerFactory, type CrudModuleAsyncOptions, type CrudOptions, type CrudRouteConfig, type CurrentUserProvider, type DynamicQueryParam, DynamicQueryParamService, DynamicQueryService, ENTITY_VALIDATION_REGISTRY, EmptyOperator, EndsWithOperator, type EntityValidationRegistry, EqualsOperator, FILTER_OPERATORS, FilterOperatorFactory, type FilterOperatorType, type GroupByQueryArgs, GtOperator, GteOperator, HasOperator, HasSomeOperator, type IFilterOperator, type IJoinClause, type IQueryBuilder, InMemoryAdapter, InOperator, IsNotNullOperator, IsNullOperator, LikeOperator, LtOperator, LteOperator, NotEmptyOperator, NotEqualsOperator, NotInOperator, NotLikeOperator, type OptimizedQuery, type PaginatedResult, PrismaAdapter, type PrismaAdapterOptions, PrismaDatabaseAdapterModule, type PrismaDatabaseAdapterModuleOptions, QueryAnalyzer, QueryBuilder, QueryParamEntity as QueryParam, QueryParamEntity, type SaveResult, SimpleEntityValidationRegistry, type SoftDeletableEntity, type SoftDeleteQueryOptions, SoftDeleteService, StartsWithOperator, TermExpressionParser, TreeController, TreeControllerHost, TreeService, ValidateEventListener, ZuckerCrudModule, calculateTotalPages, emptyPagerResult, isPaged, mergeSaveResult, noPaging, parseExpression, parseFilterMap, rePaging, toPaginatedResult };