midway-fatcms 0.0.7 → 0.0.8

package/dist/libs/crud-pro-quick/models.d.ts

@@ -0,0 +1,33 @@
+import { IRequestCfgModel } from '../../libs/crud-pro/interfaces';
+/**
+ * 常用标准表结构字段（6个字段）
+ *
+ * 用于软删除和审计跟踪：
+ * - deleted_at: 删除时间戳，0=未删除
+ * - deleted_by: 删除人ID
+ * - created_by: 创建人ID
+ * - created_at: 创建时间（毫秒时间戳）
+ * - modified_by: 修改人ID
+ * - modified_at: 修改时间（毫秒时间戳）
+ */
+export interface ICommonStandardColumns {
+    deleted_at?: number;
+    deleted_by?: string;
+    created_by?: string;
+    created_at?: number;
+    modified_by?: string;
+    modified_at?: number;
+}
+/**
+ * 扩展的请求配置模型
+ *
+ * 在 IRequestCfgModel 基础上添加了业务层常用的配置项：
+ * - enableStandardUpdateCfg: 启用标准字段自动填充
+ * - enableStandardUpdateCfgCondition: 启用标准字段条件注入
+ * - enableSoftDelete: 启用软删除
+ */
+export interface IRequestCfgModel2 extends IRequestCfgModel {
+    enableStandardUpdateCfg?: boolean | string[];
+    enableStandardUpdateCfgCondition?: boolean | string[];
+    enableSoftDelete?: boolean;
+}

package/dist/libs/crud-pro-quick/models.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,3 +1,9 @@
+import { CrudPro } from '../../libs/crud-pro/CrudPro';
+/**
+ * CrudPro 工厂函数类型
+ * 每次调用返回新的 CrudPro 实例，避免状态污染
+ */
+export declare type CrudProFactory = () => CrudPro;
 /**
  * 分表配置模型
  *
@@ -56,6 +62,13 @@ export interface IShardingConfig {
      * 用于时间分表类型（YEAR/MONTH/DAY），使用时间分表时必填
      */
     timeColumn?: string;
+    /**
+     * 主键字段
+     * 用于时间分表场景下，当 condition 中包含主键时，时间字段仅用于路由定位分表，
+     * 不参与具体表的查询条件（避免时间精度损失导致查询失败）
+     * 例如：id, order_id
+     */
+    primaryKey?: string;
     /**
      * 自定义分表路由函数
      * 用于 CUSTOM 类型
@@ -77,8 +90,8 @@ export interface IShardingConfig {
      * 适用于时间分表类型（YEAR/MONTH/DAY）。
      *
      * 默认值：
-     * - YEAR: 3（最近3年）
-     * - MONTH: 12（最近12个月）
+     * - YEAR: 2（最近2年）
+     * - MONTH: 3（最近3个月）
      * - DAY: 7（最近7天）
      *
      * @example

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

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShardingType = void 0;
 /**
  * 分表配置模型
  *
@@ -10,8 +12,6 @@
  * - HASH: 按哈希分表，如 order_01 ~ order_16
  * - CUSTOM: 自定义分表规则
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ShardingType = void 0;
 /**
  * 分表类型
  */

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

@@ -1,30 +1,7 @@
-import { CrudPro } from '../../libs/crud-pro/CrudPro';
 import { IRequestModel, IRequestCfgModel } from '../../libs/crud-pro/interfaces';
