@microi.net/cli 5.7.8 → 5.8.0

package/skills/v8-menu-buttons/references/progressive-03-10-/345/217/215/346/250/241/345/274/217-/351/201/277/345/205/215.md

@@ -1,104 +1,104 @@
-# v8-menu-buttons 详细参考 3
-
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=v8-menu-buttons-013 sha256=52939e7f29d0e3c7a2622c39bfc8484e27830ecb39a4205e57d5bdd437d60629 -->
-## 10. 反模式（避免）
-
-❌ 把所有业务逻辑塞进 `V8Code`，不创建接口引擎
-✅ 前端 `V8Code` 只负责弹窗/确认/刷新；业务逻辑写在接口引擎
-
-❌ 依赖非布尔返回值隐藏按钮
-✅ 需要隐藏时显式 `return false;` 或 `V8.Result = false;`；未返回布尔值默认显示
-
-❌ `MoreBtns` 不写 `ShowRow:true`，按钮看不见
-✅ 行内必须 `ShowRow:true`
-
-❌ 在 `diy-table.vue` / 卡片模板 / action-width mixin 中按模块、Url 或表名硬编码业务行按钮，或为单个业务面板新增 `V8.Open<业务名>`
-✅ 入口完整保存在 `sys_menu.MoreBtns`；主前端组件用 `V8.OpenDialog`，在线微服务用 `V8.OpenAppDialog`；验收同时回读按钮 JSON、打开模块引擎设计器，并检查运行态
-
-❌ 按钮 `Id` 重复或省略
-✅ 用 ULID/GUID 保证唯一
-
-❌ `BatchSelectMoreBtns` 用 `V8.Form` 取数据
-✅ 必须用 `V8.TableRowSelected`
-
-❌ 在 `V8.ConfirmTips` 中拼接复杂 HTML、表单、列表、Tab、代码编辑器或多步骤向导
-✅ 先用 `microi_list_applications` / `microi_get_application_context` 查找现有微服务；优先在已有微服务新增页面，否则通过 MCP 创建微服务，再用 `V8.OpenAppDialog` 打开
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-menu-buttons-014 sha256=2d11f4bb4b670c1051e4495ef1d95758420f520fea7d8c7d1c948f251a2ad4a3 -->
-## 10.2 复杂定制弹窗必须使用微服务
-
-`V8.ConfirmTips` 只适合纯文本确认或极少量一次性输入。出现以下任一情况即视为复杂页面：三个以上字段、响应式布局、联动校验、上传、表格、Tab、步骤条、代码编辑器、需要复用、后续会持续迭代。
-
-复杂页面标准流程：
-
-1. `microi_list_applications({ appType: 'MicroService' })` 获取现有微服务及文件清单。
-2. `microi_get_application_context({ appIdOrKey: '<AppKey>' })` 读取完整源码，判断应新增页面还是新建应用。
-3. 新建时使用 `microi_create_microservice` 注册元数据，`microi_sync_microservice_source` 上传私有源码，`microi_publish_microservice` 上传公有编译产物和页面路由。
-4. 菜单按钮只负责调用 `V8.OpenAppDialog`，把业务数据放入 `Data`，通过 `OnSuccess / OnError / OnClose` 与宿主交互。
-
-```js
-V8.OpenAppDialog({
-  AppKey: 'official-admin-app',
-  RoutePath: '/tenant/create',
-  Title: '创建租户',
-  Width: 'min(960px, calc(100vw - 32px))',
-  Data: { Source: 'SaaSMenu' },
-  OnSuccess: function (result) {
-    V8.Tips((result && result.message) || '处理成功', true);
-    V8.RefreshTable({ _PageIndex: -1 });
-  },
-  OnError: function (error) {
-    V8.Tips((error && error.message) || '页面处理失败', false);
-  }
-});
-```
-
----
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-menu-buttons-015 sha256=ab2bb9924c4468c8619237beaf94b86a98f9027649ab5c9e499652ae0068fbd4 -->
-## 11. ⚠️ `V8.CurrentUser` 拿不到的历史陷阱（必看）
-
-### 现象
-`diy-form-full.vue`（弹窗 / 详情 / 全屏表单）的 `FormBtns` / `PageBtns` / `PageTabs` / `BatchSelectMoreBtns` / `ExportMoreBtns` 中：
-- 编写 `V8.CurrentUser._IsAdmin` 总是 `undefined`
-- `V8CodeShow` 里靠用户角色判断的隐藏逻辑全部失效
-- 但 `diy-table.vue` 的 `MoreBtns` 同样代码却**正常**
-
-### 根因（2026-05 已修）
-`diy.common.js` 中有一个**进程级单例缓存** `DiyCommon._V8BaseInstance`：
-```js
-// 旧 BUG 写法
-DiyCommon._V8BaseInstance = {
-  CurrentUser : store.state.DiyStore.GetCurrentUser,   // ← Pinia getter 不在 $state 里，永远 undefined
-  CurrentToken: DiyCommon.getToken(),                  // ← 只算了一次，登录态变化后过期
-  SysConfig   : store.state.DiyStore.SysConfig,
-  ...
-}
-```
-- `store.state.DiyStore` 是 Pinia 的 `$state` 兼容层，**只有 state 字段**，**不包含 getter**。`GetCurrentUser` 是 getter → 取到 `undefined`。
-- `_V8BaseInstance` 是模块级单例，第一次构建后所有 `InitV8Code` 都会 `Object.assign(V8, _V8BaseInstance)`。
-- `diy-form-full.vue` 调用顺序是：`SetV8DefaultValue` → `InitV8Code` → `Object.assign` 把 V8.CurrentUser 改回 undefined。
-- `diy-table.vue` 调用顺序是：`InitV8Code` → `SetV8DefaultValue`，新鲜值后写胜出，所以没问题。
-
-### 正确做法
-1. **不要把会话级 / 用户级状态写进进程级单例缓存**（CurrentUser / Token / SysConfig）。
-2. 在 `InitV8Code` / `InitV8CodeSync` 的 `Object.assign` 之后，调用 `DiyCommon._RefreshV8DynamicContext(V8)`，始终从 `useDiyStore()` 实例（而不是 `$state`）取最新值：
-   ```js
-   var diyStore = getDiyStore();
-   V8.CurrentUser = diyStore.GetCurrentUser;   // Pinia getter，必须经 store 实例
-   V8.SysConfig   = diyStore.SysConfig;
-   V8.CurrentToken= DiyCommon.getToken();
-   ```
-3. 任何按钮组件（包括将来新增的 `PageBtns`、自定义 Tab 等）都**不需要**再单独 set `CurrentUser`，统一由 `_RefreshV8DynamicContext` 保证。
-
-### AI 编写按钮时的检查清单
-- [ ] `V8CodeShow` 中读 `V8.CurrentUser.RoleName` / `V8.CurrentUser._IsAdmin` 之前，**不**做 `if (!V8.CurrentUser)` 容错回写——容错会反过来掩盖框架问题。
-- [ ] 不要在 `V8Code` 里 `Object.assign(V8, {...})`，避免再次覆盖动态字段。
-- [ ] 后端接口引擎/表单事件禁止用 `setTimeout` 把业务工作延伸到请求结束之后；可靠异步任务必须使用后台任务、MQ、定时任务或持久化 outbox，并具备幂等与失败恢复。
-- [ ] 前端按钮若确需 `setTimeout`，仅限当前页面生命周期内的短时 UI 延迟/防抖。必须保存定时器句柄，在弹窗关闭、组件卸载或租户切换时清理；回调执行前还要确认页面仍有效且 `OsClient` 未变化。前端定时器不能承担写库、同步、通知或其它可靠业务任务。
-
-<!-- /microi-progressive:chunk -->
+# v8-menu-buttons 详细参考 3
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-menu-buttons-013 sha256=52939e7f29d0e3c7a2622c39bfc8484e27830ecb39a4205e57d5bdd437d60629 -->
+## 10. 反模式（避免）
+
+❌ 把所有业务逻辑塞进 `V8Code`，不创建接口引擎
+✅ 前端 `V8Code` 只负责弹窗/确认/刷新；业务逻辑写在接口引擎
+
+❌ 依赖非布尔返回值隐藏按钮
+✅ 需要隐藏时显式 `return false;` 或 `V8.Result = false;`；未返回布尔值默认显示
+
+❌ `MoreBtns` 不写 `ShowRow:true`，按钮看不见
+✅ 行内必须 `ShowRow:true`
+
+❌ 在 `diy-table.vue` / 卡片模板 / action-width mixin 中按模块、Url 或表名硬编码业务行按钮，或为单个业务面板新增 `V8.Open<业务名>`
+✅ 入口完整保存在 `sys_menu.MoreBtns`；主前端组件用 `V8.OpenDialog`，在线微服务用 `V8.OpenAppDialog`；验收同时回读按钮 JSON、打开模块引擎设计器，并检查运行态
+
+❌ 按钮 `Id` 重复或省略
+✅ 用 ULID/GUID 保证唯一
+
+❌ `BatchSelectMoreBtns` 用 `V8.Form` 取数据
+✅ 必须用 `V8.TableRowSelected`
+
+❌ 在 `V8.ConfirmTips` 中拼接复杂 HTML、表单、列表、Tab、代码编辑器或多步骤向导
+✅ 先用 `microi_list_applications` / `microi_get_application_context` 查找现有微服务；优先在已有微服务新增页面，否则通过 MCP 创建微服务，再用 `V8.OpenAppDialog` 打开
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-menu-buttons-014 sha256=2d11f4bb4b670c1051e4495ef1d95758420f520fea7d8c7d1c948f251a2ad4a3 -->
+## 10.2 复杂定制弹窗必须使用微服务
+
+`V8.ConfirmTips` 只适合纯文本确认或极少量一次性输入。出现以下任一情况即视为复杂页面：三个以上字段、响应式布局、联动校验、上传、表格、Tab、步骤条、代码编辑器、需要复用、后续会持续迭代。
+
+复杂页面标准流程：
+
+1. `microi_list_applications({ appType: 'MicroService' })` 获取现有微服务及文件清单。
+2. `microi_get_application_context({ appIdOrKey: '<AppKey>' })` 读取完整源码，判断应新增页面还是新建应用。
+3. 新建时使用 `microi_create_microservice` 注册元数据，`microi_sync_microservice_source` 上传私有源码，`microi_publish_microservice` 上传公有编译产物和页面路由。
+4. 菜单按钮只负责调用 `V8.OpenAppDialog`，把业务数据放入 `Data`，通过 `OnSuccess / OnError / OnClose` 与宿主交互。
+
+```js
+V8.OpenAppDialog({
+  AppKey: 'official-admin-app',
+  RoutePath: '/tenant/create',
+  Title: '创建租户',
+  Width: 'min(960px, calc(100vw - 32px))',
+  Data: { Source: 'SaaSMenu' },
+  OnSuccess: function (result) {
+    V8.Tips((result && result.message) || '处理成功', true);
+    V8.RefreshTable({ _PageIndex: -1 });
+  },
+  OnError: function (error) {
+    V8.Tips((error && error.message) || '页面处理失败', false);
+  }
+});
+```
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-menu-buttons-015 sha256=ab2bb9924c4468c8619237beaf94b86a98f9027649ab5c9e499652ae0068fbd4 -->
+## 11. ⚠️ `V8.CurrentUser` 拿不到的历史陷阱（必看）
+
+### 现象
+`diy-form-full.vue`（弹窗 / 详情 / 全屏表单）的 `FormBtns` / `PageBtns` / `PageTabs` / `BatchSelectMoreBtns` / `ExportMoreBtns` 中：
+- 编写 `V8.CurrentUser._IsAdmin` 总是 `undefined`
+- `V8CodeShow` 里靠用户角色判断的隐藏逻辑全部失效
+- 但 `diy-table.vue` 的 `MoreBtns` 同样代码却**正常**
+
+### 根因（2026-05 已修）
+`diy.common.js` 中有一个**进程级单例缓存** `DiyCommon._V8BaseInstance`：
+```js
+// 旧 BUG 写法
+DiyCommon._V8BaseInstance = {
+  CurrentUser : store.state.DiyStore.GetCurrentUser,   // ← Pinia getter 不在 $state 里，永远 undefined
+  CurrentToken: DiyCommon.getToken(),                  // ← 只算了一次，登录态变化后过期
+  SysConfig   : store.state.DiyStore.SysConfig,
+  ...
+}
+```
+- `store.state.DiyStore` 是 Pinia 的 `$state` 兼容层，**只有 state 字段**，**不包含 getter**。`GetCurrentUser` 是 getter → 取到 `undefined`。
+- `_V8BaseInstance` 是模块级单例，第一次构建后所有 `InitV8Code` 都会 `Object.assign(V8, _V8BaseInstance)`。
+- `diy-form-full.vue` 调用顺序是：`SetV8DefaultValue` → `InitV8Code` → `Object.assign` 把 V8.CurrentUser 改回 undefined。
+- `diy-table.vue` 调用顺序是：`InitV8Code` → `SetV8DefaultValue`，新鲜值后写胜出，所以没问题。
+
+### 正确做法
+1. **不要把会话级 / 用户级状态写进进程级单例缓存**（CurrentUser / Token / SysConfig）。
+2. 在 `InitV8Code` / `InitV8CodeSync` 的 `Object.assign` 之后，调用 `DiyCommon._RefreshV8DynamicContext(V8)`，始终从 `useDiyStore()` 实例（而不是 `$state`）取最新值：
+   ```js
+   var diyStore = getDiyStore();
+   V8.CurrentUser = diyStore.GetCurrentUser;   // Pinia getter，必须经 store 实例
+   V8.SysConfig   = diyStore.SysConfig;
+   V8.CurrentToken= DiyCommon.getToken();
+   ```
+3. 任何按钮组件（包括将来新增的 `PageBtns`、自定义 Tab 等）都**不需要**再单独 set `CurrentUser`，统一由 `_RefreshV8DynamicContext` 保证。
+
+### AI 编写按钮时的检查清单
+- [ ] `V8CodeShow` 中读 `V8.CurrentUser.RoleName` / `V8.CurrentUser._IsAdmin` 之前，**不**做 `if (!V8.CurrentUser)` 容错回写——容错会反过来掩盖框架问题。
+- [ ] 不要在 `V8Code` 里 `Object.assign(V8, {...})`，避免再次覆盖动态字段。
+- [ ] 后端接口引擎/表单事件禁止用 `setTimeout` 把业务工作延伸到请求结束之后；可靠异步任务必须使用后台任务、MQ、定时任务或持久化 outbox，并具备幂等与失败恢复。
+- [ ] 前端按钮若确需 `setTimeout`，仅限当前页面生命周期内的短时 UI 延迟/防抖。必须保存定时器句柄，在弹窗关闭、组件卸载或租户切换时清理；回调执行前还要确认页面仍有效且 `OsClient` 未变化。前端定时器不能承担写库、同步、通知或其它可靠业务任务。
+
+<!-- /microi-progressive:chunk -->

