@microi.net/cli 6.1.3 → 6.1.4

package/skills/dos-orm/SKILL.md

@@ -1,105 +1,105 @@
----
-name: dos-orm
-description: Dos.ORM C# 数据访问指南。用于 Microi.Server 中编写或审查 DbSession、Entity、From、WhereClip、事务、异步查询、BulkInsert、Upsert、SqlFunc、子查询、导航属性、CodeFirst、读写分离和分库分表代码。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Dos.ORM
-
-Dos.ORM 是 Microi.Server 底层 C# ORM。它不是接口引擎里的 `V8.Db`：
-
-- C# 服务端源码使用 `DbSession`、实体和 Section API。
-- V8 JavaScript 使用 `V8.FormEngine` 或 `V8.Db.FromSql`。
-- 不能把 C# lambda/事务示例原样放进 V8。
-
-完整 API、跨库行为与示例见 `references/api-reference.md`。
-
-## 默认选择
-
-| 需求 | 首选 |
-|---|---|
-| 普通实体查询 | `dbSession.From<T>().Where(...).ToList/ToListAsync` |
-| 动态条件 | `Where<T>` / `WhereClip` |
-| 复杂 SQL | `FromSql(...).AddInParameter(...)` |
-| 单条/小批写入 | `Insert/Update/Delete` |
-| 大于约 1000 行批量插入 | `BulkInsert/BulkInsertAsync`，先压测批大小 |
-| 按唯一键写入 | `Upsert/UpsertAsync` + 真实唯一索引 |
-| 多步原子写 | `BeginTransaction()`，`using` + Commit/Rollback |
-
-## 方言与种子转换边界
-
-- SQL AST、标识符、函数、分页、Upsert 与数据库语义由 Dos.ORM 方言编译器维护；Microi 宿主和 seed CLI 仅作输入/输出适配，不用正则或字符串替换模拟跨数据库 SQL。
-- 官方 MySQL 种子采用流式词法/语法解析，生成完整中性结构与数据模型；每次动态清单以同一来源 SHA 的独立 MySQL 导入为基准，逐表比较结构、行数与数据摘要。历史快照数量不能硬编码为当前源验收，不能用登录夹具或仅结构代替完整种子。
-- 真实数据库认证逐个方言串行运行，保留完整性与失败回执；工具和安装器回归保留在源码中，生成 SQL、ZIP、报告归 `.tmp/` 或正式 CDN。
-
-## 安全规则
-
-### 连接生命周期与在线恢复
-
-- 创建事务、准备读取器、打开连接、提交/回滚及批处理任一路径抛异常，都必须释放本层拥有的连接；借用外部事务或批处理连接时不能擅自关闭。保留原始异常，不因 Dispose 失败遮盖原始错误。
-- `DbTrans` 提交成功后先归还连接，再执行提交后通知。通知失败不能把已提交事务报告为回滚，也不能自动重放业务 SQL。调用者仍必须使用 `using`，防止业务异常绕过 Commit/Rollback。
-- `DatabasePoolExhausted`、`DatabaseCapacityExceeded`、`DatabaseEndpointUnreachable` 是不同故障；不要把应用池等待、数据库全局连接限制和慢 SQL 混为一谈。
-- 平台未显式配置的 MySQL 业务池上限为 100，最小池保持驱动默认 0，连接串显式值优先；不得因为数据库拒绝连接自动放大池。每节点/租户、独立读写池、Quartz 与外部客户端的容量须合计并保留管理余量。`Connection Lifetime` 是归还时按创建时间淘汰，不能当空闲超时。
-- 可信 C# 宿主通过 `Database.GetConnectionPoolSnapshot()` 读取脱敏状态，`ResetConnectionPool()` 只轮换准确匹配的 MySQL/SQL Server 池，`ProbeConnectionPoolAsync` 用原池执行固定 `SELECT 1`。不使用 `ClearAllPools`，不杀借出的事务，不重放 SQL。
-- 快照的 `MinimumPoolSize/ConnectionLifetimeSeconds` 是配置；`Database.GetConnectionPoolBudgetSnapshot` 按所选池身份去重合计最大/最小池。`CurrentNodeSelectedPools` 不包含其它节点、Quartz、扩展库或外部程序，不是已占用连接；未知驱动合计为 null，无池连接单列且不受池上限限制。
-- `BeginIsolatedConnections()` 仅用于有并发限制的可信应急鉴权作用域，设置无池连接与 5 秒连接/命令超时；未知驱动拒绝。不能给普通业务或 V8 增加绕过限流的开关，不能在此作用域内执行清池或把无池探测冒充原池恢复。
-- AI 在线恢复使用 `microi_manage_system_observability(action=ResetDatabasePools)` 的预览、确认和回读协议，详细决策见 [系统日志/监控](../system-observability/SKILL.md)。需要升级含 `database-pools/v1` 的后端和 MCP；事故恢复本身不要求重启数据库/API。
-
-- 数据值全程参数化；`FromSql` 的动态值用 `AddInParameter`。
-- 表名、字段名、排序名不能来自未经白名单验证的用户输入。
-- 保留 `{0}Name{1}` 标识符延迟绑定机制，不能改成字符串替换。
-- `OrderByClip` 的校验不是授权；可排序字段仍需业务白名单。
-- Upsert 幂等依赖数据库唯一键，不能只靠“先查再写”。
-- 租户业务表查询/写入必须包含真实 `OsClient` 范围。
-- 已明确需要的索引在 Microi 业务表上通过 Manifest/MCP 管理，不从临时 SQL 创建。
-- MySQL 用户名或密码包含分号时必须用连接字符串引号包裹，例如
-  `Password="a;b"`；平台统一兼容层只修复“无等号片段紧跟已明确凭据参数”的
-  历史串，其它结构错误继续失败关闭，禁止猜测用户名、密码或默认 `root`。
-
-## 事务与异步
-
-```csharp
-using (var trans = dbSession.BeginTransaction())
-{
-    try
-    {
-        trans.Insert(entity);
-        trans.Update<User>(User._.Status, 1, User._.Id == entity.Id);
-        trans.Commit();
-    }
-    catch
-    {
-        trans.Rollback();
-        throw;
-    }
-}
-```
-
-Dispose 幂等，未 Commit 时自动回滚。事务内异步操作串行执行；不要在同一个连接/
-事务上 `Task.WhenAll`。取消、超时和异常必须传播，不能吞掉后继续 Commit。
-
-## 性能与跨库
-
-- 显式选择字段，分页和流式读取，避免无界 `ToList()`。
-- BulkInsert 会按可用客户端选择原生实现并回退多行 INSERT；不同数据库必须实测。
-- 官网性能数字仅是特定环境参考，不能作为目标环境承诺。
-- 查询缓存 Key 必须包含 SQL 参数值；业务写后考虑失效。
-- 读写分离在“写后立刻读”和事务内强制读主。
-- 分片使用稳定 Hash；不能使用进程随机化的 `string.GetHashCode()`。
-
-## 验收
-
-- Oracle 原生 `TO_CHAR(value, format[, nlsparam])` 必须保留参数顺序；Provider 不得用
-  字符串扫描交换参数。单参数、嵌套函数、格式串中的逗号、注释与字面量也要原样保留。
-- `ToArray/ToList` 是查询执行与读取边界，堆栈停在这里不能证明对象转换出错。
-  遇到 `ORA-01722`，先用同一账号条件拆分计数/列表，核对最终命令文本与参数类型，
-  再执行最小原生 SQL 对照；确定性的转换/语法错误不得用盲目重试或更改业务过滤掩盖。
-
-- 至少在目标数据库 Provider 运行定向测试，不用 MySQL 结果宣称 Oracle/达梦通过。
-- 覆盖 NULL、DateTime、decimal、Guid、enum、byte[] 和分页边界。
-- FormEngine 的 decimal 字符串绑定固定使用 `InvariantCulture` 且禁用千分组，防止 `de-DE` / `tr-TR` 把 `1.500000` 转成 `1500000`。类型化 CLR 数值保留原值；无效、本地化逗号或越界仍抛字段转换错误。绑定层修复不能恢复上游 JavaScript 浮点丢失的位数，必须保留原十进制字符串并分别验收实际 Provider 往返与 HTTP 提交。
-- 覆盖事务提交/回滚、唯一冲突、超时、取消和连接故障。
-- BulkInsert/Upsert 核对受影响行、Identity 跳过、唯一键和重试副作用。
-- 读写分离覆盖从库故障、写后读主和降级。
-- CodeFirst/索引变更在隔离库验证，不直接对生产执行破坏性重建。
+---
+name: dos-orm
+description: Dos.ORM C# 数据访问指南。用于 Microi.Server 中编写或审查 DbSession、Entity、From、WhereClip、事务、异步查询、BulkInsert、Upsert、SqlFunc、子查询、导航属性、CodeFirst、读写分离和分库分表代码。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Dos.ORM
+
+Dos.ORM 是 Microi.Server 底层 C# ORM。它不是接口引擎里的 `V8.Db`：
+
+- C# 服务端源码使用 `DbSession`、实体和 Section API。
+- V8 JavaScript 使用 `V8.FormEngine` 或 `V8.Db.FromSql`。
+- 不能把 C# lambda/事务示例原样放进 V8。
+
+完整 API、跨库行为与示例见 `references/api-reference.md`。
+
+## 默认选择
+
+| 需求 | 首选 |
+|---|---|
+| 普通实体查询 | `dbSession.From<T>().Where(...).ToList/ToListAsync` |
+| 动态条件 | `Where<T>` / `WhereClip` |
+| 复杂 SQL | `FromSql(...).AddInParameter(...)` |
+| 单条/小批写入 | `Insert/Update/Delete` |
+| 大于约 1000 行批量插入 | `BulkInsert/BulkInsertAsync`，先压测批大小 |
+| 按唯一键写入 | `Upsert/UpsertAsync` + 真实唯一索引 |
+| 多步原子写 | `BeginTransaction()`，`using` + Commit/Rollback |
+
+## 方言与种子转换边界
+
+- SQL AST、标识符、函数、分页、Upsert 与数据库语义由 Dos.ORM 方言编译器维护；Microi 宿主和 seed CLI 仅作输入/输出适配，不用正则或字符串替换模拟跨数据库 SQL。
+- 官方 MySQL 种子采用流式词法/语法解析，生成完整中性结构与数据模型；每次动态清单以同一来源 SHA 的独立 MySQL 导入为基准，逐表比较结构、行数与数据摘要。历史快照数量不能硬编码为当前源验收，不能用登录夹具或仅结构代替完整种子。
+- 真实数据库认证逐个方言串行运行，保留完整性与失败回执；工具和安装器回归保留在源码中，生成 SQL、ZIP、报告归 `.tmp/` 或正式 CDN。
+
+## 安全规则
+
+### 连接生命周期与在线恢复
+
+- 创建事务、准备读取器、打开连接、提交/回滚及批处理任一路径抛异常，都必须释放本层拥有的连接；借用外部事务或批处理连接时不能擅自关闭。保留原始异常，不因 Dispose 失败遮盖原始错误。
+- `DbTrans` 提交成功后先归还连接，再执行提交后通知。通知失败不能把已提交事务报告为回滚，也不能自动重放业务 SQL。调用者仍必须使用 `using`，防止业务异常绕过 Commit/Rollback。
+- `DatabasePoolExhausted`、`DatabaseCapacityExceeded`、`DatabaseEndpointUnreachable` 是不同故障；不要把应用池等待、数据库全局连接限制和慢 SQL 混为一谈。
+- 平台未显式配置的 MySQL 业务池上限为 100，最小池保持驱动默认 0，连接串显式值优先；不得因为数据库拒绝连接自动放大池。每节点/租户、独立读写池、Quartz 与外部客户端的容量须合计并保留管理余量。`Connection Lifetime` 是归还时按创建时间淘汰，不能当空闲超时。
+- 可信 C# 宿主通过 `Database.GetConnectionPoolSnapshot()` 读取脱敏状态，`ResetConnectionPool()` 只轮换准确匹配的 MySQL/SQL Server 池，`ProbeConnectionPoolAsync` 用原池执行固定 `SELECT 1`。不使用 `ClearAllPools`，不杀借出的事务，不重放 SQL。
+- 快照的 `MinimumPoolSize/ConnectionLifetimeSeconds` 是配置；`Database.GetConnectionPoolBudgetSnapshot` 按所选池身份去重合计最大/最小池。`CurrentNodeSelectedPools` 不包含其它节点、Quartz、扩展库或外部程序，不是已占用连接；未知驱动合计为 null，无池连接单列且不受池上限限制。
+- `BeginIsolatedConnections()` 仅用于有并发限制的可信应急鉴权作用域，设置无池连接与 5 秒连接/命令超时；未知驱动拒绝。不能给普通业务或 V8 增加绕过限流的开关，不能在此作用域内执行清池或把无池探测冒充原池恢复。
+- AI 在线恢复使用 `microi_manage_system_observability(action=ResetDatabasePools)` 的预览、确认和回读协议，详细决策见 [系统日志/监控](../system-observability/SKILL.md)。需要升级含 `database-pools/v1` 的后端和 MCP；事故恢复本身不要求重启数据库/API。
+
+- 数据值全程参数化；`FromSql` 的动态值用 `AddInParameter`。
+- 表名、字段名、排序名不能来自未经白名单验证的用户输入。
+- 保留 `{0}Name{1}` 标识符延迟绑定机制，不能改成字符串替换。
+- `OrderByClip` 的校验不是授权；可排序字段仍需业务白名单。
+- Upsert 幂等依赖数据库唯一键，不能只靠“先查再写”。
+- 租户业务表查询/写入必须包含真实 `OsClient` 范围。
+- 已明确需要的索引在 Microi 业务表上通过 Manifest/MCP 管理，不从临时 SQL 创建。
+- MySQL 用户名或密码包含分号时必须用连接字符串引号包裹，例如
+  `Password="a;b"`；平台统一兼容层只修复“无等号片段紧跟已明确凭据参数”的
+  历史串，其它结构错误继续失败关闭，禁止猜测用户名、密码或默认 `root`。
+
+## 事务与异步
+
+```csharp
+using (var trans = dbSession.BeginTransaction())
+{
+    try
+    {
+        trans.Insert(entity);
+        trans.Update<User>(User._.Status, 1, User._.Id == entity.Id);
+        trans.Commit();
+    }
+    catch
+    {
+        trans.Rollback();
+        throw;
+    }
+}
+```
+
+Dispose 幂等，未 Commit 时自动回滚。事务内异步操作串行执行；不要在同一个连接/
+事务上 `Task.WhenAll`。取消、超时和异常必须传播，不能吞掉后继续 Commit。
+
+## 性能与跨库
+
+- 显式选择字段，分页和流式读取，避免无界 `ToList()`。
+- BulkInsert 会按可用客户端选择原生实现并回退多行 INSERT；不同数据库必须实测。
+- 官网性能数字仅是特定环境参考，不能作为目标环境承诺。
+- 查询缓存 Key 必须包含 SQL 参数值；业务写后考虑失效。
+- 读写分离在“写后立刻读”和事务内强制读主。
+- 分片使用稳定 Hash；不能使用进程随机化的 `string.GetHashCode()`。
+
+## 验收
+
+- Oracle 原生 `TO_CHAR(value, format[, nlsparam])` 必须保留参数顺序；Provider 不得用
+  字符串扫描交换参数。单参数、嵌套函数、格式串中的逗号、注释与字面量也要原样保留。
+- `ToArray/ToList` 是查询执行与读取边界，堆栈停在这里不能证明对象转换出错。
+  遇到 `ORA-01722`，先用同一账号条件拆分计数/列表，核对最终命令文本与参数类型，
+  再执行最小原生 SQL 对照；确定性的转换/语法错误不得用盲目重试或更改业务过滤掩盖。
+
+- 至少在目标数据库 Provider 运行定向测试，不用 MySQL 结果宣称 Oracle/达梦通过。
+- 覆盖 NULL、DateTime、decimal、Guid、enum、byte[] 和分页边界。
+- FormEngine 的 decimal 字符串绑定固定使用 `InvariantCulture` 且禁用千分组，防止 `de-DE` / `tr-TR` 把 `1.500000` 转成 `1500000`。类型化 CLR 数值保留原值；无效、本地化逗号或越界仍抛字段转换错误。绑定层修复不能恢复上游 JavaScript 浮点丢失的位数，必须保留原十进制字符串并分别验收实际 Provider 往返与 HTTP 提交。
+- 覆盖事务提交/回滚、唯一冲突、超时、取消和连接故障。
+- BulkInsert/Upsert 核对受影响行、Identity 跳过、唯一键和重试副作用。
+- 读写分离覆盖从库故障、写后读主和降级。
+- CodeFirst/索引变更在隔离库验证，不直接对生产执行破坏性重建。