midway-fatcms 0.0.7 → 0.0.9

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

@@ -0,0 +1,524 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingByTimeCrud = void 0;
+const moment = require("moment");
+const OrderByUtils_1 = require("../../libs/crud-pro/utils/OrderByUtils");
+const keys_1 = require("../../libs/crud-pro/models/keys");
+const ShardingConfig_1 = require("./ShardingConfig");
+const ShardingBase_1 = require("./ShardingBase");
+const ShardingMerger_1 = require("./ShardingMerger");
+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
+ *
+ * 支持 YEAR / MONTH / DAY 三种时间粒度分表。
+ * 路由规则：根据 timeColumn 的值计算时间后缀，定位到对应分表。
+ *
+ * 特性：
+ * - 插入：data 中的 timeColumn 决定目标分表
+ * - 更新/删除：condition 中的 timeColumn 定位分表
+ * - 查询：时间范围条件交叉过滤候选表，无条件时回退到 recentTableCount
+ * - insertOrUpdate：condition 路由查找，data 路由插入（双路由）
+ * - 智能清理：timeColumn 在有主键时仅用于路由，不参与 WHERE 条件
+ * - COUNT 缓存：历史表缓存，当前表实时查
+ * - orderBy 约束：多表查询必须以 timeColumn 排序
+ */
+class ShardingByTimeCrud extends ShardingBase_1.ShardingBase {
+    constructor(crudProFactory, config) {
+        super(crudProFactory, config);
+        // 校验
+        if (!config.timeColumn) {
+            throw new Error('[ShardingByTimeCrud] 时间分表必须显式指定 timeColumn 字段');
+        }
+        this.granularity = this.typeToGranularity(config.type);
+        this.merger = new ShardingMerger_1.ShardingMerger();
+        // 初始化 COUNT 缓存
+        if (config.countCache) {
+            const countCache = new ShardingCountCache_1.ShardingCountCache(config.type, config.baseTable, config.countCache.ttlSeconds, config.countCache.maxSize);
+            this.merger.setCountCache(countCache);
+        }
+    }
+    // ============ 路由 ============
+    typeToGranularity(type) {
+        switch (type) {
+            case ShardingConfig_1.ShardingType.YEAR: return 'year';
+            case ShardingConfig_1.ShardingType.MONTH: return 'month';
+            case ShardingConfig_1.ShardingType.DAY: return 'day';
+            default: throw new Error(`[ShardingByTimeCrud] 不支持的分表类型: ${type}`);
+        }
+    }
+    /** 从 data 中提取时间字段，计算目标分表名 */
+    resolveTableForInsert(data) {
+        const timeValue = data[this.config.timeColumn];
+        if (timeValue === undefined || timeValue === null) {
+            throw new Error(`[ShardingByTimeCrud] insert 操作的 data 必须包含时间字段 '${this.config.timeColumn}'`);
+        }
+        const m = moment(timeValue);
+        if (!m.isValid()) {
+            throw new Error(`[ShardingByTimeCrud] 无法解析时间值: ${timeValue}`);
+        }
+        const suffix = (0, ShardingUtils_1.getTimeSuffix)(m.toDate(), this.granularity);
+        return this.formatTableName(suffix);
+    }
+    /** 从 condition 中提取时间字段，计算目标分表名（单表） */
+    resolveTableForCondition(condition) {
+        const timeColumn = this.config.timeColumn;
+        const timeValue = condition[timeColumn];
+        if (timeValue === undefined || timeValue === null) {
+            throw new Error(`[ShardingByTimeCrud] 写操作的 condition 必须包含时间字段 '${timeColumn}'，` +
+                `用于路由到正确的分表。`);
+        }
+        // 如果是操作符表达式（$gte/$lte），尝试提取范围的 start
+        if ((0, ShardingUtils_1.isOperatorExpression)(timeValue)) {
+            const range = this.extractTimeRange(condition);
+            if (range) {
+                const suffix = (0, ShardingUtils_1.getTimeSuffix)(range.start, this.granularity);
+                return this.formatTableName(suffix);
+            }
+        }
+        const m = moment(timeValue);
+        if (!m.isValid()) {
+            throw new Error(`[ShardingByTimeCrud] 无法解析时间值: ${timeValue}`);
+        }
+        const suffix = (0, ShardingUtils_1.getTimeSuffix)(m.toDate(), this.granularity);
+        return this.formatTableName(suffix);
+    }
+    /** 解析查询目标表列表 */
+    async resolveFindTables(reqJson) {
+        const existingTables = await this.getExistingTablesSet();
+        const baseTablePrefix = `${this.config.baseTable}_`;
+        const shardingTables = Array.from(existingTables).filter(t => t.startsWith(baseTablePrefix));
+        if (shardingTables.length === 0)
+            return [];
+        shardingTables.sort();
+        const condition = reqJson.condition;
+        // 有 recentTableCount：取最近N张，再与条件取交集
+        if (this.config.recentTableCount !== undefined) {
+            const recentTables = shardingTables.slice(-this.config.recentTableCount);
+            return this.intersectWithCondition(recentTables, condition);
+        }
+        // 无 recentTableCount：所有表与条件取交集，最多取默认数量
+        const intersected = this.intersectWithCondition(shardingTables, condition);
+        const defaultCount = this.getDefaultRecentCount();
+        return intersected.slice(0, defaultCount);
+    }
+    intersectWithCondition(tables, condition) {
+        if (!condition)
+            return this.sortTablesByTimeDesc(tables);
+        const timeRange = this.extractTimeRange(condition);
+        if (timeRange) {
+            return this.intersectTablesByTimeRange(tables, timeRange);
+        }
+        const singleTimeValue = this.tryExtractTimeFromCondition(condition);
+        if (singleTimeValue) {
+            const suffix = (0, ShardingUtils_1.getTimeSuffix)(singleTimeValue, this.granularity);
+            const targetTable = this.formatTableName(suffix);
+            return tables.includes(targetTable) ? [targetTable] : [];
+        }
+        // condition 存在但不包含时间字段，返回所有表（降序）
+        return this.sortTablesByTimeDesc(tables);
+    }
+    intersectTablesByTimeRange(tables, timeRange) {
+        const startSuffix = (0, ShardingUtils_1.getTimeSuffix)(timeRange.start, this.granularity);
+        const endSuffix = (0, ShardingUtils_1.getTimeSuffix)(timeRange.end, this.granularity);
+        const prefix = `${this.config.baseTable}_`;
+        const prefixLen = prefix.length;
+        return this.sortTablesByTimeDesc(tables.filter(table => {
+            const suffix = table.substring(prefixLen);
+            return suffix >= startSuffix && suffix <= endSuffix;
+        }));
+    }
+    extractTimeRange(condition) {
+        var _a, _b;
+        const colCond = condition[this.config.timeColumn];
+        if (!colCond || typeof colCond !== 'object')
+            return null;
+        const start = (_a = colCond.$gte) !== null && _a !== void 0 ? _a : colCond.$gt;
+        const end = (_b = colCond.$lte) !== null && _b !== void 0 ? _b : colCond.$lt;
+        if (start && end) {
+            const sm = moment(start), em = moment(end);
+            if (!sm.isValid() || !em.isValid())
+                return null;
+            return { start: sm.toDate(), end: em.toDate() };
+        }
+        if (start) {
+            const sm = moment(start);
+            return sm.isValid() ? { start: sm.toDate(), end: new Date() } : null;
+        }
+        if (end) {
+            const em = moment(end);
+            return em.isValid() ? { start: new Date(0), end: em.toDate() } : null;
+        }
+        return null;
+    }
+    tryExtractTimeFromCondition(condition) {
+        const value = condition[this.config.timeColumn];
+        if (value === undefined || value === null)
+            return null;
+        const m = moment(value);
+        return m.isValid() ? m.toDate() : null;
+    }
+    sortTablesByTimeDesc(tables) {
+        return [...tables].sort((a, b) => b.localeCompare(a));
+    }
+    getDefaultRecentCount() {
+        if (this.config.recentTableCount !== undefined && this.config.recentTableCount > 0) {
+            return this.config.recentTableCount;
+        }
+        switch (this.granularity) {
+            case 'year': return 2;
+            case 'month': return 3;
+            case 'day': return 7;
+        }
+    }
+    formatTableName(suffix) {
+        const formattedSuffix = this.config.suffixFormatter ? this.config.suffixFormatter(suffix) : suffix;
+        return `${this.config.baseTable}_${formattedSuffix}`;
+    }
+    // ============ 写操作 ============
+    async insert(reqJson) {
+        this.validateTimeColumnForData(reqJson, 'insert');
+        const targetTable = this.resolveTableForInsert(reqJson.data);
+        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('[ShardingByTimeCrud] batchInsert requires non-empty data array');
+        }
+        this.validateTimeColumnForBatchData(dataArray, 'batchInsert');
+        // 按分表分组
+        const groupedData = new Map();
+        for (const item of dataArray) {
+            const table = this.resolveTableForInsert(item);
+            if (!groupedData.has(table))
+                groupedData.set(table, []);
+            groupedData.get(table).push(item);
+        }
+        // 确保所有目标分表存在
+        for (const tableName of groupedData.keys()) {
+            await this.createShardingTableIfNeeded(tableName);
+        }
+        // 串行执行各分表的批量插入
+        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);
+        const finalContext = lastContext || ((_b = results.find(r => r.context)) === null || _b === void 0 ? void 0 : _b.context);
+        if (!finalContext)
+            throw new Error('[ShardingByTimeCrud] 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) {
+        this.validateRoutingFieldForCondition(reqJson, 'update');
+        const targetTable = this.resolveTableForCondition(reqJson.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) {
+        this.validateRoutingFieldForCondition(reqJson, 'delete');
+        const targetTable = this.resolveTableForCondition(reqJson.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 });
+    }
+    async restore(reqJson) {
+        this.validateRoutingFieldForCondition(reqJson, 'restore');
+        const targetTable = this.resolveTableForCondition(reqJson.condition);
+        if (!reqJson.condition || Object.keys(reqJson.condition).length === 0) {
+            throw new Error('[ShardingByTimeCrud] restore 操作必须指定恢复条件');
+        }
+        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 });
+    }
+    /**
+     * 插入或更新（双路由）
+     *
+     * 1. condition 路由定位查找分表
+     * 2. 检查记录是否存在
+     * 3. 存在 → UPDATE（conditionTable）
+     * 4. 不存在 → data 路由定位插入分表，INSERT（dataTable）
+     */
+    async insertOrUpdate(reqJson) {
+        this.validateTimeColumnForData(reqJson, 'insertOrUpdate');
+        this.validateRoutingFieldForCondition(reqJson, 'insertOrUpdate');
+        const conditionTable = this.resolveTableForCondition(reqJson.condition);
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const existCtx = await this.executeOnTable(conditionTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+        const isExist = existCtx.getResModelItem('is_exist') === true;
+        if (isExist) {
+            const updateCtx = await this.executeOnTable(conditionTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE);
+            const updateAffected = updateCtx.getResModel().affected;
+            return new CrudResult_1.CrudUpsertResult({ insertAffected: undefined, updateAffected, isExist: true, rawContext: updateCtx });
+        }
+        const dataTable = this.resolveTableForInsert(reqJson.data);
+        await this.createShardingTableIfNeeded(dataTable);
+        const insertCtx = await this.executeOnTable(dataTable, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_INSERT);
+        const insertAffected = insertCtx.getResModel().affected;
+        return new CrudResult_1.CrudUpsertResult({ insertAffected, updateAffected: undefined, isExist: false, rawContext: insertCtx });
+    }
+    // ============ 查询操作 ============
+    async findOne(reqJson) {
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            throw new Error('[ShardingByTimeCrud] findOne: no matching tables found');
+        }
+        let lastCtx = null;
+        let lastTable;
+        for (const table of targetTables) {
+            try {
+                const ctx = await this.executeOnTable(table, cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_ONE);
+                lastCtx = ctx;
+                lastTable = table;
+                const row = ctx.getOneObj();
+                if (row) {
+                    return new CrudResult_1.CrudQueryOneResult({ row: row, rawContext: ctx, debugInfo: this.buildDebugInfo(table, reqJson.condition), fromTable: table });
+                }
+            }
+            catch (e) {
+                // 表不存在时跳过
+            }
+        }
+        return new CrudResult_1.CrudQueryOneResult({ row: null, rawContext: lastCtx, debugInfo: this.buildDebugInfo(targetTables[0], reqJson.condition), fromTable: lastTable });
+    }
+    async findUniqueOne(reqJson) {
+        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), fromTable: null });
+        }
+        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);
+                    if (allRows.length > 1) {
+                        throw new Error(this.formatUniqueError(allRows.length, foundTables, reqJson.condition, foundTables.length > 1));
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof Error && e.message.startsWith('[ShardingBase] findUniqueOne'))
+                    throw e;
+            }
+        }
+        const fromTable = foundTables[0] || null;
+        return new CrudResult_1.CrudQueryOneResult({
+            row: allRows[0] || null, rawContext: firstCtx,
+            debugInfo: this.buildDebugInfo(fromTable || targetTables[0], reqJson.condition),
+            fromTable: fromTable || targetTables[0],
+        });
+    }
+    async findList(reqJson) {
+        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);
+            return new CrudResult_1.CrudQueryListResult({ rows: ctx.getResRows(), rawContext: ctx });
+        }
+        this.validateFindOrderBy(reqJson);
+        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) {
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            throw new Error('[ShardingByTimeCrud] 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);
+        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;
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            throw new Error('[ShardingByTimeCrud] findCount: no matching tables found');
+        }
+        if (targetTables.length === 1) {
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_COUNT);
+            return new CrudResult_1.CrudCountResult({ count: ctx.getResModelItem('total_count') || 0, rawContext: ctx });
+        }
+        const countResults = [];
+        for (const table of targetTables) {
+            countResults.push(await this.findCountFromTable(table, cleanedReqJson));
+        }
+        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) {
+        const cleanedReqJson = this.cleanTimeColumnForSingleTableQuery(reqJson);
+        const targetTables = await this.resolveFindTables(reqJson);
+        if (targetTables.length === 0) {
+            throw new Error('[ShardingByTimeCrud] isExist: no matching tables found');
+        }
+        if (targetTables.length === 1) {
+            const ctx = await this.executeOnTable(targetTables[0], cleanedReqJson, keys_1.KeysOfSimpleSQL.SIMPLE_QUERY_EXIST);
+            return new CrudResult_1.CrudExistResult({ exists: ctx.getResModelItem('is_exist') === true, rawContext: ctx });
+        }
+        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 });
+    }
+    // ============ 校验 ============
+    validateTimeColumnForData(reqJson, operation) {
+        const timeColumn = this.config.timeColumn;
+        const data = reqJson.data;
+        if (!data || data[timeColumn] === undefined) {
+            throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 data 必须包含时间字段 '${timeColumn}'`);
+        }
+    }
+    validateTimeColumnForBatchData(dataArray, operation) {
+        const timeColumn = this.config.timeColumn;
+        for (let i = 0; i < dataArray.length; i++) {
+            if (!dataArray[i] || dataArray[i][timeColumn] === undefined) {
+                throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 data[${i}] 必须包含时间字段 '${timeColumn}'`);
+            }
+        }
+    }
+    validateRoutingFieldForCondition(reqJson, operation) {
+        const timeColumn = this.config.timeColumn;
+        const condition = reqJson.condition;
+        if (!condition || !condition[timeColumn]) {
+            throw new Error(`[ShardingByTimeCrud] ${operation} 操作的 condition 必须包含时间字段 '${timeColumn}'，` +
+                `用于路由到正确的分表。`);
+        }
+    }
+    validateFindOrderBy(reqJson) {
+        const timeColumn = this.config.timeColumn;
+        const orderBy = reqJson.orderBy;
+        if (!orderBy) {
+            throw new Error(`[ShardingByTimeCrud] 多表查询必须传 orderBy 参数。期望: '${timeColumn} DESC' 或 '${timeColumn} ASC'`);
+        }
+        const firstOrderBy = OrderByUtils_1.OrderByUtils.getFirstOrderBy(orderBy);
+        if (!firstOrderBy) {
+            throw new Error(`[ShardingByTimeCrud] orderBy 参数格式错误，无法解析`);
+        }
+        if (firstOrderBy.fieldName !== timeColumn) {
+            throw new Error(`[ShardingByTimeCrud] orderBy 首个排序字段必须为 '${timeColumn}'，当前: '${firstOrderBy.fieldName}'`);
+        }
+        const orderType = firstOrderBy.orderType.toUpperCase();
+        if (orderType !== 'ASC' && orderType !== 'DESC') {
+            throw new Error(`[ShardingByTimeCrud] orderBy 排序方向必须是 'ASC' 或 'DESC'，当前: '${firstOrderBy.orderType}'`);
+        }
+    }
+    sortTablesForOrderBy(tables, reqJson) {
+        const isAsc = OrderByUtils_1.OrderByUtils.isFirstOrderByAsc(reqJson.orderBy);
+        return [...tables].sort((a, b) => isAsc ? a.localeCompare(b) : b.localeCompare(a));
+    }
+    // ============ 时间字段智能清理（详见 TIME_COLUMN_CLEAN_SPEC.md） ============
+    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];
+        if (timeValue === undefined)
+            return reqJson;
+        // 操作符表达式 → 保留，但校验精度
+        if ((0, ShardingUtils_1.isOperatorExpression)(timeValue)) {
+            this.validateTimeOperatorPrecision(timeValue, timeColumn);
+            return reqJson;
+        }
+        const hasPrimaryKey = primaryKey && condition[primaryKey] !== undefined;
+        if (typeof timeValue === 'string') {
+            const range = (0, ShardingUtils_1.expandDateToRange)(timeValue);
+            if (hasPrimaryKey) {
+                const { [timeColumn]: _, ...cleanedCondition } = condition;
+                return { ...reqJson, condition: cleanedCondition };
+            }
+            if (range) {
+                return { ...reqJson, condition: { ...condition, [timeColumn]: range } };
+            }
+            return reqJson;
+        }
+        if (hasPrimaryKey) {
+            const { [timeColumn]: _, ...cleanedCondition } = condition;
+            return { ...reqJson, condition: cleanedCondition };
+        }
+        return reqJson;
+    }
+    validateTimeOperatorPrecision(operatorValue, timeColumn) {
+        const PRECISION_OPERATORS = ['$gte', '$lte', '$gt', '$lt'];
+        const dateOnlyPattern = /^\d{4}-\d{1,2}-\d{1,2}$/;
+        for (const op of PRECISION_OPERATORS) {
+            const value = operatorValue[op];
+            if (value !== undefined && typeof value === 'string' && dateOnlyPattern.test(value)) {
+                throw new Error(`[ShardingByTimeCrud] 时间字段 '${timeColumn}' 的 ${op} 值必须精确到秒，` +
+                    `当前值: '${value}'。` +
+                    `请使用 '${value} 23:59:59'（$lte/$lt）或 '${value} 00:00:00'（$gte/$gt），` +
+                    `或直接传粒度字符串由系统自动转换范围。`);
+            }
+        }
+        const rangeValue = operatorValue.$range;
+        if (Array.isArray(rangeValue) && rangeValue.length >= 2) {
+            for (let i = 0; i < rangeValue.length; i++) {
+                const val = rangeValue[i];
+                if (typeof val === 'string' && dateOnlyPattern.test(val)) {
+                    throw new Error(`[ShardingByTimeCrud] 时间字段 '${timeColumn}' 的 $range[${i}] 值必须精确到秒，` +
+                        `当前值: '${val}'。请使用 '${val} ${i === 0 ? '00:00:00' : '23:59:59'}'`);
+                }
+            }
+        }
+    }
+}
+exports.ShardingByTimeCrud = ShardingByTimeCrud;

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

