midway-fatcms 0.0.8 → 0.0.9

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

@@ -1,879 +0,0 @@
-"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 操作封装器
- *
- * 在 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,
- * });
- */
-class ShardingCrudPro {
-    constructor(crudProFactory, config) {
-        this.baseCfg = {};
-        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) {
-                throw new Error('[ShardingCrudPro] 时间分表（YEAR/MONTH/DAY）必须显式指定 timeColumn 字段');
-            }
-        }
-        this.router = new ShardingRouter_1.ShardingRouter();
-        this.merger = new ShardingMerger_1.ShardingMerger();
-        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);
-            this.merger.setCountCache(countCache);
-        }
-    }
-    // ============ 配置方法 ============
-    setBaseCfg(cfg) {
-        this.baseCfg = { ...this.baseCfg, ...cfg };
-        return this;
-    }
-    getConfig() {
-        return this.config;
-    }
-    /**
-     * 设置是否启用软删除
-     * @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);
-        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,
-        });
-    }
-    async batchInsert(reqJson) {
-        var _a, _b;
-        const dataArray = reqJson.data;
-        if (!Array.isArray(dataArray) || dataArray.length === 0) {
-            throw new Error('[ShardingCrudPro] batchInsert requires non-empty data array');
-        }
-        // 时间分表校验：每条 data 必须包含 timeColumn
-        this.validateTimeColumnForBatchData(dataArray, 'batchInsert');
-        // 按分表分组
-        const groupedData = this.batchInsertGroupDataByTable(dataArray);
-        // 确保所有目标分表存在（根据配置决定是否自动创建）
-        const tableNames = Array.from(groupedData.keys());
-        for (let i = 0; i < tableNames.length; i++) {
-            await this.createShardingTableIfNeeded(tableNames[i]);
-        }
-        // 串行执行各分表的批量插入
-        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);
-                lastContext = ctx;
-                results.push({
-                    table,
-                    affected: ((_a = ctx.getResModelItem('affected')) === null || _a === void 0 ? void 0 : _a.affectedRows) || items.length,
-                    rowCount: items.length,
-                    error: null,
-                    context: ctx,
-                });
-            }
-            catch (e) {
-                results.push({
-                    table,
-                    affected: 0,
-                    rowCount: items.length,
-                    error: e,
-                    context: null,
-                });
-            }
-        }
-        // 汇总结果
-        const tableResults = results.map(r => ({
-            table: r.table,
-            affected: r.affected,
-            rowCount: r.rowCount,
-        }));
-        const errors = results
-            .filter(r => r.error !== null)
-            .map(r => ({ table: r.table, error: r.error }));
-        const totalAffected = results.reduce((sum, r) => sum + r.affected, 0);
-        // 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,
-        });
-    }
-    async update(reqJson) {
-        // 时间分表校验：condition 必须包含路由字段
-        this.validateRoutingFieldForCondition(reqJson, 'update');
-        const targetTable = this.resolveSingleTable(reqJson, '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,
-        });
-    }
-    async delete(reqJson) {
-        // 时间分表校验：condition 必须包含路由字段
-        this.validateRoutingFieldForCondition(reqJson, 'delete');
-        const targetTable = this.resolveSingleTable(reqJson, '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 重置为空字符串
-     *
-     * @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' } });
-     */
-    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 路由
-        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,
-        });
-    }
-    async insertOnDuplicateUpdate(reqJson) {
-        // 时间分表校验：data 必须包含 timeColumn，condition 必须包含路由字段
-        this.validateTimeColumnForData(reqJson, 'insertOnDuplicateUpdate');
-        this.validateRoutingFieldForCondition(reqJson, 'insertOnDuplicateUpdate');
-        const targetTable = this.resolveSingleTable(reqJson, 'update'); // 使用 condition 路由
-        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,
-        });
-    }
-    // ============ 查询操作（可能多表） ============
-    async findOne(reqJson) {
-        // 清理 condition 中的时间字段（如果能确定单一分表）
-        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
-        const targetTables = await this.resolveFindTables(reqJson);
-        if (targetTables.length === 0) {
-            // 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) {
-            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) {
-                // 表不存在时跳过，继续查下一张表
-            }
-        }
-        // 未找到，使用最后一次查询的 ctx
-        return new CrudResult_1.CrudQueryOneResult({ row: null, rawContext: lastCtx, debugInfo: this.buildDebugInfo(targetTables[0], reqJson.condition) });
-    }
-    /**
-     * 查询唯一单条记录（期望结果为 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);
-     * }
-     */
-    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 new CrudResult_1.CrudQueryListResult({ rows: [], rawContext: null });
-        }
-        if (targetTables.length === 1) {
-            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.validateFindOrderBy(reqJson);
-        // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
-        const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
-        // 多表查询合并
-        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 });
-    }
-    async findPage(reqJson) {
-        // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
-        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
-        const targetTables = await this.resolveFindTables(reqJson);
-        if (targetTables.length === 0) {
-            throw new Error('[ShardingCrudPro] findPage: no matching tables found');
-        }
-        if (targetTables.length === 1) {
-            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.validateFindOrderBy(reqJson);
-        // 根据排序方向确定表顺序：DESC 新→旧，ASC 旧→新
-        const tablesForMerge = this.sortTablesForOrderBy(targetTables, reqJson);
-        // 多表分页查询：顺序累计
-        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,
-        });
-    }
-    async findCount(reqJson) {
-        var _a;
-        // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
-        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
-        const targetTables = await this.resolveFindTables(reqJson);
-        if (targetTables.length === 0) {
-            throw new Error('[ShardingCrudPro] findCount: no matching tables found');
-        }
-        if (targetTables.length === 1) {
-            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 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 });
-    }
-    async isExist(reqJson) {
-        // 清理 condition 中的时间字段（粒度字符串自动转范围、有主键时清理）
-        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
-        const targetTables = await this.resolveFindTables(reqJson);
-        if (targetTables.length === 0) {
-            throw new Error('[ShardingCrudPro] isExist: no matching tables found');
-        }
-        if (targetTables.length === 1) {
-            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;
-            }
-        }
-        return new CrudResult_1.CrudExistResult({ exists, rawContext: firstCtx });
-    }
-    // ============ 私有方法：分表路由 ============
-    batchInsertGroupDataByTable(dataArray) {
-        const groupedData = new Map();
-        for (const item of dataArray) {
-            const targetTable = this.batchInsertResolveTableForData(item);
-            if (!groupedData.has(targetTable)) {
-                groupedData.set(targetTable, []);
-            }
-            groupedData.get(targetTable).push(item);
-        }
-        return groupedData;
-    }
-    batchInsertResolveTableForData(item) {
-        const context = {
-            config: this.config,
-            data: item,
-        };
-        // 批量插入使用 resolveForInsert，确保返回单一表名
-        return this.router.resolveForInsert(this.config, context);
-    }
-    resolveSingleTable(reqJson, operation) {
-        // insert 操作使用 resolveForInsert（从 data 提取字段）
-        if (operation === 'insert') {
-            const context = {
-                config: this.config,
-                data: reqJson.data,
-            };
-            return this.router.resolveForInsert(this.config, context);
-        }
-        // 其他操作使用 resolveForCondition（从 condition 提取字段）
-        const context = {
-            config: this.config,
-            condition: reqJson.condition,
-        };
-        const result = this.router.resolveForCondition(this.config, context);
-        if (Array.isArray(result)) {
-            throw new Error(`[ShardingCrudPro] ${operation} 操作必须能确定单一目标表，` +
-                `但分表规则返回了多个表: ${result.slice(0, 5).join(', ')}${result.length > 5 ? '...' : ''}。` +
-                `请检查 condition 中是否包含分表字段（${this.getShardingColumnHint()}）。`);
-        }
-        return result;
-    }
-    getShardingColumnHint() {
-        if (this.config.type === ShardingConfig_1.ShardingType.RANGE || this.config.type === ShardingConfig_1.ShardingType.HASH) {
-            return this.config.shardingColumn || '分表字段';
-        }
-        if ([ShardingConfig_1.ShardingType.YEAR, ShardingConfig_1.ShardingType.MONTH, ShardingConfig_1.ShardingType.DAY].includes(this.config.type)) {
-            return this.config.timeColumn || 'created_at';
-        }
-        return '分表字段';
-    }
-    // ============ 私有方法：配置构建 ============
-    buildCfg(sqlSimpleName) {
-        return {
-            method: `ShardingCrudProAnonymous_${sqlSimpleName}`,
-            ...this.baseCfg,
-            sqlTable: this.config.baseTable,
-            sqlSimpleName,
-        };
-    }
-    // ============ 私有方法：执行操作 ============
-    async executeOnTable(table, reqJson, sqlSimpleName, extraCfg) {
-        const cfg = this.buildCfg(sqlSimpleName);
-        cfg.sqlTable = table; // 替换为实际分表名
-        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 findCountFromTable(table, reqJson) {
-        try {
-            const ctx = await this.executeOnTable(table, reqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
-            return { count: ctx.getResModelItem('total_count') || 0, ctx };
-        }
-        catch (e) {
-            // 表不存在时返回 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 { exists: ctx.getResModelItem('is_exist') === true, ctx };
-        }
-        catch (e) {
-            // 表不存在时返回 false
-            return { exists: false, ctx: null };
-        }
-    }
-    // ============ 表存在性检查和自动创建 ============
-    async getExistingTablesSet(skipCache = false) {
-        const { sqlDatabase, sqlDbType } = this.baseCfg;
-        if (!sqlDatabase || !sqlDbType) {
-            throw new Error('[ShardingCrudPro] 未配置 sqlDatabase 或 sqlDbType');
-        }
-        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(); // 使用缓存
-        return existingSet.has(tableName);
-    }
-    async createShardingTableIfNeeded(tableName) {
-        // 根据配置决定是否自动创建
-        if (!this.config.autoCreateTable) {
-            // 使用缓存检查表是否存在，不存在则抛异常
-            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,
-        }, this.config.tableCreateOptions);
-        if (!result.success) {
-            throw result.error || new Error(`[ShardingCrudPro] 创建分表 ${tableName} 失败`);
-        }
-        // 建表成功后刷新缓存，确保后续请求命中新表
-        if (result.createSql) {
-            await this.getExistingTablesSet(true);
-        }
-    }
-    // ============ 参数校验 ============
-    /**
-     * 判断是否为时间分表类型
-     */
-    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
-     *
-     * @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）
-     *
-     * 时间分表需要根据时间字段路由到正确的分表，
-     * 如果 condition 中缺少时间字段，将无法确定操作哪个分表。
-     *
-     * @param reqJson 请求参数
-     * @param operation 操作名称（用于错误提示）
-     * @throws Error 如果 condition 中缺少时间字段
-     */
-    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;
-        // 1. 必须传 orderBy
-        if (!orderBy) {
-            throw new Error(`[ShardingCrudPro] 查询操作必须传 orderBy 参数。` +
-                `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
-        }
-        // 2. 使用工具类解析并校验首个排序字段是否为 timeColumn
-        const firstOrderBy = OrderByUtils_1.OrderByUtils.getFirstOrderBy(orderBy);
-        if (!firstOrderBy) {
-            throw new Error(`[ShardingCrudPro] orderBy 参数格式错误，无法解析。` +
-                `期望值: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
-        }
-        if (firstOrderBy.fieldName !== timeColumn) {
-            throw new Error(`[ShardingCrudPro] orderBy 首个排序字段必须为 '${timeColumn}'，` +
-                `当前值: '${firstOrderBy.fieldName}'`);
-        }
-        // 校验排序方向是否为 ASC 或 DESC
-        const orderType = firstOrderBy.orderType.toUpperCase();
-        if (orderType !== 'ASC' && orderType !== 'DESC') {
-            throw new Error(`[ShardingCrudPro] orderBy 排序方向必须是 'ASC' 或 'DESC'，` +
-                `当前值: '${firstOrderBy.orderType}'`);
-        }
-    }
-    isAscOrderBy(reqJson) {
-        return OrderByUtils_1.OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
-    }
-    sortTablesForOrderBy(tables, reqJson) {
-        const isAsc = this.isAscOrderBy(reqJson);
-        return [...tables].sort((a, b) => isAsc ? a.localeCompare(b) : b.localeCompare(a));
-    }
-    // ============ 辅助方法 ============
-    /**
-     * 构建辅助定位信息
-     */
-    buildDebugInfo(sqlTable, condition) {
-        const info = {
-            sqlDatabase: this.baseCfg.sqlDatabase || 'unknown',
-            sqlTable: sqlTable || this.config.baseTable,
-        };
-        if (condition) {
-            info.condition = condition;
-        }
-        return info;
-    }
-    /**
-     * 格式化唯一性错误消息
-     */
-    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,
-        };
-        // 创建表信息提供者
-        const tableInfoProvider = {
-            getExistingTables: () => this.getExistingTablesSet(),
-        };
-        // 委托给 ShardingRouter 处理查询路由
-        return this.router.resolveQuery(this.config, context, tableInfoProvider);
-    }
-}
-exports.ShardingCrudPro = ShardingCrudPro;