简体中文
收款播报 APP:设计架构
这一页说明播报消息从哪里发出、经过哪些组件、落到手机后如何变成声音与小票。部署操作见部署与激活。
组件与链路
| 角色 | 职责 | 边界 |
|---|---|---|
| 支付平台 | 判定收款结果、发布播报消息、渲染小票指令流 | 消息按设备号定向发布,不广播 |
| 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)。打印失败只影响出票,不影响已经完成的语音播报与收款结果。
激活、回执与心跳
- 运营端生成设备并绑定商户,商户端展示激活二维码,内容为
daxpay:activate:{设备号},仅携带设备号; - APP 扫码后调用
/client/device/audio/**完成激活,同一族接口还承载播报回执与补打取数;接口免登录,但带 HMAC 验签与限流(IP 10 次/分钟、单设备 20 次/分钟); - 激活响应下发 MQTT 接入地址、接入账号与订阅主题,APP 据此建立 wss 长连接;
- 播报完成后 APP 回报 ack,并保持 5 分钟一次心跳,运营端与商户端据此显示在线状态;
- 连续解密失败时 APP 熔断,并引导重新激活,避免在错误凭据上反复重试。
设备本地凭证用 Android Keystore AES-256-GCM 加密保存;收款流水按月以 JSON 落盘,供 APP 内查询。重复激活会轮换 secret,旧设备随之下线。
设计约束
- 只订阅、不发布:接入账号在消息服务侧没有发布权限,防止伪造到账消息;
- 服务器地址编译期注入:APP 不提供运行时地址输入,换环境必须换安装包并重新激活,避免新旧环境凭证混用;
- 主题在激活时固化:调整主题契约后,存量设备必须重新激活才能使用新主题;
- 接口类订单默认静音:线上 API、易支付来源的订单不播报、不打印,面向人工收银场景;
- 源码交付:源码随生态扩展包以源码形式交付,含源码授权。