@microi.net/cli 5.8.5 → 5.8.7

package/skills/dos-orm/SKILL.md

@@ -1,97 +1,99 @@
----
-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 |
-
-## 安全规则
-
-### 连接生命周期与在线恢复
-
-- 创建事务、准备读取器、打开连接、提交/回滚及批处理任一路径抛异常，都必须释放本层拥有的连接；借用外部事务或批处理连接时不能擅自关闭。保留原始异常，不因 Dispose 失败遮盖原始错误。
-- `DbTrans` 提交成功后先归还连接，再执行提交后通知。通知失败不能把已提交事务报告为回滚，也不能自动重放业务 SQL。调用者仍必须使用 `using`，防止业务异常绕过 Commit/Rollback。
+---
+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 |
+
+## 安全规则
+
+### 连接生命周期与在线恢复
+
+- 创建事务、准备读取器、打开连接、提交/回滚及批处理任一路径抛异常，都必须释放本层拥有的连接；借用外部事务或批处理连接时不能擅自关闭。保留原始异常，不因 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。
-- `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/索引变更在隔离库验证，不直接对生产执行破坏性重建。
+- 快照的 `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/索引变更在隔离库验证，不直接对生产执行破坏性重建。

package/skills/dos-orm/references/api-reference.md

@@ -1,229 +1,229 @@
-# Dos.ORM API 参考
-
-## 数据库 Provider
-
-| DatabaseType | Provider |
-|---|---|
-| `SqlServer` | SQL Server 2000 |
-| `SqlServer9` | SQL Server 2005+ |
-| `MySql` | MySQL |
-| `Oracle` | Oracle |
-| `PostgreSql` | PostgreSQL |
-| `DaMeng` | 达梦 |
-| `KingBase` | 人大金仓 |
-| `Sqlite3` | SQLite |
-| `MsAccess` | Access |
-
-兼容协议数据库仍需目标库实测，不能只凭协议名称判定所有 DDL、分页和 BulkCopy 一致。
-
-默认会话入口是 `DbSession.Default`；多数据库、读写分离和分片场景使用明确的
-`DbSession` 实例，避免把默认连接误用于其它租户或数据库。
-
-## 实体
-
-```csharp
-[TableName("sys_user")]
-public class SysUser : Entity
-{
-    public string Id { get; set; }
-    public string Account { get; set; }
-    public DateTime CreateTime { get; set; }
-
-    public override Field[] GetFields() => new[] { _.Id, _.Account, _.CreateTime };
-    public override object[] GetValues() => new object[] { Id, Account, CreateTime };
-    public override Field GetIdentityField() => _.Id;
-
-    public sealed class _
-    {
-        public static readonly Field Id = new Field("Id", "sys_user");
-        public static readonly Field Account = new Field("Account", "sys_user");
-        public static readonly Field CreateTime = new Field("CreateTime", "sys_user");
-    }
-}
-```
-
-`Entity.GetFields()` 的字段顺序也是批量写入和 CodeFirst 映射依据；实体声明、
-字段数组与数据库列变更必须同步。
-
-## 查询链
-
-| API | 作用 |
-|---|---|
-| `From<T>()` / `From("table")` | 查询入口 |
-| `Where(predicate)` / `Where(WhereClip)` | 条件 |
-| `OrderBy` / `OrderByDescending` | 排序 |
-| `GroupBy` / `Having` | 分组 |
-| `Select` / `AddSelect` | 选择字段 |
-| `Distinct` / `Top` / `Page` | 去重、Top、分页 |
-| `InnerJoin/LeftJoin/RightJoin/CrossJoin/FullJoin` | Join |
-| `Union/UnionAll` | 集合联合 |
-| `SetCacheTimeOut` / `Refresh` | 查询缓存/绕过缓存 |
-| `ToList/ToListAsync` | 列表 |
-| `ToFirst/ToFirstAsync` | 第一条或 null |
-| `ToFirstDefault` | 第一条或 new 实体 |
-| `ToScalar/ToScalarAsync` | 标量 |
-| `ToDataReader` / `ToDataTable/ToDataTableAsync` | Reader/DataTable |
-| `ToEnumerable` | 流式枚举 |
-| `Count/CountAsync` | 计数 |
-| `ExecuteNonQuery/ExecuteNonQueryAsync` | 非查询 |
-
-查询缓存入口的完整成员名是 `FromSection.SetCacheTimeOut`。缓存 Key 包含 SQL
-与参数值，但写后失效、租户隔离和多节点一致性仍由业务负责。
-
-```csharp
-var users = await dbSession.From<SysUser>()
-    .Where(u => u.Account == account)
-    .OrderByDescending(u => u.CreateTime)
-    .Page(20, 1)
-    .ToListAsync();
-```
-
-## WhereClip
-
-```csharp
-var where = new Where<SysUser>();
-where.And(u => u.Status == 1);
-if (!string.IsNullOrWhiteSpace(keyword))
-    where.And(u => u.Name.Like(keyword));
-if (deptIds?.Any() == true)
-    where.And(u => u.DeptId.In(deptIds));
-
-var list = dbSession.From<SysUser>()
-    .Where(where.ToWhereClip())
-    .ToList();
-```
-
-支持比较、`Like/NotLike/StartsWith/EndsWith`、`In/NotIn` 和 NULL。
-
-## 原生 SQL
-
-```csharp
-var users = dbSession
-    .FromSql("SELECT Id,Account FROM sys_user WHERE Status=@p0")
-    .AddInParameter("@p0", 1)
-    .ToList<SysUser>();
-```
-
-动态值只走参数；动态标识符先从固定白名单映射。
-Provider 的标识符替换最终由 `DataUtils.FormatSQL` 完成；不要绕过该步骤手工
-拼接用户输入的表名或字段名。
-
-## 写入
-
-```csharp
-dbSession.Insert(entity);
-dbSession.Insert(list);
-dbSession.Update<SysUser>(u => u.Status, 0, u => u.Id == id);
-dbSession.Delete<SysUser>(u => u.Id == id);
-```
-
-批量：
-
-```csharp
-var affected = dbSession.BulkInsert(list, batchSize: 5000, bulkCopyTimeoutSeconds: 600);
-var affectedAsync = await dbSession.BulkInsertAsync(list, batchSize: 5000, ct: token);
-```
-
-原生优选：
-
-- SQL Server：SqlBulkCopy
-- MySQL：MySqlBulkCopy
-- PostgreSQL/KingBase：Binary COPY
-- Oracle/达梦/SQLite/Access：多行参数化 INSERT 回退
-
-批大小 5000 只是起点；按行宽、索引、日志、网络和数据库负载测量。
-
-## Upsert
-
-```csharp
-dbSession.Upsert(user, SysUser._.Account);
-await dbSession.UpsertAsync(
-    user,
-    ct: token,
-    conflictFields: new[] { SysUser._.Account });
-```
-
-各 Provider 使用 `ON DUPLICATE KEY`、`ON CONFLICT`、`MERGE` 或更新后插入回退。
-冲突字段必须有数据库唯一约束。
-
-## SqlFunc 与子查询
-
-`SqlFunc` 提供 `SqlFunc.IfNull`、`SqlFunc.IIF`、`SqlFunc.Length`、
-`SqlFunc.Substring`、`SqlFunc.Now`、`SqlFunc.DateDiff`、
-`SqlFunc.JsonValue`、`SqlFunc.Concat`、`SqlFunc.Upper`、`SqlFunc.Lower`、
-`SqlFunc.Trim`、`SqlFunc.Abs`、`SqlFunc.Round`、`SqlFunc.Count`、
-`SqlFunc.Sum`、`SqlFunc.Avg`、`SqlFunc.Min`、`SqlFunc.Max` 的 Provider 方言。
-
-`SqlSubQuery` 提供 `SqlSubQuery.Exists`、`SqlSubQuery.NotExists`、
-`SqlSubQuery.In`、`SqlSubQuery.NotIn`、`SqlSubQuery.Scalar` 和
-`SqlSubQuery.Count`。
-返回的是 SQL 片段，数据值仍要参数化。
-
-## 导航属性
-
-`[Navigate]` 支持 `NavigateType.OneToOne`、`NavigateType.OneToMany`、
-`NavigateType.ManyToMany`；加载入口：
-
-- `IncludeOne`
-- `IncludeMany`
-- `IncludeManyToMany`
-
-实现使用批量 IN，避免逐行 N+1。仍要限制主结果规模。
-
-## CodeFirst
-
-```csharp
-dbSession.CreateTable<SysUser>();
-dbSession.SyncSchema(typeof(SysUser), typeof(Order));
-var exists = dbSession.TableExists("sys_user");
-```
-
-`CreateTable<T>(dropIfExists: true)` 是破坏性操作，只可在明确授权的隔离环境使用。
-实体索引可用 `[Index]` 声明；Microi 低代码业务表的运行时索引仍必须走 Manifest/MCP。
-
-## 读写分离
-
-```csharp
-var router = new ReadWriteRouter(master);
-router.AddSlave(slave1, weight: 1);
-router.AddSlave(slave2, weight: 2);
-
-var read = router.GetReadSession();
-var write = router.GetWriteSession();
-
-using (router.ForceMaster())
-{
-    var latest = router.GetReadSession().From<SysUser>().ToList();
-}
-```
-
-支持加权轮询、摘除和回退。事务与读自己刚写的数据必须读主。
-
-## 分库分表
-
-表名路由：
-
-- `ShardingRouter.MonthlyTable`
-- `ShardingRouter.HashModTable`
-- `ShardingRouter.ModTable`
-
-数据库路由：
-
-- `DbShardingRouter.AddNode`
-- `RouteByHash`
-- `AllNodes`
-
-稳定 Hash 使用 FNV-1a。跨分片事务、全局唯一键、分页排序和聚合需要业务层明确设计。
-
-## 监控与缓存
-
-```csharp
-Dos.ORM.Section.SlowSqlThresholdMs = 1000;
-Dos.ORM.Section.OnSlowSql = (cmd, elapsed, operation) =>
-{
-    // 记录脱敏 SQL 模板、耗时和关联 Id；不要记录密钥参数
-};
-```
-
-反序列化器、实体元数据和字段名缓存是进程内优化，允许节点重启后重建；
-不能作为跨节点业务事实。查询缓存使用滑动过期，写后按业务失效。
+# Dos.ORM API 参考
+
+## 数据库 Provider
+
+| DatabaseType | Provider |
+|---|---|
+| `SqlServer` | SQL Server 2000 |
+| `SqlServer9` | SQL Server 2005+ |
+| `MySql` | MySQL |
+| `Oracle` | Oracle |
+| `PostgreSql` | PostgreSQL |
+| `DaMeng` | 达梦 |
+| `KingBase` | 人大金仓 |
+| `Sqlite3` | SQLite |
+| `MsAccess` | Access |
+
+兼容协议数据库仍需目标库实测，不能只凭协议名称判定所有 DDL、分页和 BulkCopy 一致。
+
+默认会话入口是 `DbSession.Default`；多数据库、读写分离和分片场景使用明确的
+`DbSession` 实例，避免把默认连接误用于其它租户或数据库。
+
+## 实体
+
+```csharp
+[TableName("sys_user")]
+public class SysUser : Entity
+{
+    public string Id { get; set; }
+    public string Account { get; set; }
+    public DateTime CreateTime { get; set; }
+
+    public override Field[] GetFields() => new[] { _.Id, _.Account, _.CreateTime };
+    public override object[] GetValues() => new object[] { Id, Account, CreateTime };
+    public override Field GetIdentityField() => _.Id;
+
+    public sealed class _
+    {
+        public static readonly Field Id = new Field("Id", "sys_user");
+        public static readonly Field Account = new Field("Account", "sys_user");
+        public static readonly Field CreateTime = new Field("CreateTime", "sys_user");
+    }
+}
+```
+
+`Entity.GetFields()` 的字段顺序也是批量写入和 CodeFirst 映射依据；实体声明、
+字段数组与数据库列变更必须同步。
+
+## 查询链
+
+| API | 作用 |
+|---|---|
+| `From<T>()` / `From("table")` | 查询入口 |
+| `Where(predicate)` / `Where(WhereClip)` | 条件 |
+| `OrderBy` / `OrderByDescending` | 排序 |
+| `GroupBy` / `Having` | 分组 |
+| `Select` / `AddSelect` | 选择字段 |
+| `Distinct` / `Top` / `Page` | 去重、Top、分页 |
+| `InnerJoin/LeftJoin/RightJoin/CrossJoin/FullJoin` | Join |
+| `Union/UnionAll` | 集合联合 |
+| `SetCacheTimeOut` / `Refresh` | 查询缓存/绕过缓存 |
+| `ToList/ToListAsync` | 列表 |
+| `ToFirst/ToFirstAsync` | 第一条或 null |
+| `ToFirstDefault` | 第一条或 new 实体 |
+| `ToScalar/ToScalarAsync` | 标量 |
+| `ToDataReader` / `ToDataTable/ToDataTableAsync` | Reader/DataTable |
+| `ToEnumerable` | 流式枚举 |
+| `Count/CountAsync` | 计数 |
+| `ExecuteNonQuery/ExecuteNonQueryAsync` | 非查询 |
+
+查询缓存入口的完整成员名是 `FromSection.SetCacheTimeOut`。缓存 Key 包含 SQL
+与参数值，但写后失效、租户隔离和多节点一致性仍由业务负责。
+
+```csharp
+var users = await dbSession.From<SysUser>()
+    .Where(u => u.Account == account)
+    .OrderByDescending(u => u.CreateTime)
+    .Page(20, 1)
+    .ToListAsync();
+```
+
+## WhereClip
+
+```csharp
+var where = new Where<SysUser>();
+where.And(u => u.Status == 1);
+if (!string.IsNullOrWhiteSpace(keyword))
+    where.And(u => u.Name.Like(keyword));
+if (deptIds?.Any() == true)
+    where.And(u => u.DeptId.In(deptIds));
+
+var list = dbSession.From<SysUser>()
+    .Where(where.ToWhereClip())
+    .ToList();
+```
+
+支持比较、`Like/NotLike/StartsWith/EndsWith`、`In/NotIn` 和 NULL。
+
+## 原生 SQL
+
+```csharp
+var users = dbSession
+    .FromSql("SELECT Id,Account FROM sys_user WHERE Status=@p0")
+    .AddInParameter("@p0", 1)
+    .ToList<SysUser>();
+```
+
+动态值只走参数；动态标识符先从固定白名单映射。
+Provider 的标识符替换最终由 `DataUtils.FormatSQL` 完成；不要绕过该步骤手工
+拼接用户输入的表名或字段名。
+
+## 写入
+
+```csharp
+dbSession.Insert(entity);
+dbSession.Insert(list);
+dbSession.Update<SysUser>(u => u.Status, 0, u => u.Id == id);
+dbSession.Delete<SysUser>(u => u.Id == id);
+```
+
+批量：
+
+```csharp
+var affected = dbSession.BulkInsert(list, batchSize: 5000, bulkCopyTimeoutSeconds: 600);
+var affectedAsync = await dbSession.BulkInsertAsync(list, batchSize: 5000, ct: token);
+```
+
+原生优选：
+
+- SQL Server：SqlBulkCopy
+- MySQL：MySqlBulkCopy
+- PostgreSQL/KingBase：Binary COPY
+- Oracle/达梦/SQLite/Access：多行参数化 INSERT 回退
+
+批大小 5000 只是起点；按行宽、索引、日志、网络和数据库负载测量。
+
+## Upsert
+
+```csharp
+dbSession.Upsert(user, SysUser._.Account);
+await dbSession.UpsertAsync(
+    user,
+    ct: token,
+    conflictFields: new[] { SysUser._.Account });
+```
+
+各 Provider 使用 `ON DUPLICATE KEY`、`ON CONFLICT`、`MERGE` 或更新后插入回退。
+冲突字段必须有数据库唯一约束。
+
+## SqlFunc 与子查询
+
+`SqlFunc` 提供 `SqlFunc.IfNull`、`SqlFunc.IIF`、`SqlFunc.Length`、
+`SqlFunc.Substring`、`SqlFunc.Now`、`SqlFunc.DateDiff`、
+`SqlFunc.JsonValue`、`SqlFunc.Concat`、`SqlFunc.Upper`、`SqlFunc.Lower`、
+`SqlFunc.Trim`、`SqlFunc.Abs`、`SqlFunc.Round`、`SqlFunc.Count`、
+`SqlFunc.Sum`、`SqlFunc.Avg`、`SqlFunc.Min`、`SqlFunc.Max` 的 Provider 方言。
+
+`SqlSubQuery` 提供 `SqlSubQuery.Exists`、`SqlSubQuery.NotExists`、
+`SqlSubQuery.In`、`SqlSubQuery.NotIn`、`SqlSubQuery.Scalar` 和
+`SqlSubQuery.Count`。
+返回的是 SQL 片段，数据值仍要参数化。
+
+## 导航属性
+
+`[Navigate]` 支持 `NavigateType.OneToOne`、`NavigateType.OneToMany`、
+`NavigateType.ManyToMany`；加载入口：
+
+- `IncludeOne`
+- `IncludeMany`
+- `IncludeManyToMany`
+
+实现使用批量 IN，避免逐行 N+1。仍要限制主结果规模。
+
+## CodeFirst
+
+```csharp
+dbSession.CreateTable<SysUser>();
+dbSession.SyncSchema(typeof(SysUser), typeof(Order));
+var exists = dbSession.TableExists("sys_user");
+```
+
+`CreateTable<T>(dropIfExists: true)` 是破坏性操作，只可在明确授权的隔离环境使用。
+实体索引可用 `[Index]` 声明；Microi 低代码业务表的运行时索引仍必须走 Manifest/MCP。
+
+## 读写分离
+
+```csharp
+var router = new ReadWriteRouter(master);
+router.AddSlave(slave1, weight: 1);
+router.AddSlave(slave2, weight: 2);
+
+var read = router.GetReadSession();
+var write = router.GetWriteSession();
+
+using (router.ForceMaster())
+{
+    var latest = router.GetReadSession().From<SysUser>().ToList();
+}
+```
+
+支持加权轮询、摘除和回退。事务与读自己刚写的数据必须读主。
+
+## 分库分表
+
+表名路由：
+
+- `ShardingRouter.MonthlyTable`
+- `ShardingRouter.HashModTable`
+- `ShardingRouter.ModTable`
+
+数据库路由：
+
+- `DbShardingRouter.AddNode`
+- `RouteByHash`
+- `AllNodes`
+
+稳定 Hash 使用 FNV-1a。跨分片事务、全局唯一键、分页排序和聚合需要业务层明确设计。
+
+## 监控与缓存
+
+```csharp
+Dos.ORM.Section.SlowSqlThresholdMs = 1000;
+Dos.ORM.Section.OnSlowSql = (cmd, elapsed, operation) =>
+{
+    // 记录脱敏 SQL 模板、耗时和关联 Id；不要记录密钥参数
+};
+```
+
+反序列化器、实体元数据和字段名缓存是进程内优化，允许节点重启后重建；
+不能作为跨节点业务事实。查询缓存使用滑动过期，写后按业务失效。