@microi.net/cli 5.5.9 → 5.6.0

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

@@ -55,50 +55,50 @@ 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 伪造。
-
-因此：
-
-- 标准模块、详情页和其字段元数据请求优先传真实 `_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/数据库调用与接口引擎一样属于可信服务器执行，可实现当前租户内的跨表事务。需要“只能修改本人数据”等业务约束以及归属字段写入时，应在这里或专用接口引擎中完成。
+## 请求 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/数据库调用与接口引擎一样属于可信服务器执行，可实现当前租户内的跨表事务。需要“只能修改本人数据”等业务约束以及归属字段写入时，应在这里或专用接口引擎中完成。
 
 ## Body 结构（POST JSON）
 
-```jsonc
-{
-  "OsClient": "demo",
-  "FormEngineKey": "mall_product",   // 形式一必填；形式二可选（已在 URL 中）
-  "_SysMenuId": "目标菜单Id",         // 标准模块推荐；必须是真实绑定目标表且当前角色有权访问的菜单
-  "_Where": [["Status","=","OnSale"], ["AND","Stock",">",0]],
-  "_SelectFields": ["Id","Title","CurrentPrice","MainImg"],
+```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 +108,7 @@ URL 中的表名小写最稳，平台不区分大小写。匿名版本目前**
 
 写操作（Add/Upt）将业务字段平铺到 body：
 ```jsonc
-{ "OsClient":"demo", "FormEngineKey":"biz_order",
+{ "OsClient":"demo", "FormEngineKey":"biz_order",
   "Id":"01ABC...", "Quantity": 2, "Selected": 1 }
 ```
 
@@ -127,63 +127,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 +198,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 +216,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` 只影响事件语义，不授予任何客户端表权限。

package/skills/v8-frontend-events/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: v8-frontend-events
-description: Microi 前端 V8 事件与客户端能力指南。用于编写浏览器端字段、按钮、列表事件，或使用 V8.EventName、V8.Form、V8.Print 蓝牙打印（佳博 GP-M322、ZICOX CC4、TSPL、CPCL、ESC/POS、BLE、SPP）、扫码、弹窗、表单联动和界面交互。
+name: v8-frontend-events
+description: Microi 前端 V8 事件与客户端能力指南。用于编写浏览器端字段、按钮、列表事件，或使用 V8.EventName、V8.Form、V8.Print 蓝牙打印（佳博 GP-M322、ZICOX CC4、TSPL、CPCL、ESC/POS、BLE、SPP）、扫码、弹窗、表单联动和界面交互。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
@@ -10,18 +10,18 @@ description: Microi 前端 V8 事件与客户端能力指南。用于编写浏
 你正在为 Microi 吾码平台编写 **前端 V8 事件** 代码。前端事件运行在浏览器，通过 `V8.EventName` 区分事件类型，可访问表单/列表/弹窗等丰富的客户端 API。
 
 > **表单生命周期事件**（InFormV8、SubmitFormV8、SubmitBeforeServerV8、SubmitAfterServerV8、OutFormV8、DataFilterV8）见 `v8-table-event/SKILL.md`。  
-> **菜单按钮事件**（MoreBtns/FormBtns 等）见 `v8-menu-buttons/SKILL.md`。  
-> 本文重点是 **字段事件、按钮事件、列表事件、模板引擎、其它前端钩子**。
-
+> **菜单按钮事件**（MoreBtns/FormBtns 等）见 `v8-menu-buttons/SKILL.md`。  
+> 本文重点是 **字段事件、按钮事件、列表事件、模板引擎、其它前端钩子**。
+
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=v8-frontend-events-000 sha256=df2662a9a006d35d989d7ff7316890ffff2c08e422d0e88033f44cdd40210c88 -->
-## 能力路由
-
-- 查询前端 V8 全部上下文、导航、表单、列表、网络、引擎与工具入口时，读取 `../v8-utilities/references/client-api-index.md`。
-- 需求包含“蓝牙打印、标签打印、TSC/TSPL、CPCL、ESC/POS、小票打印、佳博/GP-M322、ZICOX/芝柯/CC4、BLE/SPP”时，必须先读取 `references/bluetooth-print.md`；需要完整指令签名、型号转换范围、编码或位图参数时，再读取 `references/bluetooth-print-api.md`。
-- 浏览器模板打印、PDF/纸张模板、`mic_print`、`PageObj`、`PrintObj` 使用 `print-engine/SKILL.md`，不要与直接蓝牙指令混为一套 API。
-- 扫码使用 `V8.Method.ScanCode`，结果从 Promise/回调取得；`V8.ScanCodeRes` 只作兼容结果槽，详见客户端 API 索引。
-- 登录后的敏感操作使用 `V8.Identity.Verify` 完成 Passkey/严格人脸交互；前端只取得一次性 Ticket，后端接口引擎必须重算 `ActionHash` 并原子消费，不能把前端成功当作授权。
+## 能力路由
+
+- 查询前端 V8 全部上下文、导航、表单、列表、网络、引擎与工具入口时，读取 `../v8-utilities/references/client-api-index.md`。
+- 需求包含“蓝牙打印、标签打印、TSC/TSPL、CPCL、ESC/POS、小票打印、佳博/GP-M322、ZICOX/芝柯/CC4、BLE/SPP”时，必须先读取 `references/bluetooth-print.md`；需要完整指令签名、型号转换范围、编码或位图参数时，再读取 `references/bluetooth-print-api.md`。
+- 浏览器模板打印、PDF/纸张模板、`mic_print`、`PageObj`、`PrintObj` 使用 `print-engine/SKILL.md`，不要与直接蓝牙指令混为一套 API。
+- 扫码使用 `V8.Method.ScanCode`，结果从 Promise/回调取得；`V8.ScanCodeRes` 只作兼容结果槽，详见客户端 API 索引。
+- 登录后的敏感操作使用 `V8.Identity.Verify` 完成 Passkey/严格人脸交互；前端只取得一次性 Ticket，后端接口引擎必须重算 `ActionHash` 并原子消费，不能把前端成功当作授权。
 
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-frontend-events-001 sha256=a9f8e1aed64db4b57ff762eb557c0d764b5f703a722dc080d273c4111afe234f -->
@@ -133,22 +133,22 @@ V8.ConfirmTips('确认审核通过？', function() {
 });
 ```
 
-### V8BtnLimit — 按钮显隐（V8CodeShow）
+### V8BtnLimit — 按钮显隐（V8CodeShow）
 
 ```javascript
 // 推荐：直接 return boolean
 return V8.Form.Status === '待审核' && V8.CurrentUser.RoleName.indexOf('审批员') !== -1;
 
 // 兼容旧写法：V8.Result = true/false
-// V8.Result = V8.Form.Status === '待审核';
-```
-
-`V8CodeShow` 与点击事件使用同一套前端 V8 能力，允许直接使用 `await`。平台所有
-按钮入口（列表按钮、表单顶部按钮、更多按钮和子表打开的嵌套表单按钮）都必须走
-异步执行器并等待结果后再决定显隐；不得在某一层退回同步 `new Function`，否则同一段
-代码在列表可用、进入嵌套表单后会报 `await is only valid in async functions`。回归测试
-至少覆盖“主表详情 → 定制子表 → 子记录详情”链路中的含 `await` 显隐代码。
-
+// V8.Result = V8.Form.Status === '待审核';
+```
+
+`V8CodeShow` 与点击事件使用同一套前端 V8 能力，允许直接使用 `await`。平台所有
+按钮入口（列表按钮、表单顶部按钮、更多按钮和子表打开的嵌套表单按钮）都必须走
+异步执行器并等待结果后再决定显隐；不得在某一层退回同步 `new Function`，否则同一段
+代码在列表可用、进入嵌套表单后会报 `await is only valid in async functions`。回归测试
+至少覆盖“主表详情 → 定制子表 → 子记录详情”链路中的含 `await` 显隐代码。
+
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=v8-frontend-events-003 sha256=68aab95ab02bfca93b69eaea1c188650cb7ef13f8566bee81a63c660a4437512 -->
 ## 模板引擎事件

package/skills/v8-frontend-events/references/bluetooth-print-api.md

@@ -1,135 +1,135 @@
-# V8.Print TSC、CPCL 适配与 ESC/POS 源码 API
-
-本表直接按 `Microi.Client/src/utils/ble/tsc.js`、`esc.js`、
-`printer-compatibility.js` 与编码文件整理。方法名
-（包括历史拼写）必须与源码完全一致，不能根据打印机手册自行改名。
-
-## 目录
-
-- [构建器与编码](#构建器与编码)
-- [TSC/TSPL 的 28 个方法](#tsctspl-的-28-个方法)
-- [ZICOX CC4 的 CPCL 映射](#zicox-cc4-的-cpcl-映射)
-- [ESC/POS 的 25 个方法](#escpos-的-25-个方法)
-- [参数与组合规则](#参数与组合规则)
-
-## 构建器与编码
-
-```javascript
-var tsc = V8.Print.createNew();
-var esc = V8.Print.createNewESC();
-```
-
-两个构建器都把指令累积到普通字节数组，`getData()` 返回该数组。TSC 返回值还带不可枚举
-协议/操作元数据：普通遍历与 GP-M322 字节值不变，CC4 发送前据此生成 CPCL。不要复制或
-序列化 TSC 数组后再交给 `prepareSend`。TSC 的全部文本命令、
-ESC 的 `setText` 和二维码内容通过本地 `TextEncoder('gb18030', {
-NONSTANDARD_allowLegacyEncoding: true })` 编码；映射表来自同目录的
-`encoding-indexes.js`，不需要网络请求。
-
-## TSC/TSPL 的 28 个方法
-
-| 方法 | 当前生成的指令/作用 |
-|---|---|
-| `init()` | 空操作，历史兼容入口 |
-| `addCommand(content)` | 以 GB18030 追加原始 TSC 文本；只用于固定可信命令 |
-| `setSize(width,height)` | `SIZE width mm,height mm` |
-| `setSpeed(speed)` | `SPEED speed` |
-| `setDensity(density)` | `DENSITY density` |
-| `setGap(gap)` | `GAP gap mm,0 mm` |
-| `setBline(bline)` | `BLINE bline mm,0 mm`，黑标纸 |
-| `setCountry(country)` | `COUNTRY country` |
-| `setCodepage(codepage)` | `CODEPAGE codepage` |
-| `setCls()` | `CLS`，清除图像缓冲区 |
-| `setFeed(feed)` | `FEED feed`，向前走纸 |
-| `setBackFeed(backup)` | `BACKFEED backup`，回拉 |
-| `setDirection(direction)` | `DIRECTION direction` |
-| `setReference(x,y)` | `REFERENCE x,y`，坐标原点 |
-| `setFromfeed()` | 注意源码拼写；实际生成 `FORMFEED` |
-| `setHome()` | `HOME`，定位下一张标签 |
-| `setSound(level,interval)` | `SOUND level,interval` |
-| `setLimitfeed(limit)` | `LIMITFEED limit` |
-| `setBar(x,y,width,height)` | `BAR` 线条 |
-| `setBox(x1,y1,x2,y2,thickness)` | `BOX` 方框 |
-| `setErase(x,y,width,height)` | `ERASE` 清除区域 |
-| `setReverse(x,y,width,height)` | `REVERSE` 区域反相 |
-| `setText(x,y,font,xScale,yScale,text)` | `TEXT`；旋转值在源码中固定为 `0` |
-| `setQR(x,y,level,width,mode,content)` | `QRCODE`；旋转值固定为 `0` |
-| `setBarCode(x,y,type,height,readable,narrow,wide,content)` | `BARCODE`；旋转值固定为 `0` |
-| `setBitmap(x,y,mode,imageData)` | 生成 TSC `BITMAP` 二进制数据 |
-| `setPagePrint()` | `PRINT 1,1` |
-| `getData()` | 返回当前字节数组 |
-
-最小顺序通常是 `setSize` → `setGap`/`setBline` → `setCls` → 内容 →
-`setPagePrint` → `getData`。字体名、条码类型、纸张传感器、速度和浓度由打印机固件决定，
-构建器不验证范围。
-
-## ZICOX CC4 的 CPCL 映射
-
-| TSC 方法 | CC4 CPCL 结果 |
-|---|---|
-| `setSize(w,h)` | 203 dpi 下按 `8 dots/mm` 生成页宽/页高 |
-| `setSpeed` / `setDensity` | `SPEED` / `CONTRAST`，钳制到当前安全范围 |
-| `setGap` / `setBline` | `GAP-SENSE` / `BAR-SENSE` |
-| `setFeed` / `setBackFeed` | `POSTFEED` / `PREFEED` |
-| `setDirection(0/1)` | `ZPROTATE` / `ZPROTATE180` |
-| `setReference` | 转换坐标时叠加参考点 |
-| `setBar` / `setBox` / `setReverse` | `LINE` / `BOX` / `INVERSE-LINE` |
-| `setText` | `SETMAG` + `T`，字体名按 16/24/32 档映射 |
-| `setBarCode` | `BARCODE`，可选 `BARCODE-TEXT` |
-| `setQR` | 厂家 SDK 格式 `BARCODE QR ...` + 数据 + `ENDQR` |
-| `setBitmap` | `CG` + 原始单色位图字节 |
-| `setPagePrint` | 最终统一补 `FORM` + `PRINT`，每份必须恰好一次 |
-
-`init`、`setCls` 不输出。`addCommand`、`setCountry`、`setCodepage`、`setFromfeed`、
-`setHome`、`setSound`、`setLimitfeed`、`setErase` 与未知方法会抛错，并且适配发生在分包前，
-所以失败时不得写入任何一包。该白名单只表达当前有证据的等价转换，不代表 CC4 固件不具备
-其它 CPCL 能力。
-
-`createNewESC()` 的数组标记为 ESC/POS，CC4 直接原样发送，不进入 CPCL 转换。
-
-## ESC/POS 的 25 个方法
-
-| 方法 | 当前生成的指令/作用 |
-|---|---|
-| `init()` | ESC `@` 初始化 |
-| `setText(content)` | 以 GB18030 追加文字 |
-| `setFontSize(n)` | GS `! n` |
-| `bold(n)` | ESC `E n` |
-| `setUnderline(n)` | ESC `- n` |
-| `setUnderline2(n)` | FS `- n` |
-| `setSelectSizeOfModuleForQRCode(n)` | 设置二维码模块尺寸，源码钳制到 1–15 |
-| `setSelectErrorCorrectionLevelForQRCode(n)` | 设置二维码纠错值，源码不验证范围 |
-| `setStoreQRCodeData(content)` | 以 GB18030 暂存二维码内容 |
-| `setPrintQRCode()` | 输出已暂存二维码 |
-| `setHorTab()` | 水平 Tab |
-| `setAbsolutePrintPosition(where)` | 设置绝对横向位置 |
-| `setRelativePrintPositon(where)` | 设置相对横向位置；`Positon` 是现有公开拼写 |
-| `setSelectJustification(which)` | 对齐：常见值 0 左、1 中、2 右 |
-| `space(n)` | 设置水平制表位置 |
-| `setLeftMargin(n)` | 设置左边距 |
-| `textMarginRight(n)` | 设置字符右间距 |
-| `rowSpace(n)` | 设置行间距 |
-| `setPrintingAreaWidth(width)` | 设置打印区域宽度 |
-| `setSound(n,t)` | 蜂鸣器；大于 9 钳制为 9，小于 0 改为 1，0 会原样保留 |
-| `setBitmap(imageData)` | 生成 ESC/POS 光栅位图数据 |
-| `setPrint()` | 换行/打印当前行 |
-| `setPrintAndFeed(feed)` | 打印并走纸指定单位 |
-| `setPrintAndFeedRow(row)` | 打印并走纸指定行数 |
-| `getData()` | 返回当前字节数组 |
-
-ESC/POS 二维码需要按顺序调用尺寸、纠错、`setStoreQRCodeData`、
-`setPrintQRCode`。源码中虽保留条码类型数组，但没有公开 ESC/POS 条码方法，不能虚构
-`setBarCode`；条码需求应先确认型号并扩展实现。
-
-## 参数与组合规则
-
-- `setBitmap` 的参数是 ImageData 风格对象：`width`、`height`、RGBA `data`。它不是图片
-  URL、Base64 或 DOM `<img>`；调用前先在 Canvas 得到 `getImageData()`。
-- 当前位图算法按透明/非透明像素进行非常简单的黑白映射，不做通用抖动和灰度阈值处理；
-  大图先缩放、二值化，逐型号验证方向、颜色和内存。
-- TSC `setText`、`setQR`、`setBarCode` 把值放入带双引号的协议字段。移除双引号、CR/LF、
-  NUL 和控制字符，限制长度；不要让接口返回值直达 `addCommand`。
-- ESC 参数最终作为单字节或低/高字节写入，负数、浮点数、超范围值可能截断或生成无效命令。
-  坐标、宽度、走纸、字号和蜂鸣器参数应先转为目标机型允许的整数。
-- GB18030 只解决字节编码，不能替代打印机代码页、中文字库和字体配置。二维码通常比文字
-  字库更能稳定承载 Unicode 业务标识，但仍受打印机二维码命令实现限制。
+# V8.Print TSC、CPCL 适配与 ESC/POS 源码 API
+
+本表直接按 `Microi.Client/src/utils/ble/tsc.js`、`esc.js`、
+`printer-compatibility.js` 与编码文件整理。方法名
+（包括历史拼写）必须与源码完全一致，不能根据打印机手册自行改名。
+
+## 目录
+
+- [构建器与编码](#构建器与编码)
+- [TSC/TSPL 的 28 个方法](#tsctspl-的-28-个方法)
+- [ZICOX CC4 的 CPCL 映射](#zicox-cc4-的-cpcl-映射)
+- [ESC/POS 的 25 个方法](#escpos-的-25-个方法)
+- [参数与组合规则](#参数与组合规则)
+
+## 构建器与编码
+
+```javascript
+var tsc = V8.Print.createNew();
+var esc = V8.Print.createNewESC();
+```
+
+两个构建器都把指令累积到普通字节数组，`getData()` 返回该数组。TSC 返回值还带不可枚举
+协议/操作元数据：普通遍历与 GP-M322 字节值不变，CC4 发送前据此生成 CPCL。不要复制或
+序列化 TSC 数组后再交给 `prepareSend`。TSC 的全部文本命令、
+ESC 的 `setText` 和二维码内容通过本地 `TextEncoder('gb18030', {
+NONSTANDARD_allowLegacyEncoding: true })` 编码；映射表来自同目录的
+`encoding-indexes.js`，不需要网络请求。
+
+## TSC/TSPL 的 28 个方法
+
+| 方法 | 当前生成的指令/作用 |
+|---|---|
+| `init()` | 空操作，历史兼容入口 |
+| `addCommand(content)` | 以 GB18030 追加原始 TSC 文本；只用于固定可信命令 |
+| `setSize(width,height)` | `SIZE width mm,height mm` |
+| `setSpeed(speed)` | `SPEED speed` |
+| `setDensity(density)` | `DENSITY density` |
+| `setGap(gap)` | `GAP gap mm,0 mm` |
+| `setBline(bline)` | `BLINE bline mm,0 mm`，黑标纸 |
+| `setCountry(country)` | `COUNTRY country` |
+| `setCodepage(codepage)` | `CODEPAGE codepage` |
+| `setCls()` | `CLS`，清除图像缓冲区 |
+| `setFeed(feed)` | `FEED feed`，向前走纸 |
+| `setBackFeed(backup)` | `BACKFEED backup`，回拉 |
+| `setDirection(direction)` | `DIRECTION direction` |
+| `setReference(x,y)` | `REFERENCE x,y`，坐标原点 |
+| `setFromfeed()` | 注意源码拼写；实际生成 `FORMFEED` |
+| `setHome()` | `HOME`，定位下一张标签 |
+| `setSound(level,interval)` | `SOUND level,interval` |
+| `setLimitfeed(limit)` | `LIMITFEED limit` |
+| `setBar(x,y,width,height)` | `BAR` 线条 |
+| `setBox(x1,y1,x2,y2,thickness)` | `BOX` 方框 |
+| `setErase(x,y,width,height)` | `ERASE` 清除区域 |
+| `setReverse(x,y,width,height)` | `REVERSE` 区域反相 |
+| `setText(x,y,font,xScale,yScale,text)` | `TEXT`；旋转值在源码中固定为 `0` |
+| `setQR(x,y,level,width,mode,content)` | `QRCODE`；旋转值固定为 `0` |
+| `setBarCode(x,y,type,height,readable,narrow,wide,content)` | `BARCODE`；旋转值固定为 `0` |
+| `setBitmap(x,y,mode,imageData)` | 生成 TSC `BITMAP` 二进制数据 |
+| `setPagePrint()` | `PRINT 1,1` |
+| `getData()` | 返回当前字节数组 |
+
+最小顺序通常是 `setSize` → `setGap`/`setBline` → `setCls` → 内容 →
+`setPagePrint` → `getData`。字体名、条码类型、纸张传感器、速度和浓度由打印机固件决定，
+构建器不验证范围。
+
+## ZICOX CC4 的 CPCL 映射
+
+| TSC 方法 | CC4 CPCL 结果 |
+|---|---|
+| `setSize(w,h)` | 203 dpi 下按 `8 dots/mm` 生成页宽/页高 |
+| `setSpeed` / `setDensity` | `SPEED` / `CONTRAST`，钳制到当前安全范围 |
+| `setGap` / `setBline` | `GAP-SENSE` / `BAR-SENSE` |
+| `setFeed` / `setBackFeed` | `POSTFEED` / `PREFEED` |
+| `setDirection(0/1)` | `ZPROTATE` / `ZPROTATE180` |
+| `setReference` | 转换坐标时叠加参考点 |
+| `setBar` / `setBox` / `setReverse` | `LINE` / `BOX` / `INVERSE-LINE` |
+| `setText` | `SETMAG` + `T`，字体名按 16/24/32 档映射 |
+| `setBarCode` | `BARCODE`，可选 `BARCODE-TEXT` |
+| `setQR` | 厂家 SDK 格式 `BARCODE QR ...` + 数据 + `ENDQR` |
+| `setBitmap` | `CG` + 原始单色位图字节 |
+| `setPagePrint` | 最终统一补 `FORM` + `PRINT`，每份必须恰好一次 |
+
+`init`、`setCls` 不输出。`addCommand`、`setCountry`、`setCodepage`、`setFromfeed`、
+`setHome`、`setSound`、`setLimitfeed`、`setErase` 与未知方法会抛错，并且适配发生在分包前，
+所以失败时不得写入任何一包。该白名单只表达当前有证据的等价转换，不代表 CC4 固件不具备
+其它 CPCL 能力。
+
+`createNewESC()` 的数组标记为 ESC/POS，CC4 直接原样发送，不进入 CPCL 转换。
+
+## ESC/POS 的 25 个方法
+
+| 方法 | 当前生成的指令/作用 |
+|---|---|
+| `init()` | ESC `@` 初始化 |
+| `setText(content)` | 以 GB18030 追加文字 |
+| `setFontSize(n)` | GS `! n` |
+| `bold(n)` | ESC `E n` |
+| `setUnderline(n)` | ESC `- n` |
+| `setUnderline2(n)` | FS `- n` |
+| `setSelectSizeOfModuleForQRCode(n)` | 设置二维码模块尺寸，源码钳制到 1–15 |
+| `setSelectErrorCorrectionLevelForQRCode(n)` | 设置二维码纠错值，源码不验证范围 |
+| `setStoreQRCodeData(content)` | 以 GB18030 暂存二维码内容 |
+| `setPrintQRCode()` | 输出已暂存二维码 |
+| `setHorTab()` | 水平 Tab |
+| `setAbsolutePrintPosition(where)` | 设置绝对横向位置 |
+| `setRelativePrintPositon(where)` | 设置相对横向位置；`Positon` 是现有公开拼写 |
+| `setSelectJustification(which)` | 对齐：常见值 0 左、1 中、2 右 |
+| `space(n)` | 设置水平制表位置 |
+| `setLeftMargin(n)` | 设置左边距 |
+| `textMarginRight(n)` | 设置字符右间距 |
+| `rowSpace(n)` | 设置行间距 |
+| `setPrintingAreaWidth(width)` | 设置打印区域宽度 |
+| `setSound(n,t)` | 蜂鸣器；大于 9 钳制为 9，小于 0 改为 1，0 会原样保留 |
+| `setBitmap(imageData)` | 生成 ESC/POS 光栅位图数据 |
+| `setPrint()` | 换行/打印当前行 |
+| `setPrintAndFeed(feed)` | 打印并走纸指定单位 |
+| `setPrintAndFeedRow(row)` | 打印并走纸指定行数 |
+| `getData()` | 返回当前字节数组 |
+
+ESC/POS 二维码需要按顺序调用尺寸、纠错、`setStoreQRCodeData`、
+`setPrintQRCode`。源码中虽保留条码类型数组，但没有公开 ESC/POS 条码方法，不能虚构
+`setBarCode`；条码需求应先确认型号并扩展实现。
+
+## 参数与组合规则
+
+- `setBitmap` 的参数是 ImageData 风格对象：`width`、`height`、RGBA `data`。它不是图片
+  URL、Base64 或 DOM `<img>`；调用前先在 Canvas 得到 `getImageData()`。
+- 当前位图算法按透明/非透明像素进行非常简单的黑白映射，不做通用抖动和灰度阈值处理；
+  大图先缩放、二值化，逐型号验证方向、颜色和内存。
+- TSC `setText`、`setQR`、`setBarCode` 把值放入带双引号的协议字段。移除双引号、CR/LF、
+  NUL 和控制字符，限制长度；不要让接口返回值直达 `addCommand`。
+- ESC 参数最终作为单字节或低/高字节写入，负数、浮点数、超范围值可能截断或生成无效命令。
+  坐标、宽度、走纸、字号和蜂鸣器参数应先转为目标机型允许的整数。
+- GB18030 只解决字节编码，不能替代打印机代码页、中文字库和字体配置。二维码通常比文字
+  字库更能稳定承载 Unicode 业务标识，但仍受打印机二维码命令实现限制。