@microi.net/cli 4.9.6 → 4.9.7

package/skills/v8-frontend-events/references/progressive-01-/345/210/227/350/241/250/344/272/213/344/273/266.md

@@ -0,0 +1,219 @@
+# v8-frontend-events 详细参考 1
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-frontend-events-006 sha256=f9b273e42b9bf94893ecef53797876a373ad92d46f421c90c603c52259bbd2d2 -->
+## 列表事件
+
+### TableRowClick — 行点击
+
+```javascript
+// V8.Form === 被点击的行
+console.log('点击行：', V8.Form.Id);
+// 自定义跳转
+V8.OpenAnyForm({ TableName: 'OrderDetail', Id: V8.Form.Id, FormMode: 'View' });
+```
+
+### OpenTableBefore — 打开列表前（拦截/初始化筛选）
+
+```javascript
+// 固定弹出表格的可选数据范围；搜索、高级筛选、分页不会移除此条件
+V8.OpenTableSetWhere(V8.Field.CustomerId, [
+  ['OwnerId', '=', V8.CurrentUser.Id]
+]);
+```
+
+### OpenTableSubmit — 列表查询提交前（追加条件）
+
+```javascript
+// V8.Param 是即将发起查询的参数
+V8.Param._Where = V8.Param._Where || [];
+V8.Param._Where.push(['DeptId', '=', V8.CurrentUser.DeptId]);
+```
+
+### PageTab — 页签切换
+
+```javascript
+// PageTab："待办"
+V8.SearchSet({ Status: '待办' });
+V8.RefreshTable({ _PageIndex: 1 });
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-007 sha256=3a8ad420eed127357a6b5e799792325bc5c152ff8607722a7dc96c252fae0da2 -->
+## 常用前端 API
+
+| API | 说明 |
+|-----|------|
+| `V8.Tips(msg, ok?)` | 浮层提示。`ok=true` 绿色 |
+| `V8.ConfirmTips(msg, cb)` | 回调式确认弹窗；内容按 HTML 渲染，只能传可信/已转义文本 |
+| `V8.FormSet(field, value)` | 普通表单会触发目标字段 V8；列表上下文只更新当前行/模板 |
+| `V8.FieldSet(field, prop, value)` | 设置字段属性；跨上下文只依赖顶层 Visible/Required/Readonly/Data |
+| `V8.FormSubmit({CloseForm:true})` | 提交当前表单 |
+| `V8.RefreshTable({_PageIndex:1})` | 刷新表格（-1 保持当前页） |
+| `V8.SearchSet({field: value})` | 设置筛选条件 |
+| `V8.OpenAnyForm({...})` | 打开任意表单（弹窗/抽屉） |
+| `V8.OpenAnyTable({...})` | 打开任意列表 |
+| `V8.OpenDialog({...})` | 打开自定义弹窗 |
+| `V8.OpenAppDialog({...})` | 按 AppKey 打开已发布在线微服务页面，支持 Dialog/Drawer 与结果回调 |
+| `V8.ApiEngine.Run({ApiEngineKey, ...})` | 调接口引擎（前端，参数对象格式） |
+| `V8.FormEngine.GetTableData(name, params, cb)` | 前端查列表（参数对象、回调或 await） |
+| `V8.Post(url, data, cb, errCb, headers, contentType)` | 通用 POST |
+| `V8.Method.ScanCode({...})` | 调用当前终端支持的扫码能力 |
+| `V8.Print.isConnected()` | 检查当前 BLE 写特征或 Android SPP Socket 是否仍可用 |
+| `V8.Print.OpenBluetoothPage()` | 在用户手势中打开蓝牙连接页，返回 Promise |
+| `V8.Print.reconnect()` | 使用已记住的设备授权或设备 ID 尝试重连 |
+| `V8.Print.getConnectionState()` | 获取连接、设备、传输、型号、指令、记忆和错误状态快照 |
+| `V8.Print.subscribeConnection(listener)` | 订阅应用级共享连接状态，返回取消订阅函数 |
+| `V8.Print.getPrinterProfile()` | 查看自动识别或手工选择后的型号配置 |
+| `V8.Print.setPrinterProfile(mode)` | 广播名无法识别时选 `zicox-cc4` 等型号；旧业务通常不调用 |
+| `V8.Print.prepareSend(bytes)` | 按型号适配后串行分包发送 TSPL、CPCL 或 ESC/POS，必须 `await` |
+
+`V8.OpenAnyForm` 只发起打开动作，不返回“用户关闭后的 Promise”。需要替换
+子表单保存时，通过 `EventReplace.Submit(v8, param, callback)` 注册提交替换；
+其中小写 `v8` 是子表单上下文，外层 `V8` 仍是父上下文。自定义提交结束后
+必须调用 `callback(DosResult)`，否则子表单会一直等待。
+
+### 蓝牙打印最小安全流程
+
+```javascript
+if (!V8.Print) {
+  V8.Tips('当前客户端未加载蓝牙打印能力', false);
+  return;
+}
+
+if (!V8.Print.isConnected()) {
+  var connected = await V8.Print.OpenBluetoothPage();
+  if (!connected || !V8.Print.isConnected()) return;
+}
+
+var command = V8.Print.createNew(); // 同一 TSC 调用：GP-M322 原 TSPL，CC4 自动转 CPCL
+command.setSize(60, 40);
+command.setGap(2);
+command.setCls();
+command.setText(20, 20, 'TSS24.BF2', 1, 1, '测试标签');
+command.setPagePrint();
+
+try {
+  await V8.Print.prepareSend(command.getData());
+  V8.Tips('打印数据已发送', true);
+} catch (error) {
+  V8.Tips('发送失败：' + (error.message || error), false);
+}
+```
+
+PC/平板顶部导航与移动端【我的】页共用同一个应用级 `V8.Print` 实例，用户可先在全局入口连接，再进入任意模块打印。佳博 GP-M322 路径必须保持原 TSPL 字节不变；ZICOX CC4 只转换有明确 CPCL 等价语义的高层 TSC 调用，不支持的命令必须在首包写入前失败，禁止盲目透传乱码。Android 5+App 的 CC4 可在 BLE 失败时使用已配对 SPP，Web 端不能使用经典蓝牙。
+
+`prepareSend` 内部会把不同 V8 上下文排入同一发送队列；成功只证明字节已经写入 BLE 特征或 SPP 输出流，不代表打印机已走纸、无缺纸或无硬件故障。批量打印仍应逐条 `await`，不得用固定 `setTimeout` 猜测完成时间，也不要用 `Promise.all` 表达同一设备的并行打印。完整挂载范围、双型号连接、协议映射、批量恢复、安全与硬件验收见 `references/bluetooth-print.md`；源码级 TSC/ESC/CPCL 方法表见 `references/bluetooth-print-api.md`。
+
+### 常用上下文差异
+
+| 变量 | 可用范围 |
+|------|----------|
+| `V8.OldForm` | 普通表单已加载旧数据后可用；服务端提交前/后事件也可用 |
+| `V8.OldValue` | 仅表格行内字段值变更可靠提供 |
+| `V8.Event` | 插槽按钮等显式传原生事件的场景；键盘事件使用 `V8.KeyCode` |
+| `V8.Row/Rows/RowIndex` | 表格行事件 |
+| `V8.TableRowSelected/SelectedData` | 列表批量按钮，互为兼容别名 |
+| `V8.SearchParam` | 列表 `{Keyword, Where}` 搜索快照 |
+| `V8.SysMenuModel` | 列表/菜单按钮 |
+| `V8.DataAppend` | 打开表单、列表、弹窗时传入的附加数据 |
+
+### 在线微服务弹窗 V8.OpenAppDialog
+
+复杂定制页面使用 `V8.OpenAppDialog`，不要在 V8 事件中内嵌大量 HTML/CSS：
+
+```js
+V8.OpenAppDialog({
+  AppKey: 'customer_profile_editor',       // 必传：sys_microiservice.MsKey
+  RoutePath: '/edit',                      // 可选，默认 /
+  Version: '',                             // 可选，空值自动使用当前 BuildVersion
+  Title: '编辑客户资料',
+  TitleIcon: 'fas fa-user-edit',
+  Width: 'min(920px, calc(100vw - 32px))',
+  OpenType: 'Dialog',                      // Dialog / Drawer
+  Data: { id: V8.Form.Id },                // 子应用 dialogData，只放普通数据
+  OnSuccess: function (data) {
+    V8.RefreshTable({ _PageIndex: -1 });
+  },
+  OnCancel: function (data) {},
+  OnError: function (error) {
+    V8.Tips(error.message || '加载失败', false);
+  }
+});
+```
+
+子应用用 `window.microApp.getData()` 获取自动下发的 `apiBase`、`osClient`、`token`、`appKey`、`version`、`microRoute`、`dialog` 和 `dialogData`；用 `window.microApp.dispatch({type:'app-dialog:success', data:{...}})` 返回成功结果。完整参数表和结果协议见 `v8-menu-buttons/SKILL.md`。
+
+### ConfirmTips 的 HTML 安全边界
+
+`V8.ConfirmTips` 当前是 callback API，且内容使用 HTML 模式渲染。只传固定文案或经过 HTML 转义的简单展示；严禁直接拼接用户输入、接口消息、数据库富文本和不可信 URL。三个以上字段、上传、表格、Tab、步骤条、代码编辑器或需要复用的页面必须使用 `V8.OpenAppDialog`。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-008 sha256=eebeb0230087c0deb368baac02bd39bb4b5aa054ed19d9aa43be9447f8ef1d6d -->
+## 前端 FormEngine 菜单上下文与兼容授权
+
+前端 V8 不需要为每个历史项目手工补 `_SysMenuId`。新版 PC 表单引擎通过作用域 FormEngine facade 透明处理菜单上下文：
+
+- V8 调用的目标表就是当前菜单绑定表时，facade 自动注入真实 `_SysMenuId`；如果业务代码已经显式传入 `_SysMenuId` 或兼容的 `ModuleEngineKey`，平台保留显式值，由后端做严格精确校验。
+- V8 查询其它表时，不得把当前主表菜单 Id 带给目标表。facade 保持无菜单，由后端根据当前登录用户有效角色可访问的 `sys_menu` 缓存推断该目标表及当前操作权限。
+- 历史 V8 的对象参数、`表名 + 参数`、Promise、回调、批量参数等调用形式继续兼容。业务代码不得自行伪造角色、菜单或 `_TrustedServerInvocation`。
+- 平台敏感表仍对普通客户端硬拒绝；Import/Export 仍必须携带目标模块的真实菜单上下文及专项权限，不能依赖无菜单推断。
+- 菜单配置的 `SqlWhere`、`SqlJoin` / `JoinTables` 由后端追加到真实查询。前端追加 `_Where` 只能进一步缩小结果，不能扩大或覆盖服务端数据范围。
+- 标准 `TableChild` 自动携带内部 `_TableChildAuth` 关系提示。服务端仍会重载父/子表、菜单和字段配置，校验父记录范围并强制子表外键；业务 V8 禁止构造、缓存、跨父记录复用该对象。
+
+```javascript
+// 假设当前菜单绑定 Customer：平台 facade 自动注入真实菜单，无需历史 V8 手工改造
+var current = await V8.FormEngine.GetFormData('Customer', { Id: V8.Form.Id });
+
+// 跨表：不要传当前表的菜单 Id；后端按用户对 Product 的菜单授权推断
+var products = await V8.FormEngine.GetTableData('Product', {
+  _Where: [['Status', '=', 1]],
+  _PageSize: 20
+});
+```
+
+后端接口引擎和后端表单 V8 不是浏览器调用链：平台只在服务端内部构造参数时写入 `_TrustedServerInvocation`，所以它们调用 `V8.FormEngine` 不要求 `_SysMenuId`。该标记不能从浏览器 JSON、URL 或表单参数获得，前端 V8 也不得尝试设置。
+
+### 前端 FormEngine 方法矩阵
+
+前端 facade 当前公开 `GetFormData`、`GetFormDataAnonymous`、`GetTableData`、`GetTableTree`、`AddFormData`、`AddFormDataBatch`、`UptFormData`、`UptFormDataBatch`、`UptFormDataByWhere`、`DelFormData`、`DelFormDataBatch`、`DelFormDataByWhere`。全部返回 Promise，并兼容可选 callback。
+
+前端没有 `GetTableDataCount`、`GetTableDataTree`（前端名称是 `GetTableTree`）、`AddTableData`、`UptTableData`、`DelTableData`、`AddField`。Import/Export 是独立端点与专项菜单权限，也不是 facade 方法。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-009 sha256=5e83f07a0fbcebf1eb02f3af5aa58936b3d1c3d19b0a6a0b1a0f14c66fcd6177 -->
+## 异步写法（async/await vs 回调）
+
+```javascript
+// ✅ 推荐 async/await
+var r = await V8.FormEngine.GetTableData('Product', { _PageSize: 10 });
+if (r.Code === 1) { /* ... */ }
+
+// ✅ 也可回调式
+V8.FormEngine.GetTableData('Product', { _PageSize: 10 }, function(r) {
+  if (r.Code === 1) { /* ... */ }
+});
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-010 sha256=3ca077a857ffc9f58c7290e26c7e106c0e882897b1b9b669c66b4fe7615c3821 -->
+## 死循环陷阱
+
+❌ **禁止** 在 `SubmitFormV8.js` 里调用 `V8.FormSubmit()` —— 会无限递归
+⚠️ **避免** 在 `FieldValueChange` 里 `V8.FormSet(同字段)` —— 前端会阻止同步直接重入，但异步回写或多字段互相赋值仍可能形成循环；需要静默赋值时使用 `V8.Form.字段名 = value`
+❌ **禁止** 在 `InFormV8.js` 里写大量同步 `V8.FormEngine.Get*` —— 阻塞渲染
+
+### 下拉框对象赋值
+
+```javascript
+// 会更新下拉选项并触发 SelectUser 的值变更 V8。
+// 对象至少包含 SelectSaveField、SelectLabel 对应的属性；字段事件需要的其它属性也要传入。
+V8.FormSet('SelectUser', { Id: 'u1', Name: '张三', DeptId: 'd1' });
+
+// 响应式静默赋值：界面会更新，但不触发目标字段 V8，
+// 也不会执行 FormSet 的修改字段记录、模板通知等处理。
+V8.Form.SelectUser = { Id: 'u1', Name: '张三', DeptId: 'd1' };
+```
+
+<!-- /microi-progressive:chunk -->

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

