midway-fatcms 0.0.8 → 0.0.9

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

@@ -1,4 +1,5 @@
 import { CrudPro } from '../../libs/crud-pro/CrudPro';
+import { KeysOfSimpleSQL } from '../crud-pro/models/keys';
 /**
  * CrudPro 工厂函数类型
  * 每次调用返回新的 CrudPro 实例，避免状态污染
@@ -11,8 +12,8 @@ export declare type CrudProFactory = () => CrudPro;
  * - 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: 自定义分表规则
  */
 /**
@@ -25,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"
 }
@@ -47,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;
     /**
@@ -220,7 +222,7 @@ export interface IShardingRouterContext {
      * SQL 简单名称
      * 用于判断具体的查询类型
      */
-    sqlSimpleName?: string;
+    sqlSimpleName: KeysOfSimpleSQL;
 }
 /**
  * 时间范围

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

@@ -8,8 +8,8 @@ exports.ShardingType = void 0;
  * - 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: 自定义分表规则
  */
 /**
@@ -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 = {}));

package/dist/libs/crud-sharding/TIME_COLUMN_CLEAN_SPEC.md

@@ -14,7 +14,7 @@
 
 **职责**：确保写操作的 condition 包含时间字段，用于路由定位分表。
 
-**适用操作**：update / delete / restore / insertOrUpdate / insertOnDuplicateUpdate
+**适用操作**：update / delete / restore / insertOrUpdate
 
 **校验规则**：
 - condition 中必须存在 timeColumn 字段（值不能为 falsy）

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

@@ -7,15 +7,15 @@
  * - 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: 自定义分表规则
  *
  * @example
- * import { ShardingCrudPro, ShardingType } from '../../libs/crud-sharding';
+ * import { ShardingByTimeCrud, ShardingType } from '../../libs/crud-sharding';
  *
- * // 创建分表操作器
- * const sharding = new ShardingCrudPro(crudPro, {
+ * // 创建时间分表操作器
+ * const sharding = new ShardingByTimeCrud(crudProFactory, {
  *   type: ShardingType.MONTH,
  *   baseTable: 't_order',
  *   timeColumn: 'created_at',
@@ -25,16 +25,13 @@
  * 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,
- * });
  */
-export { ShardingCrudPro } from './ShardingCrudPro';
-export { ShardingRouter } from './ShardingRouter';
+export { ShardingBase } from './ShardingBase';
+export { ShardingByTimeCrud } from './ShardingByTimeCrud';
+export { ShardingByHashCrud } from './ShardingByHashCrud';
+export { ShardingByKeyCrud } from './ShardingByKeyCrud';
+export { ShardingByCustomCrud } from './ShardingByCustomCrud';
+export { ShardingBase as ShardingCrudPro } from './ShardingBase';
 export { ShardingMerger } from './ShardingMerger';
 export { ShardingType } from './ShardingConfig';
 export type { IShardingConfig, IShardingRouterContext, IShardingRouterFunc, IShardingTimeRange, IShardingTableCreateOptions, IShardingTableCreateResult, IShardingCountCacheConfig, } from './ShardingConfig';

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

@@ -8,15 +8,15 @@
  * - 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: 自定义分表规则
  *
  * @example
- * import { ShardingCrudPro, ShardingType } from '../../libs/crud-sharding';
+ * import { ShardingByTimeCrud, ShardingType } from '../../libs/crud-sharding';
  *
