monsqlize 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-02-09
+> **最后更新**: 2026-02-10
 
 ---
 
@@ -9,6 +9,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.1.5](./changelogs/v1.1.5.md) | 2026-02-10 | 🚨 **重要修复**：upsert 缓存失效 Bug (影响数据一致性) + 11 个新测试 + 代码优化 | [查看](./changelogs/v1.1.5.md) |
 | [v1.1.4](./changelogs/v1.1.4.md) | 2026-02-09 | 🎉 重大功能：通用函数缓存 - 52个测试 (100%通过) + 多层缓存 delPattern 修复 | [查看](./changelogs/v1.1.4.md) |
 | [v1.1.3](./changelogs/v1.1.3.md) | 2026-02-03 | 📚 文档完善：多连接池文档优化 + 健康检查详解 + 验证体系规范 | [查看](./changelogs/v1.1.3.md) |
 | [v1.1.2](#v112---日志优化) | 2026-01-27 | 🔧 优化：ObjectId 转换日志默认静默 + Saga 日志修复 | [查看](#v112---日志优化) |
@@ -27,11 +28,63 @@
 
 ---
 
+## 🚨 重要更新
+
+### v1.1.5 - 严重 Bug 修复：upsert 缓存失效 🔴
+
+**发布日期**: 2026-02-10  
+**版本类型**: Critical Bug Fix  
+**重要性**: ⭐⭐⭐⭐⭐ **强烈推荐立即升级**
+
+#### 🚨 修复的严重问题
+
+**问题描述**:
+- `updateOne({ upsert: true })`、`updateMany({ upsert: true })`、`replaceOne({ upsert: true })` 在**插入新文档时不会失效缓存**
+- 导致后续查询返回**过时数据**（缓存中是空数组，但数据库中已有新数据）
+- **影响**: 严重的数据一致性问题
+
+**影响场景**:
+- ❌ 用户注册后看不到新用户
+- ❌ 订单创建后看不到新订单
+- ❌ count/distinct 查询返回错误的数量
+- ❌ 统计数据不准确
+
+**修复的方法**:
+1. ✅ **updateOne** - 修复缓存失效条件 (第 146 行)
+2. ✅ **updateMany** - 修复缓存失效条件 (第 146 行)
+3. ✅ **replaceOne** - 修复缓存失效条件 (第 113 行，新发现)
+
+**测试验证**:
+- ✅ 新增 11 个测试用例，100% 通过
+- ✅ 三轮彻底验证，所有场景覆盖
+
+**升级建议**:
+```bash
+# 如果你使用了 upsert，请立即升级
+npm update monsqlize
+```
+
+📖 **详细分析**: 
+- [三轮验证报告](./reports/upsert-缓存失效-三轮验证报告.md)
+- [问题深度分析](./reports/upsert-缓存失效机制分析报告.md)
+- [完整修复总结](./reports/upsert-缓存失效-完整修复总结.md)
+
+#### 其他改进
+
+- ✅ function-cache 性能优化 (23-45% 提升)
+- ✅ 新增 17 个复杂数据类型测试
+- ✅ 代码质量提升 (A → A+)
+- ✅ 全局 Map 监控机制
+- ✅ 错误日志记录增强
+
+---
+
 ## 变更统计
 
 | 版本系列 | 版本数 | 主要改进方向 |
 |---------|-------|------------|
-| v1.0.x | 10 | 企业级功能、分布式支持、Model 层完善、Schema 验证、**统一表达式系统** 🆕 |
+| v1.1.x | 5 | **数据一致性修复** 🆕、通用函数缓存、文档完善、日志优化、100% MongoDB 操作符 |
+| v1.0.x | 10 | 企业级功能、分布式支持、Model 层完善、Schema 验证、统一表达式系统 |
 
 ---
 

package/index.mjs

@@ -0,0 +1,52 @@
+/**
+ * monSQLize ES Module Entry Point
+ *
+ * 使用方式:
+ * ```javascript
+ * import MonSQLize from 'monsqlize';
+ * // 或
+ * import { MonSQLize } from 'monsqlize';
+ *
+ * const db = new MonSQLize({
+ *   type: 'mongodb',
+ *   config: { uri: 'mongodb://localhost:27017/mydb' }
+ * });
+ *
+ * await db.connect();
+ * ```
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+// 使用 require 导入 CommonJS 模块
+const MonSQLizeClass = require('./lib/index.js');
+const Logger = require('./lib/logger.js');
+const MemoryCache = require('./lib/cache.js');
+const { createRedisCacheAdapter } = require('./lib/redis-cache-adapter.js');
+const TransactionManager = require('./lib/transaction/TransactionManager.js');
+const CacheLockManager = require('./lib/transaction/CacheLockManager.js');
+const DistributedCacheInvalidator = require('./lib/distributed-cache-invalidator.js');
+const { withCache, FunctionCache } = require('./lib/function-cache.js');
+
+// 默认导出
+export default MonSQLizeClass;
+
+// 🆕 v1.0.9: 导出表达式函数
+const { expr, createExpression } = MonSQLizeClass;
+
+// 命名导出
+export {
+  MonSQLizeClass as MonSQLize,
+  Logger,
+  MemoryCache,
+  createRedisCacheAdapter,
+  TransactionManager,
+  CacheLockManager,
+  DistributedCacheInvalidator,
+  expr,                    // 🆕 v1.0.9: 统一表达式函数
+  createExpression,        // 🆕 v1.0.9: 表达式函数别名
+  withCache,               // 🆕 v1.1.4: 函数缓存装饰器
+  FunctionCache            // 🆕 v1.1.4: 函数缓存类
+};
+

package/lib/function-cache.js

@@ -12,13 +12,46 @@
  */
 
 const CacheFactory = require('./cache');
+const crypto = require('crypto');
 
 // 并发去重映射（防止缓存击穿）
+// 使用 Map 存储正在执行的 Promise，带超时清理机制防止内存泄漏
 const __inflightFunctions = new Map();
 
 // 缓存未命中的特殊标记（使用 Symbol 确保唯一性）
 const CACHE_MISS = Symbol('CACHE_MISS');
 
+// 并发请求清理超时时间（毫秒）
+const INFLIGHT_CLEANUP_TIMEOUT_MS = 300000; // 5分钟
+
+// 🔧 v1.1.5: 全局 Map 大小限制和监控
+const MAX_INFLIGHT_SIZE = 10000;
+
+// 定期监控和清理机制
+const monitorInterval = setInterval(() => {
+    const currentSize = __inflightFunctions.size;
+
+    if (currentSize > MAX_INFLIGHT_SIZE) {
+        console.warn(`[FunctionCache] InflightMap size exceeded: ${currentSize}/${MAX_INFLIGHT_SIZE}`);
+
+        // 清理最旧的 10% 条目
+        const toDelete = Math.floor(currentSize * 0.1);
+        let count = 0;
+        for (const key of __inflightFunctions.keys()) {
+            if (count++ >= toDelete) break;
+            __inflightFunctions.delete(key);
+        }
+
+        console.warn(`[FunctionCache] Cleaned ${toDelete} entries, new size: ${__inflightFunctions.size}`);
+    }
+}, 60000); // 每分钟检查一次
+
+// 防止阻止进程退出
+monitorInterval.unref();
+
+// 缓存键最大长度（字节）
+const MAX_CACHE_KEY_LENGTH = 1024;
+
 /**
  * 基础装饰器：为函数添加缓存能力
  *
@@ -82,6 +115,7 @@ function withCache(fn, options = {}) {
     }
 
     // 统计信息
+    // 注意：在极高并发场景下，统计可能不完全准确（这是性能与精确度的权衡）
     const stats = {
         hits: 0,
         misses: 0,
@@ -95,9 +129,17 @@ function withCache(fn, options = {}) {
         // 1. 生成缓存键
         let cacheKey;
         try {
-            cacheKey = keyBuilder
+            const baseKey = keyBuilder
                 ? `${namespace}:${keyBuilder(...args)}`
                 : `${namespace}:${fn.name}:${CacheFactory.stableStringify(args)}`;
+
+            // 🔧 v1.1.5: 限制缓存键大小
+            if (baseKey.length > MAX_CACHE_KEY_LENGTH) {
+                const hash = crypto.createHash('sha256').update(baseKey).digest('hex');
+                cacheKey = `${namespace}:${fn.name}:hash:${hash}`;
+            } else {
+                cacheKey = baseKey;
+            }
         } catch (err) {
             // 键生成失败，直接执行原函数
             if (enableStats) stats.errors++;
@@ -108,16 +150,28 @@ function withCache(fn, options = {}) {
         const startTime = Date.now();
         let cached = CACHE_MISS;
         try {
+            // 优化：使用特殊标记来区分"缓存未命中"和"缓存值是 undefined"
             const value = await cacheInstance.get(cacheKey);
-            // 只有当缓存中有这个键时才认为命中（即使值是 undefined）
-            // 我们需要区分"缓存未命中"和"缓存值是 undefined"
-            // 但是 cache.get() 无法区分，所以我们使用 exists() 来判断
-            const exists = await cacheInstance.exists(cacheKey);
-            if (exists) {
+
+            // 如果缓存返回 undefined，需要确认是否真的不存在
+            if (value === undefined) {
+                // 只在返回 undefined 时才调用 exists 检查
+                const exists = await cacheInstance.exists(cacheKey);
+                if (exists) {
+                    cached = undefined; // 缓存的值就是 undefined
+                }
+                // 如果 exists 返回 false，cached 保持 CACHE_MISS
+            } else {
+                // 非 undefined 值，直接使用
                 cached = value;
             }
         } catch (err) {
             if (enableStats) stats.errors++;
+            // 🔧 v1.1.5: 添加错误日志
+            console.warn('[FunctionCache] Cache get failed:', {
+                key: cacheKey.substring(0, 100), // 截断避免日志过长
+                error: err.message
+            });
         }
 
         if (cached !== CACHE_MISS) {
@@ -165,6 +219,11 @@ function withCache(fn, options = {}) {
                         await cacheInstance.set(cacheKey, result, ttl);
                     } catch (err) {
                         if (enableStats) stats.errors++;
+                        // 🔧 v1.1.5: 添加错误日志
+                        console.warn('[FunctionCache] Cache set failed:', {
+                            key: cacheKey.substring(0, 100),
+                            error: err.message
+                        });
                     }
                 }
 
@@ -176,6 +235,17 @@ function withCache(fn, options = {}) {
 
         __inflightFunctions.set(cacheKey, promise);
 
+        // 🔧 v1.1.4-hotfix: 超时清理机制防止内存泄漏
+        // 如果 Promise 长时间未完成，自动清理
+        const cleanupTimeout = setTimeout(() => {
+            __inflightFunctions.delete(cacheKey);
+        }, INFLIGHT_CLEANUP_TIMEOUT_MS);
+
+        // Promise 完成后清除定时器
+        promise.finally(() => {
+            clearTimeout(cleanupTimeout);
+        });
+
         try {
             const result = await promise;
             if (enableStats) {
@@ -268,9 +338,10 @@ class FunctionCache {
      * @param {Function} fn - 函数实现
      * @param {Object} options - 缓存配置
      * @param {number} [options.ttl] - 缓存过期时间（毫秒）
-     * @param {Array<string>} [options.collections] - 依赖的 MongoDB 集合名称（自动失效）
+     * @param {Function} [options.keyBuilder] - 自定义键生成函数
+     * @param {Function} [options.condition] - 条件缓存函数
      */
-    register(name, fn, options = {}) {
+    async register(name, fn, options = {}) {
         if (!name || typeof name !== 'string') {
             throw new Error('Function name must be a non-empty string');
         }
@@ -299,56 +370,8 @@ class FunctionCache {
                 totalTime: 0
             });
         }
-
-        // 🆕 v1.1.4: 建立集合依赖关系（用于自动失效）
-        if (options.collections && Array.isArray(options.collections)) {
-            this._registerDependencies(name, options.collections);
-        }
     }
 
