midway-fatcms 0.0.8 → 0.0.9

package/src/libs/crud-sharding/index.ts

@@ -7,15 +7,15 @@
  * - YEAR: 按年分表，如 order_2024, order_2025
  * - MONTH: 按月分表，如 order_202401, order_202402
  * - DAY: 按日分表，如 order_20240101
- * - RANGE: 按范围分表，如 user_0 ~ user_99
  * - HASH: 按哈希分表，如 order_01 ~ order_16
+ * - KEY: 按键值分表，字段原值=表后缀，如 order_east, order_west
  * - CUSTOM: 自定义分表规则
  *
  * @example
- * import { ShardingCrudPro, ShardingType } from '@/libs/crud-sharding';
+ * import { ShardingByTimeCrud, ShardingType } from '@/libs/crud-sharding';
  *
- * // 创建分表操作器
- * const sharding = new ShardingCrudPro(crudPro, {
+ * // 创建时间分表操作器
+ * const sharding = new ShardingByTimeCrud(crudProFactory, {
  *   type: ShardingType.MONTH,
  *   baseTable: 't_order',
  *   timeColumn: 'created_at',
@@ -25,18 +25,21 @@
  * await sharding.insert({
  *   data: { order_id: '001', amount: 100, created_at: '2024-03-15' },
  * });
- *
- * // 分页查询（自动合并多表结果）
- * const result = await sharding.findPage({
- *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
- *   pageNo: 1,
- *   pageSize: 10,
- * });
  */
 
-// 核心类
-export { ShardingCrudPro } from './ShardingCrudPro';
-export { ShardingRouter } from './ShardingRouter';
+// 基类
+export { ShardingBase } from './ShardingBase';
+
+// 四个子类
+export { ShardingByTimeCrud } from './ShardingByTimeCrud';
+export { ShardingByHashCrud } from './ShardingByHashCrud';
+export { ShardingByKeyCrud } from './ShardingByKeyCrud';
+export { ShardingByCustomCrud } from './ShardingByCustomCrud';
+
+// 兼容旧代码：ShardingCrudPro → ShardingBase
+export { ShardingBase as ShardingCrudPro } from './ShardingBase';
+
+// 合并器（仅 Time 使用）
 export { ShardingMerger } from './ShardingMerger';
 
 // 配置和类型

package/src/models/RedisKeys.ts

@@ -11,6 +11,7 @@ const RedisKeys = {
   CURD_MIX_BY_DICT_PREFIX: 'FatCurdMixByDict@@',
   QUERY_ENUM_INFO_PREFIX: 'FatQueryEnum@@',
   REDIS_LOCK_MIDDILEWARE: 'FatRedisLock@@',
+  TABLE_META_CACHE_INVALIDATE_CHANNEL: 'FatTableMetaCacheInvalidate',
 };
 
 export { RedisKeys };

package/src/service/TableMetaCacheRedisSubscriber.ts

@@ -0,0 +1,105 @@
+import { RedisService } from '@midwayjs/redis';
+import { clearTableMetaCache } from '@/libs/crud-pro/services/CrudProTableMetaService';
+import { RedisKeys } from '@/models/RedisKeys';
+
+const CHANNEL = RedisKeys.TABLE_META_CACHE_INVALIDATE_CHANNEL;
+
+/**
+ * 本节点唯一标识，用于区分是自己发出的广播还是其他节点发出的
+ * 避免重复清空（本节点已在发布前清空过）
+ */
+const NODE_ID = `node_${process.pid}_${Date.now()}`;
+
+/**
+ * 用于发布消息的 Redis 客户端（复用 @midwayjs/redis 注入的实例）
+ */
+let publishClient: RedisService | null = null;
+
+/**
+ * 用于订阅的 Redis 客户端（独立连接，ioredis 规定订阅连接不能执行普通命令）
+ */
+let subscribeClient: RedisService | null = null;
+
+/**
+ * 初始化发布客户端
+ *
+ * 在 Midway 容器初始化完成后调用，注入已有的 RedisService 实例
+ * @param client RedisService 实例
+ */
+export function initTableMetaCachePublishClient(client: RedisService): void {
+  publishClient = client;
+}
+
+/**
+ * 初始化 Redis 订阅，监听缓存失效广播
+ *
+ * 使用 RedisService.duplicate() 创建独立的订阅连接。
+ * 收到广播后自动清空本节点的本地缓存。
+ *
+ * @param mainClient 已有的 RedisService 实例，用于 duplicate 出订阅连接
+ */
+export function initTableMetaCacheSubscriber(mainClient: RedisService): void {
+  if (subscribeClient) {
+    return; // 防止重复初始化
+  }
+
+  // duplicate() 创建一个同配置的独立连接
+  subscribeClient = mainClient.duplicate() as RedisService;
+
+  subscribeClient.subscribe(CHANNEL).catch((err: Error) => {
+    console.error('[TableMetaCacheRedis] subscribe failed:', err.message);
+  });
+
+  subscribeClient.on('message', (channel: string, message: string) => {
+    if (channel !== CHANNEL) return;
+
+    try {
+      const data = JSON.parse(message);
+      // 跳过自己发出的广播（本节点已在发布前清空过）
+      if (data.nodeId === NODE_ID) return;
+
+      const stats = clearTableMetaCache();
+      console.info(`[TableMetaCacheRedis] 收到其他节点(${data.nodeId})的缓存清空广播，已清空本地缓存:`, stats);
+    } catch (e) {
+      console.error('[TableMetaCacheRedis] 处理缓存失效广播异常:', e);
+    }
+  });
+
+  subscribeClient.on('error', (err: Error) => {
+    console.error('[TableMetaCacheRedis] subscriber connection error:', err.message);
+  });
+
+  console.info('[TableMetaCacheRedis] 订阅已启动，监听频道:', CHANNEL);
+}
+
+/**
+ * 清空本节点缓存并广播通知集群中其他节点
+ *
+ * 调用流程：
+ * 1. 清空本节点本地缓存
+ * 2. 通过 Redis PUBLISH 广播消息
+ * 3. 其他节点收到消息后清空各自的本地缓存
+ *
+ * @returns 清空前的缓存统计
+ */
+export function clearTableMetaCacheWithBroadcast(): { metaCacheCount: number; tableInfoCacheCount: number } {
+  // 1. 清空本节点缓存
+  const stats = clearTableMetaCache();
+
+  // 2. 广播通知其他节点
+  if (publishClient && typeof publishClient.publish === 'function') {
+    const message = JSON.stringify({
+      nodeId: NODE_ID,
+      timestamp: Date.now(),
+      beforeClear: stats,
+    });
+    publishClient.publish(CHANNEL, message).catch((err: Error) => {
+      console.error('[TableMetaCacheRedis] publish failed:', err.message);
+    });
+  } else {
+    // 没有 Redis 连接时仅清空本地（单节点部署降级）
+    console.info('[TableMetaCacheRedis] 无 Redis 发布客户端，仅清空本节点缓存');
+  }
+
+  return stats;
+}

package/src/service/curd/CurdMixService.ts

@@ -10,7 +10,7 @@ import { IRequestCfgModel2 } from '@/models/bizmodels';
 import { CurdMixByLinkToCustomService } from './CurdMixByLinkToCustomService';
 // import { SqlDbType } from '@/libs/crud-pro/models/keys';
 import { ExecuteContext, IExecuteContextCustom } from '@/libs/crud-pro/models/ExecuteContext';
-import { ShardingCrudPro } from "@/libs/crud-sharding";
+import { ShardingBase } from "@/libs/crud-sharding";
 import { IGetQuickCrudParam, IGetShardingCrudParam } from './CurdProService';
 
 export interface ILinkColumnRelationParam {
@@ -68,7 +68,7 @@ export class CurdMixService {
   }
 
 
-  public getShardingCrud(param: IGetShardingCrudParam): ShardingCrudPro {
+  public getShardingCrud(param: IGetShardingCrudParam): ShardingBase {
     this.prepare();
     return this.curdProService.getShardingCrud(param);
   }

package/src/service/curd/CurdProService.ts

@@ -17,7 +17,7 @@ import { BaseService } from '../base/BaseService';
 import { IRequestCfgModel2, IVisitorExt } from '@/models/bizmodels';
 import { IWorkbenchEntity } from '@/models/SystemEntities';
 import { CrudProQuick } from '@/libs/crud-pro-quick';
-import { ShardingCrudPro, IShardingConfig } from '@/libs/crud-sharding';
+import { ShardingBase, ShardingByTimeCrud, ShardingByHashCrud, ShardingByKeyCrud, ShardingByCustomCrud, ShardingType, IShardingConfig } from '@/libs/crud-sharding';
 import { fixCfgModel } from './fixCfgModel';
 import { GLOBAL_STATIC_CONFIG } from '@/libs/global-config/global-config';
 import { fixSoftDelete } from "@/libs/crud-pro-quick/fixSoftDelete";
@@ -172,10 +172,40 @@ export class CurdProService extends BaseService {
 
   private responseCfgHandlers: Record<RelatedType, IExecuteContextHandler> = {} as any;
 
+  /**
+   * 注册“响应配置处理器”（response cfg handler）。
+   *
+   * 这些处理器会在一次 CRUD/SQL 执行完成后被调用，用于对 `ExecuteContext` 做统一的二次加工，
+   * 例如：追加扩展数据、做字段脱敏、统一包装返回结构等。
+   *
+   * @param key 处理器类型标识（业务自定义枚举/常量）
+   * @param handler 处理器实现
+   *
+   * @example
+   * curdProService.setResponseCfgHandlers(RelatedType.USER, {
+   *   async handleExecuteContextPrepare(ctx) {
+   *     // 可在执行结果处理前做准备
+   *   },
+   *   async handleExecuteContext(ctx) {
+   *     // 对 ctx.result / ctx.data 等进行二次加工
+   *   },
+   * });
+   */
   public setResponseCfgHandlers(key: RelatedType, handler: IExecuteContextHandler) {
     this.responseCfgHandlers[key] = handler;
   }
 
+  /**
+   * 获取当前已注册的“响应配置处理器”集合。
+   *
+   * 一般用于调试或在外层框架中统一检查/复用已有 handler。
+   *
+   * @returns 以 `RelatedType` 为 key 的处理器映射表
+   *
+   * @example
+   * const handlers = curdProService.getResponseCfgHandlers();
+   * const userHandler = handlers[RelatedType.USER];
+   */
   public getResponseCfgHandlers(): Record<RelatedType, IExecuteContextHandler> {
     return this.responseCfgHandlers;
   }
@@ -213,8 +243,21 @@ export class CurdProService extends BaseService {
   }
 
   /**
-   * 依赖缓存中与加载的配置
-   * @param reqJson
+   * 通过 `method` 走配置化 CRUD 执行（从缓存/加载的配置中解析）。
+   *
+   * 适用于：前端/调用方只传 `method` + 入参，由服务端根据 `method` 找到对应的 CRUD 配置并执行。
+   * 在非调试模式下会启用配置缓存（调试模式关闭缓存，便于开发即时生效）。
+   *
+   * @param reqJson 请求模型，必须包含 `method`
+   * @returns `ExecuteContext`（包含执行过程与结果数据）
+   *
+   * @example
+   * const ctx = await curdProService.executeCrud({
+   *   method: 'user.list',
+   *   pageNo: 1,
+   *   pageSize: 20,
+   * });
+   * console.log(ctx.result);
    */
   async executeCrud(reqJson: IRequestModel): Promise<ExecuteContext> {
     if (!reqJson.method) {
@@ -228,13 +271,46 @@ export class CurdProService extends BaseService {
     return curdPro.executeCrud(reqJson, isEnableCache);
   }
 
-  // 直接执行一个SQL
+  /**
+   * 直接执行一段 SQL（不依赖 `method` 配置）。
+   *
+   * 适用于：后台管理/运维脚本/内部工具需要直接跑 SQL 的场景（仍会复用本服务的连接池、日志、visitor、事务等上下文）。
+   *
+   * @param sqlCfgModel SQL 执行配置（数据库、类型、SQL、参数等）
+   * @returns SQL 执行结果
+   *
+   * @example
+   * const res = await curdProService.executeSQL({
+   *   sqlDbType: SqlDbType.mysql,
+   *   sqlDatabase: 'mydb',
+   *   executeSql: 'select * from t_user where id = ?',
+   *   executeSqlArgs: [1],
+   * });
+   */
   public async executeSQL(sqlCfgModel: ISqlCfgModel): Promise<ExecuteSQLResult> {
     const curdPro = this.getCrudPro();
     return curdPro.executeSQL(sqlCfgModel);
   }
 
-  // 直接执行一个请求
+  /**
+   * 直接按指定配置执行一次 CRUD（不走缓存查找）。
+   *
+   * 适用于：调用方已经拿到了/动态生成了本次要执行的 CRUD 配置，想直接执行并得到结果。
+   * 该方法会对 `cfgModel` 做两类标准化处理：
+   * - 统一修正/补全配置（`fixCfgModel`）
+   * - 应用软删除规则（`fixSoftDelete`）
+   *
+   * @param reqJson 本次请求入参
+   * @param cfgModel 本次请求对应的 CRUD 配置
+   * @returns `ExecuteContext`
+   *
+   * @example
+   * const cfg = await curdProService.getCachedCfgByMethod('user.list');
+   * const ctx = await curdProService.executeCrudByCfg(
+   *   { method: 'user.list', pageNo: 1, pageSize: 20 },
+   *   cfg as any
+   * );
+   */
   public async executeCrudByCfg(reqJson: IRequestModel, cfgModel: IRequestCfgModel2): Promise<ExecuteContext> {
     this.logInfo('executeCrudByCfg', cfgModel);
     const curdPro = this.getCrudPro();
@@ -277,7 +353,7 @@ export class CurdProService extends BaseService {
    * 获取分表 CRUD 操作器
    *
    * @param param 参数对象
-   * @returns ShardingCrudPro 实例
+   * @returns ShardingBase 实例（实际类型根据 shardingConfig.type 决定）
    *
    * @example
    * const sharding = curdProService.getShardingCrud({
@@ -290,20 +366,66 @@ export class CurdProService extends BaseService {
    *   },
    * });
    */
-  public getShardingCrud(param: IGetShardingCrudParam): ShardingCrudPro {
+  public getShardingCrud(param: IGetShardingCrudParam): ShardingBase {
     const { sqlDatabase, sqlDbType, shardingConfig } = param;
-    // 传入工厂函数，每次需要时创建新的 CrudPro 实例
-    const sharding = new ShardingCrudPro(() => this.getCrudPro(), shardingConfig);
+    const factory = () => this.getCrudPro();
+
+    let sharding: ShardingBase;
+    switch (shardingConfig.type) {
+      case ShardingType.YEAR:
+      case ShardingType.MONTH:
+      case ShardingType.DAY:
+        sharding = new ShardingByTimeCrud(factory, shardingConfig);
+        break;
+      case ShardingType.HASH:
+        sharding = new ShardingByHashCrud(factory, shardingConfig);
+        break;
+      case ShardingType.KEY:
+        sharding = new ShardingByKeyCrud(factory, shardingConfig);
+        break;
+      case ShardingType.CUSTOM:
+        sharding = new ShardingByCustomCrud(factory, shardingConfig);
+        break;
+      default:
+        throw new Error(`[CurdProService] 不支持的分表类型: ${shardingConfig.type}`);
+    }
+
     sharding.setBaseCfg({ sqlDatabase, sqlDbType });
     return sharding;
   }
 
+  /**
+   * 根据 `method` 获取（可能来自缓存的）CRUD 配置。
+   *
+   * 适用于：你只想先拿到配置做检查/二次加工/审计，再决定是否执行。
+   * 非调试模式会启用缓存（调试模式关闭缓存）。
+   *
+   * @param method 配置方法名，例如：`user.list`
+   * @returns CRUD 配置模型
+   *
+   * @example
+   * const cfg = await curdProService.getCachedCfgByMethod('user.list');
+   * console.log(cfg.sqlSimpleName);
+   */
   public async getCachedCfgByMethod(method: string): Promise<IRequestCfgModel> {
     const curdPro = this.getCrudPro();
     const isEnableCache = !this.isEnableDebug(); // 开发环境不使用缓存
     return curdPro.getCachedCfgByMethod(method, isEnableCache);
   }
 
+  /**
+   * 获取数据库的表/视图等结构信息列表（用于数据源探测、表选择器、代码生成等场景）。
+   *
+   * @param query 查询条件（例如：指定数据库、关键字过滤、分页等）
+   * @param options 可选项（例如：是否包含视图/系统表、大小写处理等，具体以接口定义为准）
+   * @returns 表信息列表结果
+   *
+   * @example
+   * const tables = await curdProService.getAllTableInfos(
+   *   { sqlDbType: SqlDbType.mysql, sqlDatabase: 'mydb' },
+   *   { skipCache: true }
+   * );
+   */
   public async getAllTableInfos(query: ITableNamesQuery, options?: ITableNamesOptions): Promise<ITableListResult> {
     const curdPro = this.getCrudPro();
     return curdPro.getAllTableInfos(query, options);

package/dist/libs/crud-sharding/ShardingCrudPro.d.ts

@@ -1,208 +0,0 @@
-import { IRequestModel, IRequestCfgModel } from '../../libs/crud-pro/interfaces';
-import { IShardingConfig, CrudProFactory } from './ShardingConfig';
-import { CrudWriteResult, CrudQueryOneResult, CrudQueryListResult, CrudQueryPageResult, CrudExistResult, CrudCountResult, CrudUpsertResult } from '../../libs/crud-pro/models/CrudResult';
-import { ShardingBatchInsertResult } from './ShardingResult';
-/**
- * 分表 CRUD 操作封装器
- *
- * 在 CrudPro 之上封装分表功能，不修改 CrudPro 内部代码。
- * 提供透明的分表路由和多表查询结果合并能力。
- *
- * 支持的分表策略：
- * - YEAR: 按年分表，如 order_2024, order_2025
- * - MONTH: 按月分表，如 order_202401, order_202402
- * - DAY: 按日分表，如 order_20240101
- * - RANGE: 按范围分表，如 user_0 ~ user_99
- * - HASH: 按哈希分表，如 order_01 ~ order_16
- * - CUSTOM: 自定义分表规则
- *
- * @example
- * // 按月分表
- * const sharding = new ShardingCrudPro(crudPro, {
- *   type: ShardingType.MONTH,
- *   baseTable: 't_order',
- *   timeColumn: 'created_at',
- * });
- *
- * // 插入数据（自动路由到正确分表）
- * await sharding.insert({ data: { order_id: '001', amount: 100, created_at: '2024-03-15' } });
- *
- * // 分页查询（自动合并多表结果）
- * const result = await sharding.findPage({
- *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
- *   pageNo: 1,
- *   pageSize: 10,
- * });
- */
-export declare class ShardingCrudPro {
-    private readonly crudProFactory;
-    private readonly config;
-    private readonly router;
-    private readonly merger;
-    private readonly tableCreator;
-    private baseCfg;
-    private enableSoftDelete;
-    constructor(crudProFactory: CrudProFactory, config: IShardingConfig);
-    setBaseCfg(cfg: Partial<IRequestCfgModel>): this;
-    getConfig(): IShardingConfig;
-    /**
-     * 设置是否启用软删除
-     * @param enable 是否启用软删除
-     */
-    setEnableSoftDelete(enable: boolean): this;
-    insert(reqJson: IRequestModel): Promise<CrudWriteResult>;
-    batchInsert(reqJson: IRequestModel): Promise<ShardingBatchInsertResult>;
-    update(reqJson: IRequestModel): Promise<CrudWriteResult>;
-    delete(reqJson: IRequestModel): Promise<CrudWriteResult>;
-    /**
-     * 恢复软删除的记录
-     * 将 deleted_at 字段重置为 0，deleted_by 重置为空字符串
-     *
-     * @param reqJson 请求参数，通过 condition 指定要恢复的记录
-     * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
-     *
-     * @example
-     * // 恢复指定 ID 的记录
-     * await sharding.restore({ condition: { id: 1 } });
-     *
-     * // 恢复多条记录（使用 $in 操作符）
-     * await sharding.restore({ condition: { id: { $in: [1, 2, 3] } } });
-     *
-     * // 按条件批量恢复记录
-     * await sharding.restore({ condition: { status: 'deleted' } });
-     */
-    restore(reqJson: IRequestModel): Promise<CrudWriteResult>;
-    insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult>;
-    insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<CrudWriteResult>;
-    findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
-    /**
-     * 查询唯一单条记录（期望结果为 0 条或 1 条）
-     *
-     * 与 findOne 不同，此方法会校验查询结果的唯一性：
-     * - 如果查到 0 条：返回 row = null
-     * - 如果查到 1 条：正常返回
-     * - 如果查到多条：抛出异常，包含详细的定位信息（含分表名列表）
-     *
-     * 分表场景的特殊处理：
-     * - 单分表：直接查询并校验唯一性
-     * - 多分表：顺序查询各分表，累计找到的数量，超过 1 条立即抛异常
-     *
-     * @param reqJson 请求参数
-     * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
-     * @throws Error 如果查询到多条记录
-     *
-     * @example
-     * // 根据唯一索引查询单条
-     * const result = await sharding.findUniqueOne({ condition: { order_id: 'ORD001' } });
-     * if (result.found) {
-     *   console.log(result.row);
-     * }
-     */
-    findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
-    findList<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryListResult<T>>;
-    findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>>;
-    findCount(reqJson: IRequestModel): Promise<CrudCountResult>;
-    isExist(reqJson: IRequestModel): Promise<CrudExistResult>;
-    private batchInsertGroupDataByTable;
-    private batchInsertResolveTableForData;
-    private resolveSingleTable;
-    private getShardingColumnHint;
-    private buildCfg;
-    private executeOnTable;
-    private findCountFromTable;
-    private isExistInTable;
-    private getExistingTablesSet;
-    private isTableExists;
-    private createShardingTableIfNeeded;
-    /**
-     * 判断是否为时间分表类型
-     */
-    private isTimeSharding;
-    /**
-     * 校验时间分表插入操作的 data 必须包含 timeColumn
-     *
-     * 时间分表需要根据时间字段路由到正确的分表，
-     * 如果 data 中缺少时间字段，将无法确定数据应插入哪个分表。
-     *
-     * @param reqJson 请求参数
-     * @param operation 操作名称（用于错误提示）
-     * @throws Error 如果 data 中缺少时间字段
-     */
-    private validateTimeColumnForData;
-    /**
-     * 校验时间分表批量插入操作的每条 data 必须包含 timeColumn
-     *
-     * @param dataArray 数据数组
-     * @param operation 操作名称（用于错误提示）
-     * @throws Error 如果任一条 data 中缺少时间字段
-     */
-    private validateTimeColumnForBatchData;
-    /**
-     * 校验时间分表写操作的 condition 必须包含路由字段（timeColumn）
-     *
-     * 时间分表需要根据时间字段路由到正确的分表，
-     * 如果 condition 中缺少时间字段，将无法确定操作哪个分表。
-     *
-     * @param reqJson 请求参数
-     * @param operation 操作名称（用于错误提示）
-     * @throws Error 如果 condition 中缺少时间字段
-     */
-    private validateRoutingFieldForCondition;
-    /**
-     * 智能处理时间分表场景下的时间字段
-     *
-     * **问题背景**：
-     * 在时间分表（YEAR/MONTH/DAY）场景中，timeColumn 既是路由键也是查询条件。
-     * 用户传入的时间值可能精度不一致（如传 '2024-01-15' 但数据库存的是毫秒时间戳），
-     * 直接作为 WHERE 条件可能导致匹配失败。
-     *
-     * **处理规则**（详见 TIME_COLUMN_CLEAN_SPEC.md）：
-     * 1. 操作符表达式（$gte/$lte/$range/$in/$null 等）→ 始终保留，不做处理
-     * 2. 精确值 + 有 primaryKey → 清理（从 WHERE 移除，仅用于路由）
-     * 3. 精确值 + 无 primaryKey + 日期粒度字符串（年/月/日）→ 转换为 $gte/$lte 范围
-     * 4. 精确值 + 无 primaryKey + 其他（时间戳/datetime/null等）→ 保留原值
-     *
-     * **示例**：
-     * ```typescript
-     * // 有主键 + 精确值 → 清理
-     * { order_id: 'ORD001', created_at: '2024-01-15' }
-     * → { order_id: 'ORD001' }
-     *
-     * // 无主键 + 日期粒度字符串 → 转换为范围
-     * { status: 'paid', created_at: '2024-01' }
-     * → { status: 'paid', created_at: { $gte: '2024-01-01 00:00:00', $lte: '2024-01-31 23:59:59' } }
-     *
-     * // 操作符表达式 → 保留
-     * { order_id: 'ORD001', created_at: { $gte: '2024-01', $lte: '2024-06' } }
-     * → 不做任何处理
-     * ```
-     *
-     * @param reqJson 请求参数
-     * @returns 处理后的请求参数
-     */
-    private cleanTimeColumnForSingleTableQuery;
-    /**
-     * 校验时间操作符的值必须精确到秒
-     *
-     * MySQL 中 '2026-04-30' 等价于 '2026-04-30 00:00:00'，
-     * 导致 $lte: '2026-04-30' 会丢失当天所有数据。
-     * 如果用户需要查整月/整天数据，应传粒度字符串由系统自动转换，而非手动写 $gte/$lte。
-     *
-     * @param operatorValue 操作符表达式的值
-     * @param timeColumn 时间字段名
-     * @throws Error 如果操作符值缺少时间部分
-     */
-    private validateTimeOperatorPrecision;
-    private validateFindOrderBy;
-    private isAscOrderBy;
-    private sortTablesForOrderBy;
-    /**
-     * 构建辅助定位信息
-     */
-    private buildDebugInfo;
-    /**
-     * 格式化唯一性错误消息
-     */
-    private formatUniqueError;
-    private resolveFindTables;
-}