midway-fatcms 0.0.6 → 0.0.8

package/dist/libs/crud-sharding/ShardingCrudPro.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShardingCrudPro = void 0;
+const OrderByUtils_1 = require("../../libs/crud-pro/utils/OrderByUtils");
 const keys_1 = require("../../libs/crud-pro/models/keys");
 const ShardingConfig_1 = require("./ShardingConfig");
+const fixSoftDelete_1 = require("../../libs/crud-pro-quick/fixSoftDelete");
 const ShardingRouter_1 = require("./ShardingRouter");
 const ShardingMerger_1 = require("./ShardingMerger");
 const ShardingTableCreator_1 = require("./ShardingTableCreator");
 const ShardingCountCache_1 = require("./ShardingCountCache");
+const CrudResult_1 = require("../../libs/crud-pro/models/CrudResult");
+const ShardingResult_1 = require("./ShardingResult");
+const ShardingUtils_1 = require("./ShardingUtils");
 /**
  * 分表 CRUD 操作封装器
  *
@@ -33,17 +38,24 @@ const ShardingCountCache_1 = require("./ShardingCountCache");
  * 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,
  * });
  */
 class ShardingCrudPro {
-    constructor(crudPro, config) {
+    constructor(crudProFactory, config) {
         this.baseCfg = {};
-        this.crudPro = crudPro;
+        this.enableSoftDelete = false;
         this.config = config;
+        // 兼容旧的 CrudPro 实例方式和新的工厂函数方式
+        if (typeof crudProFactory === 'function') {
+            this.crudProFactory = crudProFactory;
+        }
+        else {
+            throw new Error('[ShardingCrudPro] 请使用 CrudProFactory 工厂函数模式');
+        }
         // 时间分表必须显式指定 timeColumn
         if ([ShardingConfig_1.ShardingType.YEAR, ShardingConfig_1.ShardingType.MONTH, ShardingConfig_1.ShardingType.DAY].includes(config.type)) {
             if (!config.timeColumn) {
@@ -52,7 +64,7 @@ class ShardingCrudPro {
         }
         this.router = new ShardingRouter_1.ShardingRouter();
         this.merger = new ShardingMerger_1.ShardingMerger();
-        this.tableCreator = new ShardingTableCreator_1.ShardingTableCreator(crudPro, config);
+        this.tableCreator = new ShardingTableCreator_1.ShardingTableCreator(this.crudProFactory, config);
         // 初始化 COUNT 缓存（如果配置了）
         if (config.countCache) {
             const countCache = new ShardingCountCache_1.ShardingCountCache(config.type, config.baseTable, config.countCache.ttlSeconds, config.countCache.maxSize);
@@ -60,101 +72,44 @@ class ShardingCrudPro {
         }
     }
     // ============ 配置方法 ============
-    /**
-     * 设置基础配置（会应用到所有操作）
-     *
-     * @param cfg 配置项，如 sqlDatabase、sqlDbType 等
-     * @returns this，支持链式调用
-     *
-     * @example
-     * sharding.setBaseCfg({
-     *   sqlDatabase: 'mydb',
-     *   sqlDbType: SqlDbType.mysql,
-     * });
-     */
     setBaseCfg(cfg) {
         this.baseCfg = { ...this.baseCfg, ...cfg };
         return this;
     }
-    /**
-     * 获取分表配置
-     */
     getConfig() {
         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 是否启用软删除
      */
+    setEnableSoftDelete(enable) {
+        this.enableSoftDelete = enable;
+        return this;
+    }
+    // ============ 写操作（单表路由） ============
     async insert(reqJson) {
+        // 时间分表校验：data 必须包含 timeColumn
+        this.validateTimeColumnForData(reqJson, 'insert');
         const targetTable = this.resolveSingleTable(reqJson, 'insert');
         // 确保分表存在（根据配置决定是否自动创建）
         await this.createShardingTableIfNeeded(targetTable);
-        return this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT);
+        const ctx = await this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.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 },
-     * // ]
-     */
     async batchInsert(reqJson) {
+        var _a, _b;
         const dataArray = reqJson.data;
         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);
         // 确保所有目标分表存在（根据配置决定是否自动创建）
@@ -162,27 +117,31 @@ class ShardingCrudPro {
         for (let i = 0; i < tableNames.length; i++) {
             await this.createShardingTableIfNeeded(tableNames[i]);
         }
-        // 并行执行各分表的批量插入
-        const insertPromises = Array.from(groupedData.entries()).map(async ([table, items]) => {
+        // 串行执行各分表的批量插入
+        const results = [];
+        let lastContext = null;
+        for (const [table, items] of groupedData.entries()) {
             try {
                 const ctx = await this.executeOnTable(table, { data: items }, keys_1.KeysOfSimpleSQL.SIMPLE_BATCH_INSERT);
-                return {
+                lastContext = ctx;
+                results.push({
                     table,
-                    affected: ctx.getResModelItem('affected') || items.length,
+                    affected: ((_a = ctx.getResModelItem('affected')) === null || _a === void 0 ? void 0 : _a.affectedRows) || items.length,
                     rowCount: items.length,
                     error: null,
-                };
+                    context: ctx,
+                });
             }
             catch (e) {
-                return {
+                results.push({
                     table,
                     affected: 0,
                     rowCount: items.length,
                     error: e,
-                };
+                    context: null,
+                });
             }
-        });
-        const results = await Promise.all(insertPromises);
+        }
         // 汇总结果
         const tableResults = results.map(r => ({
             table: r.table,
@@ -193,223 +152,312 @@ class ShardingCrudPro {
             .filter(r => r.error !== null)
             .map(r => ({ table: r.table, error: r.error }));
         const totalAffected = results.reduce((sum, r) => sum + r.affected, 0);
-        return {
+        // Use last successful context, or create a minimal one
+        const finalContext = lastContext || ((_b = results.find(r => r.context)) === null || _b === void 0 ? void 0 : _b.context);
+        if (!finalContext) {
+            throw new Error('[ShardingCrudPro] batchInsert failed - no successful inserts');
+        }
+        return new ShardingResult_1.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 },
-     * });
-     */
     async update(reqJson) {
+        // 时间分表校验：condition 必须包含路由字段
+        this.validateRoutingFieldForCondition(reqJson, 'update');
         const targetTable = this.resolveSingleTable(reqJson, 'update');
-        return this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+        // 清理 condition 中的时间字段（如果能确定单一分表）
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const ctx = await this.executeOnTable(targetTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({
+            affectedRows: affected.affectedRows,
+            insertId: affected.insertId,
+            rawContext: ctx,
+        });
     }
-    /**
-     * 删除数据
-     *
-     * 根据条件中的分表字段自动路由到目标分表。
-     *
-     * @param reqJson 请求参数，condition 为删除条件
-     * @returns 执行上下文
-     */
     async delete(reqJson) {
+        // 时间分表校验：condition 必须包含路由字段
+        this.validateRoutingFieldForCondition(reqJson, 'delete');
         const targetTable = this.resolveSingleTable(reqJson, 'delete');
-        return this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_DELETE);
+        // 清理 condition 中的时间字段（如果能确定单一分表）
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const ctx = await this.executeOnTable(targetTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_DELETE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.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' } });
      */
+    async restore(reqJson) {
+        // 时间分表校验：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 = {
+            ...cleanedReqJson,
+            data: {
+                ...cleanedReqJson.data,
+                deleted_at: 0,
+                deleted_by: '',
+            },
+        };
+        const ctx = await this.executeOnTable(targetTable, restoreReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({
+            affectedRows: affected.affectedRows,
+            insertId: affected.insertId,
+            rawContext: ctx,
+        });
+    }
     async insertOrUpdate(reqJson) {
+        var _a;
+        // 时间分表校验：data 必须包含 timeColumn，condition 必须包含路由字段
+        this.validateTimeColumnForData(reqJson, 'insertOrUpdate');
+        this.validateRoutingFieldForCondition(reqJson, 'insertOrUpdate');
         const targetTable = this.resolveSingleTable(reqJson, 'update'); // 使用 condition 路由
-        return this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE);
+        const ctx = await this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE);
+        const resModel = ctx.getResModel();
+        return new CrudResult_1.CrudUpsertResult({
+            affected: resModel.affected,
+            insertAffected: resModel.insert_affected,
+            updateAffected: resModel.update_affected,
+            isExist: (_a = resModel.is_exist) !== null && _a !== void 0 ? _a : false,
+            rawContext: ctx,
+        });
     }
-    /**
-     * 插入或更新（ON DUPLICATE KEY UPDATE）
-     *
-     * 路由逻辑：根据 condition 路由（先查询是否存在）
-     *
-     * @param reqJson 请求参数
-     * @returns 执行上下文
-     */
     async insertOnDuplicateUpdate(reqJson) {
+        // 时间分表校验：data 必须包含 timeColumn，condition 必须包含路由字段
+        this.validateTimeColumnForData(reqJson, 'insertOnDuplicateUpdate');
+        this.validateRoutingFieldForCondition(reqJson, 'insertOnDuplicateUpdate');
         const targetTable = this.resolveSingleTable(reqJson, 'update'); // 使用 condition 路由
-        return this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE);
+        const ctx = await this.executeOnTable(targetTable, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE);
+        const affected = ctx.getResModel().affected || { affectedRows: 0 };
+        return new CrudResult_1.CrudWriteResult({
+            affectedRows: affected.affectedRows,
+            insertId: affected.insertId,
+            rawContext: ctx,
+        });
     }
     // ============ 查询操作（可能多表） ============
-    /**
-     * 查询单条记录
-     *
-     * 如果能根据条件确定单一分表，则查询单表；
-     * 否则按顺序查询各分表，返回第一条匹配记录。
-     *
-     * @param reqJson 请求参数，condition 为查询条件
-     * @returns 单条记录，未找到返回 null
-     *
-     * @example
-     * const order = await sharding.queryOne({
-     *   condition: { order_id: 'ORD001' },
-     * });
-     */
-    async queryOne(reqJson) {
-        const targetTables = await this.resolveQueryTables(reqJson);
+    async findOne(reqJson) {
+        // 清理 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 = 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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+                lastCtx = ctx;
+                const row = ctx.getOneObj();
+                if (row) {
+                    return new CrudResult_1.CrudQueryOneResult({ row: row, rawContext: ctx, debugInfo: this.buildDebugInfo(table, reqJson.condition) });
+                }
+            }
+            catch (e) {
+                // 表不存在时跳过，继续查下一张表
+            }
         }
-        return null;
+        // 未找到，使用最后一次查询的 ctx
+        return new CrudResult_1.CrudQueryOneResult({ row: null, rawContext: lastCtx, debugInfo: this.buildDebugInfo(targetTables[0], reqJson.condition) });
     }
     /**
-     * 查询列表
+     * 查询唯一单条记录（期望结果为 0 条或 1 条）
      *
-     * 可能涉及多个分表，结果会自动合并。
+     * 与 findOne 不同，此方法会校验查询结果的唯一性：
+     * - 如果查到 0 条：返回 row = null
+     * - 如果查到 1 条：正常返回
+     * - 如果查到多条：抛出异常，包含详细的定位信息（含分表名列表）
      *
-     * 使用约束：
-     * - 必须传 orderBy 参数
-     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+     * 分表场景的特殊处理：
+     * - 单分表：直接查询并校验唯一性
+     * - 多分表：顺序查询各分表，累计找到的数量，超过 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);
+     * }
      */
-    async query(reqJson) {
-        const targetTables = await this.resolveQueryTables(reqJson);
+    async findUniqueOne(reqJson) {
+        // 清理 condition 中的时间字段（如果能确定单一分表）
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            // 无匹配表，返回空结果
+            return new CrudResult_1.CrudQueryOneResult({ row: null, rawContext: null, debugInfo: this.buildDebugInfo(undefined, reqJson.condition) });
+        }
+        // 统一逻辑：每个表查 maxLimit: 2，收集所有结果
+        const allRows = [];
+        const foundTables = [];
+        let firstCtx = null;
+        for (const table of targetTables) {
+            try {
+                const ctx = await this.executeOnTable(table, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY, { maxLimit: 2 });
+                if (!firstCtx) {
+                    firstCtx = ctx;
+                }
+                const rows = ctx.getResRows();
+                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 CrudResult_1.CrudQueryOneResult({
+            row: allRows[0] || null,
+            rawContext: firstCtx,
+            debugInfo: this.buildDebugInfo(foundTables[0] || targetTables[0], reqJson.condition),
+        });
+    }
+    async findList(reqJson) {
+        // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
         if (targetTables.length === 0) {
-            return []; // 无匹配表，返回空结果
+            return new CrudResult_1.CrudQueryListResult({ rows: [], rawContext: null });
         }
         if (targetTables.length === 1) {
-            const ctx = await this.executeOnTable(targetTables[0], reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY);
-            return ctx.getResRows();
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY);
+            const rows = ctx.getResRows();
+            return new CrudResult_1.CrudQueryListResult({ rows, rawContext: ctx });
         }
         // 多表查询时，需要参数校验
-        this.validateQueryOrderBy(reqJson);
+        this.validateFindOrderBy(reqJson);
         // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
         const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
         // 多表查询合并
-        return this.merger.mergeQuery(this.crudPro, tablesForMerge, reqJson, this.buildCfg(keys_1.KeysOfSimpleSQL.SIMPLE_QUERY));
+        const mergeResult = await this.merger.mergeQuery(this.crudProFactory(), tablesForMerge, cleanedReqJson, this.buildCfg(keys_1.KeysOfSimpleSQL.SIMPLE_QUERY));
+        return new CrudResult_1.CrudQueryListResult({ rows: mergeResult.rows, 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);
-     */
-    async queryPage(reqJson) {
-        const targetTables = await this.resolveQueryTables(reqJson);
+    async findPage(reqJson) {
+        // 清理 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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
-            return ctx.getResModelForQueryPage();
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_PAGE);
+            const pageResult = ctx.getResModelForQueryPage();
+            return new CrudResult_1.CrudQueryPageResult({
+                rows: pageResult.rows,
+                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, tablesForMerge, reqJson, this.buildCfg(keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_PAGE));
+        const pageResult = await this.merger.mergePageQuery(this.crudProFactory(), tablesForMerge, cleanedReqJson, this.buildCfg(keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_PAGE));
+        return new CrudResult_1.CrudQueryPageResult({
+            rows: pageResult.rows,
+            totalCount: pageResult.total_count,
+            rawContext: pageResult.lastCtx,
+        });
     }
-    /**
-     * 查询记录总数
-     *
-     * 如果涉及多个分表，会并行查询各分表并汇总。
-     *
-     * @param reqJson 请求参数
-     * @returns 记录总数
-     */
-    async queryCount(reqJson) {
-        const targetTables = await this.resolveQueryTables(reqJson);
+    async findCount(reqJson) {
+        var _a;
+        // 清理 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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
-            return ctx.getResModelItem('total_count') || 0;
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+            const count = ctx.getResModelItem('total_count') || 0;
+            return new CrudResult_1.CrudCountResult({ count, rawContext: ctx });
+        }
+        // 多表统计：串行查询后求和
+        const countResults = [];
+        for (const table of targetTables) {
+            const result = await this.findCountFromTable(table, cleanedReqJson);
+            countResults.push(result);
         }
-        // 多表统计：并行查询后求和
-        const countPromises = targetTables.map(table => this.queryCountFromTable(table, reqJson));
-        const counts = await Promise.all(countPromises);
-        return counts.reduce((sum, c) => sum + c, 0);
+        const totalCount = countResults.reduce((sum, r) => sum + r.count, 0);
+        const firstCtx = ((_a = countResults.find(r => r.ctx !== null)) === null || _a === void 0 ? void 0 : _a.ctx) || null;
+        return new CrudResult_1.CrudCountResult({ count: totalCount, rawContext: firstCtx });
     }
-    /**
-     * 判断记录是否存在
-     *
-     * 如果涉及多个分表，会并行查询，任一分表存在即返回 true。
-     *
-     * @param reqJson 请求参数
-     * @returns 是否存在
-     */
     async isExist(reqJson) {
-        const targetTables = await this.resolveQueryTables(reqJson);
+        // 清理 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, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
-            return ctx.getResModelItem('is_exist') === true;
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+            const exists = ctx.getResModelItem('is_exist') === true;
+            return new CrudResult_1.CrudExistResult({ exists, rawContext: ctx });
+        }
+        // 多表判断：串行查询，任一表存在即返回 true
+        let exists = false;
+        let firstCtx = 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;
+            }
         }
-        // 多表判断：任一表存在即返回 true
-        const promises = targetTables.map(table => this.isExistInTable(table, reqJson));
-        const results = await Promise.all(promises);
-        return results.some(exists => exists);
+        return new CrudResult_1.CrudExistResult({ exists, rawContext: firstCtx });
     }
     // ============ 私有方法：分表路由 ============
-    /**
-     * 【batchInsert 专用】按分表对数据进行分组
-     *
-     * 仅用于 batchInsert 方法，遍历所有数据项，
-     * 根据分表规则计算每条数据的目标分表，将相同分表的数据归为一组。
-     *
-     * @param dataArray 数据数组
-     * @returns 分表 -> 数据列表 的映射
-     */
     batchInsertGroupDataByTable(dataArray) {
         const groupedData = new Map();
         for (const item of dataArray) {
@@ -429,11 +477,6 @@ class ShardingCrudPro {
         // 批量插入使用 resolveForInsert，确保返回单一表名
         return this.router.resolveForInsert(this.config, context);
     }
-    /**
-     * 解析单个目标表
-     *
-     * 写操作必须确定单一目标表，否则抛出异常。
-     */
     resolveSingleTable(reqJson, operation) {
         // insert 操作使用 resolveForInsert（从 data 提取字段）
         if (operation === 'insert') {
@@ -456,9 +499,6 @@ class ShardingCrudPro {
         }
         return result;
     }
-    /**
-     * 获取分表字段提示
-     */
     getShardingColumnHint() {
         if (this.config.type === ShardingConfig_1.ShardingType.RANGE || this.config.type === ShardingConfig_1.ShardingType.HASH) {
             return this.config.shardingColumn || '分表字段';
@@ -469,110 +509,78 @@ class ShardingCrudPro {
         return '分表字段';
     }
     // ============ 私有方法：配置构建 ============
-    /**
-     * 构建配置
-     */
     buildCfg(sqlSimpleName) {
         return {
+            method: `ShardingCrudProAnonymous_${sqlSimpleName}`,
             ...this.baseCfg,
             sqlTable: this.config.baseTable,
             sqlSimpleName,
         };
     }
     // ============ 私有方法：执行操作 ============
-    /**
-     * 在指定表上执行操作
-     */
-    async executeOnTable(table, reqJson, sqlSimpleName) {
+    async executeOnTable(table, reqJson, sqlSimpleName, extraCfg) {
         const cfg = this.buildCfg(sqlSimpleName);
         cfg.sqlTable = table; // 替换为实际分表名
-        return this.crudPro.executeCrudByCfg(reqJson, cfg);
+        cfg.enableSoftDelete = this.enableSoftDelete;
+        if (extraCfg) {
+            Object.assign(cfg, extraCfg);
+        }
+        // 创建 CrudPro 实例并设置 visitor
+        const crudPro = this.crudProFactory();
+        // 应用软删除处理
+        (0, fixSoftDelete_1.fixSoftDelete)(sqlSimpleName, cfg, reqJson, crudPro.getVisitor());
+        return crudPro.executeCrudByCfg(reqJson, cfg);
     }
-    /**
-     * 从指定表查询单条
-     */
-    async queryOneFromTable(table, reqJson) {
-        try {
-            const ctx = await this.executeOnTable(table, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
-            return ctx.getOneObj();
-        }
-        catch (e) {
-            // 表不存在时返回 null
-            return null;
-        }
-    }
-    /**
-     * 从指定表查询数量
-     */
-    async queryCountFromTable(table, reqJson) {
+    async findCountFromTable(table, reqJson) {
         try {
             const ctx = await this.executeOnTable(table, reqJson, keys_1.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 };
         }
     }
-    /**
-     * 判断指定表中是否存在记录
-     */
     async isExistInTable(table, reqJson) {
         try {
             const ctx = await this.executeOnTable(table, reqJson, keys_1.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 };
         }
     }
     // ============ 表存在性检查和自动创建 ============
-    /**
-     * 获取数据库中真实存在的表名集合
-     */
-    async getExistingTablesSet() {
+    async getExistingTablesSet(skipCache = false) {
         const { sqlDatabase, sqlDbType } = this.baseCfg;
         if (!sqlDatabase || !sqlDbType) {
             throw new Error('[ShardingCrudPro] 未配置 sqlDatabase 或 sqlDbType');
         }
-        const { tables } = await this.crudPro.getAllTableInfos({
+        const { tables } = await this.crudProFactory().getAllTableInfos({
             sqlDatabase,
             sqlDbType: sqlDbType,
-        });
+        }, { skipCache });
         return new Set(tables.map(t => t.name));
     }
-    /**
-     * 检查表是否存在
-     */
     async isTableExists(tableName) {
-        const existingSet = await this.getExistingTablesSet();
+        const existingSet = await this.getExistingTablesSet(); // 使用缓存
         return existingSet.has(tableName);
     }
-    /**
-     * 创建分表（如果需要）
-     *
-     * 根据配置检查分表是否存在：
-     * - 如果分表已存在，直接返回
-     * - 如果分表不存在且 autoCreateTable=true，自动创建
-     * - 如果分表不存在且 autoCreateTable=false，抛出异常
-     *
-     * @param tableName 目标分表名
-     */
     async createShardingTableIfNeeded(tableName) {
-        // 检查表是否已存在
-        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;
         }
         // 检查数据库配置
         if (!this.baseCfg.sqlDatabase || !this.baseCfg.sqlDbType) {
             throw new Error('[ShardingCrudPro] 请先调用 setBaseCfg 设置数据库配置');
         }
-        // 执行创建
+        // 执行创建（内部有 checkTableExists + 建表 + 刷新缓存）
         const result = await this.tableCreator.createTableIfNeeded(tableName, {
             sqlDatabase: this.baseCfg.sqlDatabase,
             sqlDbType: this.baseCfg.sqlDbType,
@@ -580,110 +588,282 @@ class ShardingCrudPro {
         if (!result.success) {
             throw result.error || new Error(`[ShardingCrudPro] 创建分表 ${tableName} 失败`);
         }
+        // 建表成功后刷新缓存，确保后续请求命中新表
+        if (result.createSql) {
+            await this.getExistingTablesSet(true);
+        }
     }
     // ============ 参数校验 ============
     /**
-     * 校验查询参数的 orderBy 是否符合约束
+     * 判断是否为时间分表类型
+     */
+    isTimeSharding() {
+        return [ShardingConfig_1.ShardingType.YEAR, ShardingConfig_1.ShardingType.MONTH, ShardingConfig_1.ShardingType.DAY].includes(this.config.type);
+    }
+    /**
+     * 校验时间分表插入操作的 data 必须包含 timeColumn
+     *
+     * 时间分表需要根据时间字段路由到正确的分表，
+     * 如果 data 中缺少时间字段，将无法确定数据应插入哪个分表。
+     *
+     * @param reqJson 请求参数
+     * @param operation 操作名称（用于错误提示）
+     * @throws Error 如果 data 中缺少时间字段
+     */
+    validateTimeColumnForData(reqJson, operation) {
+        if (!this.isTimeSharding())
+            return;
+        const timeColumn = this.config.timeColumn;
+        const data = reqJson.data;
+        if (!data || data[timeColumn] === undefined) {
+            throw new Error(`[ShardingCrudPro] ${operation} 操作的 data 必须包含时间字段 '${timeColumn}'，用于路由到正确的分表。`);
+        }
+    }
+    /**
+     * 校验时间分表批量插入操作的每条 data 必须包含 timeColumn
      *
-     * 约束条件：
-     * - 必须传 orderBy 参数
-     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+     * @param dataArray 数据数组
+     * @param operation 操作名称（用于错误提示）
+     * @throws Error 如果任一条 data 中缺少时间字段
+     */
+    validateTimeColumnForBatchData(dataArray, operation) {
+        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）
      *
-     * 这是时间分表查询的核心约束：
-     * - 排序字段必须是分表字段（timeColumn），不允许其他字段
-     * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由调用方反转）
-     * - 这样无需内存排序，直接按表顺序拼接即可
+     * 时间分表需要根据时间字段路由到正确的分表，
+     * 如果 condition 中缺少时间字段，将无法确定操作哪个分表。
      *
      * @param reqJson 请求参数
+     * @param operation 操作名称（用于错误提示）
+     * @throws Error 如果 condition 中缺少时间字段
      */
-    validateQueryOrderBy(reqJson) {
+    validateRoutingFieldForCondition(reqJson, operation) {
+        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 处理后的请求参数
+     */
+    cleanTimeColumnForSingleTableQuery(reqJson) {
+        const { primaryKey, timeColumn, type } = this.config;
+        // 只有时间分表且配置了时间字段才需要处理
+        if (!timeColumn || ![ShardingConfig_1.ShardingType.YEAR, ShardingConfig_1.ShardingType.MONTH, ShardingConfig_1.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 ((0, ShardingUtils_1.isOperatorExpression)(timeValue)) {
+            this.validateTimeOperatorPrecision(timeValue, timeColumn);
+            return reqJson;
+        }
+        // 判断是否有主键
+        const hasPrimaryKey = primaryKey && condition[primaryKey] !== undefined;
+        // ---- 精确值处理 ----
+        // Date 对象：精确到毫秒，视为精确值
+        // number：时间戳，无法推断粒度，视为精确值
+        // boolean：视为精确值
+        // string：需要检测日期粒度
+        if (typeof timeValue === 'string') {
+            // 检测日期字符串粒度
+            const range = (0, ShardingUtils_1.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 如果操作符值缺少时间部分
+     */
+    validateTimeOperatorPrecision(operatorValue, timeColumn) {
+        // 需要校验精度的操作符
+        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'}'，` +
+                        `或直接传粒度字符串由系统自动转换范围。`);
+                }
+            }
+        }
+    }
+    validateFindOrderBy(reqJson) {
         // 非时间分表不强制 orderBy 约束（多表合并排序由调用方自行保证）
         const timeColumn = this.config.timeColumn;
         if (!timeColumn) {
             return;
         }
         const orderBy = reqJson.orderBy;
-        const expectedDesc = `${timeColumn} DESC`;
-        const expectedAsc = `${timeColumn} ASC`;
         // 1. 必须传 orderBy
         if (!orderBy) {
             throw new Error(`[ShardingCrudPro] 查询操作必须传 orderBy 参数。` +
                 `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
         }
-        // 2. 校验 orderBy 格式（直接字符串比较，避免正则转义问题）
-        if (typeof orderBy === 'string') {
-            const upper = orderBy.trim().toUpperCase();
-            if (upper !== expectedDesc.toUpperCase() && upper !== expectedAsc.toUpperCase()) {
-                throw new Error(`[ShardingCrudPro] orderBy 参数必须是 '${timeColumn} DESC' 或 '${timeColumn} ASC'，` +
-                    `当前值: '${orderBy}'`);
-            }
+        // 2. 使用工具类解析并校验首个排序字段是否为 timeColumn
+        const firstOrderBy = OrderByUtils_1.OrderByUtils.getFirstOrderBy(orderBy);
+        if (!firstOrderBy) {
+            throw new Error(`[ShardingCrudPro] orderBy 参数格式错误，无法解析。` +
+                `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
         }
-        else if (Array.isArray(orderBy)) {
-            // 数组格式：首个排序字段必须是 timeColumn DESC/ASC，允许附加次级排序
-            if (orderBy.length === 0) {
-                throw new Error(`[ShardingCrudPro] orderBy 数组不能为空，首个排序字段必须为 '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
-            }
-            const firstItem = orderBy[0];
-            const firstItemStr = typeof firstItem === 'string'
-                ? firstItem
-                : `${firstItem.fieldName} ${firstItem.orderType || 'ASC'}`;
-            const upper = firstItemStr.trim().toUpperCase();
-            if (upper !== expectedDesc.toUpperCase() && upper !== expectedAsc.toUpperCase()) {
-                throw new Error(`[ShardingCrudPro] orderBy 数组首个排序字段必须为 '${timeColumn} DESC' 或 '${timeColumn} ASC'，` +
-                    `当前值: '${firstItemStr}'`);
-            }
+        if (firstOrderBy.fieldName !== timeColumn) {
+            throw new Error(`[ShardingCrudPro] orderBy 首个排序字段必须为 '${timeColumn}'，` +
+                `当前值: '${firstOrderBy.fieldName}'`);
         }
-        else {
-            throw new Error(`[ShardingCrudPro] orderBy 参数格式错误，期望字符串或数组。`);
+        // 校验排序方向是否为 ASC 或 DESC
+        const orderType = firstOrderBy.orderType.toUpperCase();
+        if (orderType !== 'ASC' && orderType !== 'DESC') {
+            throw new Error(`[ShardingCrudPro] orderBy 排序方向必须是 'ASC' 或 'DESC'，` +
+                `当前值: '${firstOrderBy.orderType}'`);
         }
     }
-    /**
-     * 判断 orderBy 是否为 ASC 方向
-     *
-     * 前提：validateQueryOrderBy 已通过校验，orderBy 格式合法
-     *
-     * @param reqJson 请求参数
-     * @returns true 表示 ASC，false 表示 DESC
-     */
     isAscOrderBy(reqJson) {
-        const orderBy = reqJson.orderBy;
-        if (!orderBy)
-            return false;
-        if (typeof orderBy === 'string') {
-            return orderBy.trim().toUpperCase().endsWith('ASC');
-        }
-        if (Array.isArray(orderBy) && orderBy.length > 0) {
-            const firstItem = orderBy[0];
-            const firstItemStr = typeof firstItem === 'string'
-                ? firstItem
-                : `${firstItem.fieldName} ${firstItem.orderType || 'ASC'}`;
-            return firstItemStr.trim().toUpperCase().endsWith('ASC');
-        }
-        return false;
+        return OrderByUtils_1.OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
     }
-    /**
-     * 根据排序方向对分表列表进行排序
-     *
-     * 分表名后缀为时间格式（如 202403、20240101），字典序即时间序。
-     * - DESC：降序排列（新→旧）
-     * - ASC：升序排列（旧→新）
-     *
-     * @param tables 分表列表
-     * @param reqJson 请求参数
-     * @returns 排序后的分表列表（新数组，不修改原数组）
-     */
     sortTablesForOrderBy(tables, reqJson) {
         const isAsc = this.isAscOrderBy(reqJson);
         return [...tables].sort((a, b) => isAsc ? a.localeCompare(b) : b.localeCompare(a));
     }
-    // ============ 查询表解析（委托给 ShardingRouter） ============
+    // ============ 辅助方法 ============
     /**
-     * 解析查询表（带真实表过滤）
-     *
-     * 将查询路由委托给 ShardingRouter.resolveQuery，
-     * 由 ShardingRouter 统一处理所有查询路由逻辑。
+     * 构建辅助定位信息
+     */
+    buildDebugInfo(sqlTable, condition) {
+        const info = {
+            sqlDatabase: this.baseCfg.sqlDatabase || 'unknown',
+            sqlTable: sqlTable || this.config.baseTable,
+        };
+        if (condition) {
+            info.condition = condition;
+        }
+        return info;
+    }
+    /**
+     * 格式化唯一性错误消息
      */
-    async resolveQueryTables(reqJson) {
+    formatUniqueError(foundCount, tables, condition, isMultiTable = false) {
+        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 (_a) {
+                parts.push(`条件: [无法序列化]`);
+            }
+        }
+        return parts.join(' | ');
+    }
+    // ============ 查询表解析（委托给 ShardingRouter） ============
+    async resolveFindTables(reqJson) {
         const context = {
             config: this.config,
             condition: reqJson.condition,