-    /**
-     * 🆕 v1.1.4: 注册函数与集合的依赖关系
-     * @private
-     * @param {string} functionName - 函数名称
-     * @param {Array<string>} collections - 集合名称列表
-     */
-    _registerDependencies(functionName, collections) {
-        for (const collection of collections) {
-            const depsKey = `fn_deps:${collection}`;
-
-            // 从缓存中读取已有的依赖列表
-            let existingDeps = [];
-            try {
-                const cached = this.cache.get ? this.cache.get(depsKey) : null;
-                if (cached && Array.isArray(cached)) {
-                    existingDeps = cached;
-                }
-            } catch (err) {
-                // 读取失败，使用空数组
-            }
-
-            // 添加新的函数名（避免重复）
-            if (!existingDeps.includes(functionName)) {
-                existingDeps.push(functionName);
-
-                // 存储依赖关系（永久存储，无 TTL）
-                try {
-                    if (this.cache.set) {
-                        this.cache.set(depsKey, existingDeps, 0);
-                    }
-                } catch (err) {
-                    // 存储失败不影响注册
-                    if (this.msq && this.msq.logger) {
-                        this.msq.logger.warn('[FunctionCache] 注册依赖关系失败', {
-                            collection,
-                            function: functionName,
-                            error: err.message
-                        });
-                    }
-                }
-            }
-        }
-    }
 
     /**
      * 执行函数

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

@@ -110,7 +110,8 @@ function createReplaceOneOps(context) {
             const result = await nativeCollection.replaceOne(convertedFilter, convertedReplacement, options);
 
             // 4. 自动失效缓存
-            if (cache && result.modifiedCount > 0) {
+            // ✅ v1.1.5: 修复 upsert 场景的缓存失效问题 - 检查 modifiedCount 或 upsertedId
+            if (cache && (result.modifiedCount > 0 || result.upsertedId)) {
                 try {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
@@ -126,24 +127,33 @@ function createReplaceOneOps(context) {
                         // 事务中：调用 Transaction 的 recordInvalidation 方法
                         const tx = getTransactionFromSession(options.session);
                         if (tx && typeof tx.recordInvalidation === 'function') {
-                            await tx.recordInvalidation(pattern);
-                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                            await tx.recordInvalidation(pattern, {
+                                operation: 'write',
+                                query: filter,
+                                collection: collectionName,
+                                upserted: !!result.upsertedId
+                            });
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}${result.upsertedId ? ' (upsert)' : ''}`);
                         } else {
                             const deleted = await cache.delPattern(pattern);
                             if (deleted > 0) {
-                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
                             }
                         }
                     } else {
                         // 非事务：直接失效缓存
                         const deleted = await cache.delPattern(pattern);
                         if (deleted > 0) {
-                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
                         }
                     }
                 } catch (cacheErr) {
                     // 缓存失效失败不影响写操作
-                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
+                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, {
+                        ns: `${databaseName}.${collectionName}`,
+                        error: cacheErr,
+                        upserted: !!result.upsertedId
+                    });
                 }
             }
 

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

@@ -141,8 +141,9 @@ function createUpdateManyOps(context) {
             // 3. 执行批量更新操作
             const result = await nativeCollection.updateMany(convertedFilter, convertedUpdate, options);
 
-            // 4. 自动失效缓存（只要有匹配，就失效缓存）
-            if (cache && result.matchedCount > 0) {
+            // 4. 自动失效缓存（只要有匹配或 upsert 插入，就失效缓存）
+            // ✅ v1.1.5: 修复 upsert 场景的缓存失效问题 - 检查 matchedCount 或 upsertedId
+            if (cache && (result.matchedCount > 0 || result.upsertedId)) {
                 try {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
@@ -162,25 +163,30 @@ function createUpdateManyOps(context) {
                             await tx.recordInvalidation(pattern, {
                                 operation: 'write',
                                 query: filter,
-                                collection: collectionName
+                                collection: collectionName,
+                                upserted: !!result.upsertedId
                             });
-                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}${result.upsertedId ? ' (upsert)' : ''}`);
                         } else {
                             const deleted = await cache.delPattern(pattern);
                             if (deleted > 0) {
-                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
                             }
                         }
                     } else {
                         // 非事务：直接失效缓存
                         const deleted = await cache.delPattern(pattern);
                         if (deleted > 0) {
-                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
                         }
                     }
                 } catch (cacheErr) {
                     // 缓存失效失败不影响写操作
-                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
+                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, {
+                        ns: `${databaseName}.${collectionName}`,
+                        error: cacheErr,
+                        upserted: !!result.upsertedId
+                    });
                 }
             }
 

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

@@ -142,7 +142,8 @@ function createUpdateOneOps(context) {
             const result = await nativeCollection.updateOne(convertedFilter, convertedUpdate, options);
 
             // 4. 自动失效缓存
-            if (cache && result.modifiedCount > 0) {
+            // ✅ v1.1.5: 修复 upsert 场景的缓存失效问题 - 检查 modifiedCount 或 upsertedId
+            if (cache && (result.modifiedCount > 0 || result.upsertedId)) {
                 try {
                     // 使用标准命名空间模式删除该集合的所有缓存
                     const ns = {
@@ -163,26 +164,31 @@ function createUpdateOneOps(context) {
                             await tx.recordInvalidation(pattern, {
                                 operation: 'write',
                                 query: filter,
-                                collection: collectionName
+                                collection: collectionName,
+                                upserted: !!result.upsertedId
                             });
-                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}`);
+                            logger.debug(`[${operation}] 事务中失效缓存: ${ns.db}.${ns.collection}${result.upsertedId ? ' (upsert)' : ''}`);
                         } else {
                             // 降级处理：直接失效缓存
                             const deleted = await cache.delPattern(pattern);
                             if (deleted > 0) {
-                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                                logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
                             }
                         }
                     } else {
                         // 非事务：直接失效缓存
                         const deleted = await cache.delPattern(pattern);
                         if (deleted > 0) {
-                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键`);
+                            logger.debug(`[${operation}] 自动失效缓存: ${ns.db}.${ns.collection}, 删除 ${deleted} 个缓存键${result.upsertedId ? ' (upsert)' : ''}`);
                         }
                     }
                 } catch (cacheErr) {
                     // 缓存失效失败不影响写操作
-                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, { ns: `${databaseName}.${collectionName}`, error: cacheErr });
+                    logger.warn(`[${operation}] 缓存失效失败: ${cacheErr.message}`, {
+                        ns: `${databaseName}.${collectionName}`,
+                        error: cacheErr,
+                        upserted: !!result.upsertedId
+                    });
                 }
             }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monsqlize",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "A lightweight MongoDB ORM with multi-level caching, transaction support, distributed features, Saga distributed transactions, unified expression system with 122 operators, and universal function caching (100% MongoDB support)",
   "main": "lib/index.js",
   "module": "index.mjs",
@@ -16,7 +16,9 @@
   "types": "./index.d.ts",
   "files": [
     "lib/",
+    "types/",
     "index.d.ts",
+    "index.mjs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/types/README.md

@@ -0,0 +1,122 @@
+# Types 模块说明
+
+本目录包含 monSQLize 的所有 TypeScript 类型定义，已按功能模块拆分。
+
+## 📁 目录结构
+
+```
+types/
+├── base.ts              # 基础类型（ErrorCodes, LoggerLike, ExpressionObject）
+├── expression.ts        # 统一表达式操作符（67个操作符）
+├── cache.ts             # 缓存接口（CacheLike, MultiLevelCache）
+├── options.ts           # 配置选项（BaseOptions, SSH, Transaction）
+├── query.ts             # 查询选项（Find, Count, Aggregate, Distinct）
+├── write.ts             # 写操作（InsertOne, InsertMany, WriteConcern）
+├── batch.ts             # 批量操作（InsertBatch, UpdateBatch, DeleteBatch）
+├── pagination.ts        # 分页系统（FindPage, PageResult, Bookmark）
+├── stream.ts            # 流式查询（Stream, Explain）
+├── transaction.ts       # 事务（Transaction, MongoSession）
+├── lock.ts              # 业务锁（Lock, LockOptions）
+├── chain.ts             # 链式调用（FindChain, AggregateChain）
+├── pool.ts              # 连接池（ConnectionPoolManager, PoolConfig）
+├── saga.ts              # Saga事务（SagaOrchestrator, SagaDefinition）
+├── sync.ts              # 数据同步（Change Stream, SyncConfig）
+├── collection.ts        # Collection API（CollectionAccessor, 所有查询方法）
+├── monsqlize.ts         # MonSQLize主类
+└── model/               # Model 层
+    ├── definition.ts    # Model定义（ModelDefinition, Schema）
+    ├── relations.ts     # 关系定义（Populate, RelationConfig）
+    ├── virtuals.ts      # 虚拟字段（VirtualConfig）
+    ├── instance.ts      # Model实例和静态方法
+    └── index.ts         # Model 类型汇总
+```
+
+## 🔍 模块依赖关系
+
+```
+base.ts (基础)
+  ↓
+options.ts, query.ts (配置)
+  ↓
+write.ts, batch.ts, pagination.ts, stream.ts, chain.ts (操作)
+  ↓
+transaction.ts, lock.ts, pool.ts, saga.ts, sync.ts (功能)
+  ↓
+collection.ts (集合)
+  ↓
+model/* (Model层)
+  ↓
+monsqlize.ts (主类)
+  ↓
+index.d.ts (统一导出)
+```
+
+## 📖 使用指南
+
+### 导入类型
+
+所有类型统一从 `monsqlize` 模块导入：
+
+```typescript
+import type { FindOptions, CollectionAccessor, Model } from 'monsqlize';
+```
+
+### 查找类型定义
+
+1. **按功能查找**：参考上面的目录结构
+2. **使用 IDE**：使用 VS Code 的"转到定义"功能（F12）
+3. **全局搜索**：在 `types/` 目录中搜索类型名称
+
+## 🛠️ 开发指南
+
+### 修改类型定义
+
+1. 找到对应的模块文件（如 `types/query.ts`）
+2. 修改类型定义
+3. 如果是新类型，需要在 `index.d.ts` 中添加导出
+4. 运行 `npx tsc --noEmit` 验证编译通过
+5. 运行 `npm test` 验证测试通过
+
+### 添加新类型
+
+1. 选择合适的模块文件（或创建新模块）
+2. 添加类型定义
+3. 在 `index.d.ts` 中添加导出语句
+   ```typescript
+   export import NewType = ModuleName.NewType;
+   ```
+4. 验证编译和测试
+5. 更新本 README
+
+### 模块划分原则
+
+1. **单一职责**：每个文件只包含相关的类型
+2. **依赖清晰**：避免循环依赖
+3. **大小适中**：单个文件不超过 500 行
+4. **命名规范**：使用 kebab-case（如 `multi-level-cache.ts`）
+
+## 📦 版本历史
+
+- **v1.0.10** (2026-01-19): 将 index.d.ts 拆分为 21 个模块（2932 行 → 21 文件）
+- **v1.0.9**: 原始单文件结构（index.d.ts 2932 行）
+
+## 🔗 相关文档
+
+- [CHANGELOG.md](../CHANGELOG.md)
+- [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [实施方案](../plans/refactoring/ref-types-modularization-v1.0.10-revised.md)
+
+## 📊 统计信息
+
+- **总文件数**: 21 个
+- **总代码行数**: ~2500 行（包含注释）
+- **模块数**: 17 个主模块 + 4 个 Model 子模块
+- **导出类型数**: 100+ 个
+
+## ✅ 质量保证
+
+- ✅ 所有模块通过 TypeScript 编译
+- ✅ 保持向后兼容（原有导入方式不变）
+- ✅ 完整的依赖关系管理
+- ✅ 清晰的模块职责划分
+