midway-fatcms 0.0.8 → 0.0.9

package/dist/service/curd/CurdProService.js

@@ -123,9 +123,39 @@ let CurdProService = class CurdProService extends BaseService_1.BaseService {
         super(...arguments);
         this.responseCfgHandlers = {};
     }
+    /**
+     * 注册“响应配置处理器”（response cfg handler）。
+     *
+     * 这些处理器会在一次 CRUD/SQL 执行完成后被调用，用于对 `ExecuteContext` 做统一的二次加工，
+     * 例如：追加扩展数据、做字段脱敏、统一包装返回结构等。
+     *
+     * @param key 处理器类型标识（业务自定义枚举/常量）
+     * @param handler 处理器实现
+     *
+     * @example
+     * curdProService.setResponseCfgHandlers(RelatedType.USER, {
+     *   async handleExecuteContextPrepare(ctx) {
+     *     // 可在执行结果处理前做准备
+     *   },
+     *   async handleExecuteContext(ctx) {
+     *     // 对 ctx.result / ctx.data 等进行二次加工
+     *   },
+     * });
+     */
     setResponseCfgHandlers(key, handler) {
         this.responseCfgHandlers[key] = handler;
     }
+    /**
+     * 获取当前已注册的“响应配置处理器”集合。
+     *
+     * 一般用于调试或在外层框架中统一检查/复用已有 handler。
+     *
+     * @returns 以 `RelatedType` 为 key 的处理器映射表
+     *
+     * @example
+     * const handlers = curdProService.getResponseCfgHandlers();
+     * const userHandler = handlers[RelatedType.USER];
+     */
     getResponseCfgHandlers() {
         return this.responseCfgHandlers;
     }