@@ -11,6 +11,8 @@ description: Microi V8 HTTP 集成指南。用于通过 V8.Http.Get/Post/Patch
 
 文档维护时，前端用法更新现有 `microi.doc/docs/doc/v8-engine/v8-client.md`，后端用法更新现有 `microi.doc/docs/doc/v8-engine/v8-server.md`；不要新建重复的 V8.Http 文档页面或路由。只维护中文 `docs/doc/`，英文 `docs/en/` 由官网统一翻译生成。
 
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=v8-http-integration-000 sha256=c5600510764ba7a160557ef9acd34719d1ab8c65acf635f3d4183ed5ab2e2e1f -->
 ## V8.Http API
 
 | 方法 | 说明 | 返回值 |
@@ -66,6 +68,8 @@ if (resp.StatusCode < 200 || resp.StatusCode >= 300) {
 
 `GetResponse/PostResponse/PatchResponse` 返回 `Content`、`Headers`、`RawBytes`、`StatusCode`、`ErrorMessage`。后端 `RawBytes` 是 `.NET byte[]`，前端是 `Uint8Array`。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-http-integration-001 sha256=4cbbdd385e24d19413b7534665333c07f2516067e9f34aa40e6adabe9e0506f4 -->
 ## V8.AI 与底层 HTTP
 
 - 前端 V8 的平台 AI 普通调用优先 `await V8.AI.Chat(...)`。它自动使用当前 ApiBase 和平台登录头、接收响应 Token 轮换，并清除调用参数中的租户、身份、Endpoint、ApiKey 和认证头覆盖；只有确认问题适合进入 URL 日志时才用 `V8.AI.ChatGet(...)`。
@@ -87,6 +91,8 @@ else V8.Result = result.Data;
 
 完整授权矩阵、SSE、后端安全边界与 MCP 示例维护在官网现有 `system-engine/ai-engine.md`，不要新建重复文档。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-http-integration-002 sha256=14439c586d3379c6976513df7b3c0b2f9d586ceb4d845d6f6a1abdcb1d58705a -->
 ## POST 请求（对象参数格式）
 
 > V8 接口引擎中必须使用对象参数格式。尤其禁止 `V8.Http.Get(url)`：当前 .NET 同名重载包含 `Task<string> Get(string)`，Jint 可能把字符串调用解析为异步重载，脚本最终拿到 `[object Promise]`。GET 必须写成 `V8.Http.Get({ Url: url })`；第三方登录、微信 `jscode2session`、AccessToken 等链路保存后必须用无效 code 烟测，确认返回的是第三方明确错误而不是 Promise。
@@ -105,6 +111,8 @@ var result = V8.Http.Post({
 var data = JSON.parse(result);
 ```
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-http-integration-003 sha256=4c7c1346ea1e17b2c2ff096f1cc9b6502ae95b73087f62bc6b3531d01297eddf -->
 ## PATCH 请求
 
 PATCH 与 POST 的参数完全对称，只需把请求体参数改为 `PatchParam` / `PatchParamString`：
@@ -162,241 +170,11 @@ var result = V8.Http.Post({
 });
 ```
 
-## GET 请求
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
 
-```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: '请求第三方接口失败，请稍后重试' };
-}
-```
-
-## 注意事项
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
 
-- `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
+- [references/progressive-01-get-请求.md](references/progressive-01-get-请求.md)：GET 请求；获取完整响应（含状态码和响应头）；前端 V8 行为与兼容性；下载远程文件（图片、PDF 等二进制）；第三方密钥不要硬编码；实战模式；V8.Office.SendEmail — 发送邮件
+- [references/progressive-02-错误处理模式.md](references/progressive-02-错误处理模式.md)：错误处理模式；注意事项
+<!-- microi-progressive:end -->