WebPrint JS SDK 0.6.0 · HTTPS 网页自动连接本机打印

一、客户首次设置
1. 安装对应系统的 0.5.3 桌面软件（或后续兼容版本），并保持运行。苹果芯片 Mac 使用 arm64 版。
2. 选择系统打印机或已添加的网口设备，点击“保存打印机”。
3. 打开“服务配置与调试”，开启“允许已授权的业务网页自动连接本机打印服务”。旧版本升级后需要首次手动开启。
4. 在“允许调用的其他业务网页来源”中加入实际业务网址，例如 https://erp.example.com。只填来源，不带路径或末尾斜杠，端口非默认时需包含端口。
5. 保存设置。回到 HTTPS 业务网页，点击打印；浏览器首次请求本地网络访问权限时，请允许。

之后不需要客户复制端口或访问令牌。软件修改主服务端口后，重新自动连接即可获取最新地址。
此功能寻找的是当前电脑的软件，不扫描局域网其他电脑。实际打印机仍通过系统驱动或软件中保存的网口配置连接。

二、网站部署
将 webprint-js-sdk-0.6.0.zip 完整解压到 HTTPS 业务网站，如 /webprint/。保留 sdk.js、vendor/、render.js、chart.js、format.js 等相对目录关系。
不要只复制 sdk.js；SDK 的排版、条码等依赖也必须由业务 HTTPS 网站提供。
auto-connect-test.html 为可直接部署的测试页。访问 https://你的业务域名/webprint/auto-connect-test.html 后，按页面提示授权来源。
业务网站需要正常受信任的 HTTPS 证书。本机回环接口使用 HTTP，不安装本地证书，不要求客户跳过证书错误。

三、JS 调用示例
<script src="/webprint/sdk.js"></script>
<button onclick="printLabel(this)">打印标签</button>
<script>
async function printLabel(button) {
  button.disabled = true;
  try {
    const printer = await WebPrint.autoConnect();
    printer.init('商品标签');
    printer.setPageSize(1, '60mm', '40mm', '');
    printer.addText('2mm', '2mm', '56mm', '8mm', '商品标签 · 中文测试');
    printer.addBarcode('14mm', '2mm', '52mm', '18mm', '128Auto', 'WP10001');
    const jobId = await printer.print();
    console.log('已处理打印任务：', jobId);
  } catch (error) {
    alert(error.message);
  } finally {
    button.disabled = false;
  }
}
</script>

WebPrint.autoConnect() 返回已准备好的 WebPrint.Printer 实例，也可通过 WebPrint.getPrinter() 取得当前实例。
WebPrint JS SDK 0.6.0 使用 init、addText、print 等命名；print() 返回 Promise，成功值为本服务任务 UUID。
旧版大写方法与兼容入口仍保留，具体迁移说明见 WebPrint-JS-SDK接入说明.txt。
它自动匹配软件中已保存的本机打印机。尚未保存、设备已移除或编号不匹配时返回错误，不自动改投其他设备。
业务系统也可明确指定唯一设备：await WebPrint.autoConnect({ printerName: '系统中完整的打印机名称' })，或使用 printerId；名称匹配多个设备时会拒绝。
纸张、份数、样张仍由业务 JS 设置。任务“已提交”不代表人工确认物理出纸。

四、浏览器与 CSP
以现代 Chrome/Edge 的 HTTPS 网页为首版支持目标；浏览器的本地网络权限必须允许，不能由 JS 绕过。
SDK 使用 http://127.0.0.1 回环地址，并在 fetch 中标记 targetAddressSpace: 'loopback'。
如网站设置 CSP，至少要允许 connect-src 'self' http://127.0.0.1:*；SDK 静态文件可由 script-src 'self' 加载。使用弹出/内嵌预览时也需允许对应本机窗口或 frame-src。
不可将所有 https://业务网页 → 任意 HTTP 局域网地址理解为均可访问；本版自动发现只访问本机回环地址。
Safari、Firefox、企业定制浏览器及 WebView 的实际权限/策略兼容需要另行测试；本版不宣称所有浏览器均可无设置使用。

五、权限和故障
软件仅在 127.0.0.1 的 18118/18119/18120 中选择可用发现端口；主打印/管理服务仍使用原来的随机或指定端口。
发现端口全部占用时会在软件显示原因；手工接入配置仍可使用。不要对用户网络进行端口扫描。
SDK 不向网页提供本机管理令牌；授权网址获得约 15 分钟有效、绑定来源的临时打印凭据，只可打印、预览并查询自己创建的任务。
不同业务来源的请求编号和任务查询隔离；重复请求编号及相同内容不会产生重复任务。修改来源或关闭自动连接可撤销已有临时凭据。
自动连接不授权读写本地文件、串口、原始指令、修改软件配置或读取保存的远端连接凭据。这些扩展仍需原有的显式管理接入。
临时凭据仅保存在页面内存，不写入 URL、localStorage、sessionStorage 或测试报告。页面加载和自动连接本身不会打印。

常见错误：
AUTO_CONNECT_DISABLED：在软件配置页打开网页自动连接。
ORIGIN_NOT_AUTHORIZED：在软件中添加当前业务网页来源。
PRINTER_NOT_SAVED：先在打印软件中选择并保存打印机。
SAVED_PRINTER_UNAVAILABLE：已保存设备不可用，请检查系统驱动/网口配置后重新保存。
LOCAL_SERVICE_NOT_FOUND：软件未运行、发现端口被占用、浏览器拒绝本地网络权限或 CSP 拦截。
SERVICE_RESTARTING：正在应用服务设置，等待后重新连接。

浏览器规则参考：
https://learn.microsoft.com/en-us/deployedge/ms-edge-local-network-access
https://developer.chrome.com/blog/local-network-access
