一卡通当前接口调用与业务链路

结论摘要

调用链分三层：业务入口负责识别用户和组织订单；ai_api 通过内部接口把一卡通交易交给 store；store 统一调用厂商 API、维护状态机、幂等和补偿。

• 滨州应配置 ewallet_id=2：2 号钱包是补贴，tieEwalletObject 中的 1 号钱包是现金。
• 在线消费和离线补传均走 preorder -> orderhandle。
• preorder 与 orderhandle 均固定传 isCheckCardStatus=1。
• 外部接口失败、未知状态、远端成功但本地失败均有交易记录和定时补偿。

通用请求规则

配置来源

外部接口读取 ydy_config.config_key=one_card。真实生产地址、appid、appsecret 和内部鉴权密钥不写入本文。

Token

GET {base_url}/api/token?appid={appid}&appsecret={appsecret}

成功响应必须有 access_token 和 expires_in。token 按有效期提前刷新，并用缓存锁避免并发刷新。

业务 POST

POST {base_url}{path}?access_token={access_token}
Content-Type: application/x-www-form-urlencoded

• 除部门水位接口外，表单自动追加 sign。
• 签名：去空值、数组、对象与原 sign，按字段名升序拼接，末尾追加 key={appid}，取大写 MD5。
• 仅 code="0" 视为成功；0001、网络错误、格式错误和缺状态码进入可重试/未知处理。

当前实际调用的外部接口

同步类接口与参数

身份类别 · /api/common/queryaccclass

部门水位 · /getaccdepfixid

当前不传业务表单字段，也不传 sign；读取 data.accDepFixId。

部门增量 · /getaccdepinfobyfixid

账户水位 · /getaccfixid

参数：epId=one_card.ep_id、自动 sign；读取 data.accFixId。

账户和当前卡增量 · /getaccinfobyfixid

1. 过滤 accNum 为空、原始 phoneNo 为空/非 11 位数字、perCode 以 - 开头的数据。
2. 按 business + acc_num 更新或创建人员、用户、部门关系、账户映射和当前主卡。
3. 手机号占用时写冲突日志，不覆盖本地人员。
4. AI 同步失败时不推进本批账户水位。
5. card 命令已转为运行 account，没有独立卡增量调用。

补贴水位 · /getscparamverepbykey

参数：epId、固定 fixType=2、areaNums、自动 sign。

补贴包 · /getsubsidypackagebyfixid

补贴包写入本地幂等映射；关联 AI 用户后查询钱包、更新余额镜像，并向 yoshop_user_subsidy_log 写 scene=60 的一卡通补贴发放审计。

账户详情与双钱包

单账户详情 · /api/common/infoqueryservice/getaccount

用于手机号冲突解除后的指定账户恢复、手机号回填，以及账户增量缺少当前卡字段时的详情补查。若详情返回 accFixId，系统再精确读取该 fixid 的账户增量行。

钱包 · /api/common/infoqueryservice/getewallet

调用场景包括定时余额、补贴同步、冲突恢复、绑盘、消费前后、冲正前后和补偿后余额校准。

消费、查单与退款参数

预下单 · /api/common/payservice/preorder

订单处理 · /api/common/payservice/orderhandle

查单 · /api/common/payservice/orderquery

冲正 · /api/common/payservice/correct

冲正前后分别查询钱包，以实际钱包增量拆分现金退款与补贴退款。相同原订单和退款单号幂等；重复请求金额不一致会拒绝。

完整业务链路

定时同步

OneCardSync all
  -> identity
  -> department: 水位 -> 增量
  -> account/current card: 水位 -> 增量 -> 冲突恢复
  -> subsidy: 水位 -> 补贴包 -> 必要时钱包
  -> balance: 有效账户与有效当前卡 -> 钱包

OneCardConflictRecovery 每分钟独立重试冲突，解决主水位越过后漏同步的问题；恢复成功后继续补人员、AI 绑定、当前卡、钱包和补贴流水。

绑盘

消费机在线

入口为 POST /api/consume/orderPay 或 MQTT，order_type=1：

消费机离线补传

入口不变，order_type=2，设备端协议不变：

离线已经发生现实取餐，失败交易会保存在 ydy_one_card_trade_order 和尝试日志中，支持后台追溯。

绑盘后结算

待支付绑盘订单到结算时间后，一卡通用户走钱包、预下单、扣款和钱包后同步；访客走本地钱包。远端成功、本地失败进入补偿。

小程序余额支付

访客不调用内部一卡通支付，继续本地钱包。一卡通扣款成功后，AI 侧落本地订单及现金/补贴审计流水。

退款

原订单无成功一卡通交易时按原本地流程退款；有成功一卡通交易时调用冲正。冲正成功但本地退款失败的交易转补偿/人工，禁止重复盲目冲正。

ai_api -> store 内部接口

鉴权请求头：X-OneCard-Appid、X-OneCard-Timestamp、X-OneCard-Nonce、X-OneCard-Signature。签名使用 HMAC-SHA256，服务端校验时间窗和 nonce 防重放。

保留但当前业务未调用

数据与日志落点

运维查看建议

1. 接口是否实际调用：查 ydy_one_card_trade_attempt_log.stage 和日志 [OneCard][api]。
2. 同步是否推进：查 ydy_one_card_sync_state，不要只看命令统计。
3. 冲突解除后是否补齐：查冲突日志的 status/last_stage/last_error，再核对映射、AI、钱包与补贴包。
4. 远端扣款但本地无单：查 status=remote_success_local_failed 和修复日志。
5. 离线失败：按设备 msgid 查交易主表，再看 preorder/orderhandle/orderquery 尝试记录。
6. 查看厂商响应字段：使用 store/tests/e2e/one_card_api_inspect.php，生产只做小范围查询类调用。

代码定位

store/application/common/service/onecard/ApiClient.php · TokenProvider.php · SyncService.php · PaymentService.php · store/application/p/logic/Api.php · store/application/api/service/Consume.php · ai_api/app/common/service/onecard/PaymentClient.php