midway-fatcms 0.0.7 → 0.0.8

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

@@ -1,33 +1,25 @@
-import { CrudPro } from '@/libs/crud-pro/CrudPro';
 import { IRequestModel, IRequestCfgModel } from '@/libs/crud-pro/interfaces';
 import { OrderByUtils } from '@/libs/crud-pro/utils/OrderByUtils';
 import { ExecuteContext } from '@/libs/crud-pro/models/ExecuteContext';
 import { KeysOfSimpleSQL } from '@/libs/crud-pro/models/keys';
-import { ShardingType, IShardingConfig, IShardingRouterContext } from './ShardingConfig';
+import { ShardingType, IShardingConfig, IShardingRouterContext, CrudProFactory } from './ShardingConfig';
+import { fixSoftDelete } from '@/libs/crud-pro-quick/fixSoftDelete';
 import { ShardingRouter, ITableInfoProvider } from './ShardingRouter';
-import { ShardingMerger, IShardingPageQueryResult } from './ShardingMerger';
+import { ShardingMerger } from './ShardingMerger';
 import { ShardingTableCreator } from './ShardingTableCreator';
 import { ShardingCountCache } from './ShardingCountCache';
+import {
+  CrudWriteResult,
+  CrudQueryOneResult,
+  CrudQueryListResult,
+  CrudQueryPageResult,
+  CrudExistResult,
+  CrudCountResult,
+  CrudUpsertResult,
+} from '@/libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
+import { isOperatorExpression, expandDateToRange } from './ShardingUtils';
 
