第三方 Web 前端接入 Print Agent 的完整流程

第一步：安装并授权站点

在用户电脑安装对应平台的 Agent。生产环境不使用开发 Token，应通过安装器生成的引导凭据完成配对，并将业务站点的精确 Origin 加入允许范围。

协议、主机、端口不同就是不同 Origin；localhost 与 127.0.0.1 也不能混用。

第二步：读取能力和打印机

连接成功后先读取 capabilities、license 和 printers。前端应保留 printers 返回的精确队列名，不要删除空格、下划线或自行转换网络 URI。

• 检查 protocolVersion 是否兼容
• 检查许可证是否包含目标打印通道
• 展示系统队列的精确名称与状态
• 根据媒体和切刀能力启用对应交互

第三步：选择任务类型

动态结构化排版使用 PIR，已有可信 PDF 使用 PDF 通道，固定业务单据优先使用已发布模板，小票与切刀使用受控 ESC/POS。正式业务更推荐固定模板，因为它更容易审计、复现和升级。

第四步：幂等提交与状态追踪

每次业务打印应生成稳定的幂等键，网络重试继续使用同一个键。任务提交后轮询状态直到终态；submitted_to_spooler 表示已交给系统打印队列，不等同于传感器确认纸张已经物理输出。

第五步：上线与故障处理

上线前固定 SDK 与协议版本，保存模板版本、打印机名称和任务 ID。售后使用脱敏诊断导出定位问题，不要上传客户原始文档、正式凭据或整个状态数据库。