@microi.net/cli 4.6.2

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

@@ -0,0 +1,185 @@
+# V8.Print 蓝牙打印运行指南
+
+本参考用于 Microi 前端 V8 的 BLE 标签和小票打印。运行时事实源为
+`Microi.Client/src/utils/v8-print.js`，指令方法事实源见
+[`bluetooth-print-api.md`](bluetooth-print-api.md)。官网旧业务示例不能作为当前连接语义。
+
+## 目录
+
+- [前端挂载范围](#前端挂载范围)
+- [运行环境与能力判断](#运行环境与能力判断)
+- [连接与发送语义](#连接与发送语义)
+- [最小安全流程](#最小安全流程)
+- [批量打印与恢复](#批量打印与恢复)
+- [兼容性与当前限制](#兼容性与当前限制)
+- [安全边界](#安全边界)
+- [实机验收](#实机验收)
+
+## 前端挂载范围
+
+当前主前端有三层真实挂载，均调用幂等的 `initV8Print(V8)`：
+
+| 源码位置 | 覆盖的 V8 场景 |
+|---|---|
+| `src/utils/diy.common.js` | 通用前端 V8 基础对象和常规按钮流程 |
+| `src/views/form-engine/diy-form.vue` | 表单、字段及表单按钮 V8 |
+| `src/views/form-engine/diy-table.vue` | 列表、菜单按钮、行按钮等表格 V8 |
+
+因此不要再从租户脚本导入 `tsc.js`、`esc.js` 或自行挂载 `V8.Print`。这些能力只在
+Microi 浏览器/5+App 前端 V8 中可用，不属于后端接口引擎、后端表单事件或微信小程序
+原生 BLE API。
+
+基础 V8 对象会把同一个 `Print` 状态复制给多个前端 V8 上下文。分包游标、打印份数和
+连接引用均为可变状态，所以同一页面的所有打印任务必须共用一条串行队列，不能认为
+不同按钮或不同 V8 对象彼此隔离。
+
+## 运行环境与能力判断
+
+| 运行环境 | 当前引擎 | 结论 |
+|---|---|---|
+| 5+App 打包的 APK/IPA | `plus.bluetooth` | 支持 BLE 扫描、连接和写特征 |
+| 存在 `navigator.bluetooth.requestDevice` 的浏览器 | Web Bluetooth | 支持；通常要求安全上下文和用户手势 |
+| 其它普通 H5/浏览器 | 无 | `V8.Print` 仍可能存在，但连接页会提示能力不可用 |
+| 微信小程序原生 BLE | 不属于此模块 | 需要小程序/UniApp 侧专用实现 |
+
+不要用 `V8.ClientType === 'PC'` 判断蓝牙能力，也不要只检查
+`BLEInformation.deviceId`。正确顺序是检查 `V8.Print`、调用 `isConnected()`，再在
+用户点击事件中 `await OpenBluetoothPage()`。
+
+浏览器模板、PDF、A4 单据和 Print Engine JSON 属于 `print-engine`；TSC/TSPL 或
+ESC/POS 原生字节通过 BLE 写入才属于 `V8.Print`。
+
+## 连接与发送语义
+
+| API | 当前真实语义 |
+|---|---|
+| `createNew()` | 新建 TSC/TSPL 标签指令构建器 |
+| `createNewESC()` | 新建 ESC/POS 小票指令构建器 |
+| `OpenBluetoothPage()` | 返回 `Promise<boolean>`；在连接弹窗关闭时解析，值表示关闭时是否有连接信息 |
+| `isConnected()` | Web 端检查实时 GATT 与写特征；5+App 端只检查已保存的设备/写特征 ID |
+| `prepareSend(bytes)` | 未连接时先打开连接页，然后按包串行写入；必须 `await` 并捕获失败 |
+| `Send(bytes)` | 依赖 `prepareSend` 已设置的内部游标，属于内部状态机入口，业务代码不要直接调用 |
+| `setOneTimeData(bytes)` | 设置 BLE 包长；源码不校验，内置候选为 20–190、步长 10，默认 20 |
+| `setPrinterNum(num)` | 重复发送同一缓冲区；源码不校验，内置候选为整数 1–9 |
+| `disconnect()` | 主动断开并清理当前设备、写特征和会话元数据 |
+| `BLEInformation` | 最近设备/服务/特征元数据，只用于诊断，不代表实时连接或打印回执 |
+
+`OpenBluetoothPage()` 已打开时再次调用会返回 `false`。它不是“连接成功事件”；用户连上
+设备后仍要关闭弹窗，调用方才能继续。`prepareSend` 虽会自动打开连接页，但业务按钮主动
+建立连接更容易给出清晰提示。
+
+连接元数据会写入 `sessionStorage`，但当前 `restoreBLEInfo()` 没有进入初始化调用链，页面
+刷新后不会自动恢复可发送的 GATT/特征引用。刷新、跨页面重建或断线后应重新连接。
+5+App 的 `isConnected()` 只验证 ID 是否存在，因此发送仍可能因物理断线失败。
+
+## 最小安全流程
+
+```javascript
+function cleanCommandText(value, maxLength) {
+  return String(value == null ? '' : value)
+    .replace(/[\r\n"\x00-\x1f]/g, ' ')
+    .slice(0, maxLength || 120);
+}
+
+async function ensurePrinterConnected() {
+  if (!V8.Print) throw new Error('当前前端未加载蓝牙打印能力');
+  if (V8.Print.isConnected()) return;
+
+  var connected = await V8.Print.OpenBluetoothPage();
+  if (!connected || !V8.Print.isConnected()) {
+    throw new Error('未连接蓝牙打印机');
+  }
+}
+
+async function printLabel(order) {
+  await ensurePrinterConnected();
+
+  var cmd = V8.Print.createNew();
+  cmd.setSize(60, 40);
+  cmd.setGap(2);
+  cmd.setSpeed(4);
+  cmd.setDensity(8);
+  cmd.setDirection(1);
+  cmd.setCls();
+  cmd.setText(20, 20, 'TSS24.BF2', 1, 1, cleanCommandText(order.Name, 40));
+  cmd.setBarCode(20, 80, '128', 60, 1, 2, 2, cleanCommandText(order.Code, 40));
+  cmd.setQR(340, 30, 'L', 5, 'A', cleanCommandText(order.Id, 120));
+  cmd.setPagePrint();
+
+  await V8.Print.prepareSend(cmd.getData());
+}
+```
+
+ESC/POS 小票使用 `createNewESC()`，完整顺序和 25 个真实方法见
+[`bluetooth-print-api.md`](bluetooth-print-api.md)。发送成功只表示 BLE 写调用完成，不能
+写成“打印机已走纸”或“物理打印成功”。当前源码虽发现 read/notify 特征，但没有订阅状态
+通知，也没有消费 ACK、缺纸或故障回执。
+
+## 批量打印与恢复
+
+```javascript
+async function printBatch(rows, startIndex) {
+  var list = Array.isArray(rows) ? rows : [];
+  var begin = Math.max(0, Number(startIndex || 0));
+  var limit = Math.min(list.length, begin + 100);
+
+  for (var i = begin; i < limit; i++) {
+    try {
+      await printLabel(list[i]);
+      V8.Tips('已发送 ' + (i + 1) + '/' + list.length, true);
+    } catch (error) {
+      return {
+        Code: 0,
+        Msg: '第 ' + (i + 1) + ' 条发送失败：' + (error.message || error),
+        NextIndex: i
+      };
+    }
+  }
+
+  return { Code: 1, Data: { NextIndex: limit, HasMore: limit < list.length } };
+}
+```
+
+- 不用固定 `setTimeout(3000)` 猜测上一张是否完成。
+- 不用 `Promise.all`，也不要让两个按钮同时调用 `prepareSend`。
+- 大批次分段并持久化 `NextIndex`；页面关闭、断连或写失败后从失败位置人工确认再恢复。
+- `setPrinterNum(n)` 只适合同一缓冲区重复发送，不适合每张内容不同的批次。
+- 业务落库与蓝牙打印不是原子事务。用稳定业务单号支持受控重打，不重复执行业务写入。
+
+## 兼容性与当前限制
+
+- Web Bluetooth 仅把四个常见服务 UUID 传入 `optionalServices`：`18f0`、`ff00`、
+  `49535343-fe7d-4ae5-8fa9-9fafd205e455`、`e7810a71-73ae-499d-8c15-faa9aef0c3f2`。
+  当前没有公开的自定义服务配置，并选择枚举到的第一个可写特征；其它型号可能需要扩展源码。
+- `prepareSend` 默认每包 20 字节、包间约 20ms；同一缓冲区多份打印间约 100ms。这只是
+  BLE 写节奏，不是打印完成等待时间。包长必须是已实测的正整数，空缓冲区不得发送。
+- 当前分包公式是 `floor(length / packetSize) + 1`。长度恰好整除包长时会尝试额外写一个
+  0 字节末包；某些 BLE 栈会拒绝。实机出现此问题时应修复适配器并回归，不要靠并发或吞错绕过。
+- TSC 与 ESC 文本使用仓库内置 `encoding.js` + `encoding-indexes.js` 转为 GB18030，运行时
+  不请求网络。编码成功不等于打印机字体、代码页和固件支持全部字符；Emoji 等仍需实机验证。
+- `setBitmap` 接受 ImageData 风格 `{ width, height, data }` RGBA 数据。当前黑白转换较简单，
+  大图可能产生大缓冲区；先缩放、二值化并用小图测试。
+- `V8.Print` 没有任务锁和队列。跨 V8 上下文并发会互相覆盖 `currentTime`、`looptime`、
+  `lastData` 等共享状态，必须由业务侧全局串行化。
+
+## 安全边界
+
+- TSC 的 `setText`、`setQR`、`setBarCode` 和 `addCommand` 会拼协议文本。移除引号、换行、
+  NUL/控制字符并限制长度；`addCommand` 只接受固定、受审查的命令。
+- 蓝牙设备名称、ID 和服务特征均是外部输入。不要拼入 `innerHTML`，展示时做文本转义；不要
+  记录或上传完整 `BLEInformation`，以免泄露终端指纹。
+- 金额、数量、坐标、纸张尺寸、包长和份数先做类型/范围校验，避免无限循环或超大缓冲区。
+- 打印内容含个人信息、票据或密钥时，不写控制台、系统日志或异常上报正文。
+- 浏览器权限拒绝、用户取消、GATT 断开、找不到服务/特征和写包失败都必须可理解地提示。
+
+## 实机验收
+
+至少记录：
+
+1. 打印机品牌、型号、固件、纸张规格、服务/写特征 UUID 和指令集。
+2. 5+App 或浏览器版本；首次授权、再次连接、主动断开、页面刷新和断线重连。
+3. 中文、数字、特殊字符、二维码、条码、长文本、图片和边界金额。
+4. 默认 20 字节与目标包长；同时覆盖“长度恰好整除包长”。
+5. 连续 20 张严格串行发送，无乱序、丢包、重复或任务状态互相污染。
+6. 中途关机、缺纸、离开范围、权限撤销后的失败位置与恢复行为。
+7. 页面只确认“数据已发送”；若业务要求确认物理结果，另接状态回读或人工确认。

package/dist/microi.skills/v8-http-integration/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: v8-http-integration
+description: Microi V8 HTTP 集成指南。用于通过 V8.Http.Get/Post/Patch、对应 Response 方法及后端 Async 方法调用接口，处理请求头、JSON/form/XML 载荷、超时、文件和响应解析，并兼容前后端 V8。
+---
+
+# Microi V8 HTTP 外部接口集成
+
+你正在开发 Microi 吾码平台的 V8 引擎代码，需要调用外部 HTTP API（微信、支付宝、短信、ERP 等第三方系统）。
+
+文档维护时，前端用法更新现有 `microi.doc/docs/doc/v8-engine/v8-client.md`，后端用法更新现有 `microi.doc/docs/doc/v8-engine/v8-server.md`；不要新建重复的 V8.Http 文档页面或路由。只维护中文 `docs/doc/`，英文 `docs/en/` 由官网统一翻译生成。
+
+## V8.Http API
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `V8.Http.Get({...})` | GET 请求 | 字符串（响应体） |
+| `V8.Http.Post({...})` | POST 请求 | 字符串（响应体） |
+| `V8.Http.Patch({...})` | PATCH 请求 | 字符串（响应体） |
+| `V8.Http.GetResponse({...})` | GET（完整响应） | `{ Content, Headers, StatusCode }` |
+| `V8.Http.PostResponse({...})` | POST（完整响应） | `{ Content, Headers, StatusCode }` |
+| `V8.Http.PatchResponse({...})` | PATCH（完整响应） | `{ Content, Headers, StatusCode }` |
+
+后端接口引擎还提供真实异步方法：
+
+| 方法 | 说明 |
+|------|------|
+| `await V8.Http.GetAsync({...})` | 异步 GET，返回响应字符串 |
+| `await V8.Http.PostAsync({...})` | 异步 POST，返回响应字符串 |
+| `await V8.Http.PatchAsync({...})` | 异步 PATCH，返回响应字符串 |
+| `await V8.Http.GetResponseAsync({...})` | 异步 GET，返回完整响应 |
+| `await V8.Http.PostResponseAsync({...})` | 异步 POST，返回完整响应 |
+| `await V8.Http.PatchResponseAsync({...})` | 异步 PATCH，返回完整响应 |
+| `await V8.Http.GetStreamAsync({...})` | 异步获取响应流，供当前请求内继续处理 |
+
+前端与后端统一使用 PascalCase 对象参数格式。执行模型不同：后端既可调用同步方法，也可在本次请求内调用显式 `*Async` 方法并 `await`；前端浏览器调用无 `Async` 后缀的方法，但必须 `await` 其 `Promise`。旧版前端 `V8.Post/Get` 继续兼容，不得删除。
+
+```javascript
+// 后端接口引擎：请求内异步 I/O
+var resp = await V8.Http.PostResponseAsync({
+  Url: 'https://api.example.com/orders',
+  PostParam: { OrderNo: V8.Param.orderNo },
+  ParamType: 'json',
+  Timeout: 10
+});
+if (resp.StatusCode < 200 || resp.StatusCode >= 300) {
+  return { Code: 0, Msg: '上游接口调用失败' };
+}
+```
+
+异步方法只保证当前请求内等待完成，不能替代 Job、MQ、outbox 或平台后台任务。不得用未等待的 Promise、`setTimeout` 或 `Task.Run` 实现“响应后继续处理”。
+
+通用参数：
+
+| 参数 | 说明 |
+|---|---|
+| `Url` | 必传。后端通常使用绝对地址；前端支持相对当前 `ApiBase` 的地址和绝对地址。 |
+| `GetParam` | URL 查询参数；GET、POST、PATCH 均可使用。 |
+| `PostParam` / `PatchParam` | POST / PATCH 对象请求体。 |
+| `PostParamString` / `PatchParamString` | 已序列化的 JSON 或 XML 请求体，嵌套 JSON 优先使用。 |
+| `ParamType` | `form`（默认）、`json`、`xml`、`binary`。 |
+| `Timeout` / `TimeOut` | 超时秒数；默认 `600` 秒（10 分钟）。 |
+| `Headers` / `Header` | 请求头对象，两种参数名兼容。 |
+| `FilesByteBase64` / `FilesByteString` | 文件字段对象，键同时作为字段名和文件名。 |
+
+`GetResponse/PostResponse/PatchResponse` 返回 `Content`、`Headers`、`RawBytes`、`StatusCode`、`ErrorMessage`。后端 `RawBytes` 是 `.NET byte[]`，前端是 `Uint8Array`。
+
+## POST 请求（对象参数格式）
+
+> V8 接口引擎中必须使用对象参数格式。尤其禁止 `V8.Http.Get(url)`：当前 .NET 同名重载包含 `Task<string> Get(string)`，Jint 可能把字符串调用解析为异步重载，脚本最终拿到 `[object Promise]`。GET 必须写成 `V8.Http.Get({ Url: url })`；第三方登录、微信 `jscode2session`、AccessToken 等链路保存后必须用无效 code 烟测，确认返回的是第三方明确错误而不是 Promise。
+
+第三方授权链路还必须把身份交换、AccessToken、用户资料/手机号交换拆成独立阶段。每阶段分别捕获 HTTP 异常和第三方业务 `errcode/errmsg`，失败时写带追踪号的脱敏系统日志并把明确原因返回前端；禁止只在最外层返回固定“登录失败”。
+
+```javascript
+// POST JSON（推荐使用对象参数格式）
+var result = V8.Http.Post({
+  Url: 'https://api.example.com/users',          // 必传
+  PostParam: { name: '张三', phone: '13800001234' }, // form 参数（不支持多级嵌套）
+  ParamType: 'json',           // 请求类型：默认 form，可选 json / xml
+  Timeout: 600,                // 超时秒数，默认 600 秒（10 分钟）
+  Headers: { Authorization: 'Bearer ' + token }  // 请求头
+});
+var data = JSON.parse(result);
+```
+
+## PATCH 请求
+
+PATCH 与 POST 的参数完全对称，只需把请求体参数改为 `PatchParam` / `PatchParamString`：
+
+```javascript
+// 后端接口引擎：同步返回字符串
+var result = V8.Http.Patch({
+  Url: 'https://api.example.com/users/123',
+  PatchParamString: JSON.stringify({ profile: { name: '新名字' } }),
+  ParamType: 'json',
+  Timeout: 10,
+  Headers: { Authorization: 'Bearer ' + token }
+});
+var data = JSON.parse(result);
+
+// 前端 V8：参数相同，但浏览器请求必须 await
+var result = await V8.Http.Patch({
+  Url: '/api/users/123',
+  PatchParam: { Status: 1 },
+  ParamType: 'json'
+});
+```
+
+### POST 嵌套 JSON 对象
+
+```javascript
+// 多级嵌套对象需使用 PostParamString
+var result = V8.Http.Post({
+  Url: 'https://api.example.com/complex',
+  PostParamString: JSON.stringify({
+    user: { name: '张三', address: { city: '北京' } }
+  }),
+  ParamType: 'json'
+});
+```
+
+### POST XML
+
+```javascript
+var result = V8.Http.Post({
+  Url: 'https://api.example.com/xml',
+  ParamType: 'xml',
+  PostParamString: '<xml><text>内容</text></xml>'
+});
+```
+
+### POST 上传文件
+
+```javascript
+var result = V8.Http.Post({
+  Url: 'https://api.example.com/upload',
+  PostParam: { name: '附件' },
+  FilesByteBase64: { file: 'Base64编码的文件内容' }
+  // 或 FilesByteString: { file: '文件字节字符串' }
+});
+```
+
+## GET 请求
+
+```javascript
+// 对象参数格式
+var result = V8.Http.Get({
+  Url: 'https://api.example.com/users',
+  GetParam: { page: 1, size: 20 },   // URL 查询参数
+  Timeout: 10,
+  Headers: { Authorization: 'Bearer ' + token }
+});
+var data = JSON.parse(result);
+```
+
+## 获取完整响应（含状态码和响应头）
+
+```javascript
+var resp = V8.Http.PostResponse({
+  Url: 'https://api.example.com/submit',
+  PostParamString: JSON.stringify({ orderId: V8.Param.orderId }),
+  ParamType: 'json'
+});
+
+if (resp.StatusCode !== 200) {
+  return { Code: 0, Msg: '第三方接口返回 ' + resp.StatusCode };
+}
+// resp.Content — 响应内容（字符串）
+// resp.Headers — 响应头数组 [{ Name: '', Value: '' }]
+// resp.StatusCode — HTTP 状态码
+
+var data = JSON.parse(resp.Content);
+```
+
+PATCH 完整响应写法相同：
+
+```javascript
+var resp = V8.Http.PatchResponse({
+  Url: 'https://api.example.com/users/123',
+  PatchParam: { status: 'enabled' },
+  ParamType: 'json'
+});
+```
+
+前端调用时写为 `await V8.Http.PostResponse(...)` 或 `await V8.Http.PatchResponse(...)`。
+
+### 后端 SSRF 与重定向边界
+
+- 严格 SSRF 防护默认关闭；未配置时完全保留历史行为，不限制协议、URL 内嵌凭据、回环、私网、链路本地或云元数据地址，并继续自动处理重定向。
+- 只有在 SaaS 引擎主租户启用 `SsrfProtectionEnabled` 后，后端才只允许 HTTP(S)，拒绝 URL 内嵌凭据、回环、私网、链路本地、云元数据和其它特殊地址，并禁止自动跟随 3xx。
+- 严格模式需要跳转时读取完整响应的 `StatusCode` / `Headers`，经业务判断后显式发起下一次调用，使每一跳重新校验。
+- 严格模式的 SaaS 字段 `SsrfAllowedHosts` 只能加入受控且固定的精确主机，不接受用户输入，不要配置通配。
+- DNS 校验不能代替网络层出站 ACL。生产环境还应在容器、主机或网关阻断云元数据和非必要私网段。
+
+## 前端 V8 行为与兼容性
+
+- 前端新代码应优先使用 `await V8.Http.Get/Post/Patch`，参数与后端一致；不要再把 `V8.Post/Get` 作为新功能首选。旧 `V8.Post/Get` 仅作为兼容 API 保留，其回调和 Promise 写法保持不变。
+- 相对地址或当前 `ApiBase` 地址会沿用吾码登录头，并接收响应中的新 `authorization`；第三方绝对地址不会自动携带吾码 Token，避免凭据泄漏。
+- 浏览器请求第三方地址受 CORS 限制；这是浏览器安全策略，后端 `V8.Http` 不受浏览器 CORS 限制。
+- 前端字符串方法同后端一样返回原始响应文本，不会自动 `JSON.parse`；需要对象时显式解析。
+- 浏览器端不支持后端的 `FilesStream`，可使用 `FilesByteBase64`、`FilesByteString` 或 `FilesByte`。
+
+## 下载远程文件（图片、PDF 等二进制）
+
+```javascript
+var resp = V8.Http.GetResponse({
+  Url: 'https://example.com/file.png',
+  Timeout: 30
+});
+if (resp.StatusCode !== 200) return { Code: 0, Msg: '下载失败' };
+
+var bytes = resp.RawBytes;                            // .NET byte[]
+var base64 = System.Convert.ToBase64String(bytes);
+
+// 转存到 HDFS
+var up = V8.Method.Upload({
+  FilesByteBase64: { 'remote.png': base64 },
+  Limit: false, Path: '/imported', OsClient: V8.OsClient
+});
+```
+
+> 文件上传/下载完整模式见 `v8-file-upload/SKILL.md`
+
+## 第三方密钥不要硬编码
+
+```javascript
+// ❌ 危险：密钥写死在代码
+var apiKey = 'sk-xxxxxxxx';
+
+// ✅ 正确：放在 SaaS 引擎的 OsClientModel
+var apiKey = V8.OsClientModel.OpenAIKey;
+var secret = V8.OsClientModel.WxPaySecret;
+```
+
+详见 `v8-saas-multi-tenant/SKILL.md`
+```javascript
+// GET 完整响应
+var resp = V8.Http.GetResponse({
+  Url: 'https://api.example.com/data',
+  GetParam: { id: '123' }
+});
+```
+
+## 实战模式
+
+### 微信小程序 access_token
+
+```javascript
+var cacheKey = 'Microi:' + V8.OsClient + ':wx_access_token';
+var token = V8.Cache.Get(cacheKey);
+
+if (!token) {
+  var appId = V8.OsClientModel.WxAppId;     // 敏感配置存在 SaaS 引擎中
+  var secret = V8.OsClientModel.WxAppSecret;
+  var result = V8.Http.Get({
+    Url: 'https://api.weixin.qq.com/cgi-bin/token',
+    GetParam: { grant_type: 'client_credential', appid: appId, secret: secret }
+  });
+  var data = JSON.parse(result);
+
+  if (data.access_token) {
+    token = data.access_token;
+    V8.Cache.Set(cacheKey, token, '0.01:56:00');  // 缓存 1 小时 56 分钟
+  } else {
+    return { Code: 0, Msg: '获取 access_token 失败: ' + (data.errmsg || '') };
+  }
+}
+
+return { Code: 1, Data: { access_token: token } };
+```
+
+### 签名验证（HmacSHA256）
+
+```javascript
+var timestamp = V8.Action.GetTimestamp().toString();
+var nonce = System.Guid.NewGuid().ToString().replace(/-/g, '').substring(0, 16);
+var body = JSON.stringify({ orderId: V8.Param.orderId });
+var signStr = timestamp + '\n' + nonce + '\n' + body + '\n';
+var signature = V8.EncryptHelper.HmacSha256(apiSecret, signStr);
+
+var result = V8.Http.Post({
+  Url: 'https://api.example.com/pay',
+  PostParamString: body,
+  ParamType: 'json',
+  Headers: {
+    'X-Timestamp': timestamp,
+    'X-Nonce': nonce,
+    'X-Signature': signature
+  }
+});
+```
+
+### 调用其他 Microi 接口引擎
+
+```javascript
+// 不需要 HTTP，直接内部调用（可共享事务）
+var result = V8.ApiEngine.Run('calculate-price', {
+  productId: V8.Param.productId,
+  quantity: V8.Param.quantity
+}, V8.DbTrans);
+
+if (result.Code !== 1) {
+  return { Code: 0, Msg: '价格计算失败: ' + result.Msg };
+}
+```
+
+### Webhook 回调处理
+
+```javascript
+// 接收外部 Webhook（将此引擎作为 Webhook URL）
+var payload = V8.Param;
+
+V8.Method.AddSysLog({
+  Title: 'Webhook',
+  Content: JSON.stringify(payload),
+  Type: 'third-party'
+});
+
+if (payload.event === 'payment.success') {
+  V8.FormEngine.UptFormDataByWhere('OrderHeader', {
+    _Where: [['OrderNo', '=', payload.order_no]],
+    PayStatus: 'paid',
+    PayTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  });
+}
+
+return { Code: 1, Msg: 'ok' };
+```
+
+## V8.Office.SendEmail — 发送邮件
+
+```javascript
+V8.Office.SendEmail({
+  SmtpServer: 'smtp.qq.com',
+  SmtpPort: 587,
+  EnableSSL: true,
+  SystemEmail: 'admin@itdos.com',
+  SystemEmailPwd: 'password',
+  EmailSubject: '邮件标题',
+  EmailBody: '<b>HTML内容</b>',
+  Receivers: ['123@qq.com', '456@qq.com']
+});
+```
+
+## 错误处理模式
+
+```javascript
+try {
+  var response = V8.Http.Post({
+    Url: url,
+    PostParamString: body,
+    ParamType: 'json',
+    Timeout: 10
+  });
+  var result = JSON.parse(response);
+
+  if (result.code !== 0) {
+    console.error('Third-party API error: ' + response);
+    return { Code: 0, Msg: '第三方接口错误: ' + (result.message || result.msg || '') };
+  }
+
+  return { Code: 1, Data: result.data };
+} catch (ex) {
+  console.error('HTTP request failed: ' + ex.message);
+  return { Code: 0, Msg: '请求第三方接口失败，请稍后重试' };
+}
+```
+
+## 注意事项
+
+- `V8.Http.Post` 的 `PostParam` 不支持多级嵌套对象，嵌套需用 `PostParamString`
+- `V8.Http.Patch` 的 `PatchParam` 不支持多级嵌套对象，嵌套需用 `PatchParamString`
+- `Headers` 参数也可以写成 `Header`（两者等效）
+- 前端 `V8.Http` 必须使用 `await`；后端接口引擎无需 `await`
+- 旧版前端 `V8.Post/Get` 是兼容 API，不能删除；但新代码必须优先使用 `V8.Http`
+- 第三方 API 密钥建议存在 `V8.OsClientModel`（SaaS 引擎）中，不要硬编码
+- 调用外部接口应加 try-catch，第三方服务不可控
+- 对于需要缓存的 token（如微信 access_token），使用 `V8.Cache` 避免频繁请求
+- 缓存过期时间格式为 `d.HH:mm:ss`，如 `0.01:00:00` 表示 1 小时
+- 内部接口引擎之间的调用用 `V8.ApiEngine.Run()`，不需要 HTTP