@microi.net/cli 5.5.9 → 5.6.1

package/skills/v8-file-upload/references/progressive-02-office-/346/226/207/344/273/266/345/234/250/347/272/277/347/274/226/350/276/221/347/211/210/346/234/254/345/217/267/350/247/204/345/210/231.md

@@ -3,147 +3,147 @@
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
 
 <!-- microi-progressive:chunk id=v8-file-upload-008 sha256=5e3b59486745d3c54bd8ad25c43cbe2396e6d614394340b93d93794b6df56292 -->
-## Office 文件在线编辑版本号规则
-
-当文件上传控件开启【Office 在线预览】、【允许在线编辑】和【开启 Office 文件版本号】时，前后端必须遵循统一版本规则：
-
-- 新上传的 Office 文件（`pdf/doc/docx/xls/xlsx/ppt/pptx`）要立即写入初始版本 `v1.0.0`，字段 JSON 的 `Path` 指向该原始文件，`Version` 为 `v1.0.0`，`Versions[0]` 保存同一份原始文件路径。
-- 用户进入 OnlyOffice 在线编辑页后，每次手动点击【保存文件】才生成新版本；第一次保存生成 `v1.0.1`，之后依次生成 `v1.0.2`、`v1.0.3`。
-- 未开启版本号时，保存文件直接覆盖当前 `Path` 对应的 HDFS/OSS 源文件。
-- 开启版本号时，保存文件必须生成带版本号后缀的新文件，例如 `contract_v1.0.1.docx`，字段 JSON 的 `Path` 指向最新版本，`Versions` 保留历史版本路径。
-- 在线 Office 路由和文件上传字段都要能读取 `Versions`，用于右上角切换历史版本预览/编辑。
-
-### OnlyOffice 服务端取文件与匿名预览规则
-
-- OnlyOffice 文档服务器会在服务端再次下载文件。浏览器可以下载但 OnlyOffice 提示“下载失败”时，优先检查生成地址是否为 `localhost/127.0.0.1/内网域名`。
-- OnlyOffice 可能先对文档地址发起 `HEAD` 探测。响应文件接口除了 `GET 200`，还必须让 `HEAD` 返回相同的 `Content-Type/Content-Length/Content-Disposition`，不能返回 `405`。
-- 私有文件在线预览调用 `/apiengine/platform-private-file-url` 时传 `ForOfficePreview:true` 和权威资源上下文。审计代理应优先使用租户系统配置的公网 `ApiBase`，但仍把真实对象存储签名地址保存在共享 Redis ticket 中，禁止直接返回真实签名地址；旧 Controller 路由只作兼容转发。
-- `/online-office` 可以匿名访问。公有存储模式只允许当前 `OsClient` 目录下的 `filePathName`；接口模式通过 `fileUrl` 接收当前平台正式 `ApiBase`，或由同端口本地后端读取的 loopback `/apiengine/...` 响应文件地址，并要求 URL 显式携带当前 `OsClient`。两种模式都拒绝跨租户、路径穿越和任意第三方 URL；`isPrivate=1` 必须登录。
-- 匿名接口引擎预览不要求 V8 代码先上传 HDFS：接口开启【响应文件】和【允许匿名】后，完整地址 URL 编码传给 `fileUrl`，同时传 `fileName/fileType`。页面通过匿名安全中转让当前后端限域读取源文件，并以确定性路径缓存到当前租户公有对象存储；OnlyOffice 只接收公网 `FileServer` 地址。loopback 仅允许同端口本地后端访问，禁止开放任意 URL 代理。
-- `canEdit` 只是前端请求参数，不是权限。最终编辑条件必须是“有效登录态 && canEdit=true”；匿名始终只读，不能因 URL 参数放开编辑。
-- 匿名预览页隐藏左侧菜单、顶部导航和页签；已登录用户保持原系统布局。
-- 匿名导出响应接口应配置频率限制或保证生成逻辑足够轻量，不能让单个公网 URL 无界消耗 CPU/内存；如业务仍需要落盘缓存，缓存事实必须进入共享 Redis/HDFS，不能用进程内变量。
-
-字段 JSON 示例：
-
-```json
-{
-  "Name": "contract.docx",
-  "Path": "/tenant_demo/file/20260622/contract_v1.0.1.docx",
-  "Version": "v1.0.1",
-  "Versions": [
-    { "Version": "v1.0.0", "Name": "contract.docx", "Path": "/tenant_demo/file/20260622/contract.docx", "IsLatest": false },
-    { "Version": "v1.0.1", "Name": "contract_v1.0.1.docx", "Path": "/tenant_demo/file/20260622/contract_v1.0.1.docx", "IsLatest": true }
-  ]
-}
-```
-
+## Office 文件在线编辑版本号规则
+
+当文件上传控件开启【Office 在线预览】、【允许在线编辑】和【开启 Office 文件版本号】时，前后端必须遵循统一版本规则：
+
+- 新上传的 Office 文件（`pdf/doc/docx/xls/xlsx/ppt/pptx`）要立即写入初始版本 `v1.0.0`，字段 JSON 的 `Path` 指向该原始文件，`Version` 为 `v1.0.0`，`Versions[0]` 保存同一份原始文件路径。
+- 用户进入 OnlyOffice 在线编辑页后，每次手动点击【保存文件】才生成新版本；第一次保存生成 `v1.0.1`，之后依次生成 `v1.0.2`、`v1.0.3`。
+- 未开启版本号时，保存文件直接覆盖当前 `Path` 对应的 HDFS/OSS 源文件。
+- 开启版本号时，保存文件必须生成带版本号后缀的新文件，例如 `contract_v1.0.1.docx`，字段 JSON 的 `Path` 指向最新版本，`Versions` 保留历史版本路径。
+- 在线 Office 路由和文件上传字段都要能读取 `Versions`，用于右上角切换历史版本预览/编辑。
+
+### OnlyOffice 服务端取文件与匿名预览规则
+
+- OnlyOffice 文档服务器会在服务端再次下载文件。浏览器可以下载但 OnlyOffice 提示“下载失败”时，优先检查生成地址是否为 `localhost/127.0.0.1/内网域名`。
+- OnlyOffice 可能先对文档地址发起 `HEAD` 探测。响应文件接口除了 `GET 200`，还必须让 `HEAD` 返回相同的 `Content-Type/Content-Length/Content-Disposition`，不能返回 `405`。
+- 私有文件在线预览调用 `/apiengine/platform-private-file-url` 时传 `ForOfficePreview:true` 和权威资源上下文。审计代理应优先使用租户系统配置的公网 `ApiBase`，但仍把真实对象存储签名地址保存在共享 Redis ticket 中，禁止直接返回真实签名地址；旧 Controller 路由只作兼容转发。
+- `/online-office` 可以匿名访问。公有存储模式只允许当前 `OsClient` 目录下的 `filePathName`；接口模式通过 `fileUrl` 接收当前平台正式 `ApiBase`，或由同端口本地后端读取的 loopback `/apiengine/...` 响应文件地址，并要求 URL 显式携带当前 `OsClient`。两种模式都拒绝跨租户、路径穿越和任意第三方 URL；`isPrivate=1` 必须登录。
+- 匿名接口引擎预览不要求 V8 代码先上传 HDFS：接口开启【响应文件】和【允许匿名】后，完整地址 URL 编码传给 `fileUrl`，同时传 `fileName/fileType`。页面通过匿名安全中转让当前后端限域读取源文件，并以确定性路径缓存到当前租户公有对象存储；OnlyOffice 只接收公网 `FileServer` 地址。loopback 仅允许同端口本地后端访问，禁止开放任意 URL 代理。
+- `canEdit` 只是前端请求参数，不是权限。最终编辑条件必须是“有效登录态 && canEdit=true”；匿名始终只读，不能因 URL 参数放开编辑。
+- 匿名预览页隐藏左侧菜单、顶部导航和页签；已登录用户保持原系统布局。
+- 匿名导出响应接口应配置频率限制或保证生成逻辑足够轻量，不能让单个公网 URL 无界消耗 CPU/内存；如业务仍需要落盘缓存，缓存事实必须进入共享 Redis/HDFS，不能用进程内变量。
+
+字段 JSON 示例：
+
+```json
+{
+  "Name": "contract.docx",
+  "Path": "/tenant_demo/file/20260622/contract_v1.0.1.docx",
+  "Version": "v1.0.1",
+  "Versions": [
+    { "Version": "v1.0.0", "Name": "contract.docx", "Path": "/tenant_demo/file/20260622/contract.docx", "IsLatest": false },
+    { "Version": "v1.0.1", "Name": "contract_v1.0.1.docx", "Path": "/tenant_demo/file/20260622/contract_v1.0.1.docx", "IsLatest": true }
+  ]
+}
+```
+
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-file-upload-009 sha256=50fba71370f45de3dd677f5731f3956c328a8d3b1ca2125b853128067f9af40a -->
-## ImgUpload / FileUpload 字段值兼容规则
-
-`ImgUpload` 不能假设只是一种值结构。PC 表单、移动端、旧数据、单图/多图、公开/私有桶会混合出现以下格式：
-
-| 场景 | 可能的值 |
-|------|----------|
-| 空值/占位 | `''`、`null`、`undefined`、`'[]'`、`'null'`、`'正在上传中...'` |
-| 旧单图 | `'/upload/xxx/a.png'`、`'https://cdn/a.png'` |
-| 新单图 | `{ Path, Name, Size, Id, State }` 或 JSON 字符串 `'{"Path":"..."}'` |
-| 多图 | `[{ Path, Name, Id, State }]` 或 JSON 字符串 `'[{"Path":"..."}]'` |
-| 其它兼容字段 | `Path`、`FilePathName`、`FullPath`、`Url`、`url`、`src` |
-
-任何端（PC、uni-app、H5、小程序）渲染图片前都必须先做“归一化 -> 取 Path -> 转最终 URL”，不要直接 `JSON.parse` 后只处理数组，也不要直接把字段值拼到 `FileServer`。
-
-推荐归一化：
-
-```javascript
-function normalizeUploadValue(value) {
-  if (value == null || value === '' || value === 'undefined' || value === 'null') return [];
-  if (value === '正在上传中...' || value === '[]' || value === '[ ]') return [];
-
-  var raw = value;
-  if (typeof raw === 'string') {
-    var s = raw.trim();
-    if ((s.indexOf('{') === 0 || s.indexOf('[') === 0)) {
-      try { raw = JSON.parse(s); } catch (e) { raw = s; }
-    } else {
-      raw = s;
-    }
-  }
-
-  if (Array.isArray(raw)) {
-    return raw.map(normalizeUploadItem).filter(function (it) { return !!it.Path; });
-  }
-
-  var one = normalizeUploadItem(raw);
-  return one.Path ? [one] : [];
-}
-
-function normalizeUploadItem(item) {
-  if (!item) return {};
-  if (typeof item === 'string') {
-    return { Path: item, Name: item.split('/').pop() || item, State: 1 };
-  }
-  if (typeof item === 'object') {
-    var path = item.Path || item.FilePathName || item.FullPath || item.Url || item.url || item.src || '';
-    return {
-      Id: item.Id || item.id || '',
-      Name: item.Name || item.FileName || item.name || (path ? String(path).split('/').pop() : ''),
-      Size: item.Size || item.size || '',
-      CreateTime: item.CreateTime || item.createTime || '',
-      State: item.State == null ? 1 : item.State,
-      Path: path
-    };
-  }
-  return {};
-}
-```
-
-公开图片 URL 解析原则与 `Microi.Client/src/utils/diy.common.js` 的 `GetServerPath` 一致：
-
-```javascript
-function publicUploadUrl(path) {
-  if (!path) return '';
-  var s = String(path).trim();
-  if (!s || s === '正在上传中...') return '';
-  if (s.indexOf('.') === 0) return s;              // ./static/img/loading.gif 等本地静态资源
-  if (/^(https?:|data:|blob:)/i.test(s)) return s; // 已经是最终 URL
-  if (s.indexOf('{') === 0 || s.indexOf('[') === 0) {
-    var list = normalizeUploadValue(s);
-    s = list.length ? list[0].Path : '';
-  }
-  if (!s) return '';
-  return String(V8.SysConfig.FileServer || '').replace(/\/+$/, '') + '/' + s.replace(/^\/+/, '');
-}
-```
-
-私有桶（`Limit === true`）不要拼 `FileServer`，必须把归一化后的 `Path` 传给 `V8.Method.GetPrivateFileUrl({ FilePathName: path })` 或后端签名接口换临时 URL。
+## ImgUpload / FileUpload 字段值兼容规则
+
+`ImgUpload` 不能假设只是一种值结构。PC 表单、移动端、旧数据、单图/多图、公开/私有桶会混合出现以下格式：
+
+| 场景 | 可能的值 |
+|------|----------|
+| 空值/占位 | `''`、`null`、`undefined`、`'[]'`、`'null'`、`'正在上传中...'` |
+| 旧单图 | `'/upload/xxx/a.png'`、`'https://cdn/a.png'` |
+| 新单图 | `{ Path, Name, Size, Id, State }` 或 JSON 字符串 `'{"Path":"..."}'` |
+| 多图 | `[{ Path, Name, Id, State }]` 或 JSON 字符串 `'[{"Path":"..."}]'` |
+| 其它兼容字段 | `Path`、`FilePathName`、`FullPath`、`Url`、`url`、`src` |
+
+任何端（PC、uni-app、H5、小程序）渲染图片前都必须先做“归一化 -> 取 Path -> 转最终 URL”，不要直接 `JSON.parse` 后只处理数组，也不要直接把字段值拼到 `FileServer`。
+
+推荐归一化：
+
+```javascript
+function normalizeUploadValue(value) {
+  if (value == null || value === '' || value === 'undefined' || value === 'null') return [];
+  if (value === '正在上传中...' || value === '[]' || value === '[ ]') return [];
+
+  var raw = value;
+  if (typeof raw === 'string') {
+    var s = raw.trim();
+    if ((s.indexOf('{') === 0 || s.indexOf('[') === 0)) {
+      try { raw = JSON.parse(s); } catch (e) { raw = s; }
+    } else {
+      raw = s;
+    }
+  }
+
+  if (Array.isArray(raw)) {
+    return raw.map(normalizeUploadItem).filter(function (it) { return !!it.Path; });
+  }
+
+  var one = normalizeUploadItem(raw);
+  return one.Path ? [one] : [];
+}
+
+function normalizeUploadItem(item) {
+  if (!item) return {};
+  if (typeof item === 'string') {
+    return { Path: item, Name: item.split('/').pop() || item, State: 1 };
+  }
+  if (typeof item === 'object') {
+    var path = item.Path || item.FilePathName || item.FullPath || item.Url || item.url || item.src || '';
+    return {
+      Id: item.Id || item.id || '',
+      Name: item.Name || item.FileName || item.name || (path ? String(path).split('/').pop() : ''),
+      Size: item.Size || item.size || '',
+      CreateTime: item.CreateTime || item.createTime || '',
+      State: item.State == null ? 1 : item.State,
+      Path: path
+    };
+  }
+  return {};
+}
+```
+
+公开图片 URL 解析原则与 `Microi.Client/src/utils/diy.common.js` 的 `GetServerPath` 一致：
+
+```javascript
+function publicUploadUrl(path) {
+  if (!path) return '';
+  var s = String(path).trim();
+  if (!s || s === '正在上传中...') return '';
+  if (s.indexOf('.') === 0) return s;              // ./static/img/loading.gif 等本地静态资源
+  if (/^(https?:|data:|blob:)/i.test(s)) return s; // 已经是最终 URL
+  if (s.indexOf('{') === 0 || s.indexOf('[') === 0) {
+    var list = normalizeUploadValue(s);
+    s = list.length ? list[0].Path : '';
+  }
+  if (!s) return '';
+  return String(V8.SysConfig.FileServer || '').replace(/\/+$/, '') + '/' + s.replace(/^\/+/, '');
+}
+```
+
+私有桶（`Limit === true`）不要拼 `FileServer`，必须把归一化后的 `Path` 传给 `V8.Method.GetPrivateFileUrl({ FilePathName: path })` 或后端签名接口换临时 URL。
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-file-upload-010 sha256=f34d476435c3a8321df017b481771d757f580c8d75f7648fdd54ee1c624d116c -->
-## 安全注意
-
-- ❌ 不要让前端任意指定 `Path`（路径穿越风险），只允许后端固定路径
-- ❌ 不要不校验文件类型 / 大小：根据 ContentType + 后缀双重校验
-- ❌ 不要把持有 Token 当成私有文件授权；普通用户必须证明菜单、记录和字段引用关系
-- ❌ 不要向普通角色开放文件列表、移动、重命名、删除、覆盖等管理接口；这些接口仅限 `Level >= 9999`
-- ❌ 不要开启 UEditor `catchimage` 远程抓图；默认关闭，确需采集时另建带域名白名单、DNS/IP 校验、禁止跳转、超时和响应上限的受控接口
-- ❌ 敏感文件（合同、身份证）必须用私有桶 `Limit: true`
-- ✅ 公有桶 URL 可缓存到前端，私有桶临时 URL 每次重新生成
-- ✅ 删除数据时同步清理 HDFS 文件（避免存储泄漏）
-- ✅ Excel/PDF 等导出文件通过【响应文件】配置返回，不要拼接到 JSON 数据里
-
-### 安全升级兼容
-
-- 旧页面如果只传 `FilePathName` 获取私有地址，升级后普通帐号会失败；必须补齐 `FormEngineKey`、`FormDataId`、`FieldId`、`SysMenuId`，不能改回匿名或放开管理权限。
-- 旧自定义上传若依赖普通用户设置 `Limit:false` 或任意多级 `Path`，应改成私有上传；公开资源改走受控发布流程。
-- 历史公有文件不会自动变成私有文件。迁移时先复制对象、验证私有读取，再停止旧公有访问；数据库继续保存租户内相对路径，不能持久化临时 URL。
-- 上线验收至少覆盖：普通角色跨菜单/跨记录/跨字段读取被拒绝、单文件/单请求/数量限制、帐号与租户配额、Redis 故障失败关闭、多节点并发、公有匿名 `200`、私有匿名 `403`、授权私有访问 `200`。
-
-### 复盘：ZIP 发布端与安装端 SHA256 口径不一致
-
-- 触发场景：应用包已成功生成 ZIP 和摘要，但安装端下载 ZIP 后调用不存在的哈希辅助函数，或尝试通过当前 V8 环境不可用的 `.NET SHA256.Create()` 校验，导致安装中断。
-- 根因：发布端实际使用 `V8.EncryptHelper.Sha256Hex(FileByteBase64)`，安装端却按原始字节设计了另一套实现，函数名称、输入数据和运行时能力均未对齐。
-- 通用规则：文件摘要必须在包清单中记录算法和输入口径；当前应用 ZIP 统一使用 `SHA256-Base64Text`，发布端与安装端都对同一份 Base64 文本调用 `V8.EncryptHelper.Sha256Hex`。禁止仅凭函数名推测算法，也不要在未验证 V8 互操作能力时直接实例化 `.NET` 加密对象。
-- 自动化检查：生成同时包含源码 ZIP、编译 ZIP 的应用包，再从官方地址下载并安装；分别篡改 Base64 文本和摘要，正常包应安装成功，两个篡改包都必须在解压前被拒绝。
+## 安全注意
+
+- ❌ 不要让前端任意指定 `Path`（路径穿越风险），只允许后端固定路径
+- ❌ 不要不校验文件类型 / 大小：根据 ContentType + 后缀双重校验
+- ❌ 不要把持有 Token 当成私有文件授权；普通用户必须证明菜单、记录和字段引用关系
+- ❌ 不要向普通角色开放文件列表、移动、重命名、删除、覆盖等管理接口；这些接口仅限 `Level >= 9999`
+- ❌ 不要开启 UEditor `catchimage` 远程抓图；默认关闭，确需采集时另建带域名白名单、DNS/IP 校验、禁止跳转、超时和响应上限的受控接口
+- ❌ 敏感文件（合同、身份证）必须用私有桶 `Limit: true`
+- ✅ 公有桶 URL 可缓存到前端，私有桶临时 URL 每次重新生成
+- ✅ 删除数据时同步清理 HDFS 文件（避免存储泄漏）
+- ✅ Excel/PDF 等导出文件通过【响应文件】配置返回，不要拼接到 JSON 数据里
+
+### 安全升级兼容
+
+- 旧页面如果只传 `FilePathName` 获取私有地址，升级后普通帐号会失败；必须补齐 `FormEngineKey`、`FormDataId`、`FieldId`、`SysMenuId`，不能改回匿名或放开管理权限。
+- 旧自定义上传若依赖普通用户设置 `Limit:false` 或任意多级 `Path`，应改成私有上传；公开资源改走受控发布流程。
+- 历史公有文件不会自动变成私有文件。迁移时先复制对象、验证私有读取，再停止旧公有访问；数据库继续保存租户内相对路径，不能持久化临时 URL。
+- 上线验收至少覆盖：普通角色跨菜单/跨记录/跨字段读取被拒绝、单文件/单请求/数量限制、帐号与租户配额、Redis 故障失败关闭、多节点并发、公有匿名 `200`、私有匿名 `403`、授权私有访问 `200`。
+
+### 复盘：ZIP 发布端与安装端 SHA256 口径不一致
+
+- 触发场景：应用包已成功生成 ZIP 和摘要，但安装端下载 ZIP 后调用不存在的哈希辅助函数，或尝试通过当前 V8 环境不可用的 `.NET SHA256.Create()` 校验，导致安装中断。
+- 根因：发布端实际使用 `V8.EncryptHelper.Sha256Hex(FileByteBase64)`，安装端却按原始字节设计了另一套实现，函数名称、输入数据和运行时能力均未对齐。
+- 通用规则：文件摘要必须在包清单中记录算法和输入口径；当前应用 ZIP 统一使用 `SHA256-Base64Text`，发布端与安装端都对同一份 Base64 文本调用 `V8.EncryptHelper.Sha256Hex`。禁止仅凭函数名推测算法，也不要在未验证 V8 互操作能力时直接实例化 `.NET` 加密对象。
+- 自动化检查：生成同时包含源码 ZIP、编译 ZIP 的应用包，再从官方地址下载并安装；分别篡改 Base64 文本和摘要，正常包应安装成功，两个篡改包都必须在解压前被拒绝。
 <!-- /microi-progressive:chunk -->

