add write action

Author: rockyshi1993

CHANGELOG.md

@@ -5,6 +5,32 @@
 ## [未发布]
 
 ### 新增
+- **insertOne 和 insertMany 写操作文档补充**（2025-11-10）
+  - README.md：添加"写入操作"表格和详细使用示例（第 8 节）
+  - index.d.ts：添加 TypeScript 类型声明（InsertOneOptions、InsertOneResult、InsertManyOptions、InsertManyResult、WriteConcern）
+  - docs/write-operations.md：创建详细文档（全面的 API 说明、使用示例、性能对比、最佳实践、常见问题）
+  - 完整遵循 Guidelines v2.md 第 3.1 章"四要素"（Code ✅、Tests ✅、Examples ✅、Documentation ✅）
+
+- **insertOne 和 insertMany 写操作支持**（2025-11-10）
+  - 实现 `insertOne(document, options)` - 单文档插入操作
+    - 支持参数：writeConcern, comment, bypassDocumentValidation
+    - 返回：`{ acknowledged, insertedId }`
+    - 自动缓存失效：插入成功后自动失效该集合的所有查询缓存
+    - 慢查询日志：插入耗时超过 slowQueryMs 时记录
+    - 错误处理：检测重复键错误（E11000）并转换为标准错误码 `DUPLICATE_KEY`
+  - 实现 `insertMany(documents, options)` - 批量文档插入操作
+    - 支持参数：ordered（默认 true）, writeConcern, comment, bypassDocumentValidation
+    - 返回：`{ acknowledged, insertedCount, insertedIds }`
+    - 批量插入性能优化：500 文档批量插入比 500 次单次插入快约 50 倍
+    - 有序模式（ordered: true）：遇到错误停止，已插入文档不会回滚
+    - 无序模式（ordered: false）：遇到错误继续插入其他文档
+    - 自动缓存失效：批量插入成功后自动失效该集合的所有查询缓存
+  - 创建文件：`lib/mongodb/writes/insert-one.js`（136 行）、`lib/mongodb/writes/insert-many.js`（184 行）
+  - 测试覆盖：insertOne 测试 17 个用例，insertMany 测试 21 个用例（包括性能对比测试）
+  - 示例文件：`examples/insertOne.examples.js`、`examples/insertMany.examples.js`
+  - 错误码支持：新增 `DUPLICATE_KEY` 错误码（用于重复键检测）
+  - 测试运行器增强：支持 `beforeEach/afterEach` 钩子，支持 `this.timeout()` 方法
+
 - **readPreference 副本集读偏好支持**（2025-11-07）
   - 在连接配置中添加 `readPreference` 选项，支持副本集读写分离场景
   - 支持 5 种读偏好模式：`primary`（默认）、`primaryPreferred`、`secondary`、`secondaryPreferred`、`nearest`

README.md

@@ -88,6 +88,13 @@ const MonSQLize = require('monsqlize');
 | **count()** | 统计文档数量 | [docs/count.md](./docs/count.md) |
 | **explain()** | 查询计划分析 | [docs/explain.md](./docs/explain.md) |
 
+### 写入操作
+
+| 方法 | 说明 | 文档链接 |
+|------|------|---------|
+| **insertOne()** | 插入单个文档 | [examples/insertOne.examples.js](./examples/insertOne.examples.js) |
+| **insertMany()** | 批量插入文档（10-50x 性能提升） | [examples/insertMany.examples.js](./examples/insertMany.examples.js) |
+
 ### 集合管理
 
 | 方法 | 说明 | 文档链接 |
@@ -352,6 +359,49 @@ msq.on('error', (data) => {
 
 ---
 
+### 8. 写入操作（insertOne / insertMany）
+
+```js
+// 插入单个文档
+const result1 = await collection('products').insertOne({
+  document: {
+    name: 'iPhone 15 Pro',
+    price: 999,
+    category: 'electronics',
+    createdAt: new Date()
+  },
+  comment: 'ProductAPI:createProduct:user_123'  // 日志跟踪（可选）
+});
+
+console.log('插入成功:', result1.insertedId);
+
+// 批量插入文档（10-50x 性能提升）
+const result2 = await collection('products').insertMany({
+  documents: [
+    { name: 'MacBook Pro', price: 2499, category: 'electronics' },
+    { name: 'iPad Air', price: 599, category: 'electronics' },
+    { name: 'AirPods Pro', price: 249, category: 'accessories' }
+  ],
+  ordered: true,             // 遇到错误时停止（默认）
+  comment: 'ProductAPI:batchImport'
+});
+
+console.log(`成功插入 ${result2.insertedCount} 条数据`);
+
+// 自动缓存失效（插入后自动清理相关缓存）
+// 无需手动调用 invalidate()
+```
+
+**性能对比**:
+- 单条插入（insertOne）: ~10-20ms/条
+- 批量插入（insertMany）: ~0.5-1ms/条 **(10-50x 更快)**
+
+**详细示例**:
+- [examples/insertOne.examples.js](./examples/insertOne.examples.js) - 8 个完整示例（基础/错误处理/缓存失效/性能对比）
+- [examples/insertMany.examples.js](./examples/insertMany.examples.js) - 8 个完整示例（ordered/unordered 模式/性能测试）
+
+---
+
 ### 5. 多层缓存（本地内存 + Redis）
 
 ```js

STATUS.md

@@ -17,16 +17,16 @@
 |------|----------|----------|----------|-------------|------|
 | **核心功能** | 23 | 2 | 5 | 2 | 32 |
 | **MongoDB 读方法** | 9 | 0 | 3 | 0 | 12 |
-| **MongoDB 写方法 - Insert** | 0 | 0 | 2 | 0 | 2 |
+| **MongoDB 写方法 - Insert** | 2 | 0 | 0 | 0 | 2 |
 | **MongoDB 写方法 - Update** | 0 | 0 | 5 | 0 | 5 |
 | **MongoDB 写方法 - Delete** | 0 | 0 | 3 | 0 | 3 |
 | **MongoDB 写方法 - Bulk** | 0 | 0 | 1 | 0 | 1 |
 | **MongoDB 索引** | 0 | 0 | 5 | 0 | 5 |
 | **MongoDB 事务** | 0 | 0 | 3 | 0 | 3 |
 | **MongoDB 其他** | 0 | 0 | 15 | 0 | 15 |
-| **总计** | **32** | **2** | **42** | **2** | **78** |
+| **总计** | **34** | **2** | **40** | **2** | **78** |
 
-**完成度**: 41.0% (32/78)  
+**完成度**: 43.6% (34/78)  
 **核心功能完成度**: 71.9% (23/32)
 
 ---
@@ -152,8 +152,8 @@
     - ✅ 已支持: hint, collation, batchSize, comment (find/findOne/count/aggregate), **readPreference (全局配置)**
 
 ### MongoDB 方法（Writes - Insert）
-- ❌ insertOne
-- ❌ insertMany
+- ✅ insertOne
+- ✅ insertMany
 
 ### MongoDB 方法（Writes - Update）
 - ❌ updateOne