-import { ExecuteContext } from '../../libs/crud-pro/models/ExecuteContext';
-import { IShardingConfig } from './ShardingConfig';
-import { IShardingPageQueryResult } from './ShardingMerger';
-/**
- * 智能批量插入结果
- */
-export interface IShardingSmartBatchInsertResult {
-    /** 总插入条数 */
-    totalAffected: number;
-    /** 各分表插入结果 */
-    tableResults: Array<{
-        table: string;
-        affected: number;
-        rowCount: number;
-    }>;
-    /** 涉及的分表数量 */
-    tableCount: number;
-    /** 是否全部成功 */
-    success: boolean;
-    /** 错误信息（如果有） */
-    errors: Array<{
-        table: string;
-        error: Error;
-    }>;
-}
+import { IShardingConfig, CrudProFactory } from './ShardingConfig';
+import { CrudWriteResult, CrudQueryOneResult, CrudQueryListResult, CrudQueryPageResult, CrudExistResult, CrudCountResult, CrudUpsertResult } from '../../libs/crud-pro/models/CrudResult';
+import { ShardingBatchInsertResult } from './ShardingResult';
 /**
  * 分表 CRUD 操作封装器
  *
@@ -51,313 +28,181 @@ export interface IShardingSmartBatchInsertResult {
  * await sharding.insert({ data: { order_id: '001', amount: 100, created_at: '2024-03-15' } });
  *
  * // 分页查询（自动合并多表结果）
- * const result = await sharding.queryPage({
+ * const result = await sharding.findPage({
  *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
  *   pageNo: 1,
  *   pageSize: 10,
  * });
  */
 export declare class ShardingCrudPro {
-    private readonly crudPro;
+    private readonly crudProFactory;
     private readonly config;
     private readonly router;
     private readonly merger;
     private readonly tableCreator;
     private baseCfg;
-    constructor(crudPro: CrudPro, config: IShardingConfig);
-    /**
-     * 设置基础配置（会应用到所有操作）
-     *
-     * @param cfg 配置项，如 sqlDatabase、sqlDbType 等
-     * @returns this，支持链式调用
-     *
-     * @example
-     * sharding.setBaseCfg({
-     *   sqlDatabase: 'mydb',
-     *   sqlDbType: SqlDbType.mysql,
-     * });
-     */
+    private enableSoftDelete;
+    constructor(crudProFactory: CrudProFactory, config: IShardingConfig);
     setBaseCfg(cfg: Partial<IRequestCfgModel>): this;
-    /**
-     * 获取分表配置
-     */
     getConfig(): IShardingConfig;
     /**
-     * 插入数据
-     *
-     * 根据分表规则自动路由到目标分表。
-     * 对于时间分表，需要确保 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',
-     *   },
-     * });
-     */
-    insert(reqJson: IRequestModel): Promise<ExecuteContext>;
-    /**
-     * 批量插入数据（支持跨分表）
-     *
-     * 自动将数据按分表分组，并行插入到对应的分表。
-     *
-     * @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 },
-     * // ]
+     * 设置是否启用软删除
+     * @param enable 是否启用软删除
      */
-    batchInsert(reqJson: IRequestModel): Promise<IShardingSmartBatchInsertResult>;
+    setEnableSoftDelete(enable: boolean): this;
+    insert(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    batchInsert(reqJson: IRequestModel): Promise<ShardingBatchInsertResult>;
+    update(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    delete(reqJson: IRequestModel): Promise<CrudWriteResult>;
     /**
-     * 更新数据
-     *
-     * 根据条件中的分表字段自动路由到目标分表。
+     * 恢复软删除的记录
+     * 将 deleted_at 字段重置为 0，deleted_by 重置为空字符串
      *
-     * @param reqJson 请求参数，condition 为更新条件，data 为更新数据
-     * @returns 执行上下文
+     * @param reqJson 请求参数，通过 condition 指定要恢复的记录
+     * @returns CrudWriteResult 包含 affectedRows 和 getRawContext()
      *
      * @example
-     * await sharding.update({
-     *   condition: { order_id: 'ORD001', created_at: '2024-03-15' },
-     *   data: { amount: 200 },
-     * });
-     */
-    update(reqJson: IRequestModel): Promise<ExecuteContext>;
-    /**
-     * 删除数据
+     * // 恢复指定 ID 的记录
+     * await sharding.restore({ condition: { id: 1 } });
      *
-     * 根据条件中的分表字段自动路由到目标分表。
+     * // 恢复多条记录（使用 $in 操作符）
+     * await sharding.restore({ condition: { id: { $in: [1, 2, 3] } } });
      *
-     * @param reqJson 请求参数，condition 为删除条件
-     * @returns 执行上下文
+     * // 按条件批量恢复记录
+     * await sharding.restore({ condition: { status: 'deleted' } });
      */
-    delete(reqJson: IRequestModel): Promise<ExecuteContext>;
+    restore(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    insertOrUpdate(reqJson: IRequestModel): Promise<CrudUpsertResult>;
+    insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<CrudWriteResult>;
+    findOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
     /**
-     * 插入或更新（存在则更新，不存在则插入）
+     * 查询唯一单条记录（期望结果为 0 条或 1 条）
      *
-     * 路由逻辑：根据 condition 路由（先查询是否存在）
+     * 与 findOne 不同，此方法会校验查询结果的唯一性：
+     * - 如果查到 0 条：返回 row = null
+     * - 如果查到 1 条：正常返回
+     * - 如果查到多条：抛出异常，包含详细的定位信息（含分表名列表）
      *
-     * @param reqJson 请求参数
-     * @returns 执行上下文
-     */
-    insertOrUpdate(reqJson: IRequestModel): Promise<ExecuteContext>;
-    /**
-     * 插入或更新（ON DUPLICATE KEY UPDATE）
-     *
-     * 路由逻辑：根据 condition 路由（先查询是否存在）
+     * 分表场景的特殊处理：
+     * - 单分表：直接查询并校验唯一性
+     * - 多分表：顺序查询各分表，累计找到的数量，超过 1 条立即抛异常
      *
      * @param reqJson 请求参数
-     * @returns 执行上下文
-     */
-    insertOnDuplicateUpdate(reqJson: IRequestModel): Promise<ExecuteContext>;
-    /**
-     * 查询单条记录
-     *
-     * 如果能根据条件确定单一分表，则查询单表；
-     * 否则按顺序查询各分表，返回第一条匹配记录。
-     *
-     * @param reqJson 请求参数，condition 为查询条件
-     * @returns 单条记录，未找到返回 null
+     * @returns CrudQueryOneResult 包含 row、found 和 getRawContext()
+     * @throws Error 如果查询到多条记录
      *
      * @example
-     * const order = await sharding.queryOne({
-     *   condition: { order_id: 'ORD001' },
-     * });
-     */
-    queryOne(reqJson: IRequestModel): Promise<any>;
-    /**
-     * 查询列表
-     *
-     * 可能涉及多个分表，结果会自动合并。
-     *
-     * 使用约束：
-     * - 必须传 orderBy 参数
-     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
-     *
-     * @param reqJson 请求参数
-     * @returns 数据列表
-     *
-     * @example
-     * const orders = await sharding.query({
-     *   condition: { created_at: { $gte: '2024-01-01', $lte: '2024-03-31' } },
-     *   orderBy: 'created_at DESC',  // 或 'created_at ASC'
-     * });
-     */
-    query(reqJson: IRequestModel): Promise<any[]>;
-    /**
-     * 分页查询
-     *
-     * 自动处理跨分表的分页：
-     * 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);
-     */
-    queryPage(reqJson: IRequestModel): Promise<IShardingPageQueryResult>;
-    /**
-     * 查询记录总数
-     *
-     * 如果涉及多个分表，会并行查询各分表并汇总。
-     *
-     * @param reqJson 请求参数
-     * @returns 记录总数
-     */
-    queryCount(reqJson: IRequestModel): Promise<number>;
-    /**
-     * 判断记录是否存在
-     *
-     * 如果涉及多个分表，会并行查询，任一分表存在即返回 true。
-     *
-     * @param reqJson 请求参数
-     * @returns 是否存在
-     */
-    isExist(reqJson: IRequestModel): Promise<boolean>;
-    /**
-     * 【batchInsert 专用】按分表对数据进行分组
-     *
-     * 仅用于 batchInsert 方法，遍历所有数据项，
-     * 根据分表规则计算每条数据的目标分表，将相同分表的数据归为一组。
-     *
-     * @param dataArray 数据数组
-     * @returns 分表 -> 数据列表 的映射
-     */
+     * // 根据唯一索引查询单条
+     * const result = await sharding.findUniqueOne({ condition: { order_id: 'ORD001' } });
+     * if (result.found) {
+     *   console.log(result.row);
+     * }
+     */
+    findUniqueOne<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryOneResult<T>>;
+    findList<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryListResult<T>>;
+    findPage<T = Record<string, any>>(reqJson: IRequestModel): Promise<CrudQueryPageResult<T>>;
+    findCount(reqJson: IRequestModel): Promise<CrudCountResult>;
+    isExist(reqJson: IRequestModel): Promise<CrudExistResult>;
     private batchInsertGroupDataByTable;
     private batchInsertResolveTableForData;
-    /**
-     * 解析单个目标表
-     *
-     * 写操作必须确定单一目标表，否则抛出异常。
-     */
     private resolveSingleTable;
-    /**
-     * 获取分表字段提示
-     */
     private getShardingColumnHint;
-    /**
-     * 构建配置
-     */
     private buildCfg;
-    /**
-     * 在指定表上执行操作
-     */
     private executeOnTable;
-    /**
-     * 从指定表查询单条
-     */
-    private queryOneFromTable;
-    /**
-     * 从指定表查询数量
-     */
-    private queryCountFromTable;
-    /**
-     * 判断指定表中是否存在记录
-     */
+    private findCountFromTable;
     private isExistInTable;
-    /**
-     * 获取数据库中真实存在的表名集合
-     */
     private getExistingTablesSet;
+    private isTableExists;
+    private createShardingTableIfNeeded;
     /**
-     * 检查表是否存在
+     * 判断是否为时间分表类型
      */
-    private isTableExists;
+    private isTimeSharding;
     /**
-     * 创建分表（如果需要）
+     * 校验时间分表插入操作的 data 必须包含 timeColumn
      *
-     * 根据配置检查分表是否存在：
-     * - 如果分表已存在，直接返回
-     * - 如果分表不存在且 autoCreateTable=true，自动创建
-     * - 如果分表不存在且 autoCreateTable=false，抛出异常
+     * 时间分表需要根据时间字段路由到正确的分表，
+     * 如果 data 中缺少时间字段，将无法确定数据应插入哪个分表。
      *
-     * @param tableName 目标分表名
+     * @param reqJson 请求参数
+     * @param operation 操作名称（用于错误提示）
+     * @throws Error 如果 data 中缺少时间字段
      */
-    private createShardingTableIfNeeded;
+    private validateTimeColumnForData;
     /**
-     * 校验查询参数的 orderBy 是否符合约束
+     * 校验时间分表批量插入操作的每条 data 必须包含 timeColumn
      *
-     * 约束条件：
-     * - 必须传 orderBy 参数
-     * - orderBy 必须为 timeColumn DESC 或 timeColumn ASC（如 'created_at DESC' / 'created_at ASC'）
+     * @param dataArray 数据数组
+     * @param operation 操作名称（用于错误提示）
+     * @throws Error 如果任一条 data 中缺少时间字段
+     */
+    private validateTimeColumnForBatchData;
+    /**
+     * 校验时间分表写操作的 condition 必须包含路由字段（timeColumn）
      *
-     * 这是时间分表查询的核心约束：
-     * - 排序字段必须是分表字段（timeColumn），不允许其他字段
-     * - DESC 时表顺序为 新→旧，ASC 时表顺序为 旧→新（由调用方反转）
-     * - 这样无需内存排序，直接按表顺序拼接即可
+     * 时间分表需要根据时间字段路由到正确的分表，
+     * 如果 condition 中缺少时间字段，将无法确定操作哪个分表。
      *
      * @param reqJson 请求参数
+     * @param operation 操作名称（用于错误提示）
+     * @throws Error 如果 condition 中缺少时间字段
      */
-    private validateQueryOrderBy;
+    private validateRoutingFieldForCondition;
     /**
-     * 判断 orderBy 是否为 ASC 方向
+     * 智能处理时间分表场景下的时间字段
+     *
+     * **问题背景**：
+     * 在时间分表（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' } }
      *
-     * 前提：validateQueryOrderBy 已通过校验，orderBy 格式合法
+     * // 操作符表达式 → 保留
+     * { order_id: 'ORD001', created_at: { $gte: '2024-01', $lte: '2024-06' } }
+     * → 不做任何处理
+     * ```
      *
      * @param reqJson 请求参数
-     * @returns true 表示 ASC，false 表示 DESC
+     * @returns 处理后的请求参数
      */
-    private isAscOrderBy;
+    private cleanTimeColumnForSingleTableQuery;
     /**
-     * 根据排序方向对分表列表进行排序
+     * 校验时间操作符的值必须精确到秒
      *
-     * 分表名后缀为时间格式（如 202403、20240101），字典序即时间序。
-     * - DESC：降序排列（新→旧）
-     * - ASC：升序排列（旧→新）
+     * MySQL 中 '2026-04-30' 等价于 '2026-04-30 00:00:00'，
+     * 导致 $lte: '2026-04-30' 会丢失当天所有数据。
+     * 如果用户需要查整月/整天数据，应传粒度字符串由系统自动转换，而非手动写 $gte/$lte。
      *
-     * @param tables 分表列表
-     * @param reqJson 请求参数
-     * @returns 排序后的分表列表（新数组，不修改原数组）
+     * @param operatorValue 操作符表达式的值
+     * @param timeColumn 时间字段名
+     * @throws Error 如果操作符值缺少时间部分
      */
+    private validateTimeOperatorPrecision;
+    private validateFindOrderBy;
+    private isAscOrderBy;
     private sortTablesForOrderBy;
     /**
-     * 解析查询表（带真实表过滤）
-     *
-     * 将查询路由委托给 ShardingRouter.resolveQuery，
-     * 由 ShardingRouter 统一处理所有查询路由逻辑。
+     * 构建辅助定位信息
+     */
+    private buildDebugInfo;
+    /**
+     * 格式化唯一性错误消息
      */
-    private resolveQueryTables;
+    private formatUniqueError;
+    private resolveFindTables;
 }