package/skills/v8-formengine-http/SKILL.md

@@ -55,50 +55,68 @@ description: 移动端 / 外部系统通过 HTTP 直接调用 Microi FormEngine
 
 URL 中的表名小写最稳，平台不区分大小写。匿名版本目前**只在形式一上有**（`GetTableDataAnonymous` 等）。
 
-## 请求 Header
-
-| Header | 是否必填 | 说明 |
-| --- | --- | --- |
-| `Content-Type` | 必填 | `application/json` 推荐 |
-| `OsClient`     | 必填 | 租户标识；亦可放 querystring `?OsClient=xxx` 或 body |
-| `authorization` | 鉴权接口必填 | `Bearer <Token>`；兼容旧客户端的 `Token` Header |
-| `did` | 登录及鉴权接口推荐 | 当前终端稳定设备标识；首次生成后持久化，不能每次请求随机变化 |
-
-注意：上表是 FormEngine 路由约定。ApiEngine HTTP 复测和移动端 `callEngine` 使用稳定路径 `/apiengine/{key}`，租户通过唯一的 `osclient` Header 传递，JSON/Form Body 可冗余携带 `OsClient`。普通 POST/PUT/PATCH/DELETE 禁止追加 `--OsClient--...--`；特殊路径只用于无法设置 Header/Form/Query 的 GET/HEAD 或第三方回调。
-
-平台可能通过响应 Header `authorization`（兼容 `token`）续签或替换 Token。客户端必须立即保存新 Token，并保证并发旧响应不能覆盖已经写入的新 Token。跨域部署还必须在 CORS 中暴露 `authorization`、`token` 等需要读取的响应 Header。Token 属于凭据，禁止写入 URL、日志、错误上报和页面源码。
-
-## FormEngine 数据授权边界
-
-“Token 有效”只代表身份有效，不代表可以访问任意表。客户端 FormEngine CRUD 还会经过表、菜单、角色和行级范围授权：
-
-1. 受保护的平台敏感表优先拒绝普通用户；匿名接口也不能绕过。
-2. 标准菜单页应携带真实 `_SysMenuId`，或使用 `ModuleEngineKey`。服务器会严格校验该菜单是否绑定目标表、当前角色是否拥有菜单及对应操作权限；列表、计数、导出追加该菜单的数据范围。
-3. 列表、写入、导入、导出显式传错 `_SysMenuId` / `ModuleEngineKey` 会直接拒绝，不会降级为其它菜单或表权限。单行详情只要当前角色拥有至少一个直接绑定同表的菜单（或精确表级 `Read` 权限）即可读取，不应用菜单 `SqlWhere` / `SqlJoin`；旧客户端携带过期菜单 Id 时也按该规则恢复。
-4. 为兼容历史前端 V8/外部客户端，普通 CRUD 未传菜单上下文时，服务器会从当前用户的版本化授权缓存中查找“当前角色已获授权且直接绑定目标表”的菜单。无菜单列表仍安全合并候选菜单的数据范围，不能靠漏参绕过；详情按同表菜单访问，写入按 `Add/Edit/Del` 动作权限。也可以使用角色的精确表级 `Read/Add/Edit/Del` 授权。`JoinTables` 不是独立访问授权。
-5. 导入、导出必须锚定具体菜单，不能依赖无菜单兼容推断。
-6. `TableChild` 子表委托由标准表单运行时生成 `_TableChildAuth`，服务器重新校验父菜单、父记录、字段绑定、子表和外键，并强制父子范围。它是内部不透明上下文，外部客户端不要手工拼装。
-7. `_InvokeType:'Client'` 只决定是否执行客户端语义的表单事件，不是权限开关。可信服务器调用标记也不能通过 HTTP Body 伪造。
+## 请求 Header
+
+| Header | 是否必填 | 说明 |
+| --- | --- | --- |
+| `Content-Type` | 必填 | `application/json` 推荐 |
+| `OsClient`     | 必填 | 租户标识；亦可放 querystring `?OsClient=xxx` 或 body |
+| `authorization` | 鉴权接口必填 | `Bearer <Token>`；兼容旧客户端的 `Token` Header |
+| `did` | 登录及鉴权接口推荐 | 当前终端稳定设备标识；首次生成后持久化，不能每次请求随机变化 |
+
+注意：上表是 FormEngine 路由约定。ApiEngine HTTP 复测和移动端 `callEngine` 使用稳定路径 `/apiengine/{key}`，租户通过唯一的 `osclient` Header 传递，JSON/Form Body 可冗余携带 `OsClient`。普通 POST/PUT/PATCH/DELETE 禁止追加 `--OsClient--...--`；特殊路径只用于无法设置 Header/Form/Query 的 GET/HEAD 或第三方回调。
+
+平台可能通过响应 Header `authorization`（兼容 `token`）续签或替换 Token。客户端必须立即保存新 Token，并保证并发旧响应不能覆盖已经写入的新 Token。跨域部署还必须在 CORS 中暴露 `authorization`、`token` 等需要读取的响应 Header。Token 属于凭据，禁止写入 URL、日志、错误上报和页面源码。
+
+## FormEngine 数据授权边界
+
+“Token 有效”只代表身份有效，不代表可以访问任意表。客户端 FormEngine CRUD 还会经过表、菜单、角色和行级范围授权：
+
+1. 受保护的平台敏感表优先拒绝普通用户；匿名接口也不能绕过。
+2. 标准菜单页应携带真实 `_SysMenuId`，或使用 `ModuleEngineKey`。服务器会严格校验该菜单是否绑定目标表、当前角色是否拥有菜单及对应操作权限；列表、计数、导出追加该菜单的数据范围。
+3. 列表、写入、导入、导出显式传错 `_SysMenuId` / `ModuleEngineKey` 会直接拒绝，不会降级为其它菜单或表权限。单行详情只要当前角色拥有至少一个直接绑定同表的菜单（或精确表级 `Read` 权限）即可读取，不应用菜单 `SqlWhere` / `SqlJoin`；旧客户端携带过期菜单 Id 时也按该规则恢复。
+4. 为兼容历史前端 V8/外部客户端，普通 CRUD 未传菜单上下文时，服务器会从当前用户的版本化授权缓存中查找“当前角色已获授权且直接绑定目标表”的菜单。无菜单列表仍安全合并候选菜单的数据范围，不能靠漏参绕过；详情按同表菜单访问，写入按 `Add/Edit/Del` 动作权限。也可以使用角色的精确表级 `Read/Add/Edit/Del` 授权。`JoinTables` 不是独立访问授权。
+5. 导入、导出必须锚定具体菜单，不能依赖无菜单兼容推断。
+6. `TableChild` 子表委托由标准表单运行时生成 `_TableChildAuth`，服务器重新校验父菜单、父记录、字段绑定、子表和外键，并强制父子范围。它是内部不透明上下文，外部客户端不要手工拼装。
+7. `_InvokeType:'Client'` 只决定是否执行客户端语义的表单事件，不是权限开关。可信服务器调用标记也不能通过 HTTP Body 伪造。
+
+因此：
+
+- 标准模块、详情页和其字段元数据请求优先传真实 `_SysMenuId`，使服务器确定菜单绑定与操作权限；其中只有列表、计数、导出应用菜单查询范围。
+- 历史无 `_SysMenuId` 请求可继续工作，但前提是当前用户确实拥有目标表对应的菜单或精确表权限；不能把兼容推断理解为“有 Token 即可查表”。
+- 历史单表字段请求可在菜单缺失/过期时回退到当前角色另一个引用同表的已授权菜单；`GetDiyFieldByDiyTables` 批量字段请求按“第一张主表必须授权、后续表逐张授权并过滤”兼容。后续未授权/保护表不会导致主表失败，也不会返回其字段配置；这些规则不授予数据行权限。
+- 表单设计器 `/api/DiyField/UptDiyFieldList` 属于 `Level >= 9999` 控制面：外层一次授权、字段归属校验、同事务批量更新、批次末一次缓存/版本刷新。禁止在 100+ 字段循环中逐条调用完整 `UptFormDataAsync("diy_field", ...)`，否则会重复执行授权、V8、日志及 SaaS/Redis 缓存工作。
+- 接口引擎内的 `V8.FormEngine.*` 属于服务器端调用，不要求客户端 `_SysMenuId`。但接口引擎本身必须正确限制谁能调用，并在服务端校验业务对象范围，不能把表名和条件原样交给不可信客户端。
+- 客户端新增、修改、删除分别校验真实菜单的 `Add`、`Edit`、`Del` 权限。`SqlWhere` / `SqlJoin` 是模块查询过滤，不是行级写权限：不得把它们追加到写入 SQL，也不得因查询包含 Join 拒绝已获授权的主表写入。
+- 进入 `SubmitBeforeServerV8` / `SubmitAfterServerV8` 后，事件内 FormEngine/数据库调用与接口引擎一样属于可信服务器执行，可实现当前租户内的跨表事务。需要“只能修改本人数据”等业务约束以及归属字段写入时，应在这里或专用接口引擎中完成。
+
+## 原生详情关联数据
 
