@microi.net/cli 6.1.4 → 6.1.6

package/skills/v8-security/SKILL.md

@@ -53,13 +53,20 @@ Preview 和确认均重验当前客户端、回调及 Scope；账号变化通过
 同一 Managed 会话接口包含本人初始化与敏感管理动作时，精确 `ApiRole` 不能代替动作级鉴权。SaaS v8.4.26 / `platform-sys-user-session` v1.0.5 对已归一化的 `GetSysUserPassword`，先拒绝匿名和访问密钥，再以可信 `V8.CurrentUser`、`V8.Db` 主库的本人活动状态/等级及有效管理员角色核验后调用原可信原子；不读取密码字段做授权，不使用 `DbRead`、客户端身份字段或角色名判断。标准角色授权可用于只读账号的本人会话初始化，不能把整引擎授权解释成敏感动作许可。负例使用预先确认不存在的固定用户 Id：普通账号必须先被管理员门拒绝，管理员仅验证合法路径返回不存在，禁止为验收读取任何真实密码。
 
 <!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=v8-security-000 sha256=a6a4311b1a799ea4ed005b22c01cb8230509aaf09aeead5a17c8c46da74772c8 -->
+<!-- microi-progressive:chunk id=v8-security-000 sha256=0dfa03a03298161e6aa29dff18f68fdb00e4f0865cb7562fec090dcadd745c43 -->
 ## 0. 租户动态系统设置与密钥边界
 
 **AI 默认处理路径：** 用户交付第三方 Secret 并授权配置时，优先调用 `microi_manage_server_private_secret`：List 只确认 Key/HasSecret；Save 使用 `confirmExecution=SAVE:<ConfigKey>`，固定 `IsSecret=true / IsPublic=false` 并自动脱敏回读。例如畅捷通使用 `Integration.Changjet.AppSecret`，后端从 `V8.SysConfig.ServerPrivateSettings` 使用。不要仅拒绝硬编码后停止，也不要因为 `OsClientModel` 不暴露密钥而误判服务端 V8 无法调用第三方。工具不提供原文揭示；更换已有 Key 前回读现状，超时只回读、不盲目重写。
 
 第三方密钥（微信、支付宝、OpenAI、阿里云、ERP、SMTP）**禁止**硬编码在 V8 代码或前端。公开的租户配置必须建成当前租户 `sys_config` 的实体字段；敏感或仅供后端使用的租户业务配置保存到 `mci_system_setting`。数据库、Redis、MongoDB、MinIO、MQ 等部署控制面仍由主库 `sys_osclients` 托管，子租户不能修改。
 
