简体中文
收款精灵:设计架构
这一页说明收款精灵在收银电脑上扮演什么角色、请求怎么发到平台、本机数据与平台数据是什么关系。安装操作见安装与登录。
组件与链路
| 角色 | 职责 | 边界 |
|---|---|---|
| 收款精灵 | 读付款码、识别金额、发起收款、播报出票、记本机账本 | 只负责收款,不改造收银软件 |
| 支付平台 | 发起并判定支付、退款、查单,保存交易真相 | 唯一交易真相源,本机账本只是镜像 |
| 扫码盒 | 以 HID 键盘仿真或 HID POS 输出付款码 | 后台读取付款码 |
| 打印机 / 扬声器 | 输出小票与语音 | 失败只提示,不打断收款 |
收款精灵直连 DaxPay 后端,不经过收银系统网关。技术栈为 C# / WPF / .NET 10(net10.0-windows),OCR 使用 OnnxRuntime 加载本地 v7 tiny 模型,打印为自研 ESC/POS 实现,本机账本使用 Microsoft.Data.Sqlite。
金额链路与支付链路
两条链路是分开的,金额来源不影响支付请求的判定口径。
| 链路 | 输入 | 处理 | 输出 |
|---|---|---|---|
| 金额链路 | 扫码盒付款码、计算器面板手输、OCR 识别屏幕金额 | 金额稳定后显示到悬浮条,人工确认;自动收款默认关闭 | 待收金额与付款码 |
| 支付链路 | 付款码 + 金额 | 调用平台被扫收款接口,轮询支付结果 | 成功 / 失败 / 支付中,写入本机账本 |
支付相关接口:
| 方法与路径 | 用途 |
|---|---|
POST /elf/cashier/pay-by-auth-code | 付款码发起被扫收款 |
GET /elf/cashier/order-status | 查询订单状态 |
GET /elf/cashier/config-options | 拉取门店、应用、终端等配置项 |
POST /elf/order/refund | 发起退款 |
POST /elf/order/close | 关单接口;桌面端不暴露关单入口 |
请求头固定带 Accesstoken、x-client-code: merchant、x-terminal: elf,走商户身份域。
被扫返回 wait / progress 时,按 1.5 秒间隔轮询,最长 20 秒,每第 3 次带 sync=true 向平台强制同步。HTTP 响应丢失时按 bizOrderNo 回查恢复,不重复发起支付。
本机账本与平台真相源
- 平台是交易真相源:支付、退款、关单状态最终以平台为准;
- 本机账本(
trades.db)只做镜像,用于断网查看历史、交易记录列表与重打小票; - 退款时本机账本会校验可退余额,但最终仍以平台结果为准;
- 未支付订单到期由平台自动关单,桌面端不暴露关单入口;
- 断网时仍可查看历史流水,但发起收款、退款、查单需要平台可达。
打印与语音的降级
打印:58 / 80mm 两种纸宽,USB 免驱直发、网口 RAW TCP(默认 9100)、文件转储(调试)三种通道,支持 1 至 4 联。版式全部走 ESC/POS 指令对齐,不用空格 padding,编码 GB18030,二维码与条形码按位图渲染。打印失败只提示,不打断收银,可用「重打上一笔」补打。
语音:系统中文语音包可用时用 TTS 合成金额;不可用时自动降级为内置 WAV 词表拼接,保证播报不中断。
设计约束
- 不改造收银软件:只旁挂读取付款码与屏幕金额,收银软件照常记账;
- 只做被扫:本版不包含主扫,商家出示收款码的场景不适用;
- 小票模板在本机:使用内置模板,不支持服务端模板管理;
- 终端选择只存本机:换电脑、重装或清理配置后需重新选择;
- 关单只走平台:桌面端不暴露关单入口,未支付订单到期由平台自动关单;
- 源码交付:源码随生态扩展包以源码形式交付,含源码授权。