@@ -1,3 +1,10 @@
+import { CrudPro } from '../../libs/crud-pro/CrudPro';
+import { KeysOfSimpleSQL } from '../crud-pro/models/keys';
+/**
+ * CrudPro 工厂函数类型
+ * 每次调用返回新的 CrudPro 实例，避免状态污染
+ */
+export declare type CrudProFactory = () => CrudPro;
 /**
  * 分表配置模型
  *
@@ -5,8 +12,8 @@
  * - YEAR: 按年分表，如 order_2024, order_2025
  * - MONTH: 按月分表，如 order_202401, order_202402
  * - DAY: 按日分表，如 order_20240101
- * - RANGE: 按范围分表，如 user_0 ~ user_99
  * - HASH: 按哈希分表，如 order_01 ~ order_16
+ * - KEY: 按键值分表，字段原值=表后缀，如 order_east, order_west
  * - CUSTOM: 自定义分表规则
  */
 /**
@@ -19,10 +26,10 @@ export declare enum ShardingType {
     MONTH = "month",
     /** 按日分表：table_20240101 */
     DAY = "day",
-    /** 按范围分表：table_0 ~ table_99 */
-    RANGE = "range",
     /** 按哈希分表：table_01 ~ table_16 */
     HASH = "hash",
+    /** 按键值分表：字段原值=表后缀，如 table_east, table_west */
+    KEY = "key",
     /** 自定义分表规则 */
     CUSTOM = "custom"
 }
