monsqlize 1.0.0 → 1.0.2

package/lib/mongodb/writes/insert-batch.js

@@ -3,9 +3,10 @@
  * 分批批量插入大量文档到集合
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 insertBatch 操作
@@ -46,26 +47,34 @@ function createInsertBatchOps(context) {
         if (!Array.isArray(documents)) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 必须是数组类型",
-                [{ field: "documents", type: "array.required", message: "documents 是必需参数且必须是数组" }]
+                'documents 必须是数组类型',
+                [{ field: 'documents', type: 'array.required', message: 'documents 是必需参数且必须是数组' }]
             );
         }
 
         if (documents.length === 0) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 数组不能为空",
-                [{ field: "documents", type: "array.min", message: "documents 至少需要包含一个文档" }]
+                'documents 数组不能为空',
+                [{ field: 'documents', type: 'array.min', message: 'documents 至少需要包含一个文档' }]
             );
         }
 
-        // 2. 提取并验证选项
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedDocuments = documents.map(doc => convertObjectIdStrings(doc, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        }));
+
+        // 2. 提取选项
         const {
             batchSize = 1000,
             concurrency = 1,
             ordered = false,
             onProgress,
-            onError = "stop",
+            onError = 'stop',
             retryAttempts = 3,
             retryDelay = 1000,
             onRetry,
@@ -73,51 +82,51 @@ function createInsertBatchOps(context) {
         } = options;
 
         // 验证参数
-        if (typeof batchSize !== "number" || batchSize < 1) {
+        if (typeof batchSize !== 'number' || batchSize < 1) {
             throw createError(
                 ErrorCodes.INVALID_PARAMETER,
-                "batchSize 必须是大于 0 的数字",
-                [{ field: "batchSize", type: "number.min", message: "batchSize 必须大于 0" }]
+                'batchSize 必须是大于 0 的数字',
+                [{ field: 'batchSize', type: 'number.min', message: 'batchSize 必须大于 0' }]
             );
         }
 
-        if (typeof concurrency !== "number" || concurrency < 1) {
+        if (typeof concurrency !== 'number' || concurrency < 1) {
             throw createError(
                 ErrorCodes.INVALID_PARAMETER,
-                "concurrency 必须是大于 0 的数字",
-                [{ field: "concurrency", type: "number.min", message: "concurrency 必须大于 0" }]
+                'concurrency 必须是大于 0 的数字',
+                [{ field: 'concurrency', type: 'number.min', message: 'concurrency 必须大于 0' }]
             );
         }
 
-        const validErrorStrategies = ["stop", "skip", "collect", "retry"];
+        const validErrorStrategies = ['stop', 'skip', 'collect', 'retry'];
         if (!validErrorStrategies.includes(onError)) {
             throw createError(
                 ErrorCodes.INVALID_PARAMETER,
-                `onError 必须是以下值之一: ${validErrorStrategies.join(", ")}`,
-                [{ field: "onError", type: "enum", message: `有效值: ${validErrorStrategies.join(", ")}` }]
+                `onError 必须是以下值之一: ${validErrorStrategies.join(', ')}`,
+                [{ field: 'onError', type: 'enum', message: `有效值: ${validErrorStrategies.join(', ')}` }]
             );
         }
 
-        if (typeof retryAttempts !== "number" || retryAttempts < 0) {
+        if (typeof retryAttempts !== 'number' || retryAttempts < 0) {
             throw createError(
                 ErrorCodes.INVALID_PARAMETER,
-                "retryAttempts 必须是非负数",
-                [{ field: "retryAttempts", type: "number.min", message: "retryAttempts 必须 >= 0" }]
+                'retryAttempts 必须是非负数',
+                [{ field: 'retryAttempts', type: 'number.min', message: 'retryAttempts 必须 >= 0' }]
             );
         }
 
-        if (typeof retryDelay !== "number" || retryDelay < 0) {
+        if (typeof retryDelay !== 'number' || retryDelay < 0) {
             throw createError(
                 ErrorCodes.INVALID_PARAMETER,
-                "retryDelay 必须是非负数",
-                [{ field: "retryDelay", type: "number.min", message: "retryDelay 必须 >= 0" }]
+                'retryDelay 必须是非负数',
+                [{ field: 'retryDelay', type: 'number.min', message: 'retryDelay 必须 >= 0' }]
             );
         }
 
         // 3. 构建操作上下文
-        const operation = "insertBatch";
+        const operation = 'insertBatch';
         const ns = `${databaseName}.${collectionName}`;
-        const totalCount = documents.length;
+        const totalCount = convertedDocuments.length;
         const totalBatches = Math.ceil(totalCount / batchSize);
 
         // 结果统计
@@ -138,16 +147,16 @@ function createInsertBatchOps(context) {
             totalBatches,
             concurrency,
             onError,
-            retryAttempts: onError === "retry" ? retryAttempts : 0
+            retryAttempts: onError === 'retry' ? retryAttempts : 0
         });
 
         try {
             // 4. 分割文档为批次
             const batches = [];
-            for (let i = 0; i < documents.length; i += batchSize) {
+            for (let i = 0; i < convertedDocuments.length; i += batchSize) {
                 batches.push({
                     index: batches.length,
-                    documents: documents.slice(i, Math.min(i + batchSize, documents.length)),
+                    documents: convertedDocuments.slice(i, Math.min(i + batchSize, convertedDocuments.length)),
                     startIndex: i
                 });
             }
@@ -178,7 +187,7 @@ function createInsertBatchOps(context) {
                 try {
                     const nsObj = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -222,7 +231,7 @@ function createInsertBatchOps(context) {
             }
 
             // 8. 如果有错误且策略是 stop，抛出错误
-            if (result.errors.length > 0 && onError === "stop") {
+            if (result.errors.length > 0 && onError === 'stop') {
                 throw createError(
                     ErrorCodes.WRITE_ERROR,
                     `insertBatch 操作失败: 在批次 ${result.errors[0].batchIndex + 1}/${totalBatches} 遇到错误`,
@@ -268,7 +277,7 @@ function createInsertBatchOps(context) {
 
         let lastError = null;
         let attempts = 0;
-        const maxAttempts = onError === "retry" ? retryAttempts + 1 : 1;
+        const maxAttempts = onError === 'retry' ? retryAttempts + 1 : 1;
 
         while (attempts < maxAttempts) {
             try {
@@ -302,7 +311,7 @@ function createInsertBatchOps(context) {
                             batchIndex: batch.index,
                             attempt: attempts,
                             maxAttempts: retryAttempts,
-                            error: error,
+                            error,
                             nextRetryDelay: retryDelay
                         });
                     }
@@ -382,11 +391,11 @@ function createInsertBatchOps(context) {
                 }
 
                 // 根据错误策略处理
-                if (retryContext.onError === "stop") {
+                if (retryContext.onError === 'stop') {
                     throw batchResult.error;
-                } else if (retryContext.onError === "skip" || retryContext.onError === "retry") {
+                } else if (retryContext.onError === 'skip' || retryContext.onError === 'retry') {
                     retryContext.logger.warn(`[insertBatch] 跳过失败批次 ${batch.index + 1}/${batches.length}`, errorInfo);
-                } else if (retryContext.onError === "collect") {
+                } else if (retryContext.onError === 'collect') {
                     retryContext.logger.warn(`[insertBatch] 收集错误，继续执行 ${batch.index + 1}/${batches.length}`, errorInfo);
                 }
             }
@@ -469,7 +478,7 @@ function createInsertBatchOps(context) {
                     });
                 }
 
-                if (retryContext.onError === "stop") {
+                if (retryContext.onError === 'stop') {
                     throw batchResult.error;
                 }
             }

package/lib/mongodb/writes/insert-many.js

@@ -5,7 +5,8 @@
 
 const { createError, ErrorCodes } = require('../../errors');
 const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 insertMany 操作
@@ -36,7 +37,7 @@ function createInsertManyOps(context) {
      * @param {string} [options.comment] - 操作注释（用于日志追踪）
      * @returns {Promise<Object>} 插入结果 { acknowledged, insertedCount, insertedIds }
      * @throws {Error} 当 documents 参数无效时
-     * 
+     *
      * @example
      * const result = await collection('users').insertMany([
      *     { name: 'Alice', age: 25 },
@@ -62,36 +63,44 @@ function createInsertManyOps(context) {
         if (!Array.isArray(documents)) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 必须是数组类型",
-                [{ field: "documents", type: "array.required", message: "documents 是必需参数且必须是数组" }]
+                'documents 必须是数组类型',
+                [{ field: 'documents', type: 'array.required', message: 'documents 是必需参数且必须是数组' }]
             );
         }
 
         if (documents.length === 0) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 数组不能为空",
-                [{ field: "documents", type: "array.min", message: "documents 至少需要包含一个文档" }]
+                'documents 数组不能为空',
+                [{ field: 'documents', type: 'array.min', message: 'documents 至少需要包含一个文档' }]
             );
         }
 
         // 验证每个文档都是对象
         const invalidDocs = documents.filter((doc, index) => {
-            return !doc || typeof doc !== "object" || Array.isArray(doc);
+            return !doc || typeof doc !== 'object' || Array.isArray(doc);
         });
 
         if (invalidDocs.length > 0) {
             throw createError(
                 ErrorCodes.DOCUMENTS_REQUIRED,
-                "documents 中的所有元素必须是对象类型",
+                'documents 中的所有元素必须是对象类型',
                 invalidDocs.map((doc, idx) => ({
                     field: `documents[${idx}]`,
-                    type: "object.required",
-                    message: "必须是对象类型"
+                    type: 'object.required',
+                    message: '必须是对象类型'
                 }))
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedDocuments = documents.map(doc => convertObjectIdStrings(doc, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        }));
+
         // 2. 构建操作上下文
         const operation = 'insertMany';
         const ns = `${databaseName}.${collectionName}`;
@@ -99,7 +108,7 @@ function createInsertManyOps(context) {
 
         try {
             // 3. 执行批量插入操作
-            const result = await nativeCollection.insertMany(documents, options);
+            const result = await nativeCollection.insertMany(convertedDocuments, options);
 
             // 4. 自动失效缓存
             if (cache) {
@@ -107,7 +116,7 @@ function createInsertManyOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const nsObj = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -186,7 +195,7 @@ function createInsertManyOps(context) {
                 // MongoDB 重复键错误
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "批量插入失败：违反唯一性约束",
+                    '批量插入失败：违反唯一性约束',
                     [{ message: error.message, writeErrors: error.writeErrors }],
                     error
                 );

package/lib/mongodb/writes/insert-one.js

@@ -5,7 +5,8 @@
 
 const { createError, ErrorCodes } = require('../../errors');
 const CacheFactory = require('../../cache');
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 insertOne 操作
@@ -35,7 +36,7 @@ function createInsertOneOps(context) {
      * @param {string} [options.comment] - 操作注释（用于日志追踪）
      * @returns {Promise<Object>} 插入结果 { acknowledged, insertedId }
      * @throws {Error} 当 document 参数无效时
-     * 
+     *
      * @example
      * const result = await collection('users').insertOne(
      *     { name: 'Alice', age: 25 }
@@ -53,21 +54,29 @@ function createInsertOneOps(context) {
         const startTime = Date.now();
 
         // 1. 参数验证
-        if (!document || typeof document !== "object" || Array.isArray(document)) {
+        if (!document || typeof document !== 'object' || Array.isArray(document)) {
             throw createError(
                 ErrorCodes.DOCUMENT_REQUIRED,
-                "document 必须是对象类型",
-                [{ field: "document", type: "object.required", message: "document 是必需参数且必须是对象" }]
+                'document 必须是对象类型',
+                [{ field: 'document', type: 'object.required', message: 'document 是必需参数且必须是对象' }]
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedDocument = convertObjectIdStrings(document, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
         const operation = 'insertOne';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行插入操作
-            const result = await nativeCollection.insertOne(document, options);
+            const result = await nativeCollection.insertOne(convertedDocument, options);
 
             // 4. 自动失效缓存
             if (cache) {
@@ -75,7 +84,7 @@ function createInsertOneOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -151,8 +160,8 @@ function createInsertOneOps(context) {
                 // MongoDB 重复键错误
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "文档插入失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '文档插入失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

package/lib/mongodb/writes/replace-one.js

@@ -3,9 +3,10 @@
  * 完整替换单个匹配的文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings } = require('../../utils/objectid-converter');
 
 /**
  * 创建 replaceOne 操作
@@ -59,39 +60,54 @@ function createReplaceOneOps(context) {
         const startTime = Date.now();
 
         // 1. 参数验证
-        if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "filter 必须是对象类型",
-                [{ field: "filter", type: "object.required", message: "filter 是必需参数且必须是对象" }]
+                'filter 必须是对象类型',
+                [{ field: 'filter', type: 'object.required', message: 'filter 是必需参数且必须是对象' }]
             );
         }
 
-        if (!replacement || typeof replacement !== "object" || Array.isArray(replacement)) {
+        if (!replacement || typeof replacement !== 'object' || Array.isArray(replacement)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "replacement 必须是对象类型",
-                [{ field: "replacement", type: "object.required", message: "replacement 是必需参数且必须是对象" }]
+                'replacement 必须是对象类型',
+                [{ field: 'replacement', type: 'object.required', message: 'replacement 是必需参数且必须是对象' }]
             );
         }
 
         // 验证 replacement 不包含更新操作符（防止误用）
         const replacementKeys = Object.keys(replacement);
-        if (replacementKeys.some(key => key.startsWith("$"))) {
+        if (replacementKeys.some(key => key.startsWith('$'))) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "replacement 不能包含更新操作符（如 $set, $inc 等）",
-                [{ field: "replacement", type: "object.invalid", message: "replaceOne 用于完整替换文档，请使用 updateOne 进行部分更新" }]
+                'replacement 不能包含更新操作符（如 $set, $inc 等）',
+                [{ field: 'replacement', type: 'object.invalid', message: 'replaceOne 用于完整替换文档，请使用 updateOne 进行部分更新' }]
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
+        const convertedReplacement = convertObjectIdStrings(replacement, 'document', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
-        const operation = "replaceOne";
+        const operation = 'replaceOne';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
             // 3. 执行替换操作
-            const result = await nativeCollection.replaceOne(filter, replacement, options);
+            const result = await nativeCollection.replaceOne(convertedFilter, convertedReplacement, options);
 
             // 4. 自动失效缓存
             if (cache && result.modifiedCount > 0) {
@@ -99,7 +115,7 @@ function createReplaceOneOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -176,8 +192,8 @@ function createReplaceOneOps(context) {
                 // MongoDB 重复键错误（可能在 upsert 时发生）
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "替换失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '替换失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }

package/lib/mongodb/writes/result-handler.js

@@ -44,8 +44,8 @@ function detectDriverVersion() {
     _driverVersionChecked = true;
 
     try {
-        const mongodb = require("mongodb");
-        const versionString = mongodb.version || require("mongodb/package.json").version;
+        const mongodb = require('mongodb');
+        const versionString = mongodb.version || require('mongodb/package.json').version;
         const match = versionString.match(/^(\d+)\./);
         if (match) {
             _detectedDriverMajorVersion = parseInt(match[1], 10);
@@ -74,21 +74,21 @@ function warnUnsupportedDriverVersion(logger) {
     if (version < 6) {
         // 驱动版本小于 6.x，可能不兼容
         if (logger && logger.warn) {
-            logger.warn("[result-handler] ⚠️ 检测到 MongoDB 驱动版本过旧", {
+            logger.warn('[result-handler] ⚠️ 检测到 MongoDB 驱动版本过旧', {
                 detectedVersion: version,
-                supportedVersion: "6.x",
-                message: "monSQLize 专为 MongoDB 驱动 6.x 设计，旧版本可能存在兼容性问题",
-                recommendation: "建议升级到 MongoDB Node.js 驱动 ^6.0.0"
+                supportedVersion: '6.x',
+                message: 'monSQLize 专为 MongoDB 驱动 6.x 设计，旧版本可能存在兼容性问题',
+                recommendation: '建议升级到 MongoDB Node.js 驱动 ^6.0.0'
             });
         }
     } else if (version > 6) {
         // 驱动版本大于 6.x，未经测试
         if (logger && logger.warn) {
-            logger.warn("[result-handler] ⚠️ 检测到 MongoDB 驱动版本未经测试", {
+            logger.warn('[result-handler] ⚠️ 检测到 MongoDB 驱动版本未经测试', {
                 detectedVersion: version,
-                testedVersion: "6.x",
-                message: "monSQLize 已针对 MongoDB 驱动 6.x 测试，新版本可能存在未知问题",
-                recommendation: "如遇问题，请查看技术分析报告或回退到驱动 6.x"
+                testedVersion: '6.x',
+                message: 'monSQLize 已针对 MongoDB 驱动 6.x 测试，新版本可能存在未知问题',
+                recommendation: '如遇问题，请查看技术分析报告或回退到驱动 6.x'
             });
         }
     }
@@ -133,7 +133,7 @@ function handleFindOneAndResult(result, options = {}, logger = null) {
     // 情况 1：result 为 null 或 undefined（驱动在某些边界情况下可能返回 null）
     if (!result || result === null) {
         if (logger && logger.debug) {
-            logger.debug("[result-handler] Result is null/undefined, returning empty result", {
+            logger.debug('[result-handler] Result is null/undefined, returning empty result', {
                 includeMetadata: options.includeResultMetadata
             });
         }
@@ -152,14 +152,14 @@ function handleFindOneAndResult(result, options = {}, logger = null) {
     }
 
     // 情况 2：result 是对象但缺少 lastErrorObject（驱动版本差异或异常情况）
-    if (typeof result === "object" && !result.lastErrorObject) {
+    if (typeof result === 'object' && !result.lastErrorObject) {
         if (logger && logger.warn) {
-            logger.warn("[result-handler] ⚠️ Result missing lastErrorObject, possible driver version issue", {
+            logger.warn('[result-handler] ⚠️ Result missing lastErrorObject, possible driver version issue', {
                 hasValue: result.value !== undefined,
                 hasOk: result.ok !== undefined,
                 resultKeys: Object.keys(result),
                 driverVersion: detectDriverVersion(),
-                recommendation: "这可能表明 MongoDB 驱动返回了非预期的格式，请检查驱动版本"
+                recommendation: '这可能表明 MongoDB 驱动返回了非预期的格式，请检查驱动版本'
             });
         }
 

package/lib/mongodb/writes/update-many.js

@@ -3,9 +3,10 @@
  * 更新所有匹配的文档
  */
 
-const { createError, ErrorCodes } = require("../../errors");
-const CacheFactory = require("../../cache");
-const { isInTransaction, getTransactionFromSession } = require("../common/transaction-aware");
+const { createError, ErrorCodes } = require('../../errors');
+const CacheFactory = require('../../cache');
+const { isInTransaction, getTransactionFromSession } = require('../common/transaction-aware');
+const { convertObjectIdStrings, convertUpdateDocument } = require('../../utils/objectid-converter');
 
 /**
  * 创建 updateMany 操作
@@ -60,39 +61,54 @@ function createUpdateManyOps(context) {
         const startTime = Date.now();
 
         // 1. 参数验证
-        if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "filter 必须是对象类型",
-                [{ field: "filter", type: "object.required", message: "filter 是必需参数且必须是对象" }]
+                'filter 必须是对象类型',
+                [{ field: 'filter', type: 'object.required', message: 'filter 是必需参数且必须是对象' }]
             );
         }
 
-        if (!update || typeof update !== "object" || Array.isArray(update)) {
+        if (!update || typeof update !== 'object' || Array.isArray(update)) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "update 必须是对象类型",
-                [{ field: "update", type: "object.required", message: "update 是必需参数且必须是对象" }]
+                'update 必须是对象类型',
+                [{ field: 'update', type: 'object.required', message: 'update 是必需参数且必须是对象' }]
             );
         }
 
         // 验证 update 包含更新操作符（防止整体替换）
         const updateKeys = Object.keys(update);
-        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith("$"))) {
+        if (updateKeys.length > 0 && !updateKeys.some(key => key.startsWith('$'))) {
             throw createError(
                 ErrorCodes.INVALID_ARGUMENT,
-                "update 必须使用更新操作符（如 $set, $inc 等）",
-                [{ field: "update", type: "object.invalid", message: "请使用 $set, $inc, $push 等更新操作符" }]
+                'update 必须使用更新操作符（如 $set, $inc 等）',
+                [{ field: 'update', type: 'object.invalid', message: '请使用 $set, $inc, $push 等更新操作符' }]
             );
         }
 
+        // ✅ v1.3.0: 自动转换 ObjectId 字符串
+        const convertedFilter = convertObjectIdStrings(filter, 'filter', 0, new WeakSet(), {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
+        const convertedUpdate = convertUpdateDocument(update, {
+            logger: context.logger,
+            excludeFields: context.autoConvertConfig?.excludeFields,
+            customFieldPatterns: context.autoConvertConfig?.customFieldPatterns,
+            maxDepth: context.autoConvertConfig?.maxDepth
+        });
+
         // 2. 构建操作上下文
-        const operation = "updateMany";
+        const operation = 'updateMany';
         const ns = `${databaseName}.${collectionName}`;
 
         try {
-            // 3. 执行更新操作
-            const result = await nativeCollection.updateMany(filter, update, options);
+            // 3. 执行批量更新操作
+            const result = await nativeCollection.updateMany(convertedFilter, convertedUpdate, options);
 
             // 4. 自动失效缓存（只要有匹配，就失效缓存）
             if (cache && result.matchedCount > 0) {
@@ -100,7 +116,7 @@ function createUpdateManyOps(context) {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
                         iid: instanceId,
-                        type: "mongodb",
+                        type: 'mongodb',
                         db: databaseName,
                         collection: collectionName
                     };
@@ -182,8 +198,8 @@ function createUpdateManyOps(context) {
                 // MongoDB 重复键错误（可能在 upsert 时发生）
                 throw createError(
                     ErrorCodes.DUPLICATE_KEY,
-                    "批量更新失败：违反唯一性约束",
-                    [{ field: "_id", message: error.message }],
+                    '批量更新失败：违反唯一性约束',
+                    [{ field: '_id', message: error.message }],
                     error
                 );
             }