Skip to content

收款播报 APP:设计架构 ​

更新时间:2026/11/10 10:51:10

这一页说明播报消息从哪里发出、经过哪些组件、落到手机后如何变成声音与小票。部署操作见部署与激活。

组件与链路 ​

角色职责边界
支付平台判定收款结果、发布播报消息、渲染小票指令流消息按设备号定向发布,不广播
Artemis broker承接 MQTT over WebSocket 接入,把主题映射为 core 地址设备账号只能订阅,不能发布
收款播报 APP订阅消息、解密、播报、取小票指令并打印、回报执不做本地排版,不猜金额
打印机接收 ESC/POS 指令流输出小票纸宽须与 APP 设置一致

消息通道主题与契约 ​

设备订阅斜杠主题,平台发布点号多段 core 地址,两者由 broker 映射到同一地址(Artemis 2.33+ / ARTEMIS-4532):

方向值说明
设备订阅(激活下发)daxpay/device/audio/{设备号}APP 原样订阅;/ 是 MQTT 层级分隔符
broker core 地址daxpay.device.audio.{设备号}斜杠主题映射为多段地址,ACL / address-setting 按此匹配
平台发布(JMS Topic)daxpay.device.audio.{设备号}与订阅队列同址,broker 直接路由

broker core 前缀是 daxpay.device.,ACL 与地址策略都按这个前缀匹配。

不要用点号主题订阅,也不要发布转义字面量

Artemis 2.33+ 按 MQTT 官方语义处理主题:/ 是层级分隔符,. 是字面字符并被转义为 \.。设备若订阅点号 daxpay.device.audio.{设备号},实际落点是单段地址 daxpay\.device\.audio\.{设备号},不命中 security-setting match="daxpay.device.#",订阅会被拒(SUBACK 0x80)。平台若发布到转义字面量,则与斜杠订阅创建的多段队列不同址,消息会静默无人接收。设备凭证里的 topic 在激活时固化,主题契约调整后存量设备必须重新激活一次。

平台渲染小票,APP 只做哑管道 ​

小票不由手机排版。平台侧把版式渲染成 ESC/POS 指令流,通过 printData 字段下发,58mm 与 80mm 两条流一并给出:

  • APP 按本机设置的纸宽选择对应指令流,原样解码输出,不做二次排版;
  • 版式调整只改平台侧,APP 不需要跟着升级;
  • 语音同理,播报语音内置在 APP 中,不依赖手机 TTS,也不消耗流量。

打印通道支持经典蓝牙 SPP、USB 与网络打印机(RAW TCP 9100)。打印失败只影响出票,不影响已经完成的语音播报与收款结果。

激活、回执与心跳 ​

  1. 运营端生成设备并绑定商户,商户端展示激活二维码,内容为 daxpay:activate:{设备号},仅携带设备号;
  2. APP 扫码后调用 /client/device/audio/** 完成激活,同一族接口还承载播报回执与补打取数;接口免登录,但带 HMAC 验签与限流(IP 10 次/分钟、单设备 20 次/分钟);
  3. 激活响应下发 MQTT 接入地址、接入账号与订阅主题,APP 据此建立 wss 长连接;
  4. 播报完成后 APP 回报 ack,并保持 5 分钟一次心跳,运营端与商户端据此显示在线状态;
  5. 连续解密失败时 APP 熔断,并引导重新激活,避免在错误凭据上反复重试。

设备本地凭证用 Android Keystore AES-256-GCM 加密保存;收款流水按月以 JSON 落盘,供 APP 内查询。重复激活会轮换 secret,旧设备随之下线。

设计约束 ​

  • 只订阅、不发布:接入账号在消息服务侧没有发布权限,防止伪造到账消息;
  • 服务器地址编译期注入:APP 不提供运行时地址输入,换环境必须换安装包并重新激活,避免新旧环境凭证混用;
  • 主题在激活时固化:调整主题契约后,存量设备必须重新激活才能使用新主题;
  • 接口类订单默认静音:线上 API、易支付来源的订单不播报、不打印,面向人工收银场景;
  • 源码交付:源码随生态扩展包以源码形式交付,含源码授权。