@@ -41,14 +48,15 @@ export interface IShardingConfig {
     baseTable: string;
     /**
      * 分表数量
-     * 用于 RANGE 和 HASH 类型
-     * 默认值：RANGE 为 10，HASH 为 16
+     * 用于 HASH 类型，指定哈希取模的分表总数
      */
     tableCount?: number;
     /**
      * 分表字段
-     * 用于 RANGE 和 HASH 类型，根据字段值计算分表
-     * 例如：user_id, order_id
+     * 用于 HASH 和 KEY 类型，根据字段值计算分表
+     * - HASH: hash(shardingColumn) % tableCount
+     * - KEY: 字段原值直接作为表后缀
+     * 例如：user_id, region
      */
     shardingColumn?: string;
     /**
@@ -56,6 +64,13 @@ export interface IShardingConfig {
      * 用于时间分表类型（YEAR/MONTH/DAY），使用时间分表时必填
      */
     timeColumn?: string;
+    /**
+     * 主键字段
+     * 用于时间分表场景下，当 condition 中包含主键时，时间字段仅用于路由定位分表，
+     * 不参与具体表的查询条件（避免时间精度损失导致查询失败）
+     * 例如：id, order_id
+     */
+    primaryKey?: string;
     /**
      * 自定义分表路由函数
      * 用于 CUSTOM 类型
@@ -77,8 +92,8 @@ export interface IShardingConfig {
      * 适用于时间分表类型（YEAR/MONTH/DAY）。
      *
      * 默认值：
-     * - YEAR: 3（最近3年）
-     * - MONTH: 12（最近12个月）
+     * - YEAR: 2（最近2年）
+     * - MONTH: 3（最近3个月）
      * - DAY: 7（最近7天）
      *
      * @example
@@ -207,7 +222,7 @@ export interface IShardingRouterContext {
      * SQL 简单名称
      * 用于判断具体的查询类型
      */
-    sqlSimpleName?: string;
+    sqlSimpleName: KeysOfSimpleSQL;
 }
 /**
  * 时间范围

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

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingType = void 0;
 /**
  * 分表配置模型
  *
@@ -6,12 +8,10 @@
  * - YEAR: 按年分表，如 order_2024, order_2025
  * - MONTH: 按月分表，如 order_202401, order_202402
  * - DAY: 按日分表，如 order_20240101
- * - RANGE: 按范围分表，如 user_0 ~ user_99
  * - HASH: 按哈希分表，如 order_01 ~ order_16
+ * - KEY: 按键值分表，字段原值=表后缀，如 order_east, order_west
  * - CUSTOM: 自定义分表规则
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ShardingType = void 0;
 /**
  * 分表类型
  */
@@ -23,10 +23,10 @@ var ShardingType;
     ShardingType["MONTH"] = "month";
     /** 按日分表：table_20240101 */
     ShardingType["DAY"] = "day";
-    /** 按范围分表：table_0 ~ table_99 */
-    ShardingType["RANGE"] = "range";
     /** 按哈希分表：table_01 ~ table_16 */
     ShardingType["HASH"] = "hash";
+    /** 按键值分表：字段原值=表后缀，如 table_east, table_west */
+    ShardingType["KEY"] = "key";
     /** 自定义分表规则 */
     ShardingType["CUSTOM"] = "custom";
 })(ShardingType = exports.ShardingType || (exports.ShardingType = {}));