Skip to content

收款播报 APP:播报与小票排障 ​

更新时间:2026/11/17 11:11:43

按现象定位。部署与配置步骤见部署与激活,消息主题与回执机制见设计架构。

激活成功但收不到播报 ​

先确认是管道问题还是单笔订单问题,APP 界面与事件日志会直接显示播报连接失败的原因,可先按提示定位。九成情况出在 MQTT 消息管道:

  1. 平台配置是否填写:管理端「平台配置 → MQTT 接入」的接入地址、账号、密码是否完整,地址是否为 wss://;
  2. 消息服务是否可达:自建 Artemis 是否开放 61614、外层反代是否转发 WebSocket 升级头、证书是否有效;
  3. 订阅主题形态:激活响应下发的 topic 必须是斜杠形式 daxpay/device/audio/{设备号}。若仍是点号,说明设备未重新激活或后端未升级,点号订阅会被 broker 拒绝;
  4. ACL 是否放行:security-setting match="daxpay.device.#" 是否同时给了 amq 发布权限与 app-device 订阅、建队权限;
  5. 配置是否已下发:修改 MQTT 接入配置后,已激活设备不会自动切换,需要在 APP 中重新激活;
  6. 订单来源:线上 API、易支付来源的订单默认不播报,属设计行为。

完整逐环排查见收款播报收不到消息排查。

收款了但不打印 ​

依次检查:

检查项说明
应用开关该设备归属应用的「小票打印」是否开启,播报与打印是两个独立开关
打印机连接APP 内是否已启用打印机(在打印设置页点「启用此打印机」),连接方式与打印机是否选对
纸宽设置APP 纸宽(58 / 80mm)是否与实际用纸一致,不一致会排版异常
打印机状态是否缺纸、卡纸、离线或未开机
订单来源线上 API、易支付来源的订单默认不打印

打印数据由平台渲染成 ESC/POS 指令流,58mm 与 80mm 双流下发,APP 按纸宽选流。若语音正常、只是不出票,优先查打印机与应用开关,不必怀疑消息管道。

打印机连接断开 ​

按连接方式分别处理:

  • 经典蓝牙(SPP):确认打印机已开机并在配对范围,必要时删除配对后重新连接;
  • USB:重新插拔,确认手机识别到设备;
  • 网络(RAW TCP 9100):确认打印机与手机在同一局域网、IP 与端口填写正确、路由器未隔离终端。

打印设置即改即存,没有单独的「应用」按钮;「当前打印机」卡片置顶显示正在使用的打印机,网络打印机信息可保存备用,之后切回网络打印无需重填。参数填好后用「测试连接」验证,再点「打印测试」出测试票;运营端与商户端设备列表的「试打」入口同样可用。打印失败只影响出票,不影响语音播报与收款结果。

扫码激活失败 ​

  1. 二维码内容:应为 daxpay:activate:{设备号},只携带设备号;二维码无法识别时改用激活页手动填写设备号;
  2. 设备是否绑定商户:未绑定商户的设备无法激活,先在运营端「虚拟设备 → 设备管理」完成绑定并指定归属应用;
  3. 设备是否仍归当前商户:解绑、换绑或删除商户后,旧绑定关系失效;删除商户不会自动清理设备,需先解绑或删除;
  4. 安装包环境:服务器地址由安装包编译期内置,安装包指向的环境必须与生成设备的平台一致;
  5. 接入参数:平台侧 MQTT 接入未配置时,激活可能成功但无法建立消息连接,按上一节继续排查。

激活接口报错时,APP 会直接提示错误原因,按提示修正后重试。

提示重新激活或重复激活 ​

场景说明
换用其他环境的安装包预期行为,防止新旧环境凭证混用,按提示重新扫码
换机重新激活 / 解绑重扫码会轮换设备密钥,并把旧设备踢下线
修改 MQTT 接入配置接入地址与账号随激活下发,已激活设备需重新激活才使用新配置
主题契约调整设备凭证里的 topic 在激活时固化,契约变更后存量设备必须重新激活
连续解密失败APP 熔断并引导重新激活,说明本地凭证已与平台不一致

同一设备重复激活会轮换 secret,先前激活的终端随即失效。不要把同一设备号同时激活在两台手机上。平台侧轮换接入凭据时,APP 会自动重新激活并恢复连接,期间短暂显示「重连中」属正常,无需手动处理。

设备频繁掉线 ​

  • 接入域名不要套 CDN,长连接容易被短超时掐断;改为单独解析到源站,或经支持 WebSocket 的外层网关终结 HTTPS;
  • 反向代理的空闲超时要大于客户端心跳间隔的两倍,并关闭代理缓冲;
  • 手机侧关闭电池优化、允许自启动与后台运行,避免 APP 被系统清理;被清理后重新打开 APP 即恢复监听;
  • 用 APP「诊断」抽屉自检后台运行与播报打印两项,并复制自检报告留档。

在线状态随心跳更新。短暂离线后重连属正常,持续掉线按上述顺序排查。

小票时间是北京时间 ​

对外票据统一使用东八区时间,与平台后台展示的时区设置无关。

接口类订单不播报 ​

线上 API、易支付来源的订单面向无人收银,默认静音、不打印,不是设备故障。