Files
ws_health/doc/wechatpay-plan.md
T

434 lines
36 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 陪诊订单微信支付接入方案
> 更新时间: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 | 「退款中」(线下人工退款核销) |
| 用户申请取消(已确认订单) | 保持原值 | 保持原值 | 保持原值 | 「待取消」,等待陪诊师/管理员确认 |
**取消规则(用户端只保留「取消订单」按钮)**:
- 未确认订单:取消直接生效,无需人工确认。未收款 → 直接物理删除;已收款 → 转 `cancelled` 并进入退款(线上微信自动原路退款,线下人工核销)
- 已确认订单:用户取消后进入 `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` 取消:未确认 → 直接取消(未收款物理删除;已收款转 `cancelled` 并进入退款);已确认 → `cancel_requested`,陪诊师/管理员确认后转 `cancelled`,线上已收款订单再走退款流程;线下收款订单由平台人工退款后在管理端核销为 `refunded`。⑤ 金额 ≤ 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 /escort-record/:id/refund/manual`(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_companion`):`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 接入支付