简体中文
收款播报 APP:播报与小票排障
按现象定位。部署与配置步骤见部署与激活,消息主题与回执机制见设计架构。
激活成功但收不到播报
先确认是管道问题还是单笔订单问题,APP 界面与事件日志会直接显示播报连接失败的原因,可先按提示定位。九成情况出在 MQTT 消息管道:
- 平台配置是否填写:管理端「平台配置 → MQTT 接入」的接入地址、账号、密码是否完整,地址是否为
wss://; - 消息服务是否可达:自建 Artemis 是否开放 61614、外层反代是否转发 WebSocket 升级头、证书是否有效;
- 订阅主题形态:激活响应下发的
topic必须是斜杠形式daxpay/device/audio/{设备号}。若仍是点号,说明设备未重新激活或后端未升级,点号订阅会被 broker 拒绝; - ACL 是否放行:
security-setting match="daxpay.device.#"是否同时给了amq发布权限与app-device订阅、建队权限; - 配置是否已下发:修改 MQTT 接入配置后,已激活设备不会自动切换,需要在 APP 中重新激活;
- 订单来源:线上 API、易支付来源的订单默认不播报,属设计行为。
完整逐环排查见收款播报收不到消息排查。
收款了但不打印
依次检查:
| 检查项 | 说明 |
|---|---|
| 应用开关 | 该设备归属应用的「小票打印」是否开启,播报与打印是两个独立开关 |
| 打印机连接 | APP 内是否已启用打印机(在打印设置页点「启用此打印机」),连接方式与打印机是否选对 |
| 纸宽设置 | APP 纸宽(58 / 80mm)是否与实际用纸一致,不一致会排版异常 |
| 打印机状态 | 是否缺纸、卡纸、离线或未开机 |
| 订单来源 | 线上 API、易支付来源的订单默认不打印 |
打印数据由平台渲染成 ESC/POS 指令流,58mm 与 80mm 双流下发,APP 按纸宽选流。若语音正常、只是不出票,优先查打印机与应用开关,不必怀疑消息管道。
打印机连接断开
按连接方式分别处理:
- 经典蓝牙(SPP):确认打印机已开机并在配对范围,必要时删除配对后重新连接;
- USB:重新插拔,确认手机识别到设备;
- 网络(RAW TCP 9100):确认打印机与手机在同一局域网、IP 与端口填写正确、路由器未隔离终端。
打印设置即改即存,没有单独的「应用」按钮;「当前打印机」卡片置顶显示正在使用的打印机,网络打印机信息可保存备用,之后切回网络打印无需重填。参数填好后用「测试连接」验证,再点「打印测试」出测试票;运营端与商户端设备列表的「试打」入口同样可用。打印失败只影响出票,不影响语音播报与收款结果。
扫码激活失败
- 二维码内容:应为
daxpay:activate:{设备号},只携带设备号;二维码无法识别时改用激活页手动填写设备号; - 设备是否绑定商户:未绑定商户的设备无法激活,先在运营端「虚拟设备 → 设备管理」完成绑定并指定归属应用;
- 设备是否仍归当前商户:解绑、换绑或删除商户后,旧绑定关系失效;删除商户不会自动清理设备,需先解绑或删除;
- 安装包环境:服务器地址由安装包编译期内置,安装包指向的环境必须与生成设备的平台一致;
- 接入参数:平台侧 MQTT 接入未配置时,激活可能成功但无法建立消息连接,按上一节继续排查。
激活接口报错时,APP 会直接提示错误原因,按提示修正后重试。
提示重新激活或重复激活
| 场景 | 说明 |
|---|---|
| 换用其他环境的安装包 | 预期行为,防止新旧环境凭证混用,按提示重新扫码 |
| 换机重新激活 / 解绑 | 重扫码会轮换设备密钥,并把旧设备踢下线 |
| 修改 MQTT 接入配置 | 接入地址与账号随激活下发,已激活设备需重新激活才使用新配置 |
| 主题契约调整 | 设备凭证里的 topic 在激活时固化,契约变更后存量设备必须重新激活 |
| 连续解密失败 | APP 熔断并引导重新激活,说明本地凭证已与平台不一致 |
同一设备重复激活会轮换 secret,先前激活的终端随即失效。不要把同一设备号同时激活在两台手机上。平台侧轮换接入凭据时,APP 会自动重新激活并恢复连接,期间短暂显示「重连中」属正常,无需手动处理。
设备频繁掉线
- 接入域名不要套 CDN,长连接容易被短超时掐断;改为单独解析到源站,或经支持 WebSocket 的外层网关终结 HTTPS;
- 反向代理的空闲超时要大于客户端心跳间隔的两倍,并关闭代理缓冲;
- 手机侧关闭电池优化、允许自启动与后台运行,避免 APP 被系统清理;被清理后重新打开 APP 即恢复监听;
- 用 APP「诊断」抽屉自检后台运行与播报打印两项,并复制自检报告留档。
在线状态随心跳更新。短暂离线后重连属正常,持续掉线按上述顺序排查。
小票时间是北京时间
对外票据统一使用东八区时间,与平台后台展示的时区设置无关。
接口类订单不播报
线上 API、易支付来源的订单面向无人收银,默认静音、不打印,不是设备故障。