package/skills/v8-mongodb/SKILL.md

@@ -1,14 +1,14 @@
----
-name: v8-mongodb
-description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、UptFormData、UptFormDataByWhere、DelFormData、DelFormDataByWhere、GetFormData、GetTableData、对象过滤和文档 Id。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi V8 MongoDB 操作
-
-你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 MongoDB 存储非结构化数据（如日志、IoT 数据、大文档等）。
-
+---
+name: v8-mongodb
+description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、UptFormData、UptFormDataByWhere、DelFormData、DelFormDataByWhere、GetFormData、GetTableData、对象过滤和文档 Id。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi V8 MongoDB 操作
+
+你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 MongoDB 存储非结构化数据（如日志、IoT 数据、大文档等）。
+
 ## V8.MongoDb API
 
 ### 存量 MongoDB 兼容诊断
@@ -17,184 +17,184 @@ description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、Up
 - 平台兼容镜像以含安全修复的驱动 3.11.2 构建，恢复平台 CRUD/日志所需的 MongoDB 3.6 协议路径；不是降级至 2.30，也不声明上游继续维护 3.6。来源、单文件补丁和摘要维护在 `Microi.Server/ThirdParty/MongoDB.Driver/`。
 - 修改该兼容层必须通过真实 3.6 与当前 7.x 的认证、BSON、读写、索引、幂等重放、游标和租户隔离矩阵。不得只验证编译或 ping，也不得把驱动兼容当作修复旧数据库服务端自身漏洞。
 - C# 驱动改动需要更新后端镜像才生效。镜像更新后通过 `microi_query_system_observability` 回读日志、队列持久化和错误状态；查询失败应原样报错，禁止返回成功空表。
