feat(payment): 接入扫呗普通支付2.0

docs/扫呗支付接入说明.md

@@ -0,0 +1,50 @@
+# 扫呗普通支付 2.0 接入说明
+
+接口文档来源：<https://help.lcsw.cn/xrmpic/tisnldchblgxohfl/rinsc3>
+
+## 已接入能力
+
+| 业务 | 扫呗接口 | 项目入口 |
+| --- | --- | --- |
+| 聚合码下单（C 扫 B） | `POST /pay/open/qrpay` | `POST /api/orders/:id/start-payment` |
+| 支付查询 | `POST /pay/open/query` | `GET /api/orders/:id/query-payment` |
+| 退款申请 | `POST /pay/open/refund` | 订单退款审核、人工退款、仲裁退款 |
+| 退款查询 | `POST /pay/open/queryrefund` | 退款补偿任务、后台退款状态查询 |
+| 支付回调 | 商户 `notify_url` | `POST /api/payments/saobei/notify` |
+
+撞车商城复用同一组支付能力。
+
+## 后台配置
+
+在后台「支付配置」中新增服务商为「扫呗」的配置：
+
+| 配置项 | 必填 | 说明 |
+| --- | --- | --- |
+| 商户号 | 是 | 扫呗 `merchant_no` |
+| 终端号 | 是 | 扫呗 `terminal_id`，保存在 `extra_config.terminal_id` |
+| 终端密钥 | 是 | 扫呗 `access_token`，加密保存 |
+| 网关地址 | 是 | 扫呗技术人员提供的接口域名 |
+| 回调地址 | 是 | `https://正式域名/api/payments/saobei/notify` |
+| 设备号 | 否 | 平台已经配置设备映射时才填写 |
+| 链接有效期 | 否 | 聚合码链接有效期，默认 900 秒，最大 7200 秒 |
+| 支付方式 | 是 | 项目按微信/支付宝分别选择支付通道，扫呗下单时使用 `pay_type=000` 自动识别 |
+
+扫呗没有单独的“通知密钥”。请求、响应和支付回调统一使用终端密钥 `access_token` 按字典序加签。
+
+## 支付流程
+
+1. 后端调用 `/pay/open/qrpay` 创建收银台短链。
+2. 前端 PC 将短链渲染成二维码；移动端可直接在微信、支付宝或云闪付中打开。
+3. 用户付款后，扫呗向 `/api/payments/saobei/notify` 推送 JSON。
+4. 后端验签、核对商户号和金额，再将支付单和订单按现有事务写入。
+5. 没有收到回调时，前端“检查支付状态”会调用扫呗支付查询接口。
+
+## 联调前需要准备
+
+- 扫呗测试环境接口域名。
+- 测试商户号 `merchant_no`。
+- 测试终端号 `terminal_id`。
+- 测试终端密钥 `access_token`。
+- 可用于扫呗访问的 HTTPS 回调域名。
+
+测试环境域名和正式环境域名不同，不能混用。正式切换前应至少验证：支付成功、主动查询、重复回调、金额篡改、退款成功、退款失败和超时查询。