-/**
- * 智能批量插入结果
- */
-export interface IShardingSmartBatchInsertResult {
-  /** 总插入条数 */
-  totalAffected: number;
-  /** 各分表插入结果 */
-  tableResults: Array<{
-    table: string;
-    affected: number;
-    rowCount: number;
-  }>;
-  /** 涉及的分表数量 */
-  tableCount: number;
-  /** 是否全部成功 */
-  success: boolean;
-  /** 错误信息（如果有） */
-  errors: Array<{ table: string; error: Error }>;
-}
 
 /**
  * 分表 CRUD 操作封装器
@@ -55,25 +47,32 @@ export interface IShardingSmartBatchInsertResult {
  * await sharding.insert({ data: { order_id: '001', amount: 100, created_at: '2024-03-15' } });
  *
  * // 分页查询（自动合并多表结果）
- * const result = await sharding.queryPage({
+ * const result = await sharding.findPage({
  *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
  *   pageNo: 1,
  *   pageSize: 10,
  * });
  */
 export class ShardingCrudPro {
-  private readonly crudPro: CrudPro;
+  private readonly crudProFactory: CrudProFactory;
   private readonly config: IShardingConfig;
   private readonly router: ShardingRouter;
   private readonly merger: ShardingMerger;
   private readonly tableCreator: ShardingTableCreator;
 
   private baseCfg: Partial<IRequestCfgModel> = {};
+  private enableSoftDelete: boolean = false;
 
-  constructor(crudPro: CrudPro, config: IShardingConfig) {
-    this.crudPro = crudPro;
+  constructor(crudProFactory: CrudProFactory, config: IShardingConfig) {
     this.config = config;
 
+    // 兼容旧的 CrudPro 实例方式和新的工厂函数方式
+    if (typeof crudProFactory === 'function') {
+      this.crudProFactory = crudProFactory;
+    } else {
+      throw new Error('[ShardingCrudPro] 请使用 CrudProFactory 工厂函数模式');
+    }
+
     // 时间分表必须显式指定 timeColumn
     if ([ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(config.type)) {
       if (!config.timeColumn) {
@@ -83,7 +82,7 @@ export class ShardingCrudPro {
 
     this.router = new ShardingRouter();
     this.merger = new ShardingMerger();
-    this.tableCreator = new ShardingTableCreator(crudPro, config);
+    this.tableCreator = new ShardingTableCreator(this.crudProFactory, config);
 
     // 初始化 COUNT 缓存（如果配置了）
     if (config.countCache) {
@@ -99,109 +98,54 @@ export class ShardingCrudPro {
 
   // ============ 配置方法 ============
 
-  /**
-   * 设置基础配置（会应用到所有操作）
-   *
-   * @param cfg 配置项，如 sqlDatabase、sqlDbType 等
-   * @returns this，支持链式调用
-   *
-   * @example
-   * sharding.setBaseCfg({
-   *   sqlDatabase: 'mydb',
-   *   sqlDbType: SqlDbType.mysql,
-   * });
-   */
   public setBaseCfg(cfg: Partial<IRequestCfgModel>): this {
     this.baseCfg = { ...this.baseCfg, ...cfg };
     return this;
   }
 
-  /**
-   * 获取分表配置
-   */
   public getConfig(): IShardingConfig {
     return this.config;
   }
 
-  // ============ 写操作（单表路由） ============
-
   /**
-   * 插入数据
-   *
-   * 根据分表规则自动路由到目标分表。
-   * 对于时间分表，需要确保 data 中包含时间字段。
-   * 对于哈希/范围分表，需要确保 data 中包含分表字段。
-   *
-   * 如果目标分表不存在且配置了 autoCreateTable，会自动创建分表。
-   *
-   * @param reqJson 请求参数，data 为要插入的数据
-   * @returns 执行上下文
-   *
-   * @example
-   * await sharding.insert({
-   *   data: {
-   *     order_id: 'ORD001',
-   *     amount: 100,
-   *     created_at: '2024-03-15 10:00:00',
-   *   },
-   * });
+   * 设置是否启用软删除
+   * @param enable 是否启用软删除
    */
-  public async insert(reqJson: IRequestModel): Promise<ExecuteContext> {
+  public setEnableSoftDelete(enable: boolean): this {
+    this.enableSoftDelete = enable;
+    return this;
+  }
+
+  // ============ 写操作（单表路由） ============
+
+  public async insert(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    // 时间分表校验：data 必须包含 timeColumn
+    this.validateTimeColumnForData(reqJson, 'insert');
+
     const targetTable = this.resolveSingleTable(reqJson, 'insert');
 
     // 确保分表存在（根据配置决定是否自动创建）
     await this.createShardingTableIfNeeded(targetTable);
 
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT);
+    const ctx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
   }
 
-  /**
-   * 批量插入数据（支持跨分表）
-   *
-   * 自动将数据按分表分组，并行插入到对应的分表。
-   *
-   * @param reqJson 请求参数，data 为要插入的数据数组
-   * @returns 批量插入结果
-   *
-   * 执行流程：
-   * 1. 遍历所有数据，根据分表字段计算目标分表
-   * 2. 将数据按分表分组
-   * 3. 并行执行各分表的批量插入
-   * 4. 汇总结果返回
-   *
-   * @example
-   * // 数据分布在不同月份的分表
-   * const result = await sharding.batchInsert({
-   *   data: [
-   *     { order_id: '001', amount: 100, created_at: '2024-01-15' },  // -> t_order_202401
-   *     { order_id: '002', amount: 200, created_at: '2024-01-20' },  // -> t_order_202401
-   *     { order_id: '003', amount: 150, created_at: '2024-02-10' },  // -> t_order_202402
-   *     { order_id: '004', amount: 300, created_at: '2024-03-05' },  // -> t_order_202403
-   *   ],
-   * });
-   *
-   * console.log(result.totalAffected);    // 4
-   * console.log(result.tableCount);       // 3
-   * console.log(result.tableResults);
-   * // [
-   * //   { table: 't_order_202401', affected: 2, rowCount: 2 },
-   * //   { table: 't_order_202402', affected: 1, rowCount: 1 },
-   * //   { table: 't_order_202403', affected: 1, rowCount: 1 },
-   * // ]
-   */
-  public async batchInsert(reqJson: IRequestModel): Promise<IShardingSmartBatchInsertResult> {
+  public async batchInsert(reqJson: IRequestModel): Promise<ShardingBatchInsertResult> {
     const dataArray = reqJson.data as Record<string, any>[];
 
     if (!Array.isArray(dataArray) || dataArray.length === 0) {
-      return {
-        totalAffected: 0,
-        tableResults: [],
-        tableCount: 0,
-        success: true,
-        errors: [],
-      };
+      throw new Error('[ShardingCrudPro] batchInsert requires non-empty data array');
     }
 
+    // 时间分表校验：每条 data 必须包含 timeColumn
+    this.validateTimeColumnForBatchData(dataArray, 'batchInsert');
+
     // 按分表分组
     const groupedData = this.batchInsertGroupDataByTable(dataArray);
 
@@ -211,27 +155,31 @@ export class ShardingCrudPro {
       await this.createShardingTableIfNeeded(tableNames[i]);
     }
 
-    // 并行执行各分表的批量插入
-    const insertPromises = Array.from(groupedData.entries()).map(async ([table, items]) => {
+    // 串行执行各分表的批量插入
+    const results: Array<{ table: string; affected: number; rowCount: number; error: Error | null; context: ExecuteContext | null }> = [];
+    let lastContext: ExecuteContext | null = null;
+
+    for (const [table, items] of groupedData.entries()) {
       try {
         const ctx = await this.executeOnTable(table, { data: items }, KeysOfSimpleSQL.SIMPLE_BATCH_INSERT);
-        return {
+        lastContext = ctx;
+        results.push({
           table,
-          affected: ctx.getResModelItem('affected') || items.length,
+          affected: ctx.getResModelItem('affected')?.affectedRows || items.length,
           rowCount: items.length,
-          error: null as Error | null,
-        };
+          error: null,
+          context: ctx,
+        });
       } catch (e) {
-        return {
+        results.push({
           table,
           affected: 0,
           rowCount: items.length,
           error: e as Error,
-        };
+          context: null,
+        });
       }
-    });
-
-    const results = await Promise.all(insertPromises);
+    }
 
     // 汇总结果
     const tableResults = results.map(r => ({
@@ -246,269 +194,381 @@ export class ShardingCrudPro {
 
     const totalAffected = results.reduce((sum, r) => sum + r.affected, 0);
 
-    return {
+    // Use last successful context, or create a minimal one
+    const finalContext = lastContext || results.find(r => r.context)?.context;
+    if (!finalContext) {
+      throw new Error('[ShardingCrudPro] batchInsert failed - no successful inserts');
+    }
+
+    return new ShardingBatchInsertResult({
       totalAffected,
       tableResults,
       tableCount: groupedData.size,
       success: errors.length === 0,
       errors,
-    };
+      lastContext: finalContext,
+    });
   }
 
-  /**
-   * 更新数据
-   *
-   * 根据条件中的分表字段自动路由到目标分表。
-   *
-   * @param reqJson 请求参数，condition 为更新条件，data 为更新数据
-   * @returns 执行上下文
-   *
-   * @example
-   * await sharding.update({
-   *   condition: { order_id: 'ORD001', created_at: '2024-03-15' },
-   *   data: { amount: 200 },
-   * });
-   */
-  public async update(reqJson: IRequestModel): Promise<ExecuteContext> {
+  public async update(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    // 时间分表校验：condition 必须包含路由字段
+    this.validateRoutingFieldForCondition(reqJson, 'update');
+
     const targetTable = this.resolveSingleTable(reqJson, 'update');
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+
+    // 清理 condition 中的时间字段（如果能确定单一分表）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const ctx = await this.executeOnTable(targetTable, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
   }
 
-  /**
-   * 删除数据
-   *
-   * 根据条件中的分表字段自动路由到目标分表。
-   *
-   * @param reqJson 请求参数，condition 为删除条件
-   * @returns 执行上下文
-   */
-  public async delete(reqJson: IRequestModel): Promise<ExecuteContext> {
+  public async delete(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    // 时间分表校验：condition 必须包含路由字段
+    this.validateRoutingFieldForCondition(reqJson, 'delete');
+
     const targetTable = this.resolveSingleTable(reqJson, 'delete');
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_DELETE);
+
+    // 清理 condition 中的时间字段（如果能确定单一分表）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const ctx = await this.executeOnTable(targetTable, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_DELETE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
   }
 
   /**
-   * 插入或更新（存在则更新，不存在则插入）
+   * 恢复软删除的记录
+   * 将 deleted_at 字段重置为 0，deleted_by 重置为空字符串
    *
-   * 路由逻辑：根据 condition 路由（先查询是否存在）
+   * @param reqJson 请求参数，通过 condition 指定要恢复的记录
+   * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
    *
-   * @param reqJson 请求参数
-   * @returns 执行上下文
+   * @example
+   * // 恢复指定 ID 的记录
+   * await sharding.restore({ condition: { id: 1 } });
+   *
+   * // 恢复多条记录（使用 $in 操作符）
+   * await sharding.restore({ condition: { id: { $in: [1, 2, 3] } } });
+   *
+   * // 按条件批量恢复记录
+   * await sharding.restore({ condition: { status: 'deleted' } });
    */
-  public async insertOrUpdate(reqJson: IRequestModel): Promise<ExecuteContext> {
+  public async restore(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    // 时间分表校验：condition 必须包含路由字段
+    this.validateRoutingFieldForCondition(reqJson, 'restore');
+
+    const targetTable = this.resolveSingleTable(reqJson, 'restore');
+
+    if (!reqJson.condition || Object.keys(reqJson.condition).length === 0) {
+      throw new Error('[ShardingCrudPro] restore 操作必须指定恢复条件');
+    }
+
+    // 清理 condition 中的时间字段（如果能确定单一分表）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    // 构建恢复数据：重置软删除字段
+    const restoreReqJson: IRequestModel = {
+      ...cleanedReqJson,
+      data: {
+        ...cleanedReqJson.data,
+        deleted_at: 0,
+        deleted_by: '',
+      },
+    };
+
+    const ctx = await this.executeOnTable(targetTable, restoreReqJson, KeysOfSimpleSQL.SIMPLE_UPDATE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
+  }
+
+  public async insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult> {
+    // 时间分表校验：data 必须包含 timeColumn，condition 必须包含路由字段
+    this.validateTimeColumnForData(reqJson, 'insertOrUpdate');
+    this.validateRoutingFieldForCondition(reqJson, 'insertOrUpdate');
+
     const targetTable = this.resolveSingleTable(reqJson, 'update');  // 使用 condition 路由
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE);
+    const ctx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE);
+    const resModel = ctx.getResModel();
+    return new CrudUpsertResult({
+      affected: resModel.affected,
+      insertAffected: resModel.insert_affected,
+      updateAffected: resModel.update_affected,
+      isExist: resModel.is_exist ?? false,
+      rawContext: ctx,
+    });
   }
 
-  /**
-   * 插入或更新（ON DUPLICATE KEY UPDATE）
-   *
-   * 路由逻辑：根据 condition 路由（先查询是否存在）
-   *
-   * @param reqJson 请求参数
-   * @returns 执行上下文
-   */
-  public async insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<ExecuteContext> {
+  public async insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<CrudWriteResult> {
+    // 时间分表校验：data 必须包含 timeColumn，condition 必须包含路由字段
+    this.validateTimeColumnForData(reqJson, 'insertOnDuplicateUpdate');
+    this.validateRoutingFieldForCondition(reqJson, 'insertOnDuplicateUpdate');
+
     const targetTable = this.resolveSingleTable(reqJson, 'update');  // 使用 condition 路由
-    return this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE);
+    const ctx = await this.executeOnTable(targetTable, reqJson, KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE);
+    const affected = ctx.getResModel().affected || { affectedRows: 0 };
+    return new CrudWriteResult({
+      affectedRows: affected.affectedRows,
+      insertId: affected.insertId,
+      rawContext: ctx,
+    });
   }
 
+
   // ============ 查询操作（可能多表） ============
 
-  /**
-   * 查询单条记录
-   *
-   * 如果能根据条件确定单一分表，则查询单表；
-   * 否则按顺序查询各分表，返回第一条匹配记录。
-   *
-   * @param reqJson 请求参数，condition 为查询条件
-   * @returns 单条记录，未找到返回 null
-   *
-   * @example
-   * const order = await sharding.queryOne({
-   *   condition: { order_id: 'ORD001' },
-   * });
-   */
-  public async queryOne(reqJson: IRequestModel): Promise<any> {
-    const targetTables = await this.resolveQueryTables(reqJson);
+  public async findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>> {
+    // 清理 condition 中的时间字段（如果能确定单一分表）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const targetTables = await this.resolveFindTables(reqJson);
 
     if (targetTables.length === 0) {
-      return null; // 无匹配表
+      // Return a result with null row - we need a context for this
+      // Since there are no tables to query, we throw an error for now
+      throw new Error('[ShardingCrudPro] findOne: no matching tables found');
     }
 
     // 多表：顺序查询，找到即返回
+    let lastCtx: ExecuteContext | null = null;
     for (const table of targetTables) {
-      const result = await this.queryOneFromTable(table, reqJson);
-      if (result) return result;
+      try {
+        const ctx = await this.executeOnTable(table, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+        lastCtx = ctx;
+        const row = ctx.getOneObj();
+        if (row) {
+          return new CrudQueryOneResult<T>({ row: row as T, rawContext: ctx, debugInfo: this.buildDebugInfo(table, reqJson.condition) });
+        }
+      } catch (e) {
+        // 表不存在时跳过，继续查下一张表
+      }
     }
-    return null;
+    // 未找到，使用最后一次查询的 ctx
+    return new CrudQueryOneResult<T>({ row: null, rawContext: lastCtx, debugInfo: this.buildDebugInfo(targetTables[0], reqJson.condition) });
   }
 
   /**
-   * 查询列表
-   *
-   * 可能涉及多个分表，结果会自动合并。
-   *
-   * 使用约束：
-   * - 必须传 orderBy 参数
-   * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
-   *
+   * 查询唯一单条记录（期望结果为 0 条或 1 条）
+   * 
+   * 与 findOne 不同，此方法会校验查询结果的唯一性：
+   * - 如果查到 0 条：返回 row = null
+   * - 如果查到 1 条：正常返回
+   * - 如果查到多条：抛出异常，包含详细的定位信息（含分表名列表）
+   * 
+   * 分表场景的特殊处理：
+   * - 单分表：直接查询并校验唯一性
+   * - 多分表：顺序查询各分表，累计找到的数量，超过 1 条立即抛异常
+   * 
    * @param reqJson 请求参数
-   * @returns 数据列表
-   *
+   * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
+   * @throws Error 如果查询到多条记录
+   * 
    * @example
-   * const orders = await sharding.query({
-   *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
-   *   orderBy: 'created_at DESC',  // 或 'created_at ASC'
-   * });
+   * // 根据唯一索引查询单条
+   * const result = await sharding.findUniqueOne({ condition: { order_id: 'ORD001' } });
+   * if (result.found) {
+   *   console.log(result.row);
+   * }
    */
-  public async query(reqJson: IRequestModel): Promise<any[]> {
+  public async findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>> {
+    // 清理 condition 中的时间字段（如果能确定单一分表）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
 
+    const targetTables = await this.resolveFindTables(reqJson);
 
-    const targetTables = await this.resolveQueryTables(reqJson);
+    if (targetTables.length === 0) {
+      // 无匹配表，返回空结果
+      return new CrudQueryOneResult<T>({ row: null, rawContext: null as any, debugInfo: this.buildDebugInfo(undefined, reqJson.condition) });
+    }
+
+    // 统一逻辑：每个表查 maxLimit: 2，收集所有结果
+    const allRows: T[] = [];
+    const foundTables: string[] = [];
+    let firstCtx: ExecuteContext | null = null;
+
+    for (const table of targetTables) {
+      try {
+        const ctx = await this.executeOnTable(table, cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY, { maxLimit: 2 });
+        if (!firstCtx) {
+          firstCtx = ctx;
+        }
+        const rows = ctx.getResRows() as T[];
+        if (rows.length > 0) {
+          allRows.push(...rows);
+          foundTables.push(table);
+          // 超过 1 条，立即抛异常，不再查询后续分表
+          if (allRows.length > 1) {
+            throw new Error(this.formatUniqueError(allRows.length, foundTables, reqJson.condition, foundTables.length > 1));
+          }
+        }
+      } catch (e) {
+        // 非 formatUniqueError 的异常（如表不存在），继续查询下一张表
+        if (e instanceof Error && e.message.startsWith('[ShardingCrudPro] findUniqueOne')) {
+          throw e;
+        }
+      }
+    }
+
+    // 返回结果
+    return new CrudQueryOneResult<T>({ 
+      row: allRows[0] || null, 
+      rawContext: firstCtx,
+      debugInfo: this.buildDebugInfo(foundTables[0] || targetTables[0], reqJson.condition),
+    });
+  }
+
+  public async findList<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryListResult<T>> {
+    // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const targetTables = await this.resolveFindTables(reqJson);
 
     if (targetTables.length === 0) {
-      return []; // 无匹配表，返回空结果
+      return new CrudQueryListResult<T>({ rows: [], rawContext: null as any });
     }
 
     if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
-      return ctx.getResRows();
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY);
+      const rows = ctx.getResRows() as T[];
+      return new CrudQueryListResult<T>({ rows, rawContext: ctx });
     }
 
     // 多表查询时，需要参数校验
-    this.validateQueryOrderBy(reqJson);
+    this.validateFindOrderBy(reqJson);
 
     // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
     const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
 
     // 多表查询合并
-    return this.merger.mergeQuery(
-      this.crudPro,
+    const mergeResult = await this.merger.mergeQuery(
+      this.crudProFactory(),
       tablesForMerge,
-      reqJson,
+      cleanedReqJson,
       this.buildCfg(KeysOfSimpleSQL.SIMPLE_QUERY)
     );
+
+    return new CrudQueryListResult<T>({ rows: mergeResult.rows as T[], rawContext: mergeResult.lastCtx });
   }
 
-  /**
-   * 分页查询
-   *
-   * 自动处理跨分表的分页：
-   * 1. 顺序累计查询各分表
-   * 2. 截取目标数据（无需排序）
-   *
-   * 使用约束：
-   * - 必须传 orderBy 参数
-   * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
-   *
-   * @param reqJson 请求参数，包含 pageNo、pageSize 和 orderBy
-   * @returns 分页结果，包含 rows 和 total_count
-   *
-   * @example
-   * const result = await sharding.queryPage({
-   *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
-   *   pageNo: 1,
-   *   pageSize: 10,
-   *   orderBy: 'created_at DESC',  // 或 'created_at ASC'
-   * });
-   * console.log(result.rows, result.total_count);
-   */
-  public async queryPage(reqJson: IRequestModel): Promise<IShardingPageQueryResult> {
 
-    const targetTables = await this.resolveQueryTables(reqJson);
+
+  public async findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>> {
+    // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const targetTables = await this.resolveFindTables(reqJson);
 
     if (targetTables.length === 0) {
-      return { rows: [], total_count: 0 }; // 无匹配表
+      throw new Error('[ShardingCrudPro] findPage: no matching tables found');
     }
 
     if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
-      return ctx.getResModelForQueryPage();
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
+      const pageResult = ctx.getResModelForQueryPage();
+      return new CrudQueryPageResult<T>({
+        rows: pageResult.rows as T[],
+        totalCount: pageResult.total_count,
+        rawContext: ctx,
+      });
     }
 
     // 多表查询时，需要参数校验
-    this.validateQueryOrderBy(reqJson);
+    this.validateFindOrderBy(reqJson);
 
     // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
     const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
 
     // 多表分页查询：顺序累计
-    return this.merger.mergePageQuery(
-      this.crudPro,
+    const pageResult = await this.merger.mergePageQuery(
+      this.crudProFactory(),
       tablesForMerge,
-      reqJson,
+      cleanedReqJson,
       this.buildCfg(KeysOfSimpleSQL.SIMPLE_QUERY_PAGE)
     );
+
+    return new CrudQueryPageResult<T>({
+      rows: pageResult.rows as T[],
+      totalCount: pageResult.total_count,
+      rawContext: pageResult.lastCtx,
+    });
   }
 
-  /**
-   * 查询记录总数
-   *
-   * 如果涉及多个分表，会并行查询各分表并汇总。
-   *
-   * @param reqJson 请求参数
-   * @returns 记录总数
-   */
-  public async queryCount(reqJson: IRequestModel): Promise<number> {
-    const targetTables = await this.resolveQueryTables(reqJson);
+  public async findCount(reqJson: IRequestModel): Promise<CrudCountResult> {
+    // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const targetTables = await this.resolveFindTables(reqJson);
 
     if (targetTables.length === 0) {
-      return 0; // 无匹配表
+      throw new Error('[ShardingCrudPro] findCount: no matching tables found');
     }
 
     if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
-      return ctx.getResModelItem('total_count') || 0;
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+      const count = ctx.getResModelItem('total_count') || 0;
+      return new CrudCountResult({ count, rawContext: ctx });
     }
 
-    // 多表统计：并行查询后求和
-    const countPromises = targetTables.map(table =>
-      this.queryCountFromTable(table, reqJson)
-    );
-    const counts = await Promise.all(countPromises);
-    return counts.reduce((sum, c) => sum + c, 0);
+    // 多表统计：串行查询后求和
+    const countResults: Array<{ count: number; ctx: ExecuteContext | null }> = [];
+    for (const table of targetTables) {
+      const result = await this.findCountFromTable(table, cleanedReqJson);
+      countResults.push(result);
+    }
+    const totalCount = countResults.reduce((sum, r) => sum + r.count, 0);
+    const firstCtx = countResults.find(r => r.ctx !== null)?.ctx || null;
+
+    return new CrudCountResult({ count: totalCount, rawContext: firstCtx as any });
   }
 
-  /**
-   * 判断记录是否存在
-   *
-   * 如果涉及多个分表，会并行查询，任一分表存在即返回 true。
-   *
-   * @param reqJson 请求参数
-   * @returns 是否存在
-   */
-  public async isExist(reqJson: IRequestModel): Promise<boolean> {
-    const targetTables = await this.resolveQueryTables(reqJson);
+  public async isExist(reqJson: IRequestModel): Promise<CrudExistResult> {
+    // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
+    const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+
+    const targetTables = await this.resolveFindTables(reqJson);
 
     if (targetTables.length === 0) {
-      return false; // 无匹配表
+      throw new Error('[ShardingCrudPro] isExist: no matching tables found');
     }
 
     if (targetTables.length === 1) {
-      const ctx = await this.executeOnTable(targetTables[0], reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
-      return ctx.getResModelItem('is_exist') === true;
+      const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+      const exists = ctx.getResModelItem('is_exist') === true;
+      return new CrudExistResult({ exists, rawContext: ctx });
     }
 
-    // 多表判断：任一表存在即返回 true
-    const promises = targetTables.map(table =>
-      this.isExistInTable(table, reqJson)
-    );
-    const results = await Promise.all(promises);
-    return results.some(exists => exists);
+    // 多表判断：串行查询，任一表存在即返回 true
+    let exists = false;
+    let firstCtx: ExecuteContext | null = null;
+    for (const table of targetTables) {
+      const result = await this.isExistInTable(table, cleanedReqJson);
+      if (!firstCtx && result.ctx) {
+        firstCtx = result.ctx;
+      }
+      if (result.exists) {
+        exists = true;
+        break;
+      }
+    }
+
+    return new CrudExistResult({ exists, rawContext: firstCtx as any });
   }
 
   // ============ 私有方法：分表路由 ============
 
-  /**
-   * 【batchInsert 专用】按分表对数据进行分组
-   *
-   * 仅用于 batchInsert 方法，遍历所有数据项，
-   * 根据分表规则计算每条数据的目标分表，将相同分表的数据归为一组。
-   *
-   * @param dataArray 数据数组
-   * @returns 分表 -> 数据列表 的映射
-   */
   private batchInsertGroupDataByTable(dataArray: Record<string, any>[]): Map<string, Record<string, any>[]> {
     const groupedData = new Map<string, Record<string, any>[]>();
 
@@ -534,14 +594,9 @@ export class ShardingCrudPro {
     return this.router.resolveForInsert(this.config, context);
   }
 
-  /**
-   * 解析单个目标表
-   *
-   * 写操作必须确定单一目标表，否则抛出异常。
-   */
   private resolveSingleTable(
     reqJson: IRequestModel,
-    operation: 'insert' | 'update' | 'delete'
+    operation: 'insert' | 'update' | 'delete' | 'restore'
   ): string {
     // insert 操作使用 resolveForInsert（从 data 提取字段）
     if (operation === 'insert') {
@@ -570,9 +625,6 @@ export class ShardingCrudPro {
     return result;
   }
 
-  /**
-   * 获取分表字段提示
-   */
   private getShardingColumnHint(): string {
     if (this.config.type === ShardingType.RANGE || this.config.type === ShardingType.HASH) {
       return this.config.shardingColumn || '分表字段';
@@ -585,119 +637,95 @@ export class ShardingCrudPro {
 
   // ============ 私有方法：配置构建 ============
 
-  /**
-   * 构建配置
-   */
-  private buildCfg(sqlSimpleName: KeysOfSimpleSQL): IRequestCfgModel {
+  private buildCfg(sqlSimpleName: KeysOfSimpleSQL): IRequestCfgModel & { enableSoftDelete?: boolean } {
     return {
+      method: `ShardingCrudProAnonymous_${sqlSimpleName}`,
       ...this.baseCfg,
       sqlTable: this.config.baseTable,
       sqlSimpleName,
-    };
+    } as IRequestCfgModel & { enableSoftDelete?: boolean };
   }
 
   // ============ 私有方法：执行操作 ============
 
-  /**
-   * 在指定表上执行操作
-   */
   private async executeOnTable(
     table: string,
     reqJson: IRequestModel,
-    sqlSimpleName: KeysOfSimpleSQL
+    sqlSimpleName: KeysOfSimpleSQL,
+    extraCfg?: Partial<IRequestCfgModel>
   ): Promise<ExecuteContext> {
     const cfg = this.buildCfg(sqlSimpleName);
     cfg.sqlTable = table; // 替换为实际分表名
+    cfg.enableSoftDelete = this.enableSoftDelete;
+    
+    if (extraCfg) {
+      Object.assign(cfg, extraCfg);
+    }
 
-    return this.crudPro.executeCrudByCfg(reqJson, cfg);
-  }
+    // 创建 CrudPro 实例并设置 visitor
+    const crudPro = this.crudProFactory();
 
-  /**
-   * 从指定表查询单条
-   */
-  private async queryOneFromTable(table: string, reqJson: IRequestModel): Promise<any> {
-    try {
-      const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
-      return ctx.getOneObj();
-    } catch (e) {
-      // 表不存在时返回 null
-      return null;
-    }
+    // 应用软删除处理
+    fixSoftDelete(sqlSimpleName, cfg as any, reqJson, crudPro.getVisitor());
+
+    return crudPro.executeCrudByCfg(reqJson, cfg);
   }
 
-  /**
-   * 从指定表查询数量
-   */
-  private async queryCountFromTable(table: string, reqJson: IRequestModel): Promise<number> {
+
+
+  private async findCountFromTable(table: string, reqJson: IRequestModel): Promise<{ count: number; ctx: ExecuteContext | null }> {
     try {
       const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
-      return ctx.getResModelItem('total_count') || 0;
+      return { count: ctx.getResModelItem('total_count') || 0, ctx };
     } catch (e) {
       // 表不存在时返回 0
-      return 0;
+      return { count: 0, ctx: null };
     }
   }
 
-  /**
-   * 判断指定表中是否存在记录
-   */
-  private async isExistInTable(table: string, reqJson: IRequestModel): Promise<boolean> {
+  private async isExistInTable(table: string, reqJson: IRequestModel): Promise<{ exists: boolean; ctx: ExecuteContext | null }> {
     try {
       const ctx = await this.executeOnTable(table, reqJson, KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
-      return ctx.getResModelItem('is_exist') === true;
+      return { exists: ctx.getResModelItem('is_exist') === true, ctx };
     } catch (e) {
       // 表不存在时返回 false
-      return false;
+      return { exists: false, ctx: null };
     }
   }
 
   // ============ 表存在性检查和自动创建 ============
 
-  /**
-   * 获取数据库中真实存在的表名集合
-   */
-  private async getExistingTablesSet(): Promise<Set<string>> {
+  private async getExistingTablesSet(skipCache = false): Promise<Set<string>> {
     const { sqlDatabase, sqlDbType } = this.baseCfg;
 
     if (!sqlDatabase || !sqlDbType) {
       throw new Error('[ShardingCrudPro] 未配置 sqlDatabase 或 sqlDbType');
     }
 
-    const { tables } = await this.crudPro.getAllTableInfos({
-      sqlDatabase,
-      sqlDbType: sqlDbType as any,
-    });
+    const { tables } = await this.crudProFactory().getAllTableInfos(
+      {
+        sqlDatabase,
+        sqlDbType: sqlDbType as any,
+      },
+      { skipCache }
+    );
 
     return new Set(tables.map(t => t.name));
   }
 
-  /**
-   * 检查表是否存在
-   */
   private async isTableExists(tableName: string): Promise<boolean> {
-    const existingSet = await this.getExistingTablesSet();
+    const existingSet = await this.getExistingTablesSet(); // 使用缓存
     return existingSet.has(tableName);
   }
 
-  /**
-   * 创建分表（如果需要）
-   *
-   * 根据配置检查分表是否存在：
-   * - 如果分表已存在，直接返回
-   * - 如果分表不存在且 autoCreateTable=true，自动创建
-   * - 如果分表不存在且 autoCreateTable=false，抛出异常
-   *
-   * @param tableName 目标分表名
-   */
   private async createShardingTableIfNeeded(tableName: string): Promise<void> {
-    // 检查表是否已存在
-    if (await this.isTableExists(tableName)) {
-      return;
-    }
-
     // 根据配置决定是否自动创建
     if (!this.config.autoCreateTable) {
-      throw new Error(`[ShardingCrudPro] 分表 ${tableName} 不存在。请先创建分表，或设置 autoCreateTable: true 自动创建`);
+      // 使用缓存检查表是否存在，不存在则抛异常
+      if (!(await this.isTableExists(tableName))) {
+        throw new Error(`[ShardingCrudPro] 分表 ${tableName} 不存在。请先创建分表，或设置 autoCreateTable: true 自动创建`);
+      }
+      return;
     }
 
     // 检查数据库配置
@@ -705,7 +733,7 @@ export class ShardingCrudPro {
       throw new Error('[ShardingCrudPro] 请先调用 setBaseCfg 设置数据库配置');
     }
 
-    // 执行创建
+    // 执行创建（内部有 checkTableExists + 建表 + 刷新缓存）
     const result = await this.tableCreator.createTableIfNeeded(
       tableName,
       {
@@ -718,25 +746,241 @@ export class ShardingCrudPro {
     if (!result.success) {
       throw result.error || new Error(`[ShardingCrudPro] 创建分表 ${tableName} 失败`);
     }
+
+    // 建表成功后刷新缓存，确保后续请求命中新表
+    if (result.createSql) {
+      await this.getExistingTablesSet(true);
+    }
   }
 
   // ============ 参数校验 ============
 
   /**
-   * 校验查询参数的 orderBy 是否符合约束
+   * 判断是否为时间分表类型
+   */
+  private isTimeSharding(): boolean {
+    return [ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(this.config.type);
+  }
+
+  /**
+   * 校验时间分表插入操作的 data 必须包含 timeColumn
    *
-   * 约束条件：
-   * - 必须传 orderBy 参数
-   * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+   * 时间分表需要根据时间字段路由到正确的分表，
+   * 如果 data 中缺少时间字段，将无法确定数据应插入哪个分表。
    *
-   * 这是时间分表查询的核心约束：
-   * - 排序字段必须是分表字段（timeColumn），不允许其他字段
-   * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由调用方反转）
-   * - 这样无需内存排序，直接按表顺序拼接即可
+   * @param reqJson 请求参数
+   * @param operation 操作名称（用于错误提示）
+   * @throws Error 如果 data 中缺少时间字段
+   */
+  private validateTimeColumnForData(reqJson: IRequestModel, operation: string): void {
+    if (!this.isTimeSharding()) return;
+
+    const timeColumn = this.config.timeColumn!;
+    const data = reqJson.data as Record<string, any>;
+
+    if (!data || data[timeColumn] === undefined) {
+      throw new Error(
+        `[ShardingCrudPro] ${operation} 操作的 data 必须包含时间字段 '${timeColumn}'，用于路由到正确的分表。`
+      );
+    }
+  }
+
+  /**
+   * 校验时间分表批量插入操作的每条 data 必须包含 timeColumn
+   *
+   * @param dataArray 数据数组
+   * @param operation 操作名称（用于错误提示）
+   * @throws Error 如果任一条 data 中缺少时间字段
+   */
+  private validateTimeColumnForBatchData(dataArray: Record<string, any>[], operation: string): void {
+    if (!this.isTimeSharding()) return;
+
+    const timeColumn = this.config.timeColumn!;
+    for (let i = 0; i < dataArray.length; i++) {
+      if (!dataArray[i] || dataArray[i][timeColumn] === undefined) {
+        throw new Error(
+          `[ShardingCrudPro] ${operation} 操作的 data[${i}] 必须包含时间字段 '${timeColumn}'，用于路由到正确的分表。`
+        );
+      }
+    }
+  }
+
+  /**
+   * 校验时间分表写操作的 condition 必须包含路由字段（timeColumn）
+   *
+   * 时间分表需要根据时间字段路由到正确的分表，
+   * 如果 condition 中缺少时间字段，将无法确定操作哪个分表。
    *
    * @param reqJson 请求参数
+   * @param operation 操作名称（用于错误提示）
+   * @throws Error 如果 condition 中缺少时间字段
    */
-  private validateQueryOrderBy(reqJson: IRequestModel): void {
+  private validateRoutingFieldForCondition(reqJson: IRequestModel, operation: string): void {
+    if (!this.isTimeSharding()) return;
+
+    const timeColumn = this.config.timeColumn!;
+    const condition = reqJson.condition;
+
+    if (!condition || !condition[timeColumn]) {
+      throw new Error(
+        `[ShardingCrudPro] ${operation} 操作的 condition 必须包含时间字段 '${timeColumn}'，用于路由到正确的分表。` +
+        `请提供 '${timeColumn}' 字段（如 { ${timeColumn}: '2026-03-15' }）或时间范围（如 { ${timeColumn}: { $gte: '2024-01-01', $lte: '2024-03-31' } }）。`
+      );
+    }
+  }
+
+  /**
+   * 智能处理时间分表场景下的时间字段
+   *
+   * **问题背景**：
+   * 在时间分表（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(reqJson: IRequestModel): IRequestModel {
+    const { primaryKey, timeColumn, type } = this.config;
+
+    // 只有时间分表且配置了时间字段才需要处理
+    if (!timeColumn || ![ShardingType.YEAR, ShardingType.MONTH, ShardingType.DAY].includes(type)) {
+      return reqJson;
+    }
+
+    const condition = reqJson.condition;
+    if (!condition || typeof condition !== 'object') {
+      return reqJson;
+    }
+
+    const timeValue = condition[timeColumn];
+
+    // timeColumn 不存在 → 不处理
+    if (timeValue === undefined) {
+      return reqJson;
+    }
+
+    // 操作符表达式（$gte/$lte/$range/$in/$null 等）→ 始终保留，但校验时间精度
+    if (isOperatorExpression(timeValue)) {
+      this.validateTimeOperatorPrecision(timeValue as any, timeColumn);
+      return reqJson;
+    }
+
+    // 判断是否有主键
+    const hasPrimaryKey = primaryKey && condition[primaryKey] !== undefined;
+
+    // ---- 精确值处理 ----
+
+    // Date 对象：精确到毫秒，视为精确值
+    // number：时间戳，无法推断粒度，视为精确值
+    // boolean：视为精确值
+    // string：需要检测日期粒度
+
+    if (typeof timeValue === 'string') {
+      // 检测日期字符串粒度
+      const range = expandDateToRange(timeValue);
+
+      if (hasPrimaryKey) {
+        // 有主键 → 无论什么粒度的字符串，都清理
+        const { [timeColumn]: _, ...cleanedCondition } = condition;
+        return { ...reqJson, condition: cleanedCondition };
+      }
+
+      // 无主键 + 年/月/日粒度 → 转换为 $gte/$lte 范围
+      if (range) {
+        return {
+          ...reqJson,
+          condition: { ...condition, [timeColumn]: range },
+        };
+      }
+
+      // 无主键 + datetime 粒度或无法识别的格式 → 保留原值
+      return reqJson;
+    }
+
+    // Date / number / boolean / null 等其他精确值
+    if (hasPrimaryKey) {
+      // 有主键 → 清理
+      const { [timeColumn]: _, ...cleanedCondition } = condition;
+      return { ...reqJson, condition: cleanedCondition };
+    }
+
+    // 无主键 → 保留原值
+    return reqJson;
+  }
+
+  /**
+   * 校验时间操作符的值必须精确到秒
+   *
+   * MySQL 中 '2026-04-30' 等价于 '2026-04-30 00:00:00'，
+   * 导致 $lte: '2026-04-30' 会丢失当天所有数据。
+   * 如果用户需要查整月/整天数据，应传粒度字符串由系统自动转换，而非手动写 $gte/$lte。
+   *
+   * @param operatorValue 操作符表达式的值
+   * @param timeColumn 时间字段名
+   * @throws Error 如果操作符值缺少时间部分
+   */
+  private validateTimeOperatorPrecision(operatorValue: Record<string, any>, timeColumn: string): void {
+    // 需要校验精度的操作符
+    const PRECISION_OPERATORS = ['$gte', '$lte', '$gt', '$lt'];
+
+    for (const op of PRECISION_OPERATORS) {
+      const value = operatorValue[op];
+      if (value !== undefined && typeof value === 'string') {
+        // 匹配日期格式但缺少时间部分：'2026-04-30'
+        // datetime 格式 '2026-04-30 00:00:00' 不应被拦截
+        const dateOnlyPattern = /^\d{4}-\d{1,2}-\d{1,2}$/;
+        if (dateOnlyPattern.test(value)) {
+          throw new Error(
+            `[ShardingCrudPro] 时间字段 '${timeColumn}' 的 ${op} 值必须精确到秒，` +
+            `当前值: '${value}'。` +
+            `请使用 '${value} 23:59:59'（$lte/$lt）或 '${value} 00:00:00'（$gte/$gt），` +
+            `或直接传粒度字符串（如 '${value.substring(0, 7)}' 或 '${value}'）由系统自动转换范围。`
+          );
+        }
+      }
+    }
+
+    // $range 操作符校验：[start, end] 两个值都必须精确到秒
+    const rangeValue = operatorValue.$range;
+    if (Array.isArray(rangeValue) && rangeValue.length >= 2) {
+      const dateOnlyPattern = /^\d{4}-\d{1,2}-\d{1,2}$/;
+      for (let i = 0; i < rangeValue.length; i++) {
+        const val = rangeValue[i];
+        if (typeof val === 'string' && dateOnlyPattern.test(val)) {
+          throw new Error(
+            `[ShardingCrudPro] 时间字段 '${timeColumn}' 的 $range[${i}] 值必须精确到秒，` +
+            `当前值: '${val}'。` +
+            `请使用 '${val} ${i === 0 ? '00:00:00' : '23:59:59'}'，` +
+            `或直接传粒度字符串由系统自动转换范围。`
+          );
+        }
+      }
+    }
+  }
+
+  private validateFindOrderBy(reqJson: IRequestModel): void {
     // 非时间分表不强制 orderBy 约束（多表合并排序由调用方自行保证）
     const timeColumn = this.config.timeColumn;
     if (!timeColumn) {
@@ -780,29 +1024,10 @@ export class ShardingCrudPro {
     }
   }
 
-  /**
-   * 判断 orderBy 是否为 ASC 方向
-   *
-   * 前提：validateQueryOrderBy 已通过校验，orderBy 格式合法
-   *
-   * @param reqJson 请求参数
-   * @returns true 表示 ASC，false 表示 DESC
-   */
   private isAscOrderBy(reqJson: IRequestModel): boolean {
     return OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
   }
 
-  /**
-   * 根据排序方向对分表列表进行排序
-   *
-   * 分表名后缀为时间格式（如 202403、20240101），字典序即时间序。
-   * - DESC：降序排列（新→旧）
-   * - ASC：升序排列（旧→新）
-   *
-   * @param tables 分表列表
-   * @param reqJson 请求参数
-   * @returns 排序后的分表列表（新数组，不修改原数组）
-   */
   private sortTablesForOrderBy(tables: string[], reqJson: IRequestModel): string[] {
     const isAsc = this.isAscOrderBy(reqJson);
     return [...tables].sort((a, b) =>
@@ -810,15 +1035,60 @@ export class ShardingCrudPro {
     );
   }
 
-  // ============ 查询表解析（委托给 ShardingRouter） ============
+  // ============ 辅助方法 ============
 
   /**
-   * 解析查询表（带真实表过滤）
-   *
-   * 将查询路由委托给 ShardingRouter.resolveQuery，
-   * 由 ShardingRouter 统一处理所有查询路由逻辑。
+   * 构建辅助定位信息
+   */
+  private buildDebugInfo(sqlTable: string | undefined, condition: Record<string, any> | undefined): { sqlDatabase: string; sqlTable: string; condition?: Record<string, any> } {
+    const info: { sqlDatabase: string; sqlTable: string; condition?: Record<string, any> } = {
+      sqlDatabase: this.baseCfg.sqlDatabase || 'unknown',
+      sqlTable: sqlTable || this.config.baseTable,
+    };
+    if (condition) {
+      info.condition = condition;
+    }
+    return info;
+  }
+
+  /**
+   * 格式化唯一性错误消息
    */
-  private async resolveQueryTables(reqJson: IRequestModel): Promise<string[]> {
+  private formatUniqueError(
+    foundCount: number, 
+    tables: string | string[], 
+    condition: Record<string, any> | undefined,
+    isMultiTable: boolean = false
+  ): string {
+    const parts = [
+      `[ShardingCrudPro] findUniqueOne 期望唯一一条记录，但查询到 ${foundCount} 条`,
+    ];
+
+    if (this.baseCfg.sqlDatabase) {
+      parts.push(`数据库: ${this.baseCfg.sqlDatabase}`);
+    }
+
+    if (isMultiTable && Array.isArray(tables)) {
+      parts.push(`基表: ${this.config.baseTable}`);
+      parts.push(`分表: [${tables.join(', ')}]`);
+    } else {
+      parts.push(`表: ${typeof tables === 'string' ? tables : tables[0]}`);
+    }
+
+    if (condition) {
+      try {
+        parts.push(`条件: ${JSON.stringify(condition)}`);
+      } catch {
+        parts.push(`条件: [无法序列化]`);
+      }
+    }
+
+    return parts.join(' | ');
+  }
+
+  // ============ 查询表解析（委托给 ShardingRouter） ============
+
+  private async resolveFindTables(reqJson: IRequestModel): Promise<string[]> {
     const context: IShardingRouterContext = {
       config: this.config,
       condition: reqJson.condition,