-
-| 方法 | 说明 |
-|------|------|
-| `V8.MongoDb.AddFormData({...})` | 新增文档 |
-| `V8.MongoDb.UptFormData({...})` | 修改文档（按 Id） |
-| `V8.MongoDb.UptFormDataByWhere({...})` | 按非空 `_Where` 批量修改，禁止修改 `_id` |
-| `V8.MongoDb.DelFormData({...})` | 删除文档（按 Id） |
-| `V8.MongoDb.DelFormDataByWhere({...})` | 按非空 `_Where` 批量删除 |
-| `V8.MongoDb.GetFormData({...})` | 查询单个文档（按 Id） |
-| `V8.MongoDb.GetTableData({...})` | 查询文档列表 |
-| `V8.MongoDb.NewId()` | 生成 MongoDB Id |
-
-## 新增文档
-
-```javascript
-var newId = V8.MongoDb.NewId();
-V8.MongoDb.AddFormData({
-  DbName: 'sys_log_2024',       // 数据库名
-  TableName: 'log_2024_12',     // 集合（表）名
-  Id: newId,                     // 可选，不指定自动生成
-  _FormData: {
-    UserId: V8.CurrentUser.Id,
-    Action: '登录',
-    IP: '192.168.1.1',
-    CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
-  }
-});
-```
-
-## 修改文档
-
-```javascript
-V8.MongoDb.UptFormData({
-  DbName: 'sys_log_2024',
-  TableName: 'log_2024_12',
-  Id: V8.Param.id,              // 必传
-  _FormData: {
-    Action: '更新操作',
-    UpdateTime: DateNow('yyyy-MM-dd HH:mm:ss')
-  }
-});
-```
-
-### 按条件批量修改
-
-```javascript
-var result = V8.MongoDb.UptFormDataByWhere({
-  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
-  TableName: 'chat_' + DateNow('yyyy'),
-  _Where: [
-    ['FromUserId', '=', V8.Param.PeerUserId],
-    ['ToUserId', '=', V8.CurrentUser.Id],
-    ['IsRead', '=', false]
-  ],
-  _FormData: { IsRead: true }
-});
-```
-
-`_Where` 缺失、为空或包含无效条件时必须返回失败，不得执行全集合更新。`_FormData` 禁止设置 `_id` 或 `_id.*`。返回值的 `Data` 包含 `MatchedCount` 和 `ModifiedCount`。
-
-## 删除文档
-
-```javascript
-V8.MongoDb.DelFormData({
-  DbName: 'sys_log_2024',
-  TableName: 'log_2024_12',
-  Id: V8.Param.id               // 必传
-});
-```
-
-### 按条件批量删除
-
-```javascript
-var result = V8.MongoDb.DelFormDataByWhere({
-  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
-  TableName: 'chat_last_contact',
-  _Where: [
-    ['UserId', '=', V8.CurrentUser.Id],
-    ['ContactUserId', '=', V8.Param.PeerUserId]
-  ]
-});
-```
-
-删除条件必须包含当前权威用户/资源边界，不能只用可伪造的前端参数。返回值的 `Data` 包含 `DeletedCount`。
-
-## 查询单个文档
-
-```javascript
-var result = V8.MongoDb.GetFormData({
-  DbName: 'sys_log_2024',
-  TableName: 'log_2024_12',
-  Id: V8.Param.id               // 必传
-});
-```
-
-## 查询文档列表
-
-```javascript
-var result = V8.MongoDb.GetTableData({
-  DbName: 'sys_log_2024',
-  TableName: 'log_2024_12',
-  _Where: [
-    ['Type', '=', '访问菜单'],
-    ['OR', 'Type', '=', '点击V8按钮']
-  ],
-  _OrderBy: 'CreateTime',
-  _OrderByType: 'DESC',
-  _PageIndex: 1,
-  _PageSize: 20
-});
-```
-
-`GetFormData` 和 `GetTableData` 属于 dynamic 无模式读取。服务端会在 MongoDB 投影阶段过滤 BSON 内部 `_t` CLR 类型判别字段，避免存量强类型 C# 写入留下的旧类型名称触发反序列化失败。`_t` 不是 V8 业务契约；业务需要类型标记时应使用自有字段（例如 `DocumentType`），不得读取、筛选或依赖 `_t`。强类型 C# MongoDB 模型仍按自身的多态映射处理。
-
-## 实战模式
-
-### IoT 设备日志存储
-
-```javascript
-// 接收 MQTT 消息后存入 MongoDB
-var eventName = V8.EventName;
-if (eventName === 'MessageReceived') {
-  V8.MongoDb.AddFormData({
-    DbName: 'iot_data',
-    TableName: 'device_log_' + DateNow('yyyy_MM'),
-    _FormData: {
-      DeviceId: V8.MQTT.ClientId,
-      Topic: V8.MQTT.Topic,
-      Payload: V8.MQTT.Payload,
-      Timestamp: DateNow('yyyy-MM-dd HH:mm:ss')
-    }
-  });
-}
-```
-
-### 操作审计日志
-
-```javascript
-// 在 SubmitAfterServerV8.js 中记录审计日志到 MongoDB
-V8.MongoDb.AddFormData({
-  DbName: 'audit_log',
-  TableName: 'form_audit_' + DateNow('yyyy'),
-  _FormData: {
-    TableName: V8.TableModel.Name,
-    Action: V8.FormSubmitAction,
-    DataId: V8.Form.Id,
-    UserId: V8.CurrentUser.Id,
-    UserName: V8.CurrentUser.Name,
-    OldData: V8.FormSubmitAction === 'Update' ? JSON.stringify(V8.OldForm) : null,
-    NewData: JSON.stringify(V8.Form),
-    CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
-  }
-});
-```
-
-### 按月分表查询
-
-```javascript
-// 查询指定月份的日志
-var month = V8.Param.month || DateNow('yyyy_MM');
-var result = V8.MongoDb.GetTableData({
-  DbName: 'sys_log_2024',
-  TableName: 'log_' + month,
-  _Where: [
-    ['UserId', '=', V8.CurrentUser.Id]
-  ]
-});
-
-return { Code: 1, Data: result };
-```
-
-## 注意事项
-
-- MongoDB 参数统一使用**对象格式**：`{ DbName, TableName, Id, _FormData, _Where, _OrderBy, _OrderByType }`
-- `DbName` 是 MongoDB 数据库名，`TableName` 是集合名
-- `_Where` 条件语法与 `V8.FormEngine` 一致
-- 批量写入仅接受安全字段名、已知操作符和非空条件；条件中的租户、用户和资源 Id 应来自 `V8.OsClient` / `V8.CurrentUser` / 权威回查，不得信任 `V8.Param` 中的同名身份字段
-- 非主库 V8 运行时会把 MongoDB 操作绑定到当前租户；显式传入其它 `OsClient` 不能跨租户
-- 适合存储日志、IoT 数据、大文档等非结构化 / 海量数据
-- 建议按时间分库分表（如 `log_2024_01`），便于清理历史数据
-- MongoDB 操作不参与 `V8.DbTrans` 事务。批量写入 `Code=1` 后即是已提交事实；后续 Hook/投递失败应返回警告或进入补偿，不得返回“未发生”导致盲目重试，重试必须有稳定业务 Id 幂等
+
+| 方法 | 说明 |
+|------|------|
+| `V8.MongoDb.AddFormData({...})` | 新增文档 |
+| `V8.MongoDb.UptFormData({...})` | 修改文档（按 Id） |
+| `V8.MongoDb.UptFormDataByWhere({...})` | 按非空 `_Where` 批量修改，禁止修改 `_id` |
+| `V8.MongoDb.DelFormData({...})` | 删除文档（按 Id） |
+| `V8.MongoDb.DelFormDataByWhere({...})` | 按非空 `_Where` 批量删除 |
+| `V8.MongoDb.GetFormData({...})` | 查询单个文档（按 Id） |
+| `V8.MongoDb.GetTableData({...})` | 查询文档列表 |
+| `V8.MongoDb.NewId()` | 生成 MongoDB Id |
+
+## 新增文档
+
+```javascript
+var newId = V8.MongoDb.NewId();
+V8.MongoDb.AddFormData({
+  DbName: 'sys_log_2024',       // 数据库名
+  TableName: 'log_2024_12',     // 集合（表）名
+  Id: newId,                     // 可选，不指定自动生成
+  _FormData: {
+    UserId: V8.CurrentUser.Id,
+    Action: '登录',
+    IP: '192.168.1.1',
+    CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  }
+});
+```
+
+## 修改文档
+
+```javascript
+V8.MongoDb.UptFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id,              // 必传
+  _FormData: {
+    Action: '更新操作',
+    UpdateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  }
+});
+```
+
+### 按条件批量修改
+
+```javascript
+var result = V8.MongoDb.UptFormDataByWhere({
+  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
+  TableName: 'chat_' + DateNow('yyyy'),
+  _Where: [
+    ['FromUserId', '=', V8.Param.PeerUserId],
+    ['ToUserId', '=', V8.CurrentUser.Id],
+    ['IsRead', '=', false]
+  ],
+  _FormData: { IsRead: true }
+});
+```
+
+`_Where` 缺失、为空或包含无效条件时必须返回失败，不得执行全集合更新。`_FormData` 禁止设置 `_id` 或 `_id.*`。返回值的 `Data` 包含 `MatchedCount` 和 `ModifiedCount`。
+
+## 删除文档
+
+```javascript
+V8.MongoDb.DelFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id               // 必传
+});
+```
+
+### 按条件批量删除
+
+```javascript
+var result = V8.MongoDb.DelFormDataByWhere({
+  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
+  TableName: 'chat_last_contact',
+  _Where: [
+    ['UserId', '=', V8.CurrentUser.Id],
+    ['ContactUserId', '=', V8.Param.PeerUserId]
+  ]
+});
+```
+
+删除条件必须包含当前权威用户/资源边界，不能只用可伪造的前端参数。返回值的 `Data` 包含 `DeletedCount`。
+
+## 查询单个文档
+
+```javascript
+var result = V8.MongoDb.GetFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id               // 必传
+});
+```
+
+## 查询文档列表
+
+```javascript
+var result = V8.MongoDb.GetTableData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  _Where: [
+    ['Type', '=', '访问菜单'],
+    ['OR', 'Type', '=', '点击V8按钮']
+  ],
+  _OrderBy: 'CreateTime',
+  _OrderByType: 'DESC',
+  _PageIndex: 1,
+  _PageSize: 20
+});
+```
+
+`GetFormData` 和 `GetTableData` 属于 dynamic 无模式读取。服务端会在 MongoDB 投影阶段过滤 BSON 内部 `_t` CLR 类型判别字段，避免存量强类型 C# 写入留下的旧类型名称触发反序列化失败。`_t` 不是 V8 业务契约；业务需要类型标记时应使用自有字段（例如 `DocumentType`），不得读取、筛选或依赖 `_t`。强类型 C# MongoDB 模型仍按自身的多态映射处理。
+
+## 实战模式
+
+### IoT 设备日志存储
+
+```javascript
+// 接收 MQTT 消息后存入 MongoDB
+var eventName = V8.EventName;
+if (eventName === 'MessageReceived') {
+  V8.MongoDb.AddFormData({
+    DbName: 'iot_data',
+    TableName: 'device_log_' + DateNow('yyyy_MM'),
+    _FormData: {
+      DeviceId: V8.MQTT.ClientId,
+      Topic: V8.MQTT.Topic,
+      Payload: V8.MQTT.Payload,
+      Timestamp: DateNow('yyyy-MM-dd HH:mm:ss')
+    }
+  });
+}
+```
+
+### 操作审计日志
+
+```javascript
+// 在 SubmitAfterServerV8.js 中记录审计日志到 MongoDB
+V8.MongoDb.AddFormData({
+  DbName: 'audit_log',
+  TableName: 'form_audit_' + DateNow('yyyy'),
+  _FormData: {
+    TableName: V8.TableModel.Name,
+    Action: V8.FormSubmitAction,
+    DataId: V8.Form.Id,
+    UserId: V8.CurrentUser.Id,
+    UserName: V8.CurrentUser.Name,
+    OldData: V8.FormSubmitAction === 'Update' ? JSON.stringify(V8.OldForm) : null,
+    NewData: JSON.stringify(V8.Form),
+    CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  }
+});
+```
+
+### 按月分表查询
+
+```javascript
+// 查询指定月份的日志
+var month = V8.Param.month || DateNow('yyyy_MM');
+var result = V8.MongoDb.GetTableData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_' + month,
+  _Where: [
+    ['UserId', '=', V8.CurrentUser.Id]
+  ]
+});
+
+return { Code: 1, Data: result };
+```
+
+## 注意事项
+
+- MongoDB 参数统一使用**对象格式**：`{ DbName, TableName, Id, _FormData, _Where, _OrderBy, _OrderByType }`
+- `DbName` 是 MongoDB 数据库名，`TableName` 是集合名
+- `_Where` 条件语法与 `V8.FormEngine` 一致
+- 批量写入仅接受安全字段名、已知操作符和非空条件；条件中的租户、用户和资源 Id 应来自 `V8.OsClient` / `V8.CurrentUser` / 权威回查，不得信任 `V8.Param` 中的同名身份字段
+- 非主库 V8 运行时会把 MongoDB 操作绑定到当前租户；显式传入其它 `OsClient` 不能跨租户
+- 适合存储日志、IoT 数据、大文档等非结构化 / 海量数据
+- 建议按时间分库分表（如 `log_2024_01`），便于清理历史数据
+- MongoDB 操作不参与 `V8.DbTrans` 事务。批量写入 `Code=1` 后即是已提交事实；后续 Hook/投递失败应返回警告或进入补偿，不得返回“未发生”导致盲目重试，重试必须有稳定业务 Id 幂等