-因此：
+- `POST /api/FormEngine/GetFormRelatedData` 接收父表 `ParentFormEngineKey`、父记录
+  `ParentTableRowId`、真实 `_SysMenuId`，以及固定 `RelatedType`：
+  `Counts/DataLog/DataComment/DataVersion`。身份、租户来自 DiyToken，不能透传请求的可信标记。
+- `AuthorizeClientTableOperationAsync(..., 'Read')` 仅完成表/菜单授权，不证明父行可读。
+  必须再执行 Client `GetFormDataAsync`，让父记录不存在或 `ServerDataV8` 拒绝阻断关联查询。
+- 固定辅助表查询使用服务端新构造的 CLR 参数与可信来源；`JObject` 中写
+  `_InvokeType:'Server'` 仍是非可信参数。不得通过给普通角色开放辅助表权限来修复此类拒绝。
+- 日志和版本返回固定元信息，`DataAppend.HistoryContentMode='MetadataOnly'`；
+  当前行脱敏不授予历史 `Content/Data` 原文。客户端不能据元信息开放预览、对比、加载。
+- 评论必须同时按真实 `TableId + TableRowId` 过滤。缺少 `TableId` 时，Counts 返回
+  `DataComment=null`，以 `DataAppend.DataCommentUnavailableReason/Message` 显式说明；
+  评论详情失败。不能按单键兼容、猜旧数据归属、假报零条或承诺不存在的可用升级包。
+- 回归须区分实际 HTTP 与替身组件测试：普通角色父行可读、同菜单另一归属被 DataFilter
+  拒绝、父 Id 不存在、同 Id 不同表、伪造租户/类型/可信标记、历史敏感原文不返回都需验收。
+  安全评论绑定写入及旧数据处理须独立交付后才能宣称评论完整可用。
 
