434 lines
36 KiB
Markdown
434 lines
36 KiB
Markdown
# 陪诊订单微信支付接入方案
|
||
|
||
> 更新时间:2026-11-05
|
||
> 状态:资金安全评审(第二轮)+ 微信支付接入规范评审已完成,修复项已并入,待实施
|
||
> 2026-11-05 增补:下单页可选微信支付 / 线下支付,支付方式写入订单并支持待支付期间切换(线下支付不细分现金/转账,由平台补记);支付/退款异常统一兜底,错误详情(code/message/requestId)落库
|
||
> 2026-11-05 资金评审修复:①取消待支付订单必须关单;②回调收到支付但订单已取消时自动退款;③关单失败改为当场查单确认(不依赖本期不做的巡检);④存在未决流水时禁止改价;⑤一单多流水、商户单号不重用;⑥退款结果保留管理端手动查单兜底
|
||
> 2026-11-05 取消规则调整:用户端只保留「取消订单」(无删除入口)。待确认且未收款取消即物理删除;已确认或已收款转 `cancel_requested`,由该单陪诊师(限本人名下)或管理员确认后正式取消,不物理删除,已收款的同步进入退款
|
||
> 2026-11-05 接入规范评审修订:①下单显式传 `time_expire`(支付窗口有边界);②prepay 过期沿用原单号重下,仅旧流水已关闭/失效才换新号;③补收银链路超时设置;④退款未成功应答先查退款、原单号重试一次;⑤同一订单发起支付串行化,防两条在途流水;⑥回调分支补 `cancel_requested`,回调研启退款改在应答之后;⑦补后台轻量巡检查单/超时关单,回调丢失可收敛
|
||
|
||
## 一、背景与现状
|
||
|
||
- C 端小程序(`ui/wxapp_escort`)下单流程已上线:`itemorder` 提交订单 → `escort_record` 落库(`status: pending`、`payment.status: unpaid`)
|
||
- 当前收款为客服协助线下完成,支付方式由平台在收款时补记(`offline_cash` / `offline_transfer`)
|
||
- 本期目标:用户在小程序内直接完成线上微信支付,取消已支付订单自动原路退款
|
||
- 微信支付商户号已在官方申请完成
|
||
|
||
**现状要点(代码侧)**:
|
||
|
||
| 现状 | 位置 |
|
||
| --- | --- |
|
||
| `payment` 已预留 `online_wechat` 方法枚举与 `unpaid/partial/paid/refunding/refunded` 状态 | `api/health/models/schema/escort_record.js` |
|
||
| openid 已在登录时经 `jscode2session` 存入 `user.app["wxapp-escort"].wxopenid`,与小程序 appid 天然一致 | `api/user/handler/users.js` |
|
||
| 服务价格以字符串元存储(`"500.00"`),订单 `totalFee` 为数字元 | `api/health/resource/services.js` |
|
||
| 线上域名 `api.huashengtec.com`(HTTPS),nginx 同域分流 `/health → 9004`,回调地址可直接复用 | `ui/wxapp_escort/utils/config.js`、`api/health/nginx_site.txt` |
|
||
|
||
## 二、接入要素(已确认)
|
||
|
||
| 要素 | 结论 | 说明 |
|
||
| --- | --- | --- |
|
||
| 支付产品 | **小程序支付** | JSAPI 下单(`POST /v3/pay/transactions/jsapi`)+ `wx.requestPayment` 调起 |
|
||
| 商户角色 | **普通商户** | 直连模式,报文只带 `mchid` / `appid` |
|
||
| API 版本 | **APIv3** | JSON 报文 + RSA-SHA256 签名;APIv2 已存量维护,不新接 |
|
||
| 验签方式 | **微信支付公钥** | `PUB_KEY_ID_` 格式序列号,长期有效免轮换 |
|
||
| 支付交互 | **下单选支付方式 → 微信支付立即拉起收银台** | 下单页可选「微信支付 / 线下支付」;选微信支付则下单成功后立即调起收银台,选线下支付则直接跳订单列表。列表/详情页保留「去支付」与「修改支付方式」入口 |
|
||
| 支付时限 | **下单传 `time_expire`** | 显式给出可支付窗口,默认下单后 24 小时(且不晚于服务开始当天);取值须落在下单后 1 分钟 ~ 15 天内,超出会被微信自动调整。**窗口以下单时间为起点固定计算,不随重新发起支付延长**;到期订单不可再用微信支付,只能改线下或取消,到期流水由巡检关单 |
|
||
| 线上退款 | **本期实现** | 取消已支付订单自动调退款 API 原路退回 |
|
||
| SDK | **Node 内置 crypto 自实现** | 官方仅提供 Java/Go/PHP SDK;签名/验签/AES-GCM 解密用 `node:crypto` + `node-fetch`,无新依赖 |
|
||
|
||
## 三、整体业务流程
|
||
|
||
下单时先选支付方式,两条分支:
|
||
|
||
```
|
||
用户下单(itemorder 选择支付方式)
|
||
├─ 微信支付 ─> createRecord(payment.payChannel=online_wechat, status=unpaid)
|
||
│ └─ 下单成功后立即发起支付(见下方链路)
|
||
└─ 线下支付 ─> createRecord(payment.payChannel=offline, status=unpaid)
|
||
└─ 直接跳订单列表,等待平台收款后补记实际收款方式
|
||
```
|
||
|
||
微信支付链路:
|
||
|
||
```
|
||
用户(小程序) health后端 微信支付
|
||
│ 1.点"去支付"/下单成功 │ │
|
||
│ ─────────────────> │ POST /escort-record/:id/pay
|
||
│ │ 2.校验(本人/待支付/未付款) │
|
||
│ │ 3.写 payment_record(created) │
|
||
│ │ 4.JSAPI下单(金额=分, openid, time_expire, out_trade_no=订单_id-序号)
|
||
│ │ ─────────────────────> │ 返回 prepay_id(有效期2小时)
|
||
│ │ 5.更新流水 prepayId+过期时间 │
|
||
│ │ 6.私钥签名生成 paySign │
|
||
│ 7.返回调起支付五参数 │ <───────────────────── │
|
||
│ <───────────────── │ │
|
||
│ 8.wx.requestPayment 调起收银台 ───────────────────>│
|
||
│ │ │ 用户完成支付
|
||
│ 9.前端回调(不可信) │ │
|
||
│ ─────────────────> │ 10.查单接口:主动调微信查单确认 │
|
||
│ │ ─────────────────────> │ trade_state=SUCCESS
|
||
│ │ 11.更新流水 pay_success → 刷订单快照 paid
|
||
│ 12.返回支付结果 │ │
|
||
│ <───────────────── │ │
|
||
│ │ 13.支付成功回调(异步,权威) │
|
||
│ │ <───────────────────── │ 验签+解密+金额校验
|
||
│ │ 14.更新流水+订单快照,幂等应答200 │
|
||
```
|
||
|
||
**回调到达时的订单状态判定(关键分支)**:
|
||
|
||
```
|
||
支付成功回调(验签 + 解密 + 字段校验通过)
|
||
├─ 订单 status ∈ {pending, confirmed} 且 payment.status = unpaid
|
||
│ └─ 流水 pay_success → 刷订单快照 paid,正常进入履约
|
||
├─ 订单 status = cancel_requested(用户已申请取消、尚未确认)
|
||
│ └─ 同上:钱已到账就按已支付如实记账,不提前退款;后续确认取消时按取消流程原路退款
|
||
└─ 订单 status = cancelled(订单已正式取消)
|
||
├─ 流水仍落 pay_success(钱确实到账,是财务事实,不能丢)
|
||
├─ 订单快照保持 cancelled,不刷 paid(避免「已取消订单显示已收款」)
|
||
└─ 应答 200 之后再异步发起原路全额退款(写 refund_record(processing) → 调退款接口),不在应答前调外部接口
|
||
```
|
||
|
||
退款流程(取消已支付线上订单时自动触发):
|
||
|
||
```
|
||
用户申请取消 ──> updateStatus(cancelled) ──> status = cancel_requested
|
||
└─ 陪诊师/管理员确认取消 ──> updateStatus(cancelled)
|
||
├─ 1.先写 refund_record(processing) ← 先落库再调接口
|
||
├─ 2.调微信退款 API(POST /v3/refund/domestic/refunds)
|
||
├─ 2.1 调用异常/超时 → 先查退款确认是否受理:未受理则用同一 outRefundNo 原参数重试一次;仍失败保持 processing 转人工
|
||
├─ 3.订单快照 payment.status = refunding
|
||
└─ 4.退款回调(REFUND.SUCCESS) ─> refund_record(success) ─> 订单快照 refunded
|
||
```
|
||
|
||
### 后台巡检查单(回调丢失的唯一兜底)
|
||
|
||
- 服务启动时注册单一定时器,**默认运行**(不靠人工开启);每 10 分钟扫一次 `payment_record.status ∈ {created, closed_unconfirmed}`,按创建时间限定在最近 7 天内,避免全表扫描
|
||
- `created` 流水:按 `outTradeNo` 查单
|
||
- `SUCCESS` → 按回调同一套逻辑收敛(流水 `pay_success` + 刷订单快照;订单已取消则转退款)
|
||
- `NOTPAY` 且已过 `timeExpireAt` → 关单,流水置 `closed`
|
||
- 查单失败 → 记 `lastError`,下一轮重试
|
||
- `closed_unconfirmed` 流水:查单确认,未支付则补记 `closed`,已支付则按退款处理
|
||
|
||
官方开发指引的核心原则:
|
||
|
||
- **前端回调不可信**:`requestPayment` 回调后必须以后端查单结果为准
|
||
- **回调是权威**:验签 → AES-256-GCM 解密 → 校验 `out_trade_no` 与金额 → 落库 → 5 秒内应答 200;重复推送做幂等(已处理直接 200)
|
||
- **防重复支付**:前端按钮防抖 + 服务端以「当前有效流水」为幂等粒度(prepay_id 未过期直接复用;过期但窗口内用原单号重下;旧流水已关闭或窗口到期才换新 `outTradeNo`,唯一索引兜底)
|
||
|
||
### 支付方式选择与流转
|
||
|
||
**字段拆分**:把「用户选择的支付方式意向」与「实际收款方式」分开记录,避免把还没收到的钱记成已按某方式收款。用户端只提供「微信支付 / 线下支付」两个选项;线下支付不细分现金/转账,实际收款方式由平台收款时补记为 `offline_cash` 或 `offline_transfer`。
|
||
|
||
| 字段 | 取值 | 含义 | 写入方 |
|
||
| --- | --- | --- | --- |
|
||
| `payment.payChannel` | `online_wechat` / `offline` | 用户下单时选择的支付渠道 | 下单时写入;待支付期间用户可自助修改 |
|
||
| `payment.method` | `""` / `online_wechat` / `offline_cash` / `offline_transfer` | 实际收款方式 | 线上支付成功后由回调写入;线下由平台收款时补记 |
|
||
|
||
**状态矩阵**:
|
||
|
||
| 场景 | payChannel | method | payment.status | 列表/详情展示 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 选微信支付,尚未支付(含中途取消) | online_wechat | `""` | unpaid | 「待支付」+「去支付」 |
|
||
| 选微信支付,超过支付窗口未付 | online_wechat | `""` | unpaid | 「支付已超时」,无「去支付」,仅可改线下或取消 |
|
||
| 微信支付成功 | online_wechat | online_wechat | paid | 「已支付」 |
|
||
| 选线下支付,平台尚未收款 | offline | `""` | unpaid | 「线下支付,待收款」 |
|
||
| 线下收款完成,平台补记 | offline | offline_cash / offline_transfer | paid | 「已支付(现金/转账)」 |
|
||
| 线上已支付后取消 | online_wechat | online_wechat | refunding → refunded | 「退款中 / 已退款」 |
|
||
| 线下已收款后取消 | offline | offline_cash / offline_transfer | refunding | 「退款中」(线下人工退款核销) |
|
||
| 用户申请取消(已确认或已收款) | 保持原值 | 保持原值 | 保持原值 | 「待取消」,等待陪诊师/管理员确认 |
|
||
|
||
**取消规则(用户端只保留「取消订单」按钮)**:
|
||
|
||
- 待确认且未收款:用户取消后订单直接物理删除,无需二次确认
|
||
- 已确认或已收款:用户取消后订单进入 `cancel_requested`(待取消),**不物理删除**;由该订单的陪诊师或管理员确认后才转为 `cancelled`,已收款的同步进入退款流程
|
||
- `cancel_requested` 期间用户不可再次取消、不可修改支付方式;陪诊师只能确认自己名下的订单,管理员不限
|
||
- 已取消、已完成为终态,不可再取消
|
||
|
||
**修改支付方式规则**:
|
||
|
||
- 允许时机:订单 `status ∈ {pending, confirmed}` 且 `payment.status = unpaid`(未收到钱之前都可改)
|
||
- 用户端在订单详情页切换 `payChannel`:`online_wechat` ↔ `offline`
|
||
- 改回 `online_wechat` 后再次「去支付」时,**必须使用新的商户订单号**(`订单_id + "-" + 新尝试序号`),不复用已关闭的单号
|
||
- 已支付(`paid` / `refunding` / `refunded`)、`cancel_requested` 或已进入服务中(`in_progress`)的订单,一律不可修改支付方式
|
||
|
||
**关单是切换与取消的前置动作**(防止旧 `prepay_id` 在 2 小时内仍被支付,造成「订单已取消 / 已改线下,钱却进来了」):
|
||
|
||
```
|
||
切换为线下 / 取消订单 / 支付窗口到期
|
||
└─ 存在 payment_record(created)
|
||
├─ 1.调用微信关单接口
|
||
├─ 2.关单成功 → 流水置 closed
|
||
└─ 3.关单失败 → 立即调查单接口确认(不等巡检)
|
||
├─ trade_state = SUCCESS → 实际已付款:中止本次切换/取消,
|
||
│ 提示「订单已支付」,转入退款流程
|
||
└─ 未支付 / 查单也失败 → 流水置 closed_unconfirmed 并放行,
|
||
交对账核对(订单仍按用户意愿处理)
|
||
```
|
||
|
||
> 关单失败时「当场查单一次」是立即兜底;仍未确认的中间态由后台巡检查单收敛(见第五节)。
|
||
|
||
### 支付异常处理(统一兜底 + 错误落库)
|
||
|
||
**原则**:不按异常类型做差异化业务分支,所有外部异常统一兜底、统一提示;但**错误详情必须落库**,供财务与运维排查。
|
||
|
||
**异常来源与处理**:
|
||
|
||
| 阶段 | 典型异常 | 处理方式 |
|
||
| --- | --- | --- |
|
||
| JSAPI 下单 | 网络超时、连接失败、`APPID_MCHID_NOT_MATCH`、`MCHID_NOT_EXISTS`、`SIGN_ERROR`、`NO_AUTH` 等 | 记录流水 `lastError`;订单保持 `unpaid`;前端提示可重试或改用线下支付 |
|
||
| 查单 | 同上 | 记录 `lastError`;前端按最后一次已知状态展示 |
|
||
| 关单 | 同上 | 记录 `lastError`;**当场查单一次确认**,已支付则中止切换/取消并转退款(见本节关单流程) |
|
||
| 退款 | 商户余额不足、参数错误、网络异常 | 记录 `refund_record.lastError`;**超时/系统异常先查退款**:确认未受理则同一 `outRefundNo` 原参数重试一次;明确业务错误(余额不足等)直接转人工,保持 `processing` |
|
||
| 回调验签/解密/字段校验 | 验签失败、解密失败、`mchid` / `appid` / `currency` / 金额与本地不一致 | logger 记录并应答 4XX/5XX,**不落业务库**(报文不可信,不能作为数据来源) |
|
||
|
||
**落库字段**(`payment_record` / `refund_record` 共用同一结构):
|
||
|
||
```js
|
||
lastError: {
|
||
stage: String, // create 下单 / query 查单 / close 关单 / refund 退款
|
||
code: String, // 网络异常固定 NETWORK_ERROR;微信侧错误取应答 code;HTTP 异常记状态码
|
||
message: String, // 微信返回 message 或系统异常原文,截断 500 字符
|
||
requestId: String, // 微信应答头 Request-ID,向微信侧排查时提供
|
||
httpStatus: Number, // HTTP 状态码,网络异常时为 0
|
||
at: Date // 发生时间
|
||
},
|
||
errorCount: Number, // 累计失败次数,用于识别反复失败
|
||
lastAttemptAt: Date, // 最近一次调用时间
|
||
```
|
||
|
||
**统一封装约定**(`utils/wechatpay.js`):
|
||
|
||
- 所有微信 API 调用异常统一抛 `WechatPayError`,字段固定为 `{ stage, code, message, requestId, httpStatus }`
|
||
- 所有请求显式设置连接/读取超时(默认 5 秒);超时与连接中断按「结果不确定」处理,走查单收敛,不直接判失败
|
||
- 网络/SDK 异常 → `code = "NETWORK_ERROR"`,`message` 保留原始错误文本
|
||
- HTTP 非 2XX → `code` / `message` 取微信应答体,`requestId` 取响应头
|
||
- `message` 统一截断 500 字符,避免超长文本撑库
|
||
|
||
**前端统一处理**:
|
||
|
||
- `payOrder` 请求失败 → 提示「支付发起失败,请稍后重试;如持续失败可改用线下支付」
|
||
- `wx.requestPayment` 返回 `requestPayment:fail cancel` → 提示「已取消支付」,订单保持待支付
|
||
- 其他 fail → 先调查单兜底(可能支付已成功但网络中断),再按查单结果提示
|
||
- 不区分错误码,不向用户暴露内部错误详情
|
||
|
||
## 四、数据模型设计(对账导向)
|
||
|
||
### 设计原则:订单与支付分离,流水是事实源
|
||
|
||
```
|
||
escort_record (业务订单) payment_record (支付流水) refund_record (退款流水)
|
||
├─ status: 服务履约状态 ├─ outTradeNo 商户订单号 ├─ outRefundNo 商户退款单号
|
||
└─ payment: 汇总快照(展示用) ├─ transactionId 微信支付订单号 ├─ refundId 微信退款单号
|
||
unpaid/paid/refunded... ├─ 金额(分)/状态机/事件时间戳 ├─ 金额(分)/状态/入账账户
|
||
└─ 每次支付尝试一条文档 └─ 一次退款一条文档
|
||
```
|
||
|
||
- **流水表为财务事实源**:状态每次变更落时间戳,链路完整可审计
|
||
- **订单上的 `payment` 保留为汇总快照**:列表/详情展示免 join,写完流水后同步刷新
|
||
- **金额全链路用「分」(int)**:与微信账单口径一致,杜绝元/分浮点误差,只在展示层转元;**由 `service.price` 字符串(如 `"500.00"`)直接解析为整数分**(按小数点拆位,不做 `元 × 100` 浮点运算),换算收敛在支付模块单点
|
||
|
||
### payment_record(支付流水)
|
||
|
||
```js
|
||
{
|
||
// 业务关联
|
||
bizType: "escort", // 业务类型,后续培训报名等复用
|
||
recordId: ObjectId, // 关联 escort_record._id
|
||
userId: ObjectId, // 付款用户(按用户查支付历史)
|
||
|
||
// 微信侧标识(对账核心字段)
|
||
outTradeNo: String, // 商户订单号 = 订单_id + "-" + 尝试序号,唯一索引(永不重用)
|
||
attemptNo: Number, // 第几次支付尝试(从 1 起),区分同单多次发起
|
||
transactionId: String, // 微信支付订单号,唯一稀疏索引(支付成功后回填)
|
||
prepayId: String, // 预支付会话标识
|
||
prepayExpiresAt: Date, // prepay_id 过期时间(2小时,复用判断)
|
||
timeExpireAt: Date, // 下单传入的 time_expire(支付窗口终点)
|
||
|
||
// 渠道信息(与微信账单核对的维度)
|
||
appid: String,
|
||
mchid: String,
|
||
tradeType: "JSAPI",
|
||
|
||
// 金额(分)
|
||
totalFee: Number, // 应付金额
|
||
payerTotal: Number, // 用户实付(券后,回调回填)
|
||
|
||
// 状态机 + 事件时间戳(审计链)
|
||
status: "created", // created → pay_success / closed
|
||
// created → closed_unconfirmed(关单失败且查单未确认)
|
||
// pay_success → refunding → refunded
|
||
closeUnconfirmed: Boolean, // 关单结果不确定时置 true,进人工核对
|
||
createdAt, prepayedAt, paidAt, closedAt,
|
||
|
||
// 支付成功回调关键留档(审计/争议处理)
|
||
bankType: String, // 支付方式(如 OTHERS/CMB_CREDIT)
|
||
successTime: Date, // 微信侧支付完成时间
|
||
|
||
// 异常留档(任何外部异常都记,不区分类型,结构见第三节「支付异常处理」)
|
||
lastError: { stage, code, message, requestId, httpStatus, at },
|
||
errorCount: Number, // 累计失败次数
|
||
lastAttemptAt: Date, // 最近一次调用时间
|
||
|
||
meta: { createtime, updatetime }
|
||
}
|
||
// 索引:{ outTradeNo: 1 } unique、{ transactionId: 1 } unique sparse、
|
||
// { recordId: 1 }、{ userId: 1, createdAt: -1 }
|
||
```
|
||
|
||
**流水粒度规则(一单可多条,单号不重用)**:
|
||
|
||
- 同一订单每次重新发起支付都新建一条流水,`outTradeNo` 递增后缀(`-1`、`-2`…),**不复用已关闭的单号**
|
||
- 订单 `payment.paymentRecordId` 指向「当前有效」的那条流水;历史流水保留作为审计
|
||
- 单条流水在 prepay_id 有效期内重复点「去支付」时直接复用,不新建
|
||
- prepay_id 已过期但仍在支付窗口内:**沿用该流水与同一 `outTradeNo`、原下单参数重新下单**,刷新 `prepayId` / `prepayExpiresAt`,不新建流水
|
||
- 只有该流水已 `closed`(关单成功)或已超出 `timeExpireAt`(微信侧不可再付)才新建流水换新号
|
||
- 财务核对以 `outTradeNo` 为键:一单多次尝试对应多个未支付单号 + 至多一笔成功
|
||
|
||
### refund_record(退款流水)
|
||
|
||
```js
|
||
{
|
||
paymentId: ObjectId, // 关联 payment_record
|
||
recordId: ObjectId, // 冗余关联订单
|
||
outTradeNo: String, // 原商户订单号(冗余)
|
||
|
||
outRefundNo: String, // 商户退款单号 = 订单_id + "-R1",唯一索引
|
||
refundId: String, // 微信退款单号,唯一稀疏索引
|
||
refundAmount: Number, // 退款金额(分)
|
||
totalAmount: Number, // 原订单金额(分)
|
||
reason: String, // 退款原因(= 订单取消原因)
|
||
|
||
status: "processing", // processing → success / abnormal / closed
|
||
userReceivedAccount: String, // 退款入账账户(回调返回,客服答疑用)
|
||
successTime: Date,
|
||
lastQueriedAt: Date, // 最近一次主动查询退款结果的时间(回调丢失时的兜底依据)
|
||
|
||
// 异常留档(退款失败可查原因,如商户余额不足)
|
||
lastError: { stage, code, message, requestId, httpStatus, at },
|
||
errorCount: Number,
|
||
lastAttemptAt: Date,
|
||
|
||
meta: { createtime, updatetime }
|
||
}
|
||
```
|
||
|
||
### 对账场景
|
||
|
||
| 对账场景 | 做法 |
|
||
| --- | --- |
|
||
| 日常对账 | 下载微信**交易账单** → 按 `transactionId` / `outTradeNo` 逐笔与 `payment_record` 核对金额与状态;退款笔目对 `refund_record` |
|
||
| 状态差异 | 回调丢失导致流水停在中间态 → 后台巡检查单补齐(见第三节);T+1 再用交易账单人工核对 |
|
||
| 客诉/争议 | `bankType` + `successTime` + 完整时间戳链还原每笔交易过程 |
|
||
| 用户查"我付了哪笔" | `userId + createdAt` 索引直接查流水 |
|
||
| 退款卡单 | 退款回调丢失导致长期停在 `processing` → 管理端「查询退款结果」调退款查单接口,补写 `success` / `abnormal` |
|
||
| 关单未确认 | 流水 `closed_unconfirmed` → 按 `outTradeNo` 查单确认终态,补记 `closed`;若已支付则转退款 |
|
||
|
||
**本期退款约束**:一笔支付只发起一次全额退款(`outRefundNo = 订单_id + "-R1"`),不支持部分退款;重试必须沿用同一 `outRefundNo`(微信对同号退款幂等返回原退款单);退款结果除回调外,由管理端手动查询兜底。
|
||
|
||
## 五、后端改动清单(api/health)
|
||
|
||
| # | 文件 | 内容 |
|
||
| --- | --- | --- |
|
||
| 1 | `utils/wechatpay.js`(新增) | APIv3 请求签名、应答/回调验签(含 `WECHATPAY/SIGNTEST/` 探测流量处理)、AES-256-GCM 回调解密、JSAPI 下单/查单/关单/退款调用、调起支付 paySign 生成、Request-ID 日志;所有调用异常统一抛 `WechatPayError`(结构见第三节) |
|
||
| 2 | `models/schema/payment_record.js`(新增) | 支付流水,见第四节 |
|
||
| 3 | `models/schema/refund_record.js`(新增) | 退款流水,见第四节 |
|
||
| 4 | `handler/payment.js`(新增) | `createPayment`(校验金额 > 0 / 订单状态 / 未支付 / **未超支付窗口** → 无有效流水时新建 `outTradeNo` → 落流水 → 微信下单 → 返回五参数,prepay 有效期内复用、过期用原单号重下)、`queryPayment`(主动查单落流水+刷快照)、`paymentNotify`(验签→解密→校验 `mchid`/`appid`/`currency`/金额→按订单状态分支写流水→应答 200→已取消订单再异步发起退款)、`refundNotify`、`queryRefund`(管理端查退款结果兜底);**所有外部异常统一捕获,写入 `lastError` / `errorCount` / `lastAttemptAt` 后再返回通用错误提示**;退款异常先查退款、未受理则原单号重试一次;同一订单的 `createPayment` 按 recordId 串行(进程内锁),防止并发产生两条在途流水;模块内提供巡检函数,服务启动时注册定时器默认运行 |
|
||
| 5 | `handler/escort_record.js`(改造) | ① `createRecord`:接收用户端 `payment.payChannel`(仅 `online_wechat` / `offline`,默认 `online_wechat`),`method` 留空待支付成功或平台补记;管理员代客下单仍可指定 `method`。② `updateRecord`:为用户端放开 `payment.payChannel`,仅 `pending` / `confirmed` 且 `unpaid` 可改;**存在 `created` 流水的订单禁止修改 `payment.totalFee`**(要调价先关单)。③ 切换为线下:关单 + 失败当场查单确认,已支付则拒绝切换并转退款。④ `updateStatus` 取消:未确认且未收款 → 物理删除;已确认或已收款 → `cancel_requested`,陪诊师/管理员确认后转 `cancelled`,线上已收款订单再走退款流程;线下收款订单维持原人工退款。⑤ 金额 ≤ 0 的订单禁止发起线上支付;⑥ 支付窗口到期由巡检关单,流水置 `closed` |
|
||
| 6 | `routes/index.js` | `POST /escort-record/:id/pay`(requireAuth + createLimit 限流)、`GET /escort-record/:id/pay/status`(requireAuth)、`POST /escort-record/:id/refund/query`(requireAdmin,退款查单兜底)、`POST /pay/notify`、`POST /pay/refund-notify`(后两条**无鉴权**,微信服务器直调,靠验签保安全;注册在 `/:id` 路由之前防抢占) |
|
||
| 7 | `models/schema/escort_record.js` | `payment` 保持汇总快照角色:新增 `payChannel`(用户选择的支付渠道)与 `paymentRecordId`(指向当前有效流水);`method` 语义收窄为「实际收款方式」;其余细节字段移入流水表 |
|
||
| 8 | `conf.json` | 新增 `wechatpay` 配置段(结构占位,密钥部署时填系统级配置 `/etc/ehason/conf.json`,APIv3 密钥走环境变量,不进仓库) |
|
||
|
||
配置段结构:
|
||
|
||
```json
|
||
"wechatpay": {
|
||
"mchid": "",
|
||
"appid": "",
|
||
"merchantSerial": "",
|
||
"privateKeyPath": "",
|
||
"apiv3KeyEnv": "WXPAY_APIV3_KEY",
|
||
"publicKeyId": "",
|
||
"publicKeyPath": "",
|
||
"notifyBase": "https://api.huashengtec.com/health",
|
||
"payWindowHours": 24
|
||
}
|
||
```
|
||
|
||
## 六、前端改动清单(ui/wxapp_escort + 管理端)
|
||
|
||
| # | 文件 | 内容 |
|
||
| --- | --- | --- |
|
||
| 1 | `utils/api.js` | escort 段新增 `payOrder(id)`、`getPayStatus(id)` |
|
||
| 2 | `pages/escort/itemorder.js` | 新增支付方式选择(微信支付 / 线下支付,默认微信支付);提交订单时带 `payment.payChannel`。选微信支付:下单成功 → 立即 `payOrder` → `wx.requestPayment` → 查单确认 → 按结果跳转;选线下支付:下单成功后直接跳订单列表并提示线下支付 |
|
||
| 3 | `pages/escort/recordlist` / `recorddetail` | `unpaid` 订单按 `payChannel` 展示:`online_wechat` 显示「待支付」+「去支付」(超过支付窗口则显示「支付已超时」并隐藏去支付,只保留改线下 / 取消),`offline` 显示「线下支付」。详情页保留「取消订单」(无删除按钮):待确认且未收款取消即删除;已确认/已收款提示「取消申请已提交」。详情页增加「切换支付方式」入口(仅待支付可改);支付按钮防抖 |
|
||
|
||
管理端(`ui/wxapp_escort_admin`):`pages/order/orderDetail` 需展示 `refunding` / `refunded` 与 `payChannel`,并新增「查询退款结果」按钮(调 `POST /escort-record/:id/refund/query`),用于退款回调丢失时的人工兜底;`orderEdit` 在存在未决流水时禁用金额输入。
|
||
|
||
## 七、关键技术点与易错点
|
||
|
||
1. **金额换算**:由 `service.price` 字符串按小数点拆位直接得到整数分(不经过浮点);回调中校验 `amount.total` 与流水一致,防篡改
|
||
2. **openid 一致性**:必须用发起支付小程序自身 appid 下的 openid(现有 `user.app["wxapp-escort"].wxopenid` 满足);管理端小程序是另一个 appid,严禁串用
|
||
3. **幂等与并发**:
|
||
- 回调可能重复、乱序推送 → 以 `outTradeNo` / `outRefundNo` 唯一索引 + 状态条件更新兜底
|
||
- 同订单重复请求支付 → prepay_id 未过期(2 小时内)复用原支付参数,不新建流水
|
||
- **同一订单的 `createPayment` 串行执行**(按 recordId 的进程内锁),防并发各建一条在途流水
|
||
- 需要新建流水时一律换新 `outTradeNo`;前端支付按钮防抖
|
||
4. **回调时效**:验签后 5 秒内应答 200/204,业务处理放应答之后(或快速完成);应答失败微信将按 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h 重发至多 15 次
|
||
5. **签名探测流量**:微信会不定期发送 `WECHATPAY/SIGNTEST/` 开头签名的探测请求,验签失败按规范应答 4XX/5XX + `{"code":"FAIL"}`,不得当作攻击忽略或崩溃
|
||
6. **prepay_id 2 小时 / 支付窗口由 `time_expire` 决定**:prepay 有效期内重复点「去支付」直接复用;过期但仍在支付窗口内 → **沿用同一 `outTradeNo` 与原参数重新下单**刷新 prepay(同一业务单不因重试换号)。支付窗口(`time_expire`)到期 → 关单、流水置 `closed`,订单按失败终态处理。**prepay 过期不等于交易单失效**:不传 `time_expire` 时微信侧默认 7 天内仍可支付
|
||
7. **调起支付签名与请求签名是两套**:`paySign` 用 `appId`/`timeStamp`/`nonceStr`/`package` 四行签名串 + 商户私钥;`appId` 必须与下单 appid 一致
|
||
8. **服务器出网**:health 服务需能访问 `api.mch.weixin.qq.com`;`notify_url` 必须公网 HTTPS
|
||
9. **Request-ID 日志**:调微信接口时打印应答 HTTP 头 `Request-ID`,排障时提供给微信侧快速定位
|
||
10. **支付方式切换与关单**:用户从微信支付改为线下支付、或取消订单时,若已有未支付流水,必须调用关单接口。否则旧 `prepay_id` 在 2 小时内仍可被支付,出现「已取消 / 已改线下却线上付了」的双重收款。**关单失败不能只记日志**:立即查单确认——已支付则中止切换并转退款,未确认则标 `closed_unconfirmed` 交对账
|
||
11. **线下支付不改动现有履约链路**:`payChannel=offline` 的订单仍是 `unpaid`,平台收款后按现有管理端补记流程写入 `method` + `paidFee` + `paid`,用户端不做支付动作
|
||
12. **错误落库不能吞异常**:支付/退款失败时先写 `lastError` 再返回通用提示;若错误字段写库本身失败,必须 `logger.error` 兜底输出完整错误(含 `requestId`),不能静默丢弃
|
||
13. **错误信息脱敏**:`lastError.message` 只存微信返回的 `message` 与系统错误原文,不写入请求报文、私钥、openid 等敏感内容;长度截断 500 字符
|
||
14. **已取消订单收到支付**:回调到达时订单可能已 cancelled。钱必须入账(流水落 `pay_success`),订单不能显示已收款,必须自动全额退款。这是「取消 + 关单失败 / 竞态」的必然残留,不能省;退款在**应答之后异步发起**,不占用 5 秒应答窗口
|
||
15. **商户单号规则**:同一业务单在同一支付窗口内只留一条在途流水;prepay 过期用原 `outTradeNo` 重下,**旧单已关单或支付窗口到期后才换新号**(`订单_id` + 递增序号)。已关闭的单号永不复用
|
||
16. **改价与流水一致性**:存在 `created` 流水时禁止修改 `totalFee`;金额变更必须先关单,否则微信侧金额与本地流水错位,对账无法核对
|
||
17. **回调校验要全**:除 `out_trade_no` 与金额,还需校验解密报文中的 `mchid`、`appid`、`currency = CNY`,防跨商户报文或异常报文混入
|
||
18. **快照刷新失败**:流水已 `pay_success` 但订单快照刷失败时,必须 `logger.error` 记录,并依靠下一次回调 / 查单重刷(更新按状态条件幂等覆盖)
|
||
19. **退款幂等与兜底**:`outRefundNo` 唯一索引捕获重复取消(返回「退款处理中」而非 500);退款调用超时/系统异常时**先查退款确认是否受理,未受理用原单号原参数重试一次**;退款回调丢失时用管理端「查询退款结果」补写终态
|
||
20. **回调丢失必须由后台自己收敛**:不能只靠用户回页面或管理端手动触发。巡检随服务启动默认运行,扫在途流水查单:`SUCCESS` 按回调同一套逻辑收敛,到期仍 `NOTPAY` 则关单
|
||
|
||
## 八、部署前检查清单
|
||
|
||
**商户平台侧材料(缺一不可)**:
|
||
|
||
- [ ] JSAPI 支付权限已开通(商户平台 → 产品中心)
|
||
- [ ] 商户号与小程序 APPID 完成授权绑定(商户平台发起 + 公众平台确认,绑定后不可解绑)
|
||
- [ ] 商户 API 证书:`apiclient_cert.pem` / `apiclient_key.pem` + 证书序列号
|
||
- [ ] APIv3 密钥(32 位,账户中心 → API 安全)
|
||
- [ ] 微信支付公钥:`pub_key.pem` + 公钥 ID(`PUB_KEY_ID_` 开头)
|
||
- [ ] 商户号账户余额充足(退款从账户余额扣除,余额不足会直接退款失败)
|
||
|
||
**合规(重要)**:
|
||
|
||
- [ ] 交易类小程序须按《交易类小程序运营规范》接入**订单发货管理功能**,否则可能被公众平台限制支付权限,正式环境调不起支付
|
||
|
||
**服务器侧**:
|
||
|
||
- [ ] `/etc/ehason/conf.json` 补 `wechatpay` 段;`WXPAY_APIV3_KEY` 环境变量注入
|
||
- [ ] 出网连通 `api.mch.weixin.qq.com`;`api.huashengtec.com` HTTPS 证书有效
|
||
- [ ] 防火墙/安全组放行微信支付回调 IP 段(支付回调与退款回调是不同 IP 段,均需放行 443 入站);有 WAF 时确认不拦截回调请求
|
||
|
||
## 九、验证与测试
|
||
|
||
1. **本地自测**:签名串构造自校验(官方签名生成/验证规范逐条比对);回调解密用官方示例报文验证;**用项目自身的签名/验签/解密能力调 `POST /v3/security/echo` 实测**(读代码无法证明签名生效)
|
||
2. **沙箱/小额联调**:1 分钱真实下单 → 支付 → 回调 → 查单 → 退款全链路
|
||
3. **异常路径**:中途取消支付、重复回调、prepay_id 过期重下(应沿用原单号)、支付后立即取消(自动退款)、回调延迟时的查单兜底、支付方式切换(微信→线下后旧 prepay 不可再支付)、支付按钮连续点击、并发发起支付(只产生一条在途流水)、**支付窗口到期后关单**、**取消后用旧 prepay 完成支付(回调自动退款)**、**关单失败后切换(查单拦截已支付)**、**改线下再改回微信(新单号可正常支付)**
|
||
4. **失败落库验证**:模拟网络不可达(错误码 `NETWORK_ERROR`)、模拟微信业务错误(如 `NO_AUTH`)、模拟退款失败 → 检查 `payment_record` / `refund_record` 的 `lastError`(含 `code`/`message`/`requestId`)、`errorCount`、`lastAttemptAt` 是否正确写入,且接口返回的是统一提示而非内部错误详情
|
||
5. **资金安全专项**:①取消待支付订单后用旧 prepay 完成支付 → 校验自动退款与 `refund_record`;②管理员对存在 `created` 流水的订单改价 → 应被拒绝;③同一订单多次发起支付 → 仅一条在途流水、仅一笔成功;④重复点击取消 → 返回「退款处理中」不报 500;⑤退款回调丢失 → 管理端查询补写终态;⑥金额为 0 的订单走微信 → 应被拒绝;⑦退款调用超时 → 自动查退款并原单号重试,不产生第二笔退款
|
||
6. **兜底链路验证**:①支付成功但人为让回调丢失 → 巡检在下一轮查单补单,订单转 paid;②回调验签失败 → 应答 4XX,随后由巡检收敛;③支付窗口到期未付 → 巡检查单为 `NOTPAY` 后关单,流水置 `closed`
|
||
7. 上线前按官方《接入质量检查清单》逐项核对
|
||
|
||
## 十、后续迭代项(本期不做)
|
||
|
||
- 下载交易账单/资金账单 API 的自动对账任务(字段已对齐,随时可加;**本期经确认不做**,由巡检查单 + 人工下载账单对账兜底)
|
||
- 巡检的多频率退避与告警(本期固定 10 分钟一轮,够用)
|
||
- 退款 `ABNORMAL`(用户银行卡作废/冻结)自动发起异常退款(本期转人工,资金停留在退款中间账户由财务处理)
|
||
- 主备域名自动切换(本期只连主域名 `api.mch.weixin.qq.com`,接受单通道风险)
|
||
- 部分退款 / 多次退款(本期一单一退,`outRefundNo` 固定 `-R1`)
|
||
- 培训报名(training_application)复用 payment_record 接入支付
|