@@ -153,8 +183,21 @@ let CurdProService = class CurdProService extends BaseService_1.BaseService {
         return crudPro;
     }
     /**
-     * 依赖缓存中与加载的配置
-     * @param reqJson
+     * 通过 `method` 走配置化 CRUD 执行（从缓存/加载的配置中解析）。
+     *
+     * 适用于：前端/调用方只传 `method` + 入参，由服务端根据 `method` 找到对应的 CRUD 配置并执行。
+     * 在非调试模式下会启用配置缓存（调试模式关闭缓存，便于开发即时生效）。
+     *
+     * @param reqJson 请求模型，必须包含 `method`
+     * @returns `ExecuteContext`（包含执行过程与结果数据）
+     *
+     * @example
+     * const ctx = await curdProService.executeCrud({
+     *   method: 'user.list',
+     *   pageNo: 1,
+     *   pageSize: 20,
+     * });
+     * console.log(ctx.result);
      */
     async executeCrud(reqJson) {
         if (!reqJson.method) {
@@ -165,12 +208,45 @@ let CurdProService = class CurdProService extends BaseService_1.BaseService {
         const isEnableCache = !this.isEnableDebug();
         return curdPro.executeCrud(reqJson, isEnableCache);
     }
-    // 直接执行一个SQL
+    /**
+     * 直接执行一段 SQL（不依赖 `method` 配置）。
+     *
+     * 适用于：后台管理/运维脚本/内部工具需要直接跑 SQL 的场景（仍会复用本服务的连接池、日志、visitor、事务等上下文）。
+     *
+     * @param sqlCfgModel SQL 执行配置（数据库、类型、SQL、参数等）
+     * @returns SQL 执行结果
+     *
+     * @example
+     * const res = await curdProService.executeSQL({
+     *   sqlDbType: SqlDbType.mysql,
+     *   sqlDatabase: 'mydb',
+     *   executeSql: 'select * from t_user where id = ?',
+     *   executeSqlArgs: [1],
+     * });
+     */
     async executeSQL(sqlCfgModel) {
         const curdPro = this.getCrudPro();
         return curdPro.executeSQL(sqlCfgModel);
     }
-    // 直接执行一个请求
+    /**
+     * 直接按指定配置执行一次 CRUD（不走缓存查找）。
+     *
+     * 适用于：调用方已经拿到了/动态生成了本次要执行的 CRUD 配置，想直接执行并得到结果。
+     * 该方法会对 `cfgModel` 做两类标准化处理：
+     * - 统一修正/补全配置（`fixCfgModel`）
+     * - 应用软删除规则（`fixSoftDelete`）
+     *
+     * @param reqJson 本次请求入参
+     * @param cfgModel 本次请求对应的 CRUD 配置
+     * @returns `ExecuteContext`
+     *
+     * @example
+     * const cfg = await curdProService.getCachedCfgByMethod('user.list');
+     * const ctx = await curdProService.executeCrudByCfg(
+     *   { method: 'user.list', pageNo: 1, pageSize: 20 },
+     *   cfg as any
+     * );
+     */
     async executeCrudByCfg(reqJson, cfgModel) {
         this.logInfo('executeCrudByCfg', cfgModel);
         const curdPro = this.getCrudPro();
@@ -210,7 +286,7 @@ let CurdProService = class CurdProService extends BaseService_1.BaseService {
      * 获取分表 CRUD 操作器
      *
      * @param param 参数对象
-     * @returns ShardingCrudPro 实例
+     * @returns ShardingBase 实例（实际类型根据 shardingConfig.type 决定）
      *
      * @example
      * const sharding = curdProService.getShardingCrud({
@@ -225,16 +301,60 @@ let CurdProService = class CurdProService extends BaseService_1.BaseService {
      */
     getShardingCrud(param) {
         const { sqlDatabase, sqlDbType, shardingConfig } = param;
-        // 传入工厂函数，每次需要时创建新的 CrudPro 实例
-        const sharding = new crud_sharding_1.ShardingCrudPro(() => this.getCrudPro(), shardingConfig);
+        const factory = () => this.getCrudPro();
+        let sharding;
+        switch (shardingConfig.type) {
+            case crud_sharding_1.ShardingType.YEAR:
+            case crud_sharding_1.ShardingType.MONTH:
+            case crud_sharding_1.ShardingType.DAY:
+                sharding = new crud_sharding_1.ShardingByTimeCrud(factory, shardingConfig);
+                break;
+            case crud_sharding_1.ShardingType.HASH:
+                sharding = new crud_sharding_1.ShardingByHashCrud(factory, shardingConfig);
+                break;
+            case crud_sharding_1.ShardingType.KEY:
+                sharding = new crud_sharding_1.ShardingByKeyCrud(factory, shardingConfig);
+                break;
+            case crud_sharding_1.ShardingType.CUSTOM:
+                sharding = new crud_sharding_1.ShardingByCustomCrud(factory, shardingConfig);
+                break;
+            default:
+                throw new Error(`[CurdProService] 不支持的分表类型: ${shardingConfig.type}`);
+        }
         sharding.setBaseCfg({ sqlDatabase, sqlDbType });
         return sharding;
     }
+    /**
+     * 根据 `method` 获取（可能来自缓存的）CRUD 配置。
+     *
+     * 适用于：你只想先拿到配置做检查/二次加工/审计，再决定是否执行。
+     * 非调试模式会启用缓存（调试模式关闭缓存）。
+     *
+     * @param method 配置方法名，例如：`user.list`
+     * @returns CRUD 配置模型
+     *
+     * @example
+     * const cfg = await curdProService.getCachedCfgByMethod('user.list');
+     * console.log(cfg.sqlSimpleName);
+     */
     async getCachedCfgByMethod(method) {
         const curdPro = this.getCrudPro();
         const isEnableCache = !this.isEnableDebug(); // 开发环境不使用缓存
         return curdPro.getCachedCfgByMethod(method, isEnableCache);
     }
+    /**
+     * 获取数据库的表/视图等结构信息列表（用于数据源探测、表选择器、代码生成等场景）。
+     *
+     * @param query 查询条件（例如：指定数据库、关键字过滤、分页等）
+     * @param options 可选项（例如：是否包含视图/系统表、大小写处理等，具体以接口定义为准）
+     * @returns 表信息列表结果
+     *
+     * @example
+     * const tables = await curdProService.getAllTableInfos(
+     *   { sqlDbType: SqlDbType.mysql, sqlDatabase: 'mydb' },
+     *   { skipCache: true }
+     * );
+     */
     async getAllTableInfos(query, options) {
         const curdPro = this.getCrudPro();
         return curdPro.getAllTableInfos(query, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midway-fatcms",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "This is a midway component sample",
   "main": "dist/index.js",
   "typings": "index.d.ts",

package/src/configuration.ts

@@ -15,6 +15,8 @@ import { GlobalMiddleware } from './middleware/global.middleware';
 import { ForbiddenMiddleware } from './middleware/forbidden.middleware';
 import { SCHEDULE_QUEUE, ANONYMOUS_CONTEXT, INNER_SCHEDULE_INTERVAL } from './schedule';
 import { privateAES } from './libs/utils/crypto-utils';
+import { initTableMetaCachePublishClient, initTableMetaCacheSubscriber } from './service/TableMetaCacheRedisSubscriber';
+import { RedisService } from '@midwayjs/redis';
 
 @Configuration({
   // namespace: 'fatcms',
@@ -65,6 +67,11 @@ export class ContainerLifeCycle {
      */
     ANONYMOUS_CONTEXT.setApp(this.app);
 
+    /**
+     * 初始化表元数据缓存 Redis 广播
+     */
+    await this.initTableMetaCacheRedis();
+
     /**
      * 启动定时任务
      */
@@ -78,6 +85,26 @@ export class ContainerLifeCycle {
     // this.app.useFilter([NotFoundFilter, DefaultErrorFilter]);
   }
 
+  /**
+   * 初始化表元数据缓存的 Redis Pub/Sub 广播
+   *
+   * - 发布客户端：复用已有的 RedisService 实例
+   * - 订阅客户端：通过 duplicate() 创建独立连接
+   *
+   * 集群部署时，任意节点调用 clearTableMetaCacheWithBroadcast()
+   * 会通过 Redis 广播通知所有节点清空本地缓存。
+   */
+  private async initTableMetaCacheRedis() {
+    try {
+      const redisService = await this.app.getApplicationContext().getAsync(RedisService);
+      initTableMetaCachePublishClient(redisService);
+      initTableMetaCacheSubscriber(redisService);
+    } catch (e) {
+      // Redis 未配置或不可用时，降级为单节点模式（仅清空本地缓存）
+      this.app.getLogger().warn('ContainerLifeCycle ==> initTableMetaCacheRedis Redis不可用，降级为单节点模式:', e.message);
+    }
+  }
+
   private async startScheduleOnReady() {
     const logger = this.app.getLogger();
     const config = this.app.getConfig();

package/src/controller/helpers.controller.ts

@@ -7,6 +7,7 @@ import { createUniqueId } from '@/libs/utils/functions';
 import { privateAES } from '@/libs/utils/crypto-utils';
 import { CommonResult } from '@/libs/utils/common-dto';
 import {SystemRoleCode} from "@/models/SystemPerm";
+import { clearTableMetaCacheWithBroadcast } from '@/service/TableMetaCacheRedisSubscriber';
 
 // http://127.0.0.1:7002/ns/api/helpers/getApiScript?prefix=/ns/api/manage
 // http://127.0.0.1:7002/ns/api/helpers/getApiScript
@@ -145,6 +146,20 @@ export class HelpersApi {
     });
   }
 
+  /**
+   * 工具函数: 清空表元数据缓存（集群广播）
+   * 清空本节点缓存，并通过 Redis Pub/Sub 广播通知集群中其他节点。
+   * 清空后，下次请求会自动从数据库重新加载（懒加载刷新）。
+   */
+  @Get('/clearTableMetaCache')
+  async clearTableMetaCacheApi() {
+    const stats = clearTableMetaCacheWithBroadcast();
+    return CommonResult.successRes({
+      message: '表元数据缓存已清空（已广播集群）',
+      beforeClear: stats,
+    });
+  }
+
   private checkLocalPermissionEnv() {
     //是否是开发者
    const isDevelopUser = (): boolean=> {

package/src/libs/crud-pro/CrudPro.ts

@@ -1,4 +1,4 @@
-import { ICrudProCfg, ILogger, IRequestCfgModel, IRequestModel, ISqlCfgModel, ITableListResult, ITableNamesOptions, ITableNamesQuery, IVisitor, ExecuteSQLResult } from './interfaces';
+import { ICrudProCfg, ILogger, IRequestCfgModel, IRequestModel, ISqlCfgModel, ITableListResult, ITableMetaQuery, ITableNamesOptions, ITableNamesQuery, IVisitor, ExecuteSQLResult } from './interfaces';
 import { ExecuteContext } from './models/ExecuteContext';
 import { RequestModel } from './models/RequestModel';
 import { CurdProServiceHub } from './services/CurdProServiceHub';
@@ -165,12 +165,16 @@ class CrudPro {
     exeCtx.setReqModel(reqModel);
     exeCtx.setCfgModel(cfgModel);
 
+    // insertOrUpdate 参数校验
+    this.validateParamsIfNeeded(reqModel, cfgModel);
+
     // 如果是 sqlSimpleName模式的 update/insert，则需要将 reqJson.data 部分根据真实的表结构进行过滤
     await this.filterDataByTableMetaIfNeeded(reqModel, cfgModel);
 
-    // 根据表结构字段类型，自动转换数据格式（如 PostgreSQL ARRAY 字段）
+    //插入和更新时： 根据表结构字段类型，自动转换 data 数据格式（如 PostgreSQL ARRAY 字段）
     await this.convertDataFieldTypeIfNeeded(reqModel, cfgModel);
-
+    //查询时：根据表结构字段类型，自动转换 condition 数据格式（防止数据库隐式类型转换导致索引失效）
+    await this.convertConditionTypeIfNeeded(reqModel, cfgModel);
     // 参数校验
     this.serviceHub.validateDataType(cfgModel, reqModel);
     this.serviceHub.validateByAllow(cfgModel, reqModel);
@@ -214,6 +218,19 @@ class CrudPro {
     return this.serviceHub.getAllTableInfos(query, options);
   }
 
+  /**
+   * 获取表的主键列名列表
+   *
+   * 复用 CrudProTableMetaService 的 getTableMeta 缓存，
+   * 从 columnDetails 中筛选 isPrimaryKey 的列。
+   *
+   * @param query 表元数据查询参数
+   * @returns 主键列名数组
+   */
+  public async getPrimaryKeyColumns(query: ITableMetaQuery): Promise<string[]> {
+    return this.serviceHub.getPrimaryKeyColumns(query);
+  }
+
   /**
    * 如果是 INSERT/UPDATE 操作（sqlSimpleName 模式），根据真实表结构过滤 reqModel.data 中的字段
    * 避免传入不存在的字段导致 SQL 执行报错
@@ -266,6 +283,48 @@ class CrudPro {
     reqModel.data = filteredData;
   }
 
+  /**
+   * 校验特定操作的必填参数
+   *
+   * - insertOrUpdate 和 update：condition 和 data 均为必填
+   * - insertOnDuplicateUpdate 和 insert：只有data 为必填
+   * @param reqModel 请求模型
+   * @param cfgModel 配置模型
+   * @throws CommonException 如果缺少必填参数
+   */
+  private validateParamsIfNeeded(reqModel: RequestModel, cfgModel: RequestCfgModel): void {
+    // insertOrUpdate 和 update：condition 和 data 均为必填
+    if (cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE ||
+        cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_UPDATE) {
+      if (!reqModel.condition || Object.keys(reqModel.condition).length === 0) {
+        throw new CommonException(
+          Exceptions.INSERT_OR_UPDATE_CONDITION_EMPTY,
+          '[CrudPro] insertOrUpdate/update 操作的 condition 不能为空。' +
+          'condition 用于判断记录是否存在或定位更新目标。'
+        );
+      }
+      if (!reqModel.data || Object.keys(reqModel.data as Record<string, any>).length === 0) {
+        throw new CommonException(
+          Exceptions.INSERT_OR_UPDATE_DATA_EMPTY,
+          '[CrudPro] insertOrUpdate/update 操作的 data 不能为空。' +
+          'data 用于指定插入或更新的内容。'
+        );
+      }
+    }
+
+    // insertOnDuplicateUpdate 和 insert：只有 data 为必填
+    if (cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE ||
+        cfgModel.sqlSimpleName === KeysOfSimpleSQL.SIMPLE_INSERT) {
+      if (!reqModel.data || Object.keys(reqModel.data as Record<string, any>).length === 0) {
+        throw new CommonException(
+          Exceptions.INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY,
+          '[CrudPro] insert/insertOnDuplicateUpdate 操作的 data 不能为空。' +
+          'data 用于指定插入或更新的内容。'
+        );
+      }
+    }
+  }
+
   /**
    * 判断 sqlSimpleName 是否为 INSERT/UPDATE 类型
    * @param sqlSimpleName 简单 SQL 名称
@@ -282,7 +341,7 @@ class CrudPro {
   }
 
   /**
-   * 根据表结构字段类型，自动转换数据格式
+   * 根据表结构字段类型，自动转换 data 数据格式
    * 例如：PostgreSQL 的 ARRAY 类型字段，需要将 JSON 数组转为 PG 数组字面量格式
    * @param reqModel 请求模型
    * @param cfgModel 配置模型
@@ -291,6 +350,16 @@ class CrudPro {
     await this.serviceHub.convertDataTypeByTableMeta(reqModel, cfgModel);
   }
 
+  /**
+   * 查询时：根据表结构字段类型，自动转换 condition 数据格式
+   * 防止数据库隐式类型转换导致索引失效（如 WHERE int_col = '123' 导致索引无法命中）
+   * @param reqModel 请求模型
+   * @param cfgModel 配置模型
+   */
+  private async convertConditionTypeIfNeeded(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void> {
+    await this.serviceHub.convertConditionTypeByTableMeta(reqModel, cfgModel);
+  }
+
   private async executeSQLList() {
     try {
       await this.serviceHub.executeSqlCfgModels();

package/src/libs/crud-pro/exceptions.ts

@@ -61,6 +61,13 @@ export enum Exceptions {
   DATA_GET_DATA_EMPTY_ON_INSERT_VALUES = 'DATA_GET_DATA_EMPTY_ON_INSERT_VALUES',
   BATCH_INSERT_KEYS_MISMATCH = 'BATCH_INSERT_KEYS_MISMATCH', // 批量插入时字段不一致
 
+  /**
+   * insertOrUpdate 参数缺失
+   */
+  INSERT_OR_UPDATE_CONDITION_EMPTY = 'INSERT_OR_UPDATE_CONDITION_EMPTY', // insertOrUpdate/update 的 condition 不能为空
+  INSERT_OR_UPDATE_DATA_EMPTY = 'INSERT_OR_UPDATE_DATA_EMPTY', // insertOrUpdate/update 的 data 不能为空
+  INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY = 'INSERT_ON_DUPLICATE_UPDATE_DATA_EMPTY', // insertOnDuplicateUpdate/insert 的 data 不能为空
+
   /**
    * 请求的Method字段为空
    */
@@ -85,6 +92,7 @@ export enum Exceptions {
   RUN_PICK_ERR_VISITOR_FIELD_NULL = 'RUN_PICK_ERR_VISITOR_FIELD_NULL',
   RUN_EXECUTE_VALIDATE = 'RUN_EXECUTE_VALIDATE',
   RUN_FUNCTION_NOT_FOUND = 'RUN_FUNCTION_NOT_FOUND',
+  MORE_THAN_ONE_RECORDS_FOUND = 'MORE_THAN_ONE_RECORDS_FOUND',
 
   /**
    * 参数校验错误

package/src/libs/crud-pro/interfaces.ts

@@ -17,6 +17,7 @@ export interface ITableColumn {
   type: string; // 数据类型
   isNullable: boolean; // 是否可空
   isPrimaryKey?: boolean; // 是否主键
+  isIdentity?: boolean; // 是否自增列（SQL Server）
   defaultValue?: any; // 默认值
   maxLength?: number; // 最大长度
   comment?: string; // 字段注释

package/src/libs/crud-pro/models/CrudResult.ts

@@ -89,11 +89,14 @@ class CrudWriteResult extends CrudResultBase {
 class CrudQueryOneResult<T = Record<string, any>> extends CrudResultBase {
   readonly row: T | null;
   readonly found: boolean;
+  /** 数据来源的物理表名（分表场景下为实际分表名，如 t_order_202403） */
+  readonly fromTable: string;
 
-  constructor(data: { row: T | null; rawContext: ExecuteContext; debugInfo?: CrudResultDebugInfo }) {
+  constructor(data: { row: T | null; rawContext: ExecuteContext; debugInfo?: CrudResultDebugInfo; fromTable: string }) {
     super(data.rawContext, data.debugInfo);
     this.row = data.row;
-    this.found = (this.row !== null && this.row !== undefined );
+    this.found = (this.row !== null && this.row !== undefined);
+    this.fromTable = data.fromTable;
   }
 }
 
@@ -145,13 +148,11 @@ class CrudCountResult extends CrudResultBase {
 
 /** InsertOrUpdate 结果 */
 class CrudUpsertResult extends CrudResultBase {
-  readonly affected?: ResModelAffected;
   readonly insertAffected?: ResModelAffected;
   readonly updateAffected?: ResModelAffected;
   readonly isExist: boolean;
 
   constructor(data: {
-    affected?: ResModelAffected;
     insertAffected?: ResModelAffected;
     updateAffected?: ResModelAffected;
     isExist: boolean;
@@ -159,7 +160,6 @@ class CrudUpsertResult extends CrudResultBase {
     debugInfo?: CrudResultDebugInfo;
   }) {
     super(data.rawContext, data.debugInfo);
-    this.affected = data.affected;
     this.insertAffected = data.insertAffected;
     this.updateAffected = data.updateAffected;
     this.isExist = data.isExist;

package/src/libs/crud-pro/models/ServiceHub.ts

@@ -30,5 +30,9 @@ export interface ICurdProServiceHub {
 
   getTableMeta(query: ITableMetaQuery): Promise<ITableMeta>;
 
+  getPrimaryKeyColumns(query: ITableMetaQuery): Promise<string[]>;
+
   convertDataTypeByTableMeta(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void>;
+
+  convertConditionTypeByTableMeta(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void>;
 }