-- 标准模块、详情页和其字段元数据请求优先传真实 `_SysMenuId`，使服务器确定菜单绑定与操作权限；其中只有列表、计数、导出应用菜单查询范围。
-- 历史无 `_SysMenuId` 请求可继续工作，但前提是当前用户确实拥有目标表对应的菜单或精确表权限；不能把兼容推断理解为“有 Token 即可查表”。
-- 历史单表字段请求可在菜单缺失/过期时回退到当前角色另一个引用同表的已授权菜单；`GetDiyFieldByDiyTables` 批量字段请求按“第一张主表必须授权、后续表逐张授权并过滤”兼容。后续未授权/保护表不会导致主表失败，也不会返回其字段配置；这些规则不授予数据行权限。
-- 表单设计器 `/api/DiyField/UptDiyFieldList` 属于 `Level >= 9999` 控制面：外层一次授权、字段归属校验、同事务批量更新、批次末一次缓存/版本刷新。禁止在 100+ 字段循环中逐条调用完整 `UptFormDataAsync("diy_field", ...)`，否则会重复执行授权、V8、日志及 SaaS/Redis 缓存工作。
-- 接口引擎内的 `V8.FormEngine.*` 属于服务器端调用，不要求客户端 `_SysMenuId`。但接口引擎本身必须正确限制谁能调用，并在服务端校验业务对象范围，不能把表名和条件原样交给不可信客户端。
-- 客户端新增、修改、删除分别校验真实菜单的 `Add`、`Edit`、`Del` 权限。`SqlWhere` / `SqlJoin` 是模块查询过滤，不是行级写权限：不得把它们追加到写入 SQL，也不得因查询包含 Join 拒绝已获授权的主表写入。
-- 进入 `SubmitBeforeServerV8` / `SubmitAfterServerV8` 后，事件内 FormEngine/数据库调用与接口引擎一样属于可信服务器执行，可实现当前租户内的跨表事务。需要“只能修改本人数据”等业务约束以及归属字段写入时，应在这里或专用接口引擎中完成。
-
-## Body 结构（POST JSON）
-
-```jsonc
-{
-  "OsClient": "demo",
-  "FormEngineKey": "mall_product",   // 形式一必填；形式二可选（已在 URL 中）
-  "_SysMenuId": "目标菜单Id",         // 标准模块推荐；必须是真实绑定目标表且当前角色有权访问的菜单
-  "_Where": [["Status","=","OnSale"], ["AND","Stock",">",0]],
-  "_SelectFields": ["Id","Title","CurrentPrice","MainImg"],
+## Body 结构（POST JSON）
+
+```jsonc
+{
+  "OsClient": "demo",
+  "FormEngineKey": "mall_product",   // 形式一必填；形式二可选（已在 URL 中）
+  "_SysMenuId": "目标菜单Id",         // 标准模块推荐；必须是真实绑定目标表且当前角色有权访问的菜单
+  "_Where": [["Status","=","OnSale"], ["AND","Stock",">",0]],
+  "_SelectFields": ["Id","Title","CurrentPrice","MainImg"],
   "_OrderBy": "SoldCount",
   "_OrderByType": "DESC",
   "_PageIndex": 1,
@@ -108,7 +126,7 @@ URL 中的表名小写最稳，平台不区分大小写。匿名版本目前**
 
 写操作（Add/Upt）将业务字段平铺到 body：
 ```jsonc
-{ "OsClient":"demo", "FormEngineKey":"biz_order",
+{ "OsClient":"demo", "FormEngineKey":"biz_order",
   "Id":"01ABC...", "Quantity": 2, "Selected": 1 }
 ```
 
@@ -127,63 +145,63 @@ URL 中的表名小写最稳，平台不区分大小写。匿名版本目前**
 ## 客户端封装样板（uni-app）
 
 ```javascript
-const BASE = 'https://api.itdos.com';
-const OS_CLIENT = runtimeConfig.osClient;
-const TOKEN_KEY = 'mall_token';
-const DID_KEY = 'mall_did';
-
-function normalizeToken(value) {
-  return String(value || '').replace(/^Bearer\s+/i, '').trim();
-}
-function getToken() {
-  return normalizeToken(uni.getStorageSync(TOKEN_KEY));
-}
-function getDid() {
-  let did = uni.getStorageSync(DID_KEY);
-  if (!did) {
-    did = `uni-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    uni.setStorageSync(DID_KEY, did);
-  }
-  return did;
-}
-function readHeader(headers, name) {
-  const key = Object.keys(headers || {}).find(k => k.toLowerCase() === name);
-  return key ? headers[key] : '';
-}
-function applyResponseToken(headers, requestToken) {
-  const responseToken = normalizeToken(
-    readHeader(headers, 'authorization') || readHeader(headers, 'token')
-  );
-  if (!responseToken) return;
-
-  const currentToken = getToken();
-  // 旧请求若只回显旧 Token，不得覆盖其它请求/标签页已保存的新 Token。
-  if (currentToken && requestToken && currentToken !== requestToken && responseToken === requestToken) {
-    return;
-  }
-  uni.setStorageSync(TOKEN_KEY, responseToken);
-}
-
-function formEngineRequest(action, table, body = {}) {
-  return new Promise((resolve, reject) => {
-    const requestToken = getToken();
-    uni.request({
-      url: `${BASE}/api/formengine/${action}-${table}`,
-      method: 'POST',
+const BASE = 'https://api.itdos.com';
+const OS_CLIENT = runtimeConfig.osClient;
+const TOKEN_KEY = 'mall_token';
+const DID_KEY = 'mall_did';
+
+function normalizeToken(value) {
+  return String(value || '').replace(/^Bearer\s+/i, '').trim();
+}
+function getToken() {
+  return normalizeToken(uni.getStorageSync(TOKEN_KEY));
+}
+function getDid() {
+  let did = uni.getStorageSync(DID_KEY);
+  if (!did) {
+    did = `uni-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    uni.setStorageSync(DID_KEY, did);
+  }
+  return did;
+}
+function readHeader(headers, name) {
+  const key = Object.keys(headers || {}).find(k => k.toLowerCase() === name);
+  return key ? headers[key] : '';
+}
+function applyResponseToken(headers, requestToken) {
+  const responseToken = normalizeToken(
+    readHeader(headers, 'authorization') || readHeader(headers, 'token')
+  );
+  if (!responseToken) return;
+
+  const currentToken = getToken();
+  // 旧请求若只回显旧 Token，不得覆盖其它请求/标签页已保存的新 Token。
+  if (currentToken && requestToken && currentToken !== requestToken && responseToken === requestToken) {
+    return;
+  }
+  uni.setStorageSync(TOKEN_KEY, responseToken);
+}
+
+function formEngineRequest(action, table, body = {}) {
+  return new Promise((resolve, reject) => {
+    const requestToken = getToken();
+    uni.request({
+      url: `${BASE}/api/formengine/${action}-${table}`,
+      method: 'POST',
       header: {
-        'Content-Type': 'application/json',
-        'OsClient': OS_CLIENT,
-        'authorization': requestToken ? `Bearer ${requestToken}` : '',
-        'did': getDid()
-      },
-      data: { OsClient: OS_CLIENT, FormEngineKey: table, ...body },
-      success: (res) => {
-        applyResponseToken(res.header || res.headers, requestToken);
-        resolve(res.data || {});
-      },
-      fail: reject
-    });
-  });
+        'Content-Type': 'application/json',
+        'OsClient': OS_CLIENT,
+        'authorization': requestToken ? `Bearer ${requestToken}` : '',
+        'did': getDid()
+      },
+      data: { OsClient: OS_CLIENT, FormEngineKey: table, ...body },
+      success: (res) => {
+        applyResponseToken(res.header || res.headers, requestToken);
+        resolve(res.data || {});
+      },
+      fail: reject
+    });
+  });
 }
 export const formEngineGet    = (t, w) => formEngineRequest('gettabledata', t, w);
 export const formEngineGetOne = (t, w) => formEngineRequest('getformdata',  t, w);
@@ -198,13 +216,13 @@ export const formEngineDel    = (t, d) => formEngineRequest('delformdata',  t, d
 | --- | --- |
 | 404 Not Found | URL 缺 `/api/` 前缀，或表名/动作之间用 `/` 而不是 `-` |
 | 405 Method Not Allowed | 用了 GET（FormEngine 全部为 POST） |
-| 1001 登录身份已过期 | 没传 Token / Token 过期 / Redis 重启 |
-| 1002 身份验证失败 | OsClient 不匹配 |
-| `NoAuth` / `您没有权限做此操作` | Token 有效但菜单、表操作权限、表绑定角色、行级范围或敏感表策略不允许 |
-| 显式传 `_SysMenuId` 后无权限 | 列表/写入使用错误菜单会严格拒绝；唯一详情在当前角色仍拥有另一个同表菜单时可恢复，不应用菜单查询范围 |
-| 无 `_SysMenuId` 仍无权限 | 当前角色没有直接绑定该表的菜单授权，也没有精确表级授权 |
-| 并发后提示 TokenReplaced / MissingToken | 客户端没有接收响应新 Token，或旧请求/其它标签页覆盖或清除了共享新 Token |
-| Code:0 表不存在 | `FormEngineKey` 在 `diy_table` 不存在 |
+| 1001 登录身份已过期 | 没传 Token / Token 过期 / Redis 重启 |
+| 1002 身份验证失败 | OsClient 不匹配 |
+| `NoAuth` / `您没有权限做此操作` | Token 有效但菜单、表操作权限、表绑定角色、行级范围或敏感表策略不允许 |
+| 显式传 `_SysMenuId` 后无权限 | 列表/写入使用错误菜单会严格拒绝；唯一详情在当前角色仍拥有另一个同表菜单时可恢复，不应用菜单查询范围 |
+| 无 `_SysMenuId` 仍无权限 | 当前角色没有直接绑定该表的菜单授权，也没有精确表级授权 |
+| 并发后提示 TokenReplaced / MissingToken | 客户端没有接收响应新 Token，或旧请求/其它标签页覆盖或清除了共享新 Token |
+| Code:0 表不存在 | `FormEngineKey` 在 `diy_table` 不存在 |
 | Code:0 字段不存在 | `_Where` / `_SelectFields` 写了表上没有的字段 |
 | 返回 `null` 而不是 DosResult | Controller 抛了异常被吞，到后端日志看 `Microi.Core` 报错 |
 
@@ -216,5 +234,5 @@ export const formEngineDel    = (t, d) => formEngineRequest('delformdata',  t, d
 | POST `/api/formengine/getformdata-mall_member`   | `V8.FormEngine.GetFormData('mall_member', {...})` |
 | POST `/api/formengine/uptformdata-mall_shopping_cart` | `V8.FormEngine.UptFormData('mall_shopping_cart', {...})` |
 
-> 客户端 HTTP 调用**会**触发 `SubmitBeforeServerV8`、`SubmitAfterServerV8`、`DataFilterV8` 等服务端事件；
-> 而 V8 引擎内调用 `V8.FormEngine.*` 默认**不**触发，除非显式传 `_InvokeType:'Client'`。`_InvokeType` 只影响事件语义，不授予任何客户端表权限。
+> 客户端 HTTP 调用**会**触发 `SubmitBeforeServerV8`、`SubmitAfterServerV8`、`DataFilterV8` 等服务端事件；
+> 而 V8 引擎内调用 `V8.FormEngine.*` 默认**不**触发，除非显式传 `_InvokeType:'Client'`。`_InvokeType` 只影响事件语义，不授予任何客户端表权限。