滨州健康科技职业学院一卡通接口对接实现方案

基于正元智慧一卡通 OpenAPI 与 Word 接口文档，先完成支付消费闭环，再扩展对账补偿、人员与余额查询能力。

一期核心闭环token 获取、二维码交易、订单查询对账、交易冲正。

技术重点服务端 token 缓存、签名封装、流水号幂等、请求日志脱敏、未知状态补偿。

边界一期不做门禁考勤、银行转账、公寓、人脸同步、第三方 H5 和全量人员同步。

一期接口范围

能力	接口	用途
获取 token	`GET /api/token`	通过 appid / appsecret 获取 access_token，服务端缓存。
用户二维码交易	`POST /api/common/thirdappservice/qrcodetransaction`	食堂扫码消费扣款。
订单查询对账	`POST /api/common/thirdappservice/orderquery`	按一卡通订单号或我方流水号确认交易状态。
交易冲正	`POST /api/common/thirdappservice/correctorder`	出餐失败、撤销、重复扣款等异常场景处理。

架构

食堂业务系统
  -> OneCardTradeService
    -> OneCardClient
      -> TokenProvider
      -> Signer
      -> RequestLog
      -> 正元智慧一卡通 API
  -> 本地订单/流水映射表
对账补偿任务 -> OneCardTradeService

建议封装独立一卡通服务层，不让控制器、订单模型或设备端代码直接拼接第三方接口参数。

核心流程

1. Token

首次调用前懒加载 token，按 expires_in 缓存，过期前 5 分钟刷新；接口返回 token 失效时刷新一次并重试。

2. 扫码扣款

本地订单先生成全局唯一 otherTransRecId，调用二维码交易接口。明确成功则保存一卡通订单号和 transSource 并置本地订单已支付；明确失败则置失败；超时或响应异常进入 unknown，等待查询补偿。

3. 查询补偿

默认按我方流水号查询，queryType=2，同时传 recDate。定时扫描最近 30 分钟内 unknown 或 paying 订单，多次仍未知则转人工处理，禁止自动补扣。

4. 冲正

冲正必须有一卡通订单号；没有时先订单查询。冲正流水号必须与消费流水号分开，全额冲正可不传 correctMon。

本地数据

字段	说明
`local_order_no`	本地订单号。
`other_trans_rec_id`	我方消费流水号，全局唯一。
`one_card_trans_rec_id`	一卡通订单流水号。
`trans_source`	一卡通返回交易来源。
`status`	`init` / `paying` / `success` / `failed` / `unknown` / `correcting` / `corrected`。
`request_snapshot` / `response_snapshot`	脱敏后的请求和响应摘要。

测试重点

token 成功、失败、过期刷新。
扣款成功、二维码无效、金额错误、重复流水号、签名错误、网络超时。
超时但实际扣款成功后，能通过查询补偿收敛为成功。
本地业务失败后一卡通冲正成功。
重复点击、断网恢复、对账限速和人工处理队列。

实施步骤

现场确认一卡通版本、测试/正式地址、签名指南、商户号、钱包号、设备号、营业时段和 IP 白名单。
确定目标代码仓库和任务分支。
封装 token、签名、请求发送、响应解析和脱敏日志。
实现扫码消费、本地流水映射和订单状态机。
实现查询补偿和冲正。
补齐接口契约测试、业务场景测试和联调记录。

待确认：签名完整规则、消费接口返回字段名、是否必须先解析二维码、是否需要余额展示、目标业务仓库是否为 zhctproject/store。