+MinIO 部署凭据使用专用 `microi_manage_saas_minio`，不能误存到普通第三方业务 Secret，
+也不能为此放宽 `microi_admin_table_data` 的秘密字段限制。先 Inspect 当前主租户及运行分区，
+再以其 Revision 和 `SAVE_MINIO:<tenant>:<revision>` 确认保存；省略凭据保留，候选先探测、
+事务行锁 CAS、提交后缓存刷新及运行回读。只返回 HasAccessKey/HasSecretKey，拒绝子租户和
+访问密钥会话，不修改 HDFS/OSS 或桶权限。超时和 Persisted=true 的失败先 Inspect/Probe，
+不能盲重放；旧后端不支持时升级正式后端，禁止用 SQL、普通表单或临时 V8 绕过。
+
 能力是否启用、入口是否显示、公开交互模式等 Bool/Enum 配置即使属于登录或第三方集成，也必须放在 `sys_config`；API Key、ClientSecret、RP ID、Origin、Issuer、Scope、供应商地址等后端参数才放在 `mci_system_setting`。禁止给同一个新配置双写两张表。迁移旧开关时采用“新 `sys_config` 显式值 → 旧私密 Key → 存量安全默认”的只读回退，并从私密设置的列表、保存和删除入口移除旧 Key。
 
 ```javascript

package/skills/v8-sql-query/SKILL.md

@@ -1,302 +1,302 @@
----
-name: v8-sql-query
-description: Microi V8 安全 SQL 查询指南。用于选择 V8.FormEngine _Where 或 V8.Db.FromSql，处理参数化查询、联表、聚合并避免 SQL 注入。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi V8 安全 SQL 查询
-
-你正在开发 Microi 吾码平台的 V8 引擎代码。数据库查询有两种方式：`V8.FormEngine`（推荐）和 `V8.Db`（原始 SQL）。必须遵守安全规范。
-
-## 性能门禁（必须执行）
-
-写接口引擎前必须先做数据访问计划，避免“循环套循环查数据库”：
-
-- 禁止在 `for` / `while` / `forEach` / `map` 循环内调用 `V8.FormEngine.GetFormData`、`GetTableData`、`V8.Db.FromSql`、`V8.ApiEngine.Run` 或 `V8.Http.*`。确实无法避免时，必须先说明原因，并加分页、缓存或限流。
-- 多条 Id、编码、外键查询必须一次性用 `_Where: [['Id','In', ids]]`、SQL `IN`、JOIN 或聚合查询取回，再用内存字典映射。
-- 需要父子、主从、用户/部门/角色名称映射时，先批量取关联表，只保留 `_SelectFields` 必要列，不要逐行查名称。
-- 统计、计数、汇总优先让数据库一次 `GROUP BY` / `COUNT` / `SUM` 完成，不要把大表全部拉到 V8 里循环统计。
-- 列表接口必须限制 `_PageSize`，管理端默认不要超过 100，导出或批处理必须显式分批。
-- 每次查询都要写 `_SelectFields` 或明确 SQL 字段列表，禁止 `SELECT *` 用在大表、接口列表、循环前置查询中。
-- 外部 HTTP、翻译、短信、AI 等慢调用不能放在数据库事务和大循环中；要么异步队列，要么批量预处理并设置超时。
-- 返回前自检一次：数据库访问次数应与数据量无关或近似常数级，不能随着行数线性增长为 N 次查询。
-
-## 首选：V8.FormEngine + _Where（自动防注入）
-
-`_Where` 是参数化查询语法，自动防 SQL 注入，**永远优先使用**。
-
-```javascript
-// ✅ 安全：_Where 自动参数化
-var result = V8.FormEngine.GetTableData('SysUser', {
-  _Where: [
-    ['Account', '=', V8.Param.account],
-    ['AND', 'Status', '=', 1]
-  ],
-  _PageIndex: 1,
-  _PageSize: 20
-});
-```
-
-### _Where 完整语法
-
-```javascript
-// 基本条件
-[['Field', '操作符', value]]
-
-// 操作符：=, ==, <>, !=, >, >=, <, <=, Like, NotLike, StartLike, EndLike, In, NotIn
-
-// 多条件 AND
-[['A', '=', 1], ['AND', 'B', '>', 10]]
-
-// 多条件 OR
-[['A', '=', 1], ['OR', 'B', '=', 2]]
-
-// IN 查询
-[['Id', 'In', ['id1', 'id2', 'id3']]]
-
-// NULL 判断
-[['Field', '=', null]]    // IS NULL
-[['Field', '<>', null]]   // IS NOT NULL
-
-// 分组（括号）：(Age > 18 OR Status = 1)
-[['Name', 'Like', '张'], ['AND', '(', 'Age', '>', 18], ['OR', 'Status', '=', 1, ')']]
-
-// 日期范围
-[['CreateTime', '>=', '2024-01-01'], ['AND', 'CreateTime', '<', '2024-02-01']]
-```
-
-### 旧版 _Where 兼容（V8.Method.ParseWhere）
-
-老版本前端可能传对象格式（`{Name, Value, Type, AndOr, GroupStart, GroupEnd}`）。
-`V8.Method.ParseWhere` 返回统一的 `DiyWhere` 对象集合；它不是“对象转数组”函数。
-
-```javascript
-var objectWhere = V8.Method.ParseWhere(V8.Param._Where);
-V8.FormEngine.GetTableData('Table', { _Where: objectWhere });
-```
-
-合并客户端筛选与接口固定条件时，必须先统一格式，禁止直接把数组条件追加到对象条件集合。
-部分部署按首项类型解析整个集合，混合格式会触发转换失败并退化为空条件，导致统计返回未筛选总数。
-需要兼容混合输入时，逐条调用 `ParseWhere(JSON.stringify([condition]))`，确认每条恰好解析出一个有效条件后，
-再合并为同一种格式；非空输入解析为空、非法操作符或括号不平衡必须返回失败，不能继续执行统计。
-存在顶层 OR 时，还须保证语义为“整个客户端筛选 AND 固定条件”，不能仅在原表达式末尾追加 AND。
-回归至少比较纯数组、纯对象、混合条件、OR/分组、零结果和非法输入。
-
-## 次选：V8.Db.FromSql（仅 SQL 字符串 + AddInParameter）
-
-> **⚠️ FormEngine 优先原则：** 增删改操作（INSERT / UPDATE / DELETE）必须**优先**使用 `V8.FormEngine.AddFormData` / `UptFormData` / `UptFormDataByWhere` / `DelFormData` 等方法。**只有**多表 JOIN、复杂子查询、GROUP BY 聚合等 FormEngine 无法表达的场景才使用 `V8.Db.FromSql`。
-
-> **⚠️ FromSql 调用规则：** `V8.Db.FromSql` 在 V8 中只传 SQL 字符串，不要把动态值作为第二个或后续参数传给 `FromSql`。动态值必须用链式 `.AddInParameter('@p0', value)` 绑定；否则会生成平台不支持的调用签名。
-
-> **共享事务：** `V8.Db` 是主库会话，`V8.Db.FromSql` 不会自动加入接口引擎事务。需要与表单、其它 SQL 或流程共同提交/回滚的操作，必须使用 `V8.DbTrans.FromSql`；依赖本事务尚未提交结果的查询也一样。`V8.FormEngine`、`V8.ApiEngine.Run` 继续显式传第三参数 `V8.DbTrans`。禁止从安全代理取内部事务并自行提交。
-
-```javascript
-// ❌ 错误形态：不要把动态值作为 FromSql 的第二个参数传入
-
-// ✅ 优先：改用 FormEngine（单表增删改查都优先这样写）
-V8.FormEngine.UptFormData('t', { Id: id, A: val1, B: val2 });
-
-// ✅ 必须用原生 SQL 时：FromSql 只传 SQL，参数用 AddInParameter
-V8.DbTrans.FromSql("UPDATE t SET A=@p0, B=@p1 WHERE Id=@p2")
-     .AddInParameter("@p0", val1)
-     .AddInParameter("@p1", val2)
-     .AddInParameter("@p2", id)
-     .ExecuteNonQuery();
-```
-
-当 `_Where` 无法满足复杂查询（多表 JOIN、子查询、聚合统计）时使用 `V8.Db`：
-
-```javascript
-// ✅ 安全：使用 @p0, @p1 占位符，并用 AddInParameter 绑定
-var list = V8.Db.FromSql(
-  'SELECT a.Id, a.Name, b.OrderCount FROM Customer a LEFT JOIN (SELECT CustomerId, COUNT(*) OrderCount FROM OrderHeader GROUP BY CustomerId) b ON a.Id = b.CustomerId WHERE a.Status = @p0'
-).AddInParameter("@p0", 1).ToArray();
-
-// ✅ 安全：多个参数
-var row = V8.Db.FromSql(
-  'SELECT * FROM SysUser WHERE Account = @p0 AND DeptId = @p1'
-).AddInParameter("@p0", V8.Param.account)
- .AddInParameter("@p1", V8.Param.deptId)
- .First();
-
-// 统计
-var count = V8.Db.FromSql(
-  'SELECT COUNT(*) FROM OrderHeader WHERE Status = @p0 AND CreateTime >= @p1'
-).AddInParameter("@p0", 1)
- .AddInParameter("@p1", V8.Param.startDate)
- .ToScalar();
-
-// 非查询（UPDATE / INSERT / DELETE）
-V8.DbTrans.FromSql(
-  'UPDATE SysUser SET LastLoginTime = @p0 WHERE Id = @p1'
-).AddInParameter("@p0", DateNow('yyyy-MM-dd HH:mm:ss'))
- .AddInParameter("@p1", V8.CurrentUser.Id)
- .ExecuteNonQuery();
-```
-
-> 老版本兼容：要把维护接口复制到旧部署时，不要假定 `DateNow` 或 `System.DateTime.Now.ToString(...)` 一定可用。若数据库类型固定，可直接使用该数据库的当前时间表达式（例如 MySQL 的 `NOW()`）；跨数据库代码则应按数据库类型选择表达式或传入平台已确认支持的时间值。
-
-### V8.Db 方法速查
-
-| 方法 | 返回 | 用途 |
-|------|------|------|
-| `.ToArray()` | 数组 | 查询多条 |
-| `.First()` | 对象 \| null | 查询单条 |
-| `.ToScalar()` | 单值 | COUNT / MAX / SUM 等 |
-| `.ExecuteNonQuery()` | 影响行数 | UPDATE / DELETE / INSERT |
-
-> 别名：`.ToList()` = `.ToArray()`，`.ToModel()` = `.First()`，`.ExecuteScalar()` = `.ToScalar()`
-
-### 读写分离
-
-```javascript
-V8.Db.FromSql(...)      // 主库（读写）
-V8.DbRead.FromSql(...)  // 从库（只读，适合报表和大量查询）
-// 未部署读写分离时 V8.DbRead 与 V8.Db 一致
-```
-
-### 跨应用查询（扩展数据库）
-
-```javascript
-var list = V8.Dbs.OracleDB1.FromSql('SELECT * FROM Table WHERE Id = @p0')
-  .AddInParameter("@p0", id)
-  .ToArray();
-
-// 不写入 microi_database：创建仅当前请求使用的临时会话
-var tempDb = V8.Dbs.Open(
-  'SqlServer',
-  'Server=127.0.0.1,1433;Database=app;User Id=user;Password=***;TrustServerCertificate=True;'
-);
-var tempList = tempDb.FromSql('SELECT Id, Name FROM Customer WHERE Status = @p0')
-  .AddInParameter('@p0', 1)
-  .ToArray();
-```
-
-`V8.Dbs.Open` 与保存连接均只支持 Dos.ORM 已认证的 `MySql`、`SqlServer`、`Oracle`、`PostgreSql`、`DaMeng`、`KingBase`。动态连接串只能来自可信服务端密钥或管理员代码，禁止使用 `V8.Param.ConnectionString`，禁止记录或返回。外部 SQL 的表名、列名、排序字段必须来自已校验元数据白名单；动态值继续使用 `AddInParameter`。
-
-MCP 结构发现使用 `microi_inspect_external_database`，安全抽样默认使用只读的 `microi_query_external_database`。当用户明确要求数据库管理级能力时，使用独立的 `microi_execute_external_database`：它只允许后端确认的 `Level >= 9999` 当前用户调用，显式确认后可执行目标数据库账号有权执行的任意 DML、DDL、存储过程、数据库原生命令或多语句。输出行数限制只保护 MCP 传输，不限制数据库副作用；审计只记录 SQL 哈希、长度、模式和结果，不得记录 SQL 正文、连接串或密码。
-
-不要用 `microi_get_db_schema` 读取第三方库，也不要在对话中搬运全库数据；持续同步应创建参数化、分页、幂等的服务端任务。最高权限入口不等于跨租户，也不能超越目标数据库账号自身权限。
-
-## 数据库事务
-
-### 接口引擎事务（自动管理）
-
-```javascript
-// 接口引擎创建 V8.DbTrans；V8.Db 是独立主库会话，不自动加入它：
-// 返回 Code=1 → 自动提交事务
-// 返回 Code≠1 → 自动回滚事务
-// 手动调用 V8.DbTrans.Commit() 或 V8.DbTrans.Rollback() 均无效
-V8.DbTrans.FromSql('UPDATE Account SET Balance = Balance - @p0 WHERE Id = @p1')
-  .AddInParameter("@p0", 100)
-  .AddInParameter("@p1", fromId)
-  .ExecuteNonQuery();
-V8.DbTrans.FromSql('UPDATE Account SET Balance = Balance + @p0 WHERE Id = @p1')
-  .AddInParameter("@p0", 100)
-  .AddInParameter("@p1", toId)
-  .ExecuteNonQuery();
-
-// V8.DbTrans 可传给 FormEngine 和 ApiEngine.Run 共享事务
-V8.FormEngine.UptFormData('Table1', { Id: 'x', Status: 1 }, V8.DbTrans);
-V8.ApiEngine.Run('other-engine', { Id: 'x' }, V8.DbTrans);
-```
-
-### 扩展数据库事务（手动管理）
-
-```javascript
-// 扩展数据库需要手动管理事务
-var exTrans = V8.Dbs.OracleDB1.BeginTransaction();
-try {
-  exTrans.FromSql('UPDATE t1 SET a = @p0 WHERE Id = @p1')
-    .AddInParameter("@p0", 1)
-    .AddInParameter("@p1", id1)
-    .ExecuteNonQuery();
-  exTrans.FromSql('UPDATE t2 SET b = @p0 WHERE Id = @p1')
-    .AddInParameter("@p0", 2)
-    .AddInParameter("@p1", id2)
-    .ExecuteNonQuery();
-  exTrans.Commit();
-} catch (ex) {
-  exTrans.Rollback();
-} finally {
-  exTrans.Close();  // 必须释放事务对象
-}
-```
-
-## 绝对禁止
-
-```javascript
-// ❌ 绝对禁止：拼接 SQL 字符串
-var sql = "SELECT * FROM SysUser WHERE Account = '" + V8.Param.account + "'";
-V8.Db.FromSql(sql).ToArray();  // SQL 注入漏洞！
-
-// ❌ 禁止：动态拼接表名
-var sql = "SELECT * FROM " + V8.Param.tableName + " WHERE Id = @p0";
-
-// ✅ 正确做法：单表查询优先使用 FormEngine + _Where
-var result = V8.FormEngine.GetTableData('SysUser', {
-  _Where: [['Account', '=', V8.Param.account]],
-  _PageSize: 20
-});
-```
-
-## 常见查询模式
-
-### 分页查询
-
-```javascript
-var pageIndex = parseInt(V8.Param.pageIndex) || 1;
-var pageSize = Math.min(parseInt(V8.Param.pageSize) || 20, 100); // 限制最大100
-
-var result = V8.FormEngine.GetTableData('TableName', {
-  _Where: [['Status', '=', 1]],
-  _OrderBy: 'CreateTime',
-  _OrderByType: 'DESC',
-  _PageIndex: pageIndex,
-  _PageSize: pageSize
-});
-
-return { Code: 1, Data: result.Data, Total: result.DataCount };
-```
-
-### 模糊搜索（多字段）
-
-```javascript
-var keyword = V8.Param.keyword;
-var where = [['Status', '=', 1]];
-if (keyword) {
-  where.push(['AND', '(', 'Name', 'Like', keyword]);
-  where.push(['OR', 'Code', 'Like', keyword]);
-  where.push(['OR', 'Phone', 'Like', keyword, ')']);
-}
-
-var result = V8.FormEngine.GetTableData('Customer', {
-  _Where: where,
-  _PageIndex: 1,
-  _PageSize: 20
-});
-```
-
-### 关联查询（SQL JOIN）
-
-```javascript
-var list = V8.Db.FromSql(`
-  SELECT o.Id, o.OrderNo, o.TotalAmount, c.Name AS CustomerName
-  FROM OrderHeader o
-  INNER JOIN Customer c ON o.CustomerId = c.Id
-  WHERE o.Status = @p0 AND o.CreateTime >= @p1
-  ORDER BY o.CreateTime DESC
-`).AddInParameter("@p0", 1)
-  .AddInParameter("@p1", V8.Param.startDate)
-  .ToArray();
-```
-
-## 注意事项
-
-- `V8.Db.FromSql` 只传 SQL 字符串，参数占位符从 `@p0` 开始递增，动态值用 `.AddInParameter("@p0", value)` 绑定
-- 服务端 `V8.FormEngine` 操作默认不触发表单 V8 事件；确需触发时在参数中加 `_InvokeType: 'Client'`
-- 查询结果数量较大时务必分页，`_PageSize` 默认最大 1000
-- `V8.DbRead` 适用于不需要实时性的报表查询
-- 接口引擎的事务由平台自动管理，**不要手动调用** `V8.DbTrans.Commit/Rollback`
-- 扩展数据库事务必须手动调用 `BeginTransaction/Commit/Rollback/Close`
+---
+name: v8-sql-query
+description: Microi V8 安全 SQL 查询指南。用于选择 V8.FormEngine _Where 或 V8.Db.FromSql，处理参数化查询、联表、聚合并避免 SQL 注入。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 安全 SQL 查询
+
+你正在开发 Microi 吾码平台的 V8 引擎代码。数据库查询有两种方式：`V8.FormEngine`（推荐）和 `V8.Db`（原始 SQL）。必须遵守安全规范。
+
+## 性能门禁（必须执行）
+
+写接口引擎前必须先做数据访问计划，避免“循环套循环查数据库”：
+
+- 禁止在 `for` / `while` / `forEach` / `map` 循环内调用 `V8.FormEngine.GetFormData`、`GetTableData`、`V8.Db.FromSql`、`V8.ApiEngine.Run` 或 `V8.Http.*`。确实无法避免时，必须先说明原因，并加分页、缓存或限流。
+- 多条 Id、编码、外键查询必须一次性用 `_Where: [['Id','In', ids]]`、SQL `IN`、JOIN 或聚合查询取回，再用内存字典映射。
+- 需要父子、主从、用户/部门/角色名称映射时，先批量取关联表，只保留 `_SelectFields` 必要列，不要逐行查名称。
+- 统计、计数、汇总优先让数据库一次 `GROUP BY` / `COUNT` / `SUM` 完成，不要把大表全部拉到 V8 里循环统计。
+- 列表接口必须限制 `_PageSize`，管理端默认不要超过 100，导出或批处理必须显式分批。
+- 每次查询都要写 `_SelectFields` 或明确 SQL 字段列表，禁止 `SELECT *` 用在大表、接口列表、循环前置查询中。
+- 外部 HTTP、翻译、短信、AI 等慢调用不能放在数据库事务和大循环中；要么异步队列，要么批量预处理并设置超时。
+- 返回前自检一次：数据库访问次数应与数据量无关或近似常数级，不能随着行数线性增长为 N 次查询。
+
+## 首选：V8.FormEngine + _Where（自动防注入）
+
+`_Where` 是参数化查询语法，自动防 SQL 注入，**永远优先使用**。
+
+```javascript
+// ✅ 安全：_Where 自动参数化
+var result = V8.FormEngine.GetTableData('SysUser', {
+  _Where: [
+    ['Account', '=', V8.Param.account],
+    ['AND', 'Status', '=', 1]
+  ],
+  _PageIndex: 1,
+  _PageSize: 20
+});
+```
+
+### _Where 完整语法
+
+```javascript
+// 基本条件
+[['Field', '操作符', value]]
+
+// 操作符：=, ==, <>, !=, >, >=, <, <=, Like, NotLike, StartLike, EndLike, In, NotIn
+
+// 多条件 AND
+[['A', '=', 1], ['AND', 'B', '>', 10]]
+
+// 多条件 OR
+[['A', '=', 1], ['OR', 'B', '=', 2]]
+
+// IN 查询
+[['Id', 'In', ['id1', 'id2', 'id3']]]
+
+// NULL 判断
+[['Field', '=', null]]    // IS NULL
+[['Field', '<>', null]]   // IS NOT NULL
+
+// 分组（括号）：(Age > 18 OR Status = 1)
+[['Name', 'Like', '张'], ['AND', '(', 'Age', '>', 18], ['OR', 'Status', '=', 1, ')']]
+
+// 日期范围
+[['CreateTime', '>=', '2024-01-01'], ['AND', 'CreateTime', '<', '2024-02-01']]
+```
+
+### 旧版 _Where 兼容（V8.Method.ParseWhere）
+
+老版本前端可能传对象格式（`{Name, Value, Type, AndOr, GroupStart, GroupEnd}`）。
+`V8.Method.ParseWhere` 返回统一的 `DiyWhere` 对象集合；它不是“对象转数组”函数。
+
+```javascript
+var objectWhere = V8.Method.ParseWhere(V8.Param._Where);
+V8.FormEngine.GetTableData('Table', { _Where: objectWhere });
+```
+
+合并客户端筛选与接口固定条件时，必须先统一格式，禁止直接把数组条件追加到对象条件集合。
+部分部署按首项类型解析整个集合，混合格式会触发转换失败并退化为空条件，导致统计返回未筛选总数。
+需要兼容混合输入时，逐条调用 `ParseWhere(JSON.stringify([condition]))`，确认每条恰好解析出一个有效条件后，
+再合并为同一种格式；非空输入解析为空、非法操作符或括号不平衡必须返回失败，不能继续执行统计。
+存在顶层 OR 时，还须保证语义为“整个客户端筛选 AND 固定条件”，不能仅在原表达式末尾追加 AND。
+回归至少比较纯数组、纯对象、混合条件、OR/分组、零结果和非法输入。
+
+## 次选：V8.Db.FromSql（仅 SQL 字符串 + AddInParameter）
+
+> **⚠️ FormEngine 优先原则：** 增删改操作（INSERT / UPDATE / DELETE）必须**优先**使用 `V8.FormEngine.AddFormData` / `UptFormData` / `UptFormDataByWhere` / `DelFormData` 等方法。**只有**多表 JOIN、复杂子查询、GROUP BY 聚合等 FormEngine 无法表达的场景才使用 `V8.Db.FromSql`。
+
+> **⚠️ FromSql 调用规则：** `V8.Db.FromSql` 在 V8 中只传 SQL 字符串，不要把动态值作为第二个或后续参数传给 `FromSql`。动态值必须用链式 `.AddInParameter('@p0', value)` 绑定；否则会生成平台不支持的调用签名。
+
+> **共享事务：** `V8.Db` 是主库会话，`V8.Db.FromSql` 不会自动加入接口引擎事务。需要与表单、其它 SQL 或流程共同提交/回滚的操作，必须使用 `V8.DbTrans.FromSql`；依赖本事务尚未提交结果的查询也一样。`V8.FormEngine`、`V8.ApiEngine.Run` 继续显式传第三参数 `V8.DbTrans`。禁止从安全代理取内部事务并自行提交。
+
+```javascript
+// ❌ 错误形态：不要把动态值作为 FromSql 的第二个参数传入
+
+// ✅ 优先：改用 FormEngine（单表增删改查都优先这样写）
+V8.FormEngine.UptFormData('t', { Id: id, A: val1, B: val2 });
+
+// ✅ 必须用原生 SQL 时：FromSql 只传 SQL，参数用 AddInParameter
+V8.DbTrans.FromSql("UPDATE t SET A=@p0, B=@p1 WHERE Id=@p2")
+     .AddInParameter("@p0", val1)
+     .AddInParameter("@p1", val2)
+     .AddInParameter("@p2", id)
+     .ExecuteNonQuery();
+```
+
+当 `_Where` 无法满足复杂查询（多表 JOIN、子查询、聚合统计）时使用 `V8.Db`：
+
+```javascript
+// ✅ 安全：使用 @p0, @p1 占位符，并用 AddInParameter 绑定
+var list = V8.Db.FromSql(
+  'SELECT a.Id, a.Name, b.OrderCount FROM Customer a LEFT JOIN (SELECT CustomerId, COUNT(*) OrderCount FROM OrderHeader GROUP BY CustomerId) b ON a.Id = b.CustomerId WHERE a.Status = @p0'
+).AddInParameter("@p0", 1).ToArray();
+
+// ✅ 安全：多个参数
+var row = V8.Db.FromSql(
+  'SELECT * FROM SysUser WHERE Account = @p0 AND DeptId = @p1'
+).AddInParameter("@p0", V8.Param.account)
+ .AddInParameter("@p1", V8.Param.deptId)
+ .First();
+
+// 统计
+var count = V8.Db.FromSql(
+  'SELECT COUNT(*) FROM OrderHeader WHERE Status = @p0 AND CreateTime >= @p1'
+).AddInParameter("@p0", 1)
+ .AddInParameter("@p1", V8.Param.startDate)
+ .ToScalar();
+
+// 非查询（UPDATE / INSERT / DELETE）
+V8.DbTrans.FromSql(
+  'UPDATE SysUser SET LastLoginTime = @p0 WHERE Id = @p1'
+).AddInParameter("@p0", DateNow('yyyy-MM-dd HH:mm:ss'))
+ .AddInParameter("@p1", V8.CurrentUser.Id)
+ .ExecuteNonQuery();
+```
+
+> 老版本兼容：要把维护接口复制到旧部署时，不要假定 `DateNow` 或 `System.DateTime.Now.ToString(...)` 一定可用。若数据库类型固定，可直接使用该数据库的当前时间表达式（例如 MySQL 的 `NOW()`）；跨数据库代码则应按数据库类型选择表达式或传入平台已确认支持的时间值。
+
+### V8.Db 方法速查
+
+| 方法 | 返回 | 用途 |
+|------|------|------|
+| `.ToArray()` | 数组 | 查询多条 |
+| `.First()` | 对象 \| null | 查询单条 |
+| `.ToScalar()` | 单值 | COUNT / MAX / SUM 等 |
+| `.ExecuteNonQuery()` | 影响行数 | UPDATE / DELETE / INSERT |
+
+> 别名：`.ToList()` = `.ToArray()`，`.ToModel()` = `.First()`，`.ExecuteScalar()` = `.ToScalar()`
+
+### 读写分离
+
+```javascript
+V8.Db.FromSql(...)      // 主库（读写）
+V8.DbRead.FromSql(...)  // 从库（只读，适合报表和大量查询）
+// 未部署读写分离时 V8.DbRead 与 V8.Db 一致
+```
+
+### 跨应用查询（扩展数据库）
+
+```javascript
+var list = V8.Dbs.OracleDB1.FromSql('SELECT * FROM Table WHERE Id = @p0')
+  .AddInParameter("@p0", id)
+  .ToArray();
+
+// 不写入 microi_database：创建仅当前请求使用的临时会话
+var tempDb = V8.Dbs.Open(
+  'SqlServer',
+  'Server=127.0.0.1,1433;Database=app;User Id=user;Password=***;TrustServerCertificate=True;'
+);
+var tempList = tempDb.FromSql('SELECT Id, Name FROM Customer WHERE Status = @p0')
+  .AddInParameter('@p0', 1)
+  .ToArray();
+```
+
+`V8.Dbs.Open` 与保存连接均只支持 Dos.ORM 已认证的 `MySql`、`SqlServer`、`Oracle`、`PostgreSql`、`DaMeng`、`KingBase`。动态连接串只能来自可信服务端密钥或管理员代码，禁止使用 `V8.Param.ConnectionString`，禁止记录或返回。外部 SQL 的表名、列名、排序字段必须来自已校验元数据白名单；动态值继续使用 `AddInParameter`。
+
+MCP 结构发现使用 `microi_inspect_external_database`，安全抽样默认使用只读的 `microi_query_external_database`。当用户明确要求数据库管理级能力时，使用独立的 `microi_execute_external_database`：它只允许后端确认的 `Level >= 9999` 当前用户调用，显式确认后可执行目标数据库账号有权执行的任意 DML、DDL、存储过程、数据库原生命令或多语句。输出行数限制只保护 MCP 传输，不限制数据库副作用；审计只记录 SQL 哈希、长度、模式和结果，不得记录 SQL 正文、连接串或密码。
+
+不要用 `microi_get_db_schema` 读取第三方库，也不要在对话中搬运全库数据；持续同步应创建参数化、分页、幂等的服务端任务。最高权限入口不等于跨租户，也不能超越目标数据库账号自身权限。
+
+## 数据库事务
+
+### 接口引擎事务（自动管理）
+
+```javascript
+// 接口引擎创建 V8.DbTrans；V8.Db 是独立主库会话，不自动加入它：
+// 返回 Code=1 → 自动提交事务
+// 返回 Code≠1 → 自动回滚事务
+// 手动调用 V8.DbTrans.Commit() 或 V8.DbTrans.Rollback() 均无效
+V8.DbTrans.FromSql('UPDATE Account SET Balance = Balance - @p0 WHERE Id = @p1')
+  .AddInParameter("@p0", 100)
+  .AddInParameter("@p1", fromId)
+  .ExecuteNonQuery();
+V8.DbTrans.FromSql('UPDATE Account SET Balance = Balance + @p0 WHERE Id = @p1')
+  .AddInParameter("@p0", 100)
+  .AddInParameter("@p1", toId)
+  .ExecuteNonQuery();
+
+// V8.DbTrans 可传给 FormEngine 和 ApiEngine.Run 共享事务
+V8.FormEngine.UptFormData('Table1', { Id: 'x', Status: 1 }, V8.DbTrans);
+V8.ApiEngine.Run('other-engine', { Id: 'x' }, V8.DbTrans);
+```
+
+### 扩展数据库事务（手动管理）
+
+```javascript
+// 扩展数据库需要手动管理事务
+var exTrans = V8.Dbs.OracleDB1.BeginTransaction();
+try {
+  exTrans.FromSql('UPDATE t1 SET a = @p0 WHERE Id = @p1')
+    .AddInParameter("@p0", 1)
+    .AddInParameter("@p1", id1)
+    .ExecuteNonQuery();
+  exTrans.FromSql('UPDATE t2 SET b = @p0 WHERE Id = @p1')
+    .AddInParameter("@p0", 2)
+    .AddInParameter("@p1", id2)
+    .ExecuteNonQuery();
+  exTrans.Commit();
+} catch (ex) {
+  exTrans.Rollback();
+} finally {
+  exTrans.Close();  // 必须释放事务对象
+}
+```
+
+## 绝对禁止
+
+```javascript
+// ❌ 绝对禁止：拼接 SQL 字符串
+var sql = "SELECT * FROM SysUser WHERE Account = '" + V8.Param.account + "'";
+V8.Db.FromSql(sql).ToArray();  // SQL 注入漏洞！
+
+// ❌ 禁止：动态拼接表名
+var sql = "SELECT * FROM " + V8.Param.tableName + " WHERE Id = @p0";
+
+// ✅ 正确做法：单表查询优先使用 FormEngine + _Where
+var result = V8.FormEngine.GetTableData('SysUser', {
+  _Where: [['Account', '=', V8.Param.account]],
+  _PageSize: 20
+});
+```
+
+## 常见查询模式
+
+### 分页查询
+
+```javascript
+var pageIndex = parseInt(V8.Param.pageIndex) || 1;
+var pageSize = Math.min(parseInt(V8.Param.pageSize) || 20, 100); // 限制最大100
+
+var result = V8.FormEngine.GetTableData('TableName', {
+  _Where: [['Status', '=', 1]],
+  _OrderBy: 'CreateTime',
+  _OrderByType: 'DESC',
+  _PageIndex: pageIndex,
+  _PageSize: pageSize
+});
+
+return { Code: 1, Data: result.Data, Total: result.DataCount };
+```
+
+### 模糊搜索（多字段）
+
+```javascript
+var keyword = V8.Param.keyword;
+var where = [['Status', '=', 1]];
+if (keyword) {
+  where.push(['AND', '(', 'Name', 'Like', keyword]);
+  where.push(['OR', 'Code', 'Like', keyword]);
+  where.push(['OR', 'Phone', 'Like', keyword, ')']);
+}
+
+var result = V8.FormEngine.GetTableData('Customer', {
+  _Where: where,
+  _PageIndex: 1,
+  _PageSize: 20
+});
+```
+
+### 关联查询（SQL JOIN）
+
+```javascript
+var list = V8.Db.FromSql(`
+  SELECT o.Id, o.OrderNo, o.TotalAmount, c.Name AS CustomerName
+  FROM OrderHeader o
+  INNER JOIN Customer c ON o.CustomerId = c.Id
+  WHERE o.Status = @p0 AND o.CreateTime >= @p1
+  ORDER BY o.CreateTime DESC
+`).AddInParameter("@p0", 1)
+  .AddInParameter("@p1", V8.Param.startDate)
+  .ToArray();
+```
+
+## 注意事项
+
+- `V8.Db.FromSql` 只传 SQL 字符串，参数占位符从 `@p0` 开始递增，动态值用 `.AddInParameter("@p0", value)` 绑定
+- 服务端 `V8.FormEngine` 操作默认不触发表单 V8 事件；确需触发时在参数中加 `_InvokeType: 'Client'`
+- 查询结果数量较大时务必分页，`_PageSize` 默认最大 1000
+- `V8.DbRead` 适用于不需要实时性的报表查询
+- 接口引擎的事务由平台自动管理，**不要手动调用** `V8.DbTrans.Commit/Rollback`
+- 扩展数据库事务必须手动调用 `BeginTransaction/Commit/Rollback/Close`