@microi.net/cli 5.8.5 → 5.8.6

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

@@ -1,258 +1,258 @@
-# V8.Print 蓝牙打印运行指南（GP-M322 / ZICOX CC4）
-
-本参考用于 Microi 前端 V8 的 BLE/SPP 标签和小票打印。运行时事实源为
-`Microi.Client/src/utils/v8-print.js`，型号与协议适配事实源为
-`Microi.Client/src/utils/ble/printer-compatibility.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。
-
-三个入口都会取得同一个应用级 `Print` 单例。分包游标、打印份数和连接引用仍是可变状态，
-但 `prepareSend` 已把所有前端 V8 上下文排进同一条运行时发送队列。业务代码仍应逐次
-`await` 保持明确的结果顺序，不能认为不同按钮或不同 V8 对象彼此隔离。
-
-PC/平板顶部导航和移动端【我的】页的蓝牙入口也使用该单例：它们展示实时连接状态和设备名，
-点击后复用 `OpenBluetoothPage()`，因此用户可以先在全局入口连接，再进入任意模块执行 V8 打印。
-
-## 微服务中的平台普通打印桥
-
-隔离运行的 MicroService 不能直接访问父页面 `V8.Print`、Vue 组件或打印弹窗。微服务页面需要
-提供“普通打印”时，调用 `microi.host.v1` 的 `openPlatformPrint` 宿主动作；参数为当前租户
-`mic_print.Id`、标题，以及当前 `apiBase` 同源、路径以 `/apiengine/` 开头并明确携带同一
-`OsClient` 的绝对数据地址。禁止把 Token、帐号密码或其它凭据放进 URL。
-
-`openPlatformPrint` 只打开 Print Engine 预览，不发送 TSPL/CPCL/ESC-POS；它不是蓝牙代理，
-也不发送 BLE/SPP 字节。
-宿主返回 `accepted:true` 只表示预览已打开，不代表浏览器已打印或打印机已出纸。独立运行没有
-宿主能力时应隐藏/禁用该入口。完整调用示例与结果协议见
-`../../microi-microservice/references/runtime-delivery.md` 的“微服务调用平台普通打印”。
-
-## 运行环境与能力判断
-
-| 运行环境 | 当前引擎 | 结论 |
-|---|---|---|
-| Android 5+App | `plus.bluetooth` + `plus.android` | BLE；ZICOX CC4 可回退到已配对 RFCOMM/SPP；Android 12+ 需要附近设备权限 |
-| iOS 5+App | `plus.bluetooth` | BLE，不使用 Android SPP |
-| 存在 `navigator.bluetooth.requestDevice` 的浏览器 | Web Bluetooth | 支持；通常要求安全上下文和用户手势 |
-| 其它普通 H5/浏览器 | 无 | `V8.Print` 仍可能存在，但连接页会提示能力不可用 |
-| 微信小程序原生 BLE | 不属于此模块 | 需要小程序/UniApp 侧专用实现 |
-
-不要用 `V8.ClientType === 'PC'` 判断蓝牙能力，也不要只检查
-`BLEInformation.deviceId`。正确顺序是检查 `V8.Print`、调用 `isConnected()`，再在
-用户点击事件中 `await OpenBluetoothPage()`。
-
-Android 12+ 宿主必须启用 DCloud Bluetooth 模块并声明 `BLUETOOTH_SCAN`、
-`BLUETOOTH_CONNECT`。运行时只在用户主动点击“搜索”时申请，不得在页面初始化或自动重连
-时弹授权框；拒绝或永久拒绝要引导用户进入系统“附近的设备”权限设置。
-
-浏览器模板、PDF、A4 单据和 Print Engine JSON 属于 `print-engine`；TSC/TSPL 或
-CPCL/ESC/POS 原生字节通过 BLE/SPP 写入才属于 `V8.Print`。
-
-## 双型号兼容契约
-
-| 型号 | 标签协议 | 传输 | 兼容承诺 |
-|---|---|---|---|
-| 佳博 GP-M322 | TSPL | BLE | `createNew().getData()` 原字节发送，协议适配层不得改写 |
-| ZICOX CC4 | CPCL | BLE 优先，Android SPP 兜底 | 同一份标准 TSC 高层调用在首包写入前转换为 CPCL |
-| 其它 TSPL | TSPL | BLE | 保持原字节路径 |
-
-`createNewESC()` 在 CC4 上也原样发送，因为厂家声明 CC4 支持 ESC/POS。不要根据厂家 Demo
-里存在测试字符串就擅自宣称其它协议；以产品页、准确手册和实机固件为准。
-
-TSC 构建器给字节数组附加不可枚举的操作元数据，因此 GP 字节值、长度与数组枚举完全不变。
-CC4 必须直接收到同一次 `getData()` 返回值；`Array.from`、展开、JSON 序列化等复制会丢失
-元数据并失败关闭。适配器先完成整份转换和校验，再开始分包；不支持的命令不得产生半张输出。
-
-CC4 可转换：纸张尺寸、速度、浓度、间隙/黑标、前后走纸、方向 0/1、参考点、线/框/反相、
-文字、条码、二维码、位图及单次 `setPagePrint`。`init`/`setCls` 无需输出。原始 `addCommand`、
-国家/代码页、`setFromfeed`、`setHome`、蜂鸣、限位、擦除和未知方法没有足够等价语义，必须
-在首包写入前拒绝。扩展白名单前要同时增加协议单测和两台目标机回归。
-
-Android SPP 与厂家 Demo 一致，优先 RFCOMM 通道 1，再以标准 UUID
-`00001101-0000-1000-8000-00805F9B34FB` 兜底。自动模式只显示名称可识别为 CC4 的已配对
-经典设备；广播名不规范时，用户先手工选择 `zicox-cc4`。Web Bluetooth 不能访问 SPP。
-
-## 连接与发送语义
-
-| API | 当前真实语义 |
-|---|---|
-| `createNew()` | 新建 TSC/TSPL 标签指令构建器 |
-| `createNewESC()` | 新建 ESC/POS 小票指令构建器 |
-| `OpenBluetoothPage()` | 返回 `Promise<boolean>`；在连接弹窗关闭时解析，重复打开复用同一个 Promise |
-| `isConnected()` | Web 端检查实时 GATT 与写特征；5+App 结合连接事件在线标记与设备/写特征 ID |
-| `reconnect()` | 使用已记住的设备 ID 或浏览器保留的设备授权重连，不弹选择框 |
-| `getConnectionState()` | 返回可展示的连接、记忆、设备、错误和重连状态快照 |
-| `subscribeConnection(listener)` | 立即回调当前快照并持续通知状态变化，返回取消订阅函数 |
-| `getPrinterProfile()` | 返回最终型号、标签指令和传输偏好；普通业务无需调用 |
-| `setPrinterProfile(mode)` | 手工选 `gprinter-gp-m322`、`zicox-cc4`、`generic-tspl`，或恢复 `auto` |
-| `prepareSend(bytes)` | 先恢复连接、完成型号协议适配，再进入应用级队列按包串行写入 |
-| `Send(bytes)` | 依赖 `prepareSend` 已设置的内部游标，属于内部状态机入口，业务代码不要直接调用 |
-| `setOneTimeData(bytes)` | 设置 BLE 包长；只接受 1–512 整数，连接页候选 20–190，默认 20 |
-| `setPrinterNum(num)` | 重复发送同一缓冲区；只接受 1–99 整数，连接页候选 1–9 |
-| `disconnect()` | 主动断开、停止自动重连并忘记当前设备 |
-| `BLEInformation` | 最近设备/型号/通道/服务/特征元数据，只用于诊断，不代表实时连接或打印回执 |
-
-`getConnectionState()` 额外含 `transport`、`profileMode`、`profileId`、`profileName`、
-`commandLanguage`；前端展示可以使用，打印判断仍使用 `isConnected()`。
-
-`OpenBluetoothPage()` 不是“连接成功事件”；用户连上设备后仍要关闭弹窗，调用方才能继续。
-设备元数据会写入 `localStorage` 与兼容用 `sessionStorage`。应用初始化、页面恢复、重新获得
-焦点和意外断线时会做有限次数自动重连：5+App 使用设备 ID；Web 端只有浏览器保留授权且
-支持 `navigator.bluetooth.getDevices()` 时才可无弹窗恢复。系统蓝牙、浏览器权限、设备电源、
-休眠、距离等仍会造成真实断线；重试结束后必须让用户从全局入口重新选择。
-
-## 最小安全流程
-
-```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.reconnect();
-  if (!connected) 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());
-}
-```
-
-同一段标签代码在 GP-M322 上保持 TSPL，在 CC4 上转换为 CPCL。ESC/POS 小票使用
-`createNewESC()`，完整顺序和 25 个真实方法见
-[`bluetooth-print-api.md`](bluetooth-print-api.md)。发送成功只表示 BLE/SPP 写调用完成，不能
-写成“打印机已走纸”或“物理打印成功”。当前源码虽发现 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` 表达同一设备的并行打印。运行时会把同时到达的调用排队，但业务仍应逐条
-  `await`，以便准确记录哪一条成功或失败。
-- 大批次分段并持久化 `NextIndex`；页面关闭、断连或写失败后从失败位置人工确认再恢复。
-- `setPrinterNum(n)` 只适合同一缓冲区重复发送，不适合每张内容不同的批次。
-- 业务落库与蓝牙打印不是原子事务。用稳定业务单号支持受控重打，不重复执行业务写入。
-
-## 兼容性与当前限制
-
-- Web Bluetooth 仅把四个常见服务 UUID 传入 `optionalServices`：`18f0`、`ff00`、
-  `49535343-fe7d-4ae5-8fa9-9fafd205e455`、`e7810a71-73ae-499d-8c15-faa9aef0c3f2`。
-  当前没有公开的自定义服务配置，并选择枚举到的第一个可写特征；其它型号可能需要扩展源码。
-  CC4 固件若只开放 SPP 或使用其它私有 UUID，Web 端不可连接；Android 5+App 使用已配对 SPP，
-  或先取得厂家准确 BLE UUID 再扩展源码，禁止猜 UUID。
-- `prepareSend` 默认每包 20 字节；Android 5+ 的佳博 GP-M322 在特征支持时优先使用同一
-  `plus.bluetooth` 连接的 `writeNoResponse`，逐包 await API 回调并保留约 8ms 的 GATT 保护窗口；
-  即使协商出 180 字节有效载荷也只采用 100 字节稳定档。不支持无响应写时保留 `write` 兼容路径。其它型号、iOS、Web 与 SPP
-  保留约 20ms，同一缓冲区多份间约 100ms。5+ BLE 的连接、服务发现和写入统一使用 `plus.bluetooth`，
-  禁止用 `uni.writeBLECharacteristicValue` 写入由 `plus.bluetooth` 建立的连接。
-  这是写节奏，不是物理走纸确认。5+ BLE 同时受本次连接的 `maxWriteBytes` 和更保守的
-  `recommendedPacketSize` 限制；未知 MTU 为 20。
-- 5+ 佳博在服务发现后协商 MTU，最多等待 1.5 秒，`getConnectionState()` 返回 `mtu`、
-  `maxWriteBytes`、`recommendedPacketSize`（20/100）、`writeType`、`packetIntervalMs`。
-  必须读取真实回调的 `mtu`；空成功、失败、超时或缺 API 不可按请求值升档，迟到回调不得提升能力，
-  断开时清除能力。自定义微服务需按这些字段判断，不能只允许 `engine === 'web'`。
-  `microi.app` 在线壳更新远程前端即可获取本修复；WebView 缺少 Web Bluetooth 时不增加无效切换选项。
-- 当前分包公式使用 `Math.ceil(length / packetSize)`，长度恰好整除时不会产生 0 字节末包；
-  空数据、非法包长和非法份数会直接抛错。合法数值仍须按目标打印机实测。
-- TSC 与 ESC 文本使用仓库内置 `encoding.js` + `encoding-indexes.js` 转为 GB18030，运行时
-  不请求网络。编码成功不等于打印机字体、代码页和固件支持全部字符；Emoji 等仍需实机验证。
-- `setBitmap` 接受 ImageData 风格 `{ width, height, data }` RGBA 数据。当前黑白转换较简单，
-  大图可能产生大缓冲区；先缩放、二值化并用小图测试。
-- `V8.Print` 使用应用级共享发送队列，跨 V8 上下文不会再并发覆盖 `currentTime`、`looptime`、
-  `lastData` 等共享状态。队列只保证写入顺序，不提供打印机 ACK、业务事务或自动重打语义。
-- CC4 遇到不支持的方法、复制后丢失元数据、缺少或重复 `setPagePrint()` 时应零写入失败；不要
-  在业务层捕获后把原 TSPL 盲目重发给 CC4。
-
-## 安全边界
-
-- TSC 的 `setText`、`setQR`、`setBarCode` 和 `addCommand` 会拼协议文本。移除引号、换行、
-  NUL/控制字符并限制长度；`addCommand` 只接受固定、受审查的命令。
-- 蓝牙设备名称、ID 和服务特征均是外部输入。不要拼入 `innerHTML`，展示时做文本转义；不要
-  记录或上传完整 `BLEInformation`，以免泄露终端指纹。
-- 金额、数量、坐标、纸张尺寸、包长和份数先做类型/范围校验，避免无限循环或超大缓冲区。
-- 打印内容含个人信息、票据或密钥时，不写控制台、系统日志或异常上报正文。
-- 浏览器权限拒绝、用户取消、GATT 断开、找不到服务/特征和写包失败都必须可理解地提示。
-- 搜索不到设备的头号原因是残留 GATT 连接：BLE 外设在已连接期间停止广播，上一次连接被并发流程打断或 App 重启后系统仍保留旧链路时，打印机“没在用”但也搜不到。平台在开始发现前会先 `getConnectedBluetoothDevices` 并关闭应用未持有的连接，被断开/重连事件接管时也会显式关闭自己建立的链路；排查顺序据此固定为“清理残留连接 → 打印机重新上电 → 系统蓝牙忽略设备 → 再搜索”，不要先去改包长、MTU 或指令集。
-
-## 实机验收
-
-至少记录：
-
-1. GP-M322 与 CC4 的固件、纸张规格、服务/写特征 UUID 或 SPP、指令集。
-2. 5+App 或浏览器版本；首次授权/配对、自动/手工选型、再次连接、主动断开、页面刷新和断线重连。
-3. 中文、数字、特殊字符、二维码、条码、长文本、图片和边界金额。
-4. 默认 20 字节与目标包长；同时覆盖“长度恰好整除包长”。
-5. 连续 20 张严格串行发送，无乱序、丢包、重复或任务状态互相污染。
-6. 中途关机、缺纸、离开范围、权限撤销后的失败位置与恢复行为。
-7. 两种设备交替连接，证明 GP 原 TSPL 不变、CC4 收到 CPCL/ESC-POS；CC4 分别记录 BLE 与 SPP。
-8. 页面只确认“数据已发送”；若业务要求确认物理结果，另接状态回读或人工确认。
+# V8.Print 蓝牙打印运行指南（GP-M322 / ZICOX CC4）
+
+本参考用于 Microi 前端 V8 的 BLE/SPP 标签和小票打印。运行时事实源为
+`Microi.Client/src/utils/v8-print.js`，型号与协议适配事实源为
+`Microi.Client/src/utils/ble/printer-compatibility.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。
+
+三个入口都会取得同一个应用级 `Print` 单例。分包游标、打印份数和连接引用仍是可变状态，
+但 `prepareSend` 已把所有前端 V8 上下文排进同一条运行时发送队列。业务代码仍应逐次
+`await` 保持明确的结果顺序，不能认为不同按钮或不同 V8 对象彼此隔离。
+
+PC/平板顶部导航和移动端【我的】页的蓝牙入口也使用该单例：它们展示实时连接状态和设备名，
+点击后复用 `OpenBluetoothPage()`，因此用户可以先在全局入口连接，再进入任意模块执行 V8 打印。
+
+## 微服务中的平台普通打印桥
+
+隔离运行的 MicroService 不能直接访问父页面 `V8.Print`、Vue 组件或打印弹窗。微服务页面需要
+提供“普通打印”时，调用 `microi.host.v1` 的 `openPlatformPrint` 宿主动作；参数为当前租户
+`mic_print.Id`、标题，以及当前 `apiBase` 同源、路径以 `/apiengine/` 开头并明确携带同一
+`OsClient` 的绝对数据地址。禁止把 Token、帐号密码或其它凭据放进 URL。
+
+`openPlatformPrint` 只打开 Print Engine 预览，不发送 TSPL/CPCL/ESC-POS；它不是蓝牙代理，
+也不发送 BLE/SPP 字节。
+宿主返回 `accepted:true` 只表示预览已打开，不代表浏览器已打印或打印机已出纸。独立运行没有
+宿主能力时应隐藏/禁用该入口。完整调用示例与结果协议见
+`../../microi-microservice/references/runtime-delivery.md` 的“微服务调用平台普通打印”。
+
+## 运行环境与能力判断
+
+| 运行环境 | 当前引擎 | 结论 |
+|---|---|---|
+| Android 5+App | `plus.bluetooth` + `plus.android` | BLE；ZICOX CC4 可回退到已配对 RFCOMM/SPP；Android 12+ 需要附近设备权限 |
+| iOS 5+App | `plus.bluetooth` | BLE，不使用 Android SPP |
+| 存在 `navigator.bluetooth.requestDevice` 的浏览器 | Web Bluetooth | 支持；通常要求安全上下文和用户手势 |
+| 其它普通 H5/浏览器 | 无 | `V8.Print` 仍可能存在，但连接页会提示能力不可用 |
+| 微信小程序原生 BLE | 不属于此模块 | 需要小程序/UniApp 侧专用实现 |
+
+不要用 `V8.ClientType === 'PC'` 判断蓝牙能力，也不要只检查
+`BLEInformation.deviceId`。正确顺序是检查 `V8.Print`、调用 `isConnected()`，再在
+用户点击事件中 `await OpenBluetoothPage()`。
+
+Android 12+ 宿主必须启用 DCloud Bluetooth 模块并声明 `BLUETOOTH_SCAN`、
+`BLUETOOTH_CONNECT`。运行时只在用户主动点击“搜索”时申请，不得在页面初始化或自动重连
+时弹授权框；拒绝或永久拒绝要引导用户进入系统“附近的设备”权限设置。
+
+浏览器模板、PDF、A4 单据和 Print Engine JSON 属于 `print-engine`；TSC/TSPL 或
+CPCL/ESC/POS 原生字节通过 BLE/SPP 写入才属于 `V8.Print`。
+
+## 双型号兼容契约
+
+| 型号 | 标签协议 | 传输 | 兼容承诺 |
+|---|---|---|---|
+| 佳博 GP-M322 | TSPL | BLE | `createNew().getData()` 原字节发送，协议适配层不得改写 |
+| ZICOX CC4 | CPCL | BLE 优先，Android SPP 兜底 | 同一份标准 TSC 高层调用在首包写入前转换为 CPCL |
+| 其它 TSPL | TSPL | BLE | 保持原字节路径 |
+
+`createNewESC()` 在 CC4 上也原样发送，因为厂家声明 CC4 支持 ESC/POS。不要根据厂家 Demo
+里存在测试字符串就擅自宣称其它协议；以产品页、准确手册和实机固件为准。
+
+TSC 构建器给字节数组附加不可枚举的操作元数据，因此 GP 字节值、长度与数组枚举完全不变。
+CC4 必须直接收到同一次 `getData()` 返回值；`Array.from`、展开、JSON 序列化等复制会丢失
+元数据并失败关闭。适配器先完成整份转换和校验，再开始分包；不支持的命令不得产生半张输出。
+
+CC4 可转换：纸张尺寸、速度、浓度、间隙/黑标、前后走纸、方向 0/1、参考点、线/框/反相、
+文字、条码、二维码、位图及单次 `setPagePrint`。`init`/`setCls` 无需输出。原始 `addCommand`、
+国家/代码页、`setFromfeed`、`setHome`、蜂鸣、限位、擦除和未知方法没有足够等价语义，必须
+在首包写入前拒绝。扩展白名单前要同时增加协议单测和两台目标机回归。
+
+Android SPP 与厂家 Demo 一致，优先 RFCOMM 通道 1，再以标准 UUID
+`00001101-0000-1000-8000-00805F9B34FB` 兜底。自动模式只显示名称可识别为 CC4 的已配对
+经典设备；广播名不规范时，用户先手工选择 `zicox-cc4`。Web Bluetooth 不能访问 SPP。
+
+## 连接与发送语义
+
+| API | 当前真实语义 |
+|---|---|
+| `createNew()` | 新建 TSC/TSPL 标签指令构建器 |
+| `createNewESC()` | 新建 ESC/POS 小票指令构建器 |
+| `OpenBluetoothPage()` | 返回 `Promise<boolean>`；在连接弹窗关闭时解析，重复打开复用同一个 Promise |
+| `isConnected()` | Web 端检查实时 GATT 与写特征；5+App 结合连接事件在线标记与设备/写特征 ID |
+| `reconnect()` | 使用已记住的设备 ID 或浏览器保留的设备授权重连，不弹选择框 |
+| `getConnectionState()` | 返回可展示的连接、记忆、设备、错误和重连状态快照 |
+| `subscribeConnection(listener)` | 立即回调当前快照并持续通知状态变化，返回取消订阅函数 |
+| `getPrinterProfile()` | 返回最终型号、标签指令和传输偏好；普通业务无需调用 |
+| `setPrinterProfile(mode)` | 手工选 `gprinter-gp-m322`、`zicox-cc4`、`generic-tspl`，或恢复 `auto` |
+| `prepareSend(bytes)` | 先恢复连接、完成型号协议适配，再进入应用级队列按包串行写入 |
+| `Send(bytes)` | 依赖 `prepareSend` 已设置的内部游标，属于内部状态机入口，业务代码不要直接调用 |
+| `setOneTimeData(bytes)` | 设置 BLE 包长；只接受 1–512 整数，连接页候选 20–190，默认 20 |
+| `setPrinterNum(num)` | 重复发送同一缓冲区；只接受 1–99 整数，连接页候选 1–9 |
+| `disconnect()` | 主动断开、停止自动重连并忘记当前设备 |
+| `BLEInformation` | 最近设备/型号/通道/服务/特征元数据，只用于诊断，不代表实时连接或打印回执 |
+
+`getConnectionState()` 额外含 `transport`、`profileMode`、`profileId`、`profileName`、
+`commandLanguage`；前端展示可以使用，打印判断仍使用 `isConnected()`。
+
+`OpenBluetoothPage()` 不是“连接成功事件”；用户连上设备后仍要关闭弹窗，调用方才能继续。
+设备元数据会写入 `localStorage` 与兼容用 `sessionStorage`。应用初始化、页面恢复、重新获得
+焦点和意外断线时会做有限次数自动重连：5+App 使用设备 ID；Web 端只有浏览器保留授权且
+支持 `navigator.bluetooth.getDevices()` 时才可无弹窗恢复。系统蓝牙、浏览器权限、设备电源、
+休眠、距离等仍会造成真实断线；重试结束后必须让用户从全局入口重新选择。
+
+## 最小安全流程
+
+```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.reconnect();
+  if (!connected) 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());
+}
+```
+
+同一段标签代码在 GP-M322 上保持 TSPL，在 CC4 上转换为 CPCL。ESC/POS 小票使用
+`createNewESC()`，完整顺序和 25 个真实方法见
+[`bluetooth-print-api.md`](bluetooth-print-api.md)。发送成功只表示 BLE/SPP 写调用完成，不能
+写成“打印机已走纸”或“物理打印成功”。当前源码虽发现 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` 表达同一设备的并行打印。运行时会把同时到达的调用排队，但业务仍应逐条
+  `await`，以便准确记录哪一条成功或失败。
+- 大批次分段并持久化 `NextIndex`；页面关闭、断连或写失败后从失败位置人工确认再恢复。
+- `setPrinterNum(n)` 只适合同一缓冲区重复发送，不适合每张内容不同的批次。
+- 业务落库与蓝牙打印不是原子事务。用稳定业务单号支持受控重打，不重复执行业务写入。
+
+## 兼容性与当前限制
+
+- Web Bluetooth 仅把四个常见服务 UUID 传入 `optionalServices`：`18f0`、`ff00`、
+  `49535343-fe7d-4ae5-8fa9-9fafd205e455`、`e7810a71-73ae-499d-8c15-faa9aef0c3f2`。
+  当前没有公开的自定义服务配置，并选择枚举到的第一个可写特征；其它型号可能需要扩展源码。
+  CC4 固件若只开放 SPP 或使用其它私有 UUID，Web 端不可连接；Android 5+App 使用已配对 SPP，
+  或先取得厂家准确 BLE UUID 再扩展源码，禁止猜 UUID。
+- `prepareSend` 默认每包 20 字节；Android 5+ 的佳博 GP-M322 在特征支持时优先使用同一
+  `plus.bluetooth` 连接的 `writeNoResponse`，逐包 await API 回调并保留约 8ms 的 GATT 保护窗口；
+  即使协商出 180 字节有效载荷也只采用 100 字节稳定档。不支持无响应写时保留 `write` 兼容路径。其它型号、iOS、Web 与 SPP
+  保留约 20ms，同一缓冲区多份间约 100ms。5+ BLE 的连接、服务发现和写入统一使用 `plus.bluetooth`，
+  禁止用 `uni.writeBLECharacteristicValue` 写入由 `plus.bluetooth` 建立的连接。
+  这是写节奏，不是物理走纸确认。5+ BLE 同时受本次连接的 `maxWriteBytes` 和更保守的
+  `recommendedPacketSize` 限制；未知 MTU 为 20。
+- 5+ 佳博在服务发现后协商 MTU，最多等待 1.5 秒，`getConnectionState()` 返回 `mtu`、
+  `maxWriteBytes`、`recommendedPacketSize`（20/100）、`writeType`、`packetIntervalMs`。
+  必须读取真实回调的 `mtu`；空成功、失败、超时或缺 API 不可按请求值升档，迟到回调不得提升能力，
+  断开时清除能力。自定义微服务需按这些字段判断，不能只允许 `engine === 'web'`。
+  `microi.app` 在线壳更新远程前端即可获取本修复；WebView 缺少 Web Bluetooth 时不增加无效切换选项。
+- 当前分包公式使用 `Math.ceil(length / packetSize)`，长度恰好整除时不会产生 0 字节末包；
+  空数据、非法包长和非法份数会直接抛错。合法数值仍须按目标打印机实测。
+- TSC 与 ESC 文本使用仓库内置 `encoding.js` + `encoding-indexes.js` 转为 GB18030，运行时
+  不请求网络。编码成功不等于打印机字体、代码页和固件支持全部字符；Emoji 等仍需实机验证。
+- `setBitmap` 接受 ImageData 风格 `{ width, height, data }` RGBA 数据。当前黑白转换较简单，
+  大图可能产生大缓冲区；先缩放、二值化并用小图测试。
+- `V8.Print` 使用应用级共享发送队列，跨 V8 上下文不会再并发覆盖 `currentTime`、`looptime`、
+  `lastData` 等共享状态。队列只保证写入顺序，不提供打印机 ACK、业务事务或自动重打语义。
+- CC4 遇到不支持的方法、复制后丢失元数据、缺少或重复 `setPagePrint()` 时应零写入失败；不要
+  在业务层捕获后把原 TSPL 盲目重发给 CC4。
+
+## 安全边界
+
+- TSC 的 `setText`、`setQR`、`setBarCode` 和 `addCommand` 会拼协议文本。移除引号、换行、
+  NUL/控制字符并限制长度；`addCommand` 只接受固定、受审查的命令。
+- 蓝牙设备名称、ID 和服务特征均是外部输入。不要拼入 `innerHTML`，展示时做文本转义；不要
+  记录或上传完整 `BLEInformation`，以免泄露终端指纹。
+- 金额、数量、坐标、纸张尺寸、包长和份数先做类型/范围校验，避免无限循环或超大缓冲区。
+- 打印内容含个人信息、票据或密钥时，不写控制台、系统日志或异常上报正文。
+- 浏览器权限拒绝、用户取消、GATT 断开、找不到服务/特征和写包失败都必须可理解地提示。
+- 搜索不到设备的头号原因是残留 GATT 连接：BLE 外设在已连接期间停止广播，上一次连接被并发流程打断或 App 重启后系统仍保留旧链路时，打印机“没在用”但也搜不到。平台在开始发现前会先 `getConnectedBluetoothDevices` 并关闭应用未持有的连接，被断开/重连事件接管时也会显式关闭自己建立的链路；排查顺序据此固定为“清理残留连接 → 打印机重新上电 → 系统蓝牙忽略设备 → 再搜索”，不要先去改包长、MTU 或指令集。
+
+## 实机验收
+
+至少记录：
+
+1. GP-M322 与 CC4 的固件、纸张规格、服务/写特征 UUID 或 SPP、指令集。
+2. 5+App 或浏览器版本；首次授权/配对、自动/手工选型、再次连接、主动断开、页面刷新和断线重连。
+3. 中文、数字、特殊字符、二维码、条码、长文本、图片和边界金额。
+4. 默认 20 字节与目标包长；同时覆盖“长度恰好整除包长”。
+5. 连续 20 张严格串行发送，无乱序、丢包、重复或任务状态互相污染。
+6. 中途关机、缺纸、离开范围、权限撤销后的失败位置与恢复行为。
+7. 两种设备交替连接，证明 GP 原 TSPL 不变、CC4 收到 CPCL/ESC-POS；CC4 分别记录 BLE 与 SPP。
+8. 页面只确认“数据已发送”；若业务要求确认物理结果，另接状态回读或人工确认。