fix: preserve v1 smooth-upgrade compatibility

Author: rockyshi1993

.github/workflows/publish.yml

@@ -9,7 +9,7 @@ on:
       version:
         description: "Version to publish. Must match package.json."
         required: true
-        default: "2.0.0"
+        default: "2.0.1"
 
 concurrency:
   group: publish-${{ github.ref }}

CHANGELOG.md

@@ -1,14 +1,15 @@
 # CHANGELOG
 
-> Summary index — current release details are packaged in [changelogs/v2.0.0.md](./changelogs/v2.0.0.md); historical details live in the repository changelog archive.
-> **Last updated**: 2026-06-01
+> Summary index — current release details are packaged in [changelogs/v2.0.1.md](./changelogs/v2.0.1.md); historical details live in the repository changelog archive.
+> **Last updated**: 2026-06-03
 
 ---
 
 ## Version Overview
 
 | Version | Date | Summary | Details |
 |---------|------|---------|---------|
+| [v2.0.1](./changelogs/v2.0.1.md) | 2026-06-03 | Patch: model collection/pool compatibility, automatic-index task dedupe, runtime cache/pool v1 smooth-upgrade fixes, and current docs/types alignment | [View](./changelogs/v2.0.1.md) |
 | [v2.0.0](./changelogs/v2.0.0.md) | 2026-06-01 | 🎉 **v2.0.0 — TypeScript rewrite**: full TypeScript source, cache-hub integration, schema-dsl `^2.0.3` TS dependency, Apache-2.0 licensing, English README, MultiLevel cache support, v1 API compat preserved, optimized npm artifact boundary without default sourcemaps, JSDoc coverage complete, `getPoolStats/getPoolHealth` keyed by pool name, v1 compat fixes included, workspace smooth-upgrade bridge validated for downstream consumers | [View](./changelogs/v2.0.0.md) |
 | [v1.3.0](https://github.com/vextjs/monSQLize/blob/main/changelogs/v1.3.0.md) | 2026-04-27 | 🆕 **新功能**：链式池访问 API — `pool(name)` / `use(dbName)` / `scopedCollection()` / `scopedModel()` 四个公开方法，支持多连接池多数据库路由，connection 合并语义，TypeScript 类型签名完整覆盖 | [查看](https://github.com/vextjs/monSQLize/blob/main/changelogs/v1.3.0.md) |
 | [v1.2.3](https://github.com/vextjs/monSQLize/blob/main/changelogs/v1.2.3.md) | 2026-04-26 | 🐛 **Bug Fix**：`model()` 方法修复注册 key 直接作为 MongoDB 集合名的问题，优先读 `definition.collection > definition.name`，注册 key 仅作 fallback，向后兼容 | [查看](https://github.com/vextjs/monSQLize/blob/main/changelogs/v1.2.3.md) |
@@ -443,7 +444,8 @@ const result = await msq.collection('orders').insertOne(dataFromMongoose);
 changelogs/
 ├── README.md          # 变更文档说明
 ├── TEMPLATE.md        # 变更文档模板
-├── v2.0.0.md         # 当前发布详细变更
+├── v2.0.1.md         # 当前发布详细变更
+├── v2.0.0.md         # v2 TypeScript 重写发布详细变更
 └── v1.x.y.md         # 历史版本详细变更（仓库归档）
 ```
 
@@ -494,11 +496,11 @@ changelogs/
 
 ## 相关文档
 
-- [changelogs/v2.0.0.md](./changelogs/v2.0.0.md) - 当前发布详细变更文档
+- [changelogs/v2.0.1.md](./changelogs/v2.0.1.md) - 当前发布详细变更文档
 - [README.md](./README.md) - 项目说明
 - [docs/](https://github.com/vextjs/monSQLize/blob/main/docs/index.md) - API 文档
 
 ---
 
-**最后更新**: 2026-06-01
+**最后更新**: 2026-06-03
 

README.md

@@ -423,7 +423,7 @@ const user = await users.findOne({ email });
 const list = await users.find({ status: 'active' }).toArray();
 ```
 
-The current v2.0.0 release candidate has been validated against the workspace consumers `chat`, `payment`, `user`, `admin`, `search`, `vext`, and `permission-core` without requiring business-source changes in those projects.
+The current v2.0.1 release has been validated against the workspace consumers `chat`, `payment`, `user`, `admin`, `search`, `vext`, and `permission-core` without requiring business-source changes in those projects.
 
 ## Compatibility
 
@@ -490,7 +490,7 @@ npm run test:real-env:private
 
 ## Release Status
 
-The current release candidate is `v2.0.0`.
+The current published release is `v2.0.1`.
 
 Key release-readiness points:
 
@@ -503,6 +503,11 @@ Key release-readiness points:
 
 ## Roadmap
 
+### v2.0.1
+
+- v1 smooth-upgrade compatibility patch for Model actual collection names, scoped pools/databases, automatic-index dedupe, and cache/pool option aliases.
+- Documentation and public types aligned with the current runtime behavior.
+
 ### v2.0.0
 
 - TypeScript-native runtime and declarations.

changelogs/README.md

@@ -10,6 +10,7 @@
 changelogs/
 ├── README.md           # 本说明文档
 ├── TEMPLATE.md         # 变更文档模板
+├── v2.0.1.md          # v2.0.1 详细变更
 ├── v2.0.0.md          # v2.0.0 详细变更
 └── v1.x.y.md          # 历史版本详细变更（仓库归档）
 ```
@@ -43,18 +44,19 @@ changelogs/
 
 ### 按版本类型
 
-- **正式发布**: v2.0.0, v1.0.0
+- **正式发布**: v2.0.1, v2.0.0, v1.0.0
 - **功能版本**: v1.x
 - **修复版本**: v1.x.y
 
 ### 按功能领域
 
-- **TypeScript 重构与 v1 平滑升级**: v2.0.0
+- **TypeScript 重构与 v1 平滑升级**: v2.0.1, v2.0.0
 - **实时监听 / 管理功能 / 核心功能**: v1.x 历史版本
 
 ### 按风险级别
 
 - **P0 (Critical)**: v2.0.0
+- **Patch**: v2.0.1
 - **P1 (High)**: v1.x 破坏性或高风险历史版本
 - **P2 (Low)**: v1.x 修复版本
 
@@ -149,12 +151,13 @@ git push origin main --tags
 
 | 版本 | 文件 | 状态 | 发布日期 |
 |------|------|------|---------|
-| v2.0.0 | v2.0.0.md | ✅ 待发布候选 | 2026-06-01 |
+| v2.0.1 | v2.0.1.md | ✅ 已发布 | 2026-06-03 |
+| v2.0.0 | v2.0.0.md | ✅ 已发布 | 2026-06-01 |
 | v1.x | 仓库历史归档 | ✅ 已发布 | 2025-12-03 起 |
 
 ---
 
 **目录版本**: 2.0
-**最后更新**: 2026-06-01
+**最后更新**: 2026-06-03
 **维护者**: monSQLize Team
 

changelogs/v2.0.1.md

@@ -0,0 +1,39 @@
+# v2.0.1 — 2026-06-03
+
+## Overview
+
+v2.0.1 is a compatibility and documentation patch for the v2 TypeScript line. It preserves the v2.0.0 public package shape while tightening v1 smooth-upgrade behavior and aligning the published documentation with the current runtime.
+
+---
+
+## Fixes
+
+- **Model routing:** `definition.collection` is now used as the actual MongoDB collection name, with `definition.name` and the registered model name as fallbacks.
+- **Model pool scope:** Model connection metadata now routes through the configured pool and database when creating scoped collections.
+- **Model cache identity:** Model instance cache keys include pool, database, registered model name, and actual collection name to avoid cross-scope reuse.
+- **Populate compatibility:** `relations.from` resolves registered Model names to their actual MongoDB collection names, while still allowing direct collection names when no registered Model exists.
+- **Automatic indexes:** Model index creation is deduplicated per runtime / pool / database / collection / index fingerprint; pending and fulfilled tasks are reused, while failed tasks may retry.
+- **Cache compatibility:** Runtime cache option normalization preserves v1 aliases and millisecond TTL semantics.
+- **Pool compatibility:** Pool selector operation names accept v1-style string inputs.
+
+---
+
+## Documentation and Types
+
+- Added `ModelDefinition.collection` and `ModelDefinition.name` to the public type surface.
+- Documented the actual automatic-index flow: `connect()` only registers models; `ModelInstance` creation schedules per-index `createIndex()` calls; no `listIndexes()` preflight is performed.
+- Updated the current release status, API index count, examples count, and advanced capability index entries.
+- Kept historical changelog archive links unchanged; current published package links remain clean.
+
+---
+
+## Validation
+
+- `npm run build`
+- `npm run type-check`
+- `npm run lint`
+- `npm run test:runtime`
+- `npm run test:compatibility`
+- `npm run check:sizes:strict`
+- `npm run test:examples`
+- `npm pack --json --dry-run`

docs/api-index.md

@@ -190,9 +190,8 @@
 
 ---
 
-**文档总数**: 85个  
-**最后更新**: 2025-01-06
+**文档总数**: 96个
+**最后更新**: 2026-06-03
 **新增**: 
 - ✨ esm-support.md - ES Module (import) 支持
 - ✨ findOneAnd-return-value-unified.md - 返回值统一说明
-

docs/capability-index.md

@@ -69,7 +69,13 @@
 - slow-query-log：manager / queue / runtime façade
 - saga：orchestrator / runtime façade
 
-当前 `docs/**` 先只提供能力索引，不在本轮把这三类能力全部展开成独立专题。
+当前仓库已提供这些能力的专题入口与可执行示例：
+
+- sync：`docs/sync-backup.md`，示例 `examples/docs/sync.ts`、`examples/docs/sync-target-failure.ts`
+- slow-query-log：`docs/slow-query-log.md`，示例 `examples/docs/slow-query-log.ts`
+- saga：`docs/saga-transaction.md`、`docs/saga-advanced.md`，示例 `examples/docs/saga.ts`
+
+后续扩展重点是继续补充运行时故障注入、真实部署拓扑与性能边界，而不是补缺基础入口。
 
 ## 5. 当前仓库内的推荐入口
 

docs/examples.md

@@ -2,7 +2,7 @@
 
 文档站中的每个核心 API，都应尽量对应到**当前仓库内可直接运行的示例**。
 
-> 当前官方示例总览见 [`../examples/README.md`](../examples/README.md)，其中 `npm run test:examples` 会统一编译并执行当前 **44 个** TypeScript 示例。
+> 当前官方示例总览见 [`../examples/README.md`](../examples/README.md)，其中 `npm run test:examples` 会统一编译并执行当前 **43 个** TypeScript 示例；`examples/helpers/bootstrap.ts` 是辅助模块，不单独执行。
 
 ## 运行方式
 

docs/model.md

@@ -65,6 +65,8 @@ if (user.checkPassword('secret123')) {
 **参数**：
 - `collectionName` - 集合名称
 - `definition` - Model 定义
+  - `collection` - 实际 MongoDB 集合名；不填时依次回退到 `name` 与 `collectionName`
+  - `name` - Model 自动加载文件中的兼容集合名；`collection` 优先级更高
   - `schema` (必需) - Schema 定义
   - `enums` - 枚举配置
   - `methods` - 自定义方法
@@ -76,6 +78,8 @@ if (user.checkPassword('secret123')) {
 
 ```javascript
 Model.define('users', {
+    // 可选：把注册名与实际 MongoDB 集合名分开
+    // collection: 'app_users',
     enums: {
         role: 'admin|user|guest'
     },
@@ -253,7 +257,11 @@ Model.define('users', newDefinition);
 
 获取 Model 实例。
 
-> **缓存行为**（v1.2.1+）：同一 `collectionName` 多次调用 `msq.model()` 返回**同一 ModelInstance 实例**。索引仅在首次创建实例时触发一次 `createIndexes` 命令。
+> **缓存行为**（v1.2.1+）：同一 runtime / pool / database / 注册名 / 实际集合名 / 定义版本下，多次调用 `msq.model()` 返回同一 `ModelInstance` 实例。
+> - 首次创建实例时会调度 Model 自动索引；每个索引实际调用一次 `createIndex()`，同一进程内 pending / fulfilled 的索引任务会去重
+> - `connect()` 只加载与注册 Model 定义，不会单独创建 `ModelInstance`，也不会单独触发索引创建
+> - 进程重启后内存任务表清空，首次使用对应 Model 时会再次发送 `createIndex()` ensure 命令；相同索引定义由 MongoDB 驱动/服务端按幂等语义处理
+> - 自动索引不会先调用 `listIndexes()` 预检；索引定义冲突时由 MongoDB 抛错
 > - `Model.redefine()` 或 `Model.undefine()` 后，下次调用 `msq.model()` 自动获取新定义的实例
 > - `Model._clear()` 后（v1.2.2 修复），所有已注册 Model 的缓存均自动失效，下次调用 `msq.model()` 重建实例
 > - `msq.close()` 后全部缓存清空
@@ -288,6 +296,32 @@ if (!result.valid) {
 
 ---
 
+## 注册名与实际集合名
+
+`Model.define(collectionName, definition)` 的第一个参数是注册名，也是调用 `msq.model(collectionName)` 时使用的名称。运行时访问 MongoDB 时会按以下顺序解析实际集合名：
+
+1. `definition.collection`
+2. `definition.name`
+3. `Model.define()` 的 `collectionName`
+
+```javascript
+Model.define('UserModel', {
+    collection: 'users',
+    schema: (dsl) => dsl({
+        username: 'string!'
+    })
+});
+
+const User = msq.model('UserModel'); // 使用注册名获取 Model
+await User.insertOne({ username: 'alice' }); // 实际写入 MongoDB users 集合
+```
+
+`definition.name` 主要兼容自动加载文件格式；在手动注册时优先使用 `collection` 表达实际集合名。Model 实例缓存键同时包含 pool、database、注册名和实际集合名，避免不同路由或不同实际集合复用同一个实例。
+
+如果 `relations.from` 指向一个已注册 Model，populate 会使用该 Model 的实际集合名；如果没有同名 Model，则把 `from` 当作原始集合名使用。这样既兼容 v1 常见的“按 Model 名引用关系”，也保留直接写 MongoDB 集合名的方式。
+
+---
+
 ## 数据源绑定（v1.2.2+）
 
 通过 `Model.define()` 的 `connection` 字段，将 Model 绑定到指定连接池和/或数据库，实现多数据源路由。
@@ -831,6 +865,14 @@ indexes: [
 ]
 ```
 
+自动索引只在 `ModelInstance` 创建时调度，不会在每次查询或每次请求时重复创建。同一进程内，monSQLize 会按 runtime / pool / database / collection / index 指纹记录索引任务：任务处于 pending 或 fulfilled 状态时会跳过重复调度；失败任务允许下次重新调度。
+
+该流程不会先读取 `listIndexes()` 做数据库预检，而是直接调用 MongoDB `createIndex()`。因此：
+
+- 相同索引定义通常会被 MongoDB 幂等处理
+- 索引选项冲突、同名冲突等问题会由 MongoDB 返回错误
+- 如果业务需要在手动索引管理前做差异化判断，可先调用 `listIndexes()` 再决定是否调用 `createIndex()` / `createIndexes()`
+
 ---
 
 ### 5. enums - 枚举配置

examples/README.md

@@ -3,7 +3,7 @@
 Runnable TypeScript examples for every major monSQLize API.
 Each file uses an in-memory MongoDB server (`mongodb-memory-server`) — no real database needed.
 
-> 当前共 **44 个**可执行 TypeScript 示例，统一由 `npm run test:examples` 编译并执行。
+> 当前共 **43 个**可执行 TypeScript 示例，另有 `examples/helpers/bootstrap.ts` 作为示例辅助模块；可执行示例统一由 `npm run test:examples` 编译并执行。
 
 ## Prerequisites