- * // 创建分表操作器
- * const sharding = new ShardingCrudPro(crudPro, {
+ * // 创建时间分表操作器
+ * const sharding = new ShardingByTimeCrud(crudProFactory, {
  *   type: ShardingType.MONTH,
  *   baseTable: 't_order',
  *   timeColumn: 'created_at',
@@ -26,21 +26,25 @@
  * 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,
- * });
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shardingHashCondition = exports.ShardingCountCache = exports.ShardingTableCreator = exports.CrudUpsertResult = exports.CrudCountResult = exports.CrudExistResult = exports.CrudQueryPageResult = exports.CrudQueryListResult = exports.CrudQueryOneResult = exports.CrudWriteResult = exports.ShardingBatchInsertResult = exports.ShardingType = exports.ShardingMerger = exports.ShardingRouter = exports.ShardingCrudPro = void 0;
-// 核心类
-var ShardingCrudPro_1 = require("./ShardingCrudPro");
-Object.defineProperty(exports, "ShardingCrudPro", { enumerable: true, get: function () { return ShardingCrudPro_1.ShardingCrudPro; } });
-var ShardingRouter_1 = require("./ShardingRouter");
-Object.defineProperty(exports, "ShardingRouter", { enumerable: true, get: function () { return ShardingRouter_1.ShardingRouter; } });
+exports.shardingHashCondition = exports.ShardingCountCache = exports.ShardingTableCreator = exports.CrudUpsertResult = exports.CrudCountResult = exports.CrudExistResult = exports.CrudQueryPageResult = exports.CrudQueryListResult = exports.CrudQueryOneResult = exports.CrudWriteResult = exports.ShardingBatchInsertResult = exports.ShardingType = exports.ShardingMerger = exports.ShardingCrudPro = exports.ShardingByCustomCrud = exports.ShardingByKeyCrud = exports.ShardingByHashCrud = exports.ShardingByTimeCrud = exports.ShardingBase = void 0;
+// 基类
+var ShardingBase_1 = require("./ShardingBase");
+Object.defineProperty(exports, "ShardingBase", { enumerable: true, get: function () { return ShardingBase_1.ShardingBase; } });
+// 四个子类
+var ShardingByTimeCrud_1 = require("./ShardingByTimeCrud");
+Object.defineProperty(exports, "ShardingByTimeCrud", { enumerable: true, get: function () { return ShardingByTimeCrud_1.ShardingByTimeCrud; } });
+var ShardingByHashCrud_1 = require("./ShardingByHashCrud");
+Object.defineProperty(exports, "ShardingByHashCrud", { enumerable: true, get: function () { return ShardingByHashCrud_1.ShardingByHashCrud; } });
+var ShardingByKeyCrud_1 = require("./ShardingByKeyCrud");
+Object.defineProperty(exports, "ShardingByKeyCrud", { enumerable: true, get: function () { return ShardingByKeyCrud_1.ShardingByKeyCrud; } });
+var ShardingByCustomCrud_1 = require("./ShardingByCustomCrud");
+Object.defineProperty(exports, "ShardingByCustomCrud", { enumerable: true, get: function () { return ShardingByCustomCrud_1.ShardingByCustomCrud; } });
+// 兼容旧代码：ShardingCrudPro → ShardingBase
+var ShardingBase_2 = require("./ShardingBase");
+Object.defineProperty(exports, "ShardingCrudPro", { enumerable: true, get: function () { return ShardingBase_2.ShardingBase; } });
+// 合并器（仅 Time 使用）
 var ShardingMerger_1 = require("./ShardingMerger");
 Object.defineProperty(exports, "ShardingMerger", { enumerable: true, get: function () { return ShardingMerger_1.ShardingMerger; } });
 // 配置和类型

package/dist/models/RedisKeys.d.ts

@@ -11,5 +11,6 @@ declare const RedisKeys: {
     CURD_MIX_BY_DICT_PREFIX: string;
     QUERY_ENUM_INFO_PREFIX: string;
     REDIS_LOCK_MIDDILEWARE: string;
+    TABLE_META_CACHE_INVALIDATE_CHANNEL: string;
 };
 export { RedisKeys };

package/dist/models/RedisKeys.js

@@ -14,5 +14,6 @@ const RedisKeys = {
     CURD_MIX_BY_DICT_PREFIX: 'FatCurdMixByDict@@',
     QUERY_ENUM_INFO_PREFIX: 'FatQueryEnum@@',
     REDIS_LOCK_MIDDILEWARE: 'FatRedisLock@@',
+    TABLE_META_CACHE_INVALIDATE_CHANNEL: 'FatTableMetaCacheInvalidate',
 };
 exports.RedisKeys = RedisKeys;

package/dist/service/TableMetaCacheRedisSubscriber.d.ts

@@ -0,0 +1,31 @@
+import { RedisService } from '@midwayjs/redis';
+/**
+ * 初始化发布客户端
+ *
+ * 在 Midway 容器初始化完成后调用，注入已有的 RedisService 实例
+ * @param client RedisService 实例
+ */
+export declare function initTableMetaCachePublishClient(client: RedisService): void;
+/**
+ * 初始化 Redis 订阅，监听缓存失效广播
+ *
+ * 使用 RedisService.duplicate() 创建独立的订阅连接。
+ * 收到广播后自动清空本节点的本地缓存。
+ *
+ * @param mainClient 已有的 RedisService 实例，用于 duplicate 出订阅连接
+ */
+export declare function initTableMetaCacheSubscriber(mainClient: RedisService): void;
+/**
+ * 清空本节点缓存并广播通知集群中其他节点
+ *
+ * 调用流程：
+ * 1. 清空本节点本地缓存
+ * 2. 通过 Redis PUBLISH 广播消息
+ * 3. 其他节点收到消息后清空各自的本地缓存
+ *
+ * @returns 清空前的缓存统计
+ */
+export declare function clearTableMetaCacheWithBroadcast(): {
+    metaCacheCount: number;
+    tableInfoCacheCount: number;
+};

package/dist/service/TableMetaCacheRedisSubscriber.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearTableMetaCacheWithBroadcast = exports.initTableMetaCacheSubscriber = exports.initTableMetaCachePublishClient = void 0;
+const CrudProTableMetaService_1 = require("../libs/crud-pro/services/CrudProTableMetaService");
+const RedisKeys_1 = require("../models/RedisKeys");
+const CHANNEL = RedisKeys_1.RedisKeys.TABLE_META_CACHE_INVALIDATE_CHANNEL;
+/**
+ * 本节点唯一标识，用于区分是自己发出的广播还是其他节点发出的
+ * 避免重复清空（本节点已在发布前清空过）
+ */
+const NODE_ID = `node_${process.pid}_${Date.now()}`;
+/**
+ * 用于发布消息的 Redis 客户端（复用 @midwayjs/redis 注入的实例）
+ */
+let publishClient = null;
+/**
+ * 用于订阅的 Redis 客户端（独立连接，ioredis 规定订阅连接不能执行普通命令）
+ */
+let subscribeClient = null;
+/**
+ * 初始化发布客户端
+ *
+ * 在 Midway 容器初始化完成后调用，注入已有的 RedisService 实例
+ * @param client RedisService 实例
+ */
+function initTableMetaCachePublishClient(client) {
+    publishClient = client;
+}
+exports.initTableMetaCachePublishClient = initTableMetaCachePublishClient;
+/**
+ * 初始化 Redis 订阅，监听缓存失效广播
+ *
+ * 使用 RedisService.duplicate() 创建独立的订阅连接。
+ * 收到广播后自动清空本节点的本地缓存。
+ *
+ * @param mainClient 已有的 RedisService 实例，用于 duplicate 出订阅连接
+ */
+function initTableMetaCacheSubscriber(mainClient) {
+    if (subscribeClient) {
+        return; // 防止重复初始化
+    }
+    // duplicate() 创建一个同配置的独立连接
+    subscribeClient = mainClient.duplicate();
+    subscribeClient.subscribe(CHANNEL).catch((err) => {
+        console.error('[TableMetaCacheRedis] subscribe failed:', err.message);
+    });
+    subscribeClient.on('message', (channel, message) => {
+        if (channel !== CHANNEL)
+            return;
+        try {
+            const data = JSON.parse(message);
+            // 跳过自己发出的广播（本节点已在发布前清空过）
+            if (data.nodeId === NODE_ID)
+                return;
+            const stats = (0, CrudProTableMetaService_1.clearTableMetaCache)();
+            console.info(`[TableMetaCacheRedis] 收到其他节点(${data.nodeId})的缓存清空广播，已清空本地缓存:`, stats);
+        }
+        catch (e) {
+            console.error('[TableMetaCacheRedis] 处理缓存失效广播异常:', e);
+        }
+    });
+    subscribeClient.on('error', (err) => {
+        console.error('[TableMetaCacheRedis] subscriber connection error:', err.message);
+    });
+    console.info('[TableMetaCacheRedis] 订阅已启动，监听频道:', CHANNEL);
+}
+exports.initTableMetaCacheSubscriber = initTableMetaCacheSubscriber;
+/**
+ * 清空本节点缓存并广播通知集群中其他节点
+ *
+ * 调用流程：
+ * 1. 清空本节点本地缓存
+ * 2. 通过 Redis PUBLISH 广播消息
+ * 3. 其他节点收到消息后清空各自的本地缓存
+ *
+ * @returns 清空前的缓存统计
+ */
+function clearTableMetaCacheWithBroadcast() {
+    // 1. 清空本节点缓存
+    const stats = (0, CrudProTableMetaService_1.clearTableMetaCache)();
+    // 2. 广播通知其他节点
+    if (publishClient && typeof publishClient.publish === 'function') {
+        const message = JSON.stringify({
+            nodeId: NODE_ID,
+            timestamp: Date.now(),
+            beforeClear: stats,
+        });
+        publishClient.publish(CHANNEL, message).catch((err) => {
+            console.error('[TableMetaCacheRedis] publish failed:', err.message);
+        });
+    }
+    else {
+        // 没有 Redis 连接时仅清空本地（单节点部署降级）
+        console.info('[TableMetaCacheRedis] 无 Redis 发布客户端，仅清空本节点缓存');
+    }
+    return stats;
+}
+exports.clearTableMetaCacheWithBroadcast = clearTableMetaCacheWithBroadcast;

package/dist/service/curd/CurdMixService.d.ts

@@ -1,7 +1,7 @@
 import { ColumnRelation, IRequestCfgModel, IRequestModel, ISqlCfgModel, ITableListResult, ITableNamesOptions, ITableNamesQuery, ExecuteSQLResult } from '../../libs/crud-pro/interfaces';
 import { IRequestCfgModel2 } from '../../models/bizmodels';
 import { ExecuteContext } from '../../libs/crud-pro/models/ExecuteContext';
-import { ShardingCrudPro } from "../../libs/crud-sharding";
+import { ShardingBase } from "../../libs/crud-sharding";
 import { IGetQuickCrudParam, IGetShardingCrudParam } from './CurdProService';
 export interface ILinkColumnRelationParam {
     columnsRelations: ColumnRelation[];
@@ -16,7 +16,7 @@ export declare class CurdMixService {
     private prepare;
     executeCrudByCfg(reqJson: IRequestModel, cfgModel: IRequestCfgModel2): Promise<ExecuteContext>;
     getQuickCrud(param: IGetQuickCrudParam): import("../..").CrudProQuick;
-    getShardingCrud(param: IGetShardingCrudParam): ShardingCrudPro;
+    getShardingCrud(param: IGetShardingCrudParam): ShardingBase;
     executeSQL(sqlCfgModel: ISqlCfgModel): Promise<ExecuteSQLResult>;
     executeCrud(reqJson: IRequestModel): Promise<ExecuteContext>;
     getCachedCfgByMethod(method: string): Promise<IRequestCfgModel>;

package/dist/service/curd/CurdProService.d.ts

@@ -6,7 +6,7 @@ import { RelatedType } from './CurdMixUtils';
 import { BaseService } from '../base/BaseService';
 import { IRequestCfgModel2 } from '../../models/bizmodels';
 import { CrudProQuick } from '../../libs/crud-pro-quick';
-import { ShardingCrudPro, IShardingConfig } from '../../libs/crud-sharding';
+import { ShardingBase, IShardingConfig } from '../../libs/crud-sharding';
 /**
  * getQuickCrud 参数接口
  */
@@ -36,7 +36,37 @@ export declare class CurdProService extends BaseService {
     private sqlserver2Config;
     private crudProCfg;
     private 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: RelatedType, handler: IExecuteContextHandler): void;
+    /**
+     * 获取当前已注册的“响应配置处理器”集合。
+     *
+     * 一般用于调试或在外层框架中统一检查/复用已有 handler。
+     *
+     * @returns 以 `RelatedType` 为 key 的处理器映射表
+     *
+     * @example
+     * const handlers = curdProService.getResponseCfgHandlers();
+     * const userHandler = handlers[RelatedType.USER];
+     */
     getResponseCfgHandlers(): Record<RelatedType, IExecuteContextHandler>;
     /**
      * Execute级别：每次调用都会产生新的
@@ -44,11 +74,59 @@ export declare class CurdProService extends BaseService {
      */
     private getCrudPro;
     /**
-     * 依赖缓存中与加载的配置
-     * @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);
      */
     executeCrud(reqJson: IRequestModel): Promise<ExecuteContext>;
+    /**
+     * 直接执行一段 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],
+     * });
+     */
     executeSQL(sqlCfgModel: ISqlCfgModel): Promise<ExecuteSQLResult>;
+    /**
+     * 直接按指定配置执行一次 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
+     * );
+     */
     executeCrudByCfg(reqJson: IRequestModel, cfgModel: IRequestCfgModel2): Promise<ExecuteContext>;
     /**
      * 获取 CrudProQuick 工具类
@@ -71,7 +149,7 @@ export declare class CurdProService extends BaseService {
      * 获取分表 CRUD 操作器
      *
      * @param param 参数对象
-     * @returns ShardingCrudPro 实例
+     * @returns ShardingBase 实例（实际类型根据 shardingConfig.type 决定）
      *
      * @example
      * const sharding = curdProService.getShardingCrud({
@@ -84,7 +162,33 @@ export declare class CurdProService extends BaseService {
      *   },
      * });
      */
-    getShardingCrud(param: IGetShardingCrudParam): ShardingCrudPro;
+    getShardingCrud(param: IGetShardingCrudParam): ShardingBase;
+    /**
+     * 根据 `method` 获取（可能来自缓存的）CRUD 配置。
+     *
+     * 适用于：你只想先拿到配置做检查/二次加工/审计，再决定是否执行。
+     * 非调试模式会启用缓存（调试模式关闭缓存）。
+     *
+     * @param method 配置方法名，例如：`user.list`
+     * @returns CRUD 配置模型
+     *
+     * @example
+     * const cfg = await curdProService.getCachedCfgByMethod('user.list');
+     * console.log(cfg.sqlSimpleName);
+     */
     getCachedCfgByMethod(method: string): Promise<IRequestCfgModel>;
+    /**
+     * 获取数据库的表/视图等结构信息列表（用于数据源探测、表选择器、代码生成等场景）。
+     *
+     * @param query 查询条件（例如：指定数据库、关键字过滤、分页等）
+     * @param options 可选项（例如：是否包含视图/系统表、大小写处理等，具体以接口定义为准）
+     * @returns 表信息列表结果
+     *
+     * @example
+     * const tables = await curdProService.getAllTableInfos(
+     *   { sqlDbType: SqlDbType.mysql, sqlDatabase: 'mydb' },
+     *   { skipCache: true }
+     * );
+     */
     getAllTableInfos(query: ITableNamesQuery, options?: ITableNamesOptions): Promise<ITableListResult>;
 }