midway-fatcms 0.0.8 → 0.0.9

package/.qoder/skills/midway-fatcms/02-crud-quick.md

@@ -38,6 +38,7 @@ const quick = this.curdProService.getQuickCrud({
 | `restore(req, table?)` | `CrudWriteResult` | 恢复软删除记录（重置 deleted_at/deleted_by） |
 | `insertOrUpdate(req, table?)` | `CrudUpsertResult` | 先查再插/更 |
 | `insertOnDuplicateUpdate(req, uniqueCols?, table?)` | `CrudWriteResult` | 原生 upsert |
+| `save(req, table?)` | `CrudUpsertResult` | 自动判断 INSERT/UPDATE |
 
 ### SQL 方法
 
@@ -220,6 +221,21 @@ console.log(result.isExist ? '更新' : '插入');
 
 ### insertOnDuplicateUpdate - 原生 Upsert
 
+> **前置条件**：目标表必须拥有 UNIQUE 索引（除自增主键外）。
+>
+> `INSERT ON DUPLICATE KEY UPDATE` 只在 UNIQUE 索引或 PRIMARY KEY 冲突时触发 UPDATE。
+> 如果表只有普通索引（KEY/INDEX），MySQL 不会报错，但**永远走 INSERT 路径，不会触发 UPDATE**，且每次调用都会插入新行。
+>
+> ```sql
+> -- 检查表是否有 UNIQUE 索引
+> SELECT DISTINCT INDEX_NAME FROM information_schema.STATISTICS
+> WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'your_table'
+>   AND NON_UNIQUE = 0 AND INDEX_NAME != 'PRIMARY';
+>
+> -- 添加 UNIQUE 索引
+> ALTER TABLE your_table ADD UNIQUE KEY uk_xxx (column_name);
+> ```
+
 ```typescript
 const result = await quick.insertOnDuplicateUpdate(
   { data: { id: 1, name: '用户' } },
@@ -227,6 +243,28 @@ const result = await quick.insertOnDuplicateUpdate(
 );
 ```
 
+### save - 自动判断 INSERT/UPDATE
+
+只需传入 `data`，无需手动指定 `condition`。方法会自动查询表的主键列，根据 `data` 中是否包含主键值来决定操作：
+
+- **data 包含主键且值不为 null/undefined** → 调用 `insertOrUpdate`（先查后写，存在则更新，不存在则插入）
+- **data 不包含主键或主键值为 null/undefined** → 调用 `insert`（直接插入）
+
+```typescript
+// 有主键 → 先查后写
+await quick.save({ data: { id: 1, name: '张三' } });
+
+// 无主键 → 直接 INSERT
+await quick.save({ data: { name: '李四' } });
+
+// 主键值为 null → 视为无主键，直接 INSERT
+await quick.save({ data: { id: null, name: '王五' } });
+```
+
+> **与 insertOrUpdate 的区别**：`save` 不需要传 `condition`，自动从 `data` 中提取主键组成 `condition`。本质是 `insertOrUpdate` 的便捷版。
+>
+> **性能说明**：首次调用 `save` 时会查询表的主键列信息，结果缓存 24 小时，后续调用无额外开销。
+
 ---
 
 ## SQL 方法详解

package/.qoder/skills/midway-fatcms/03-crud-sharding.md

@@ -1,6 +1,8 @@
-# ShardingCrudPro 分表操作
+# 分表 CRUD 操作
 
-ShardingCrudPro 提供自动路由分表的能力，支持时间分表、哈希分表、范围分表、自定义分表四种策略。
+分表模块提供自动路由分表的能力，支持四种策略：时间分表（ShardingByTimeCrud）、哈希分表（ShardingByHashCrud）、键值分表（ShardingByKeyCrud）、自定义分表（ShardingByCustomCrud）。
+
+基类 `ShardingBase` 提供通用基础设施。`ShardingByTimeCrud` 和 `ShardingByCustomCrud` 各自包含完整的路由和 CRUD 逻辑；`ShardingByHashCrud` 和 `ShardingByKeyCrud` 内部委托 `ShardingByCustomCrud` 实现，仅在构造函数中定义路由逻辑。
 
 ## 获取实例
 
@@ -26,20 +28,20 @@ const sharding = this.curdProService.getShardingCrud({
 
 ## 分表类型
 
-| 类型 | 枚举值 | 后缀示例 | 适用场景 |
-|------|--------|----------|----------|
-| 按年 | `ShardingType.YEAR` | `_2024` | 数据量适中，按年归档 |
-| 按月 | `ShardingType.MONTH` | `_202401` | 大数据量，按月分表 |
-| 按日 | `ShardingType.DAY` | `_20240115` | 超大数据量，按天分表 |
-| 范围 | `ShardingType.RANGE` | `_0`, `_1`... | 按数值范围分布 |
-| 哈希 | `ShardingType.HASH` | `_01`, `_02`... | 均匀分布数据 |
-| 自定义 | `ShardingType.CUSTOM` | 自定义 | 特殊业务规则 |
+| 类型 | 枚举值 | 实现类 | 后缀示例 | 适用场景 |
+|------|--------|--------|----------|----------|
+| 按年 | `ShardingType.YEAR` | `ShardingByTimeCrud` | `_2024` | 数据量适中，按年归档 |
+| 按月 | `ShardingType.MONTH` | `ShardingByTimeCrud` | `_202401` | 大数据量，按月分表 |
+| 按日 | `ShardingType.DAY` | `ShardingByTimeCrud` | `_20240115` | 超大数据量，按天分表 |
+| 哈希 | `ShardingType.HASH` | `ShardingByHashCrud` | `_00`, `_01`... | 均匀分布数据 |
+| 键值 | `ShardingType.KEY` | `ShardingByKeyCrud` | `_east`, `_west`... | 字段原值=表后缀，一值一表 |
+| 自定义 | `ShardingType.CUSTOM` | `ShardingByCustomCrud` | 自定义 | 特殊业务规则（含原 RANGE） |
 
 ## 配置选项
 
 ```typescript
 interface IShardingConfig {
-  type: ShardingType;                    // 分表类型（必填）
+  type: ShardingType;                    // 分表类型（YEAR/MONTH/DAY/HASH/KEY/CUSTOM）
   baseTable: string;                     // 基础表名（必填）
 
   // 时间分表（YEAR/MONTH/DAY）
@@ -52,9 +54,9 @@ interface IShardingConfig {
     tableOptions?: string;             // 表选项（如MySQL引擎配置）
   };
 
-  // 范围/哈希分表（RANGE/HASH）
-  shardingColumn?: string;               // 分表字段（RANGE/HASH必填）
-  tableCount?: number;                   // 分表数量（RANGE默认10，HASH默认16）
+  // 哈希/键值分表（HASH/KEY）
+  shardingColumn?: string;               // 分表字段（HASH/KEY必填）
+  tableCount?: number;                   // 分表数量（仅 HASH，必填）
 
   // COUNT 缓存（仅时间分表有效）
   countCache?: {
@@ -74,8 +76,8 @@ interface IShardingConfig {
 
 | 方法 | 返回类型 | 说明 |
 |------|----------|------|
-| `findOne(req)` | `CrudQueryOneResult<T>` | 查询单条（顺序查多表，找到即返回） |
-| `findUniqueOne(req)` | `CrudQueryOneResult<T>` | 唯一查询（0条返回null，多条报错） |
+| `findOne(req)` | `CrudQueryOneResult<T>` | 查询单条（顺序查多表，找到即返回，含 fromTable 物理表名） |
+| `findUniqueOne(req)` | `CrudQueryOneResult<T>` | 唯一查询（0条返回null，多条报错，含 fromTable 物理表名） |
 | `find(req)` | `T[]` | 列表查询（多表自动合并） |
 | `findList(req)` | `CrudQueryListResult<T>` | 列表查询（带结果包装） |
 | `findPage(req)` | `CrudQueryPageResult<T>` | 分页查询（跨分表自动处理） |
@@ -91,8 +93,7 @@ interface IShardingConfig {
 | `update(req)` | `CrudWriteResult` | 更新（必须能确定单一目标表） |
 | `delete(req)` | `CrudWriteResult` | 删除（必须能确定单一目标表） |
 | `restore(req)` | `CrudWriteResult` | 恢复软删除记录（重置 deleted_at/deleted_by） |
-| `insertOrUpdate(req)` | `CrudUpsertResult` | 插入或更新（condition决定分表） |
-| `insertOnDuplicateUpdate(req)` | `CrudWriteResult` | 原生upsert（condition决定分表） |
+| `insertOrUpdate(req)` | `CrudUpsertResult` | 插入或更新（统一由 condition 路由定位分表） |
 
 ### 配置方法
 
@@ -113,8 +114,7 @@ interface IShardingConfig {
 | `insert` | `data[分表字段]` | 提取值 → 计算后缀 → 单表 | 插入单条数据 |
 | `batchInsert` | `data[i][分表字段]` | 每条数据单独计算分表 | 支持跨分表并行写入 |
 | `update/delete` | `condition[分表字段]` | 提取值 → 计算后缀 → 单表 | condition决定分表，data是更新内容 |
-| `insertOrUpdate` | `condition[分表字段]` | 提取值 → 计算后缀 → 单表 | condition决定分表 |
-| `insertOnDuplicateUpdate` | `condition[分表字段]` | 提取值 → 计算后缀 → 单表 | condition决定分表 |
+| `insertOrUpdate` | `condition[分表字段]` | condition 路由定位分表，查找与插入在同一分表 | 统一由 condition 决定目标分表 |
 | `find/findPage` | `condition[分表字段]` | 时间范围 → 候选表 → 与真实表取交集 → 多表 | 自动合并多表结果 |
 | `findOne/findUniqueOne` | `condition[分表字段]` | 同 find | 顺序查询各分表 |
 | `findCount/isExist` | `condition[分表字段]` | 同 find | 多表并行查询后汇总 |
@@ -123,7 +123,8 @@ interface IShardingConfig {
 
 - **插入类操作**（insert/batchInsert）：只使用 `data`，不需要传 `condition`
 - **查询类操作**（find/delete/isExist等）：只使用 `condition`，不使用 `data`
-- **更新类操作**（update/insertOrUpdate/insertOnDuplicateUpdate）：`condition` 用于路由，`data` 是更新内容
+- **更新类操作**（update）：`condition` 用于路由，`data` 是更新内容
+- **插入或更新**（insertOrUpdate）：统一由 `condition` 路由定位分表，查找与插入在同一分表
 
 ## 时间分表约束
 
@@ -141,7 +142,6 @@ interface IShardingConfig {
 | `delete` | `condition` 必须包含 `timeColumn` | `delete 操作的 condition 必须包含时间字段 'xxx'` |
 | `restore` | `condition` 必须包含 `timeColumn` | `restore 操作的 condition 必须包含时间字段 'xxx'` |
 | `insertOrUpdate` | `data` + `condition` 均须包含 `timeColumn` | 同上 |
-| `insertOnDuplicateUpdate` | `data` + `condition` 均须包含 `timeColumn` | 同上 |
 
 ```typescript
 // ✅ 正确 - insert 包含时间字段
@@ -277,7 +277,7 @@ condition: { created_at: '2026' }         // → { $gte: '2026-01-01 00:00:00',
 
 ### 软删除支持
 
-ShardingCrudPro 支持软删除模式，启用后 `delete` 操作会设置 `deleted_at` 和 `deleted_by` 字段，而非物理删除：
+分表 CRUD 支持软删除模式，启用后 `delete` 操作会设置 `deleted_at` 和 `deleted_by` 字段，而非物理删除：
 
 ```typescript
 const sharding = this.curdProService
@@ -410,7 +410,7 @@ const sharding = this.curdProService.getShardingCrud({
     type: ShardingType.HASH,
     baseTable: 't_user',
     shardingColumn: 'user_id',
-    tableCount: 16,  // t_user_01 ~ t_user_16
+    tableCount: 16,  // t_user_00 ~ t_user_15
   },
 });
 
@@ -419,15 +419,14 @@ await sharding.insert({
   data: { user_id: 10001, name: '张三' }  // → 路由到 t_user_05
 });
 
-// 查询 - 需要提供 user_id 用于路由
+// 查询 - 必须提供 user_id 用于路由
 const user = await sharding.findOne({
   condition: { user_id: 10001 }  // 根据 user_id 确定分表
 });
 
-// 查询多用户 - 无 user_id 时扫描多个分表
-const users = await sharding.find({
-  condition: { status: 'active' },
-  orderBy: 'created_at DESC',
+// ❌ 错误 - 缺少 shardingColumn 会抛出异常
+await sharding.findOne({
+  condition: { status: 'active' }  // 报错：condition 必须包含分表字段 'user_id'
 });
 ```
 
@@ -479,10 +478,12 @@ const sharding = this.curdProService.getShardingCrud({
 ## 注意事项
 
 1. **时间分表写操作必须包含 timeColumn**：insert 的 `data` 或 update/delete 的 `condition` 中必须提供时间字段值
-2. **插入操作必须包含分表字段**：`data` 中必须有分表字段值
-3. **批量插入支持跨分表**：自动按分表分组并行写入
-4. **查询时无时间范围限制**：默认查询最近 N 张分表（YEAR=2, MONTH=3, DAY=7，可配置 `recentTableCount`）
-5. **COUNT 缓存仅对时间分表有效**：哈希/范围分表不启用缓存
-6. **时间字段智能处理**：有主键时精确值自动清理；无主键时日期粒度字符串自动转换为 $gte/$lte 范围；操作符表达式始终保留
-7. **软删除恢复**：启用 setEnableSoftDelete 后可使用 restore 方法恢复已删除记录
-8. **$gte/$lte 必须精确到秒**：使用操作符查询时间字段时值必须包含时分秒（如 `'2026-04-30 23:59:59'`），不允许只传日期部分（`'2026-04-30'`）；如需查整月/整天数据，推荐直接传粒度字符串（`'2026-04'`/`'2026-04-15'`）由系统自动转换
+2. **哈希/键值分表所有操作必须包含 shardingColumn**：insert 的 `data`、query/update/delete 的 `condition` 中必须提供分表字段值，否则抛出异常
+3. **insertOrUpdate 统一路由**：由 `condition` 路由定位分表，查找与插入在同一分表
+4. **批量插入支持跨分表**：自动按分表分组并行写入
+5. **查询时无时间范围限制**：默认查询最近 N 张分表（YEAR=2, MONTH=3, DAY=7，可配置 `recentTableCount`）
+6. **COUNT 缓存仅对时间分表有效**：哈希/键值/自定义分表不启用缓存
+7. **时间字段智能处理**：有主键时精确值自动清理；无主键时日期粒度字符串自动转换为 $gte/$lte 范围；操作符表达式始终保留
+8. **软删除恢复**：启用 setEnableSoftDelete 后可使用 restore 方法恢复已删除记录
+9. **$gte/$lte 必须精确到秒**：使用操作符查询时间字段时值必须包含时分秒（如 `'2026-04-30 23:59:59'`），不允许只传日期部分（`'2026-04-30'`）；如需查整月/整天数据，推荐直接传粒度字符串（`'2026-04'`/`'2026-04-15'`）由系统自动转换
+10. **findOne/findUniqueOne 返回 fromTable**：结果中的 `fromTable` 字段标识数据来源的物理分表名（如 `t_order_202403`），未找到数据时为 undefined

package/.qoder/skills/midway-fatcms/07-examples.md

@@ -196,6 +196,10 @@ await quick.insertOnDuplicateUpdate(
   { data: { id: 1, name: '用户', age: 25 } },
   ['id']  // 唯一列，PostgreSQL/SQL Server 必填
 );
+
+// save - 自动判断 INSERT/UPDATE（只需 data）
+await quick.save({ data: { id: 1, name: '用户', age: 25 } });  // 有主键 → 先查后写
+await quick.save({ data: { name: '新用户', age: 20 } });       // 无主键 → 直接插入
 ```
 
 ## 软删除与恢复

package/dist/configuration.d.ts

@@ -3,5 +3,15 @@ export declare class ContainerLifeCycle {
     app: koa.Application;
     onConfigLoad(): Promise<any>;
     onReady(): Promise<void>;
+    /**
+     * 初始化表元数据缓存的 Redis Pub/Sub 广播
+     *
+     * - 发布客户端：复用已有的 RedisService 实例
+     * - 订阅客户端：通过 duplicate() 创建独立连接
+     *
+     * 集群部署时，任意节点调用 clearTableMetaCacheWithBroadcast()
+     * 会通过 Redis 广播通知所有节点清空本地缓存。
+     */
+    private initTableMetaCacheRedis;
     private startScheduleOnReady;
 }

package/dist/configuration.js

@@ -27,6 +27,8 @@ const global_middleware_1 = require("./middleware/global.middleware");
 const forbidden_middleware_1 = require("./middleware/forbidden.middleware");
 const schedule_1 = require("./schedule");
 const crypto_utils_1 = require("./libs/utils/crypto-utils");
+const TableMetaCacheRedisSubscriber_1 = require("./service/TableMetaCacheRedisSubscriber");
+const redis_1 = require("@midwayjs/redis");
 let ContainerLifeCycle = class ContainerLifeCycle {
     async onConfigLoad() {
         const config = this.app.getConfig();
@@ -53,6 +55,10 @@ let ContainerLifeCycle = class ContainerLifeCycle {
          * 让ANONYMOUS_CONTEXT获取app对象
          */
         schedule_1.ANONYMOUS_CONTEXT.setApp(this.app);
+        /**
+         * 初始化表元数据缓存 Redis 广播
+         */
+        await this.initTableMetaCacheRedis();
         /**
          * 启动定时任务
          */
@@ -63,6 +69,26 @@ let ContainerLifeCycle = class ContainerLifeCycle {
         // add filter
         // this.app.useFilter([NotFoundFilter, DefaultErrorFilter]);
     }
+    /**
+     * 初始化表元数据缓存的 Redis Pub/Sub 广播
+     *
+     * - 发布客户端：复用已有的 RedisService 实例
+     * - 订阅客户端：通过 duplicate() 创建独立连接
+     *
+     * 集群部署时，任意节点调用 clearTableMetaCacheWithBroadcast()
+     * 会通过 Redis 广播通知所有节点清空本地缓存。
+     */
+    async initTableMetaCacheRedis() {
+        try {
+            const redisService = await this.app.getApplicationContext().getAsync(redis_1.RedisService);
+            (0, TableMetaCacheRedisSubscriber_1.initTableMetaCachePublishClient)(redisService);
+            (0, TableMetaCacheRedisSubscriber_1.initTableMetaCacheSubscriber)(redisService);
+        }
+        catch (e) {
+            // Redis 未配置或不可用时，降级为单节点模式（仅清空本地缓存）
+            this.app.getLogger().warn('ContainerLifeCycle ==> initTableMetaCacheRedis Redis不可用，降级为单节点模式:', e.message);
+        }
+    }
     async startScheduleOnReady() {
         const logger = this.app.getLogger();
         const config = this.app.getConfig();

package/dist/controller/helpers.controller.d.ts

@@ -32,5 +32,11 @@ export declare class HelpersApi {
      * @param queryData
      */
     cryptoAes128CBC(queryData: any): Promise<CommonResult>;
+    /**
+     * 工具函数: 清空表元数据缓存（集群广播）
+     * 清空本节点缓存，并通过 Redis Pub/Sub 广播通知集群中其他节点。
+     * 清空后，下次请求会自动从数据库重新加载（懒加载刷新）。
+     */
+    clearTableMetaCacheApi(): Promise<CommonResult>;
     private checkLocalPermissionEnv;
 }

package/dist/controller/helpers.controller.js

@@ -21,6 +21,7 @@ const functions_1 = require("../libs/utils/functions");
 const crypto_utils_1 = require("../libs/utils/crypto-utils");
 const common_dto_1 = require("../libs/utils/common-dto");
 const SystemPerm_1 = require("../models/SystemPerm");
+const TableMetaCacheRedisSubscriber_1 = require("../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
 // http://127.0.0.1:7002/ns/api/helpers/getApiEnv
@@ -124,6 +125,18 @@ let HelpersApi = class HelpersApi {
             isEqual: input === decrypted,
         });
     }
+    /**
+     * 工具函数: 清空表元数据缓存（集群广播）
+     * 清空本节点缓存，并通过 Redis Pub/Sub 广播通知集群中其他节点。
+     * 清空后，下次请求会自动从数据库重新加载（懒加载刷新）。
+     */
+    async clearTableMetaCacheApi() {
+        const stats = (0, TableMetaCacheRedisSubscriber_1.clearTableMetaCacheWithBroadcast)();
+        return common_dto_1.CommonResult.successRes({
+            message: '表元数据缓存已清空（已广播集群）',
+            beforeClear: stats,
+        });
+    }
     checkLocalPermissionEnv() {
         //是否是开发者
         const isDevelopUser = () => {
@@ -181,6 +194,12 @@ __decorate([
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", Promise)
 ], HelpersApi.prototype, "cryptoAes128CBC", null);
+__decorate([
+    (0, core_1.Get)('/clearTableMetaCache'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], HelpersApi.prototype, "clearTableMetaCacheApi", null);
 HelpersApi = __decorate([
     (0, core_1.Controller)('/ns/api/helpers')
 ], HelpersApi);

package/dist/libs/crud-pro/CrudPro.d.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 { Transaction } from './models/Transaction';
 import { IExecuteContextFunc } from './models/ExecuteContextFunc';
@@ -51,6 +51,16 @@ declare class CrudPro {
     private executeCrudByCfgInternal;
     getCachedCfgByMethod(method: string, isEnableCache: boolean): Promise<IRequestCfgModel>;
     getAllTableInfos(query: ITableNamesQuery, options?: ITableNamesOptions): Promise<ITableListResult>;
+    /**
+     * 获取表的主键列名列表
+     *
+     * 复用 CrudProTableMetaService 的 getTableMeta 缓存，
+     * 从 columnDetails 中筛选 isPrimaryKey 的列。
+     *
+     * @param query 表元数据查询参数
+     * @returns 主键列名数组
+     */
+    getPrimaryKeyColumns(query: ITableMetaQuery): Promise<string[]>;
     /**
      * 如果是 INSERT/UPDATE 操作（sqlSimpleName 模式），根据真实表结构过滤 reqModel.data 中的字段
      * 避免传入不存在的字段导致 SQL 执行报错
@@ -59,6 +69,16 @@ declare class CrudPro {
      * @param cfgModel 配置模型
      */
     private filterDataByTableMetaIfNeeded;
+    /**
+     * 校验特定操作的必填参数
+     *
+     * - insertOrUpdate 和 update：condition 和 data 均为必填
+     * - insertOnDuplicateUpdate 和 insert：只有data 为必填
+     * @param reqModel 请求模型
+     * @param cfgModel 配置模型
+     * @throws CommonException 如果缺少必填参数
+     */
+    private validateParamsIfNeeded;
     /**
      * 判断 sqlSimpleName 是否为 INSERT/UPDATE 类型
      * @param sqlSimpleName 简单 SQL 名称
@@ -66,12 +86,19 @@ declare class CrudPro {
      */
     private isSimpleInsertOrUpdateType;
     /**
-     * 根据表结构字段类型，自动转换数据格式
+     * 根据表结构字段类型，自动转换 data 数据格式
      * 例如：PostgreSQL 的 ARRAY 类型字段，需要将 JSON 数组转为 PG 数组字面量格式
      * @param reqModel 请求模型
      * @param cfgModel 配置模型
      */
     private convertDataFieldTypeIfNeeded;
+    /**
+     * 查询时：根据表结构字段类型，自动转换 condition 数据格式
+     * 防止数据库隐式类型转换导致索引失效（如 WHERE int_col = '123' 导致索引无法命中）
+     * @param reqModel 请求模型
+     * @param cfgModel 配置模型
+     */
+    private convertConditionTypeIfNeeded;
     private executeSQLList;
     private parseRunSqlException;
     private afterExecuteSQLList;

package/dist/libs/crud-pro/CrudPro.js

@@ -138,10 +138,14 @@ class CrudPro {
         const cfgModel = new RequestCfgModel_1.RequestCfgModel(cfgJson);
         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);
@@ -175,6 +179,18 @@ class CrudPro {
     async getAllTableInfos(query, options) {
         return this.serviceHub.getAllTableInfos(query, options);
     }
+    /**
+     * 获取表的主键列名列表
+     *
+     * 复用 CrudProTableMetaService 的 getTableMeta 缓存，
+     * 从 columnDetails 中筛选 isPrimaryKey 的列。
+     *
+     * @param query 表元数据查询参数
+     * @returns 主键列名数组
+     */
+    async getPrimaryKeyColumns(query) {
+        return this.serviceHub.getPrimaryKeyColumns(query);
+    }
     /**
      * 如果是 INSERT/UPDATE 操作（sqlSimpleName 模式），根据真实表结构过滤 reqModel.data 中的字段
      * 避免传入不存在的字段导致 SQL 执行报错
@@ -219,6 +235,37 @@ class CrudPro {
         // 直接修改 reqModel.data，只保留表中存在的字段
         reqModel.data = filteredData;
     }
+    /**
+     * 校验特定操作的必填参数
+     *
+     * - insertOrUpdate 和 update：condition 和 data 均为必填
+     * - insertOnDuplicateUpdate 和 insert：只有data 为必填
+     * @param reqModel 请求模型
+     * @param cfgModel 配置模型
+     * @throws CommonException 如果缺少必填参数
+     */
+    validateParamsIfNeeded(reqModel, cfgModel) {
+        // insertOrUpdate 和 update：condition 和 data 均为必填
+        if (cfgModel.sqlSimpleName === keys_1.KeysOfSimpleSQL.SIMPLE_INSERT_OR_UPDATE ||
+            cfgModel.sqlSimpleName === keys_1.KeysOfSimpleSQL.SIMPLE_UPDATE) {
+            if (!reqModel.condition || Object.keys(reqModel.condition).length === 0) {
+                throw new exceptions_1.CommonException(exceptions_1.Exceptions.INSERT_OR_UPDATE_CONDITION_EMPTY, '[CrudPro] insertOrUpdate/update 操作的 condition 不能为空。' +
+                    'condition 用于判断记录是否存在或定位更新目标。');
+            }
+            if (!reqModel.data || Object.keys(reqModel.data).length === 0) {
+                throw new exceptions_1.CommonException(exceptions_1.Exceptions.INSERT_OR_UPDATE_DATA_EMPTY, '[CrudPro] insertOrUpdate/update 操作的 data 不能为空。' +
+                    'data 用于指定插入或更新的内容。');
+            }
+        }
+        // insertOnDuplicateUpdate 和 insert：只有 data 为必填
+        if (cfgModel.sqlSimpleName === keys_1.KeysOfSimpleSQL.SIMPLE_INSERT_ON_DUPLICATE_UPDATE ||
+            cfgModel.sqlSimpleName === keys_1.KeysOfSimpleSQL.SIMPLE_INSERT) {
+            if (!reqModel.data || Object.keys(reqModel.data).length === 0) {
+                throw new exceptions_1.CommonException(exceptions_1.Exceptions.INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY, '[CrudPro] insert/insertOnDuplicateUpdate 操作的 data 不能为空。' +
+                    'data 用于指定插入或更新的内容。');
+            }
+        }
+    }
     /**
      * 判断 sqlSimpleName 是否为 INSERT/UPDATE 类型
      * @param sqlSimpleName 简单 SQL 名称
@@ -234,7 +281,7 @@ class CrudPro {
         return insertOrUpdateTypes.includes(sqlSimpleName);
     }
     /**
-     * 根据表结构字段类型，自动转换数据格式
+     * 根据表结构字段类型，自动转换 data 数据格式
      * 例如：PostgreSQL 的 ARRAY 类型字段，需要将 JSON 数组转为 PG 数组字面量格式
      * @param reqModel 请求模型
      * @param cfgModel 配置模型
@@ -242,6 +289,15 @@ class CrudPro {
     async convertDataFieldTypeIfNeeded(reqModel, cfgModel) {
         await this.serviceHub.convertDataTypeByTableMeta(reqModel, cfgModel);
     }
+    /**
+     * 查询时：根据表结构字段类型，自动转换 condition 数据格式
+     * 防止数据库隐式类型转换导致索引失效（如 WHERE int_col = '123' 导致索引无法命中）
+     * @param reqModel 请求模型
+     * @param cfgModel 配置模型
+     */
+    async convertConditionTypeIfNeeded(reqModel, cfgModel) {
+        await this.serviceHub.convertConditionTypeByTableMeta(reqModel, cfgModel);
+    }
     async executeSQLList() {
         try {
             await this.serviceHub.executeSqlCfgModels();

package/dist/libs/crud-pro/exceptions.d.ts

@@ -56,6 +56,12 @@ export declare enum Exceptions {
     DATA_GET_DATA_EMPTY_ON_INSERT_KEYS = "DATA_GET_DATA_EMPTY_ON_INSERT_KEYS",
     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",
+    INSERT_OR_UPDATE_DATA_EMPTY = "INSERT_OR_UPDATE_DATA_EMPTY",
+    INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY = "INSERT_ON_DUPLICATE_UPDATE_DATA_EMPTY",
     /**
      * 请求的Method字段为空
      */
@@ -79,6 +85,7 @@ export declare 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/dist/libs/crud-pro/exceptions.js

@@ -60,6 +60,12 @@ var Exceptions;
     Exceptions["DATA_GET_DATA_EMPTY_ON_INSERT_KEYS"] = "DATA_GET_DATA_EMPTY_ON_INSERT_KEYS";
     Exceptions["DATA_GET_DATA_EMPTY_ON_INSERT_VALUES"] = "DATA_GET_DATA_EMPTY_ON_INSERT_VALUES";
     Exceptions["BATCH_INSERT_KEYS_MISMATCH"] = "BATCH_INSERT_KEYS_MISMATCH";
+    /**
+     * insertOrUpdate 参数缺失
+     */
+    Exceptions["INSERT_OR_UPDATE_CONDITION_EMPTY"] = "INSERT_OR_UPDATE_CONDITION_EMPTY";
+    Exceptions["INSERT_OR_UPDATE_DATA_EMPTY"] = "INSERT_OR_UPDATE_DATA_EMPTY";
+    Exceptions["INSERT_OR_DUPLICATE_UPDATE_DATA_EMPTY"] = "INSERT_ON_DUPLICATE_UPDATE_DATA_EMPTY";
     /**
      * 请求的Method字段为空
      */
@@ -83,6 +89,7 @@ var Exceptions;
     Exceptions["RUN_PICK_ERR_VISITOR_FIELD_NULL"] = "RUN_PICK_ERR_VISITOR_FIELD_NULL";
     Exceptions["RUN_EXECUTE_VALIDATE"] = "RUN_EXECUTE_VALIDATE";
     Exceptions["RUN_FUNCTION_NOT_FOUND"] = "RUN_FUNCTION_NOT_FOUND";
+    Exceptions["MORE_THAN_ONE_RECORDS_FOUND"] = "MORE_THAN_ONE_RECORDS_FOUND";
     /**
      * 参数校验错误
      */

package/dist/libs/crud-pro/interfaces.d.ts

@@ -13,6 +13,7 @@ export interface ITableColumn {
     type: string;
     isNullable: boolean;
     isPrimaryKey?: boolean;
+    isIdentity?: boolean;
     defaultValue?: any;
     maxLength?: number;
     comment?: string;

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

@@ -51,10 +51,13 @@ declare class CrudWriteResult extends CrudResultBase {
 declare 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;
+        fromTable: string;
     });
 }
 /** 列表查询结果 */
@@ -99,12 +102,10 @@ declare class CrudCountResult extends CrudResultBase {
 }
 /** InsertOrUpdate 结果 */
 declare 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;

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

@@ -75,6 +75,7 @@ class CrudQueryOneResult extends CrudResultBase {
         super(data.rawContext, data.debugInfo);
         this.row = data.row;
         this.found = (this.row !== null && this.row !== undefined);
+        this.fromTable = data.fromTable;
     }
 }
 exports.CrudQueryOneResult = CrudQueryOneResult;
@@ -117,7 +118,6 @@ exports.CrudCountResult = CrudCountResult;
 class CrudUpsertResult extends CrudResultBase {
     constructor(data) {
         super(data.rawContext, data.debugInfo);
-        this.affected = data.affected;
         this.insertAffected = data.insertAffected;
         this.updateAffected = data.updateAffected;
         this.isExist = data.isExist;

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

@@ -17,5 +17,7 @@ export interface ICurdProServiceHub {
     convertOriginToExecuteSql(sqlCfgModel: SqlCfgModel): Promise<void>;
     executeFuncCfg(tmpFunCfg: IFuncCfgModel, exeFunCtx: FuncContext): string;
     getTableMeta(query: ITableMetaQuery): Promise<ITableMeta>;
+    getPrimaryKeyColumns(query: ITableMetaQuery): Promise<string[]>;
     convertDataTypeByTableMeta(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void>;
+    convertConditionTypeByTableMeta(reqModel: RequestModel, cfgModel: RequestCfgModel): Promise<void>;
 }