liufumingren 8949b7198c feat(pay): 微信 Native 扫码支付(下单出码 + 回调入账 + 扫码轮询)
- 新增 service/wxpay.js:统一下单 / 查询订单 / 关闭订单 / APIv2 验签,二维码在服务端本地生成 SVG
- 新增 pay/wechat.js 与 XML 编解码,公开回调 POST /api/pay/wechat/notify
- 订单:同主体 + 同套餐复用未超时待支付单;2 小时超时关单;回调 / 查单 / 手工确认统一走 payNotify
- 迁移 subject_orders 增加 code_url / prepay_id 等字段,配置项 WXPAY_*
- 前端续期弹窗展示二维码并按 2s 轮询支付结果
- 文档与测试同步更新

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 16:23:03 +08:00

325 lines
13 KiB
JavaScript
Raw Permalink 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.

'use strict';
const { Service } = require('egg');
const crypto = require('crypto');
const qrcode = require('qrcode-generator');
const { buildXml, parseXml, parseWxTime, formatWxTime, truncateUtf8 } = require('../lib/wxpay-xml');
/** 交易状态(`trade_state`)→ 中文,仅用于日志/排查 */
const TRADE_STATE_TEXT = {
SUCCESS: '支付成功',
REFUND: '转入退款',
NOTPAY: '未支付',
CLOSED: '已关闭',
REVOKED: '已撤销',
USERPAYING: '用户支付中',
PAYERROR: '支付失败',
};
/** 回调地址兜底(未配 `config.wxpay.notifyUrl` 时用 SITE_URL 拼) */
const NOTIFY_PATH = '/api/pay/wechat/notify';
/** 上一次记过的配置问题(同一条只记一次,避免每单刷屏) */
let warnedIssues = '';
/**
* 微信支付 Native(原生扫码)—— **APIv2 统一下单**
*
* 文档:https://pay.weixin.qq.com/doc/v2/merchant/4011936530
*
* - `unifiedOrder()` 拿 `code_url`(`weixin://wxpay/bizpayurl?pr=xxx`)→ 本地画成二维码;
* - `queryOrder()` 用于「没收到支付通知」时主动补单(前端轮询订单详情时顺手做);
* - `closeOrder()` 用于关单,保证本地关掉的订单二维码也付不了;
* - `verifySign()` / `signOf()` 负责 APIv2 签名(MD5 或 HMAC-SHA256,密钥是 `config.wxpay.apiKey`)。
*
* ⚠️ 未配置 appId / mchId / apiKey 时 `enabled === false`:调用方据此降级(只建单、不出二维码)。
*/
class WxPayService extends Service {
get cfg() {
return this.app.config.wxpay || {};
}
/** 凭证齐全(且没被 `WXPAY_ENABLED=false` 关掉)才算开通 */
get enabled() {
const cfg = this.cfg;
return Boolean(cfg.enabled !== false && cfg.appId && cfg.mchId && cfg.apiKey);
}
/** 未开通时直接 503,前端据此提示「微信支付未配置」 */
assertEnabled() {
if (!this.enabled) this.fail(503, '微信支付未配置');
}
/**
* 抛一个「消息可以给用户看」的支付错误(`expose = true`)
*
* 这类错误几乎都是配置/凭证问题(签名错误、appid 不匹配…),
* 藏成「服务器内部错误」除了浪费时间没有任何好处;排查细节仍然进日志。
* @param {number} status HTTP 状态码
* @param {string} message 给调用方看的中文原因
* @param {object} [extra] 微信返回的字段表(带上 `err_code`,便于调用方判断 ORDERPAID / ORDERCLOSED)
* @return {never}
*/
fail(status, message, extra = null) {
const err = new Error(message);
err.status = status;
err.expose = true;
if (extra) {
err.code = extra.err_code || null;
err.wxpay = extra;
}
throw err;
}
/**
* 配置自检:列出需要人工处理的问题(缺字段 / 密钥长度不对)
*
* 微信 APIv2 密钥固定 **32 位字母数字**(商户平台 → 账户中心 → API 安全里设置的那个);
* 长度不对时下单会被微信以「签名错误」拒绝,提前指出来省得排查半天。
* @return {string[]} 问题列表,空数组表示没问题
*/
configIssues() {
const cfg = this.cfg;
const issues = [];
if (!cfg.appId) issues.push('缺少 WXPAY_APP_ID');
if (!cfg.mchId) issues.push('缺少 WXPAY_MCH_ID');
if (!cfg.apiKey) {
issues.push('缺少 WXPAY_API_KEY');
} else if (!/^[A-Za-z0-9]{32}$/.test(String(cfg.apiKey))) {
issues.push(`WXPAY_API_KEY 应为 32 位字母数字,当前 ${String(cfg.apiKey).length} 位`);
}
return issues;
}
/**
* 配置有问题就记一条 WARN(同一条提示只记一次)
* @return {string[]} 问题列表(调用方可以据此降级)
*/
warnIfMisconfigured() {
const issues = this.configIssues();
const text = issues.join(';');
if (text && text !== warnedIssues) {
warnedIssues = text;
this.ctx.logger.warn('[wxpay] 配置自检未通过:%s(改 config/env.prod.sh 后重新发布才生效)', text);
}
return issues;
}
/** 回调地址:优先 `WXPAY_NOTIFY_URL`,其次 `SITE_URL`,最后退回本次请求的 origin */
get notifyUrl() {
const cfg = this.cfg;
if (cfg.notifyUrl) return String(cfg.notifyUrl);
const siteUrl = String((this.config.email && this.config.email.siteUrl) || this.ctx.origin || '');
return `${siteUrl.replace(/\/+$/, '')}${NOTIFY_PATH}`;
}
/** 商品描述:`WXPAY_BODY`(或站点名)+ 套餐名,按 128 字节截断 */
bodyOf(description) {
const base = this.cfg.body || `${this.config.siteName}续期`;
return truncateUtf8(description ? `${base}-${description}` : base, 128);
}
/**
* APIv2 签名:字段按 key 升序拼 `k=v&`,末尾接 `&key=<apiKey>`,再 MD5 / HMAC-SHA256 并转大写
*
* 空值字段不参与签名(与微信一致);`sign` 字段本身必须排除。
* @param {object} params 参数表
* @param {string} [signType] MD5 | HMAC-SHA256
* @return {string} 签名(大写十六进制)
*/
signOf(params = {}, signType = this.cfg.signType || 'MD5') {
const content = Object.keys(params)
.filter(key => key !== 'sign' && params[key] !== undefined && params[key] !== null && params[key] !== '')
.sort()
.map(key => `${key}=${params[key]}`)
.join('&');
const payload = `${content}&key=${this.cfg.apiKey}`;
const digest = signType === 'HMAC-SHA256'
? crypto.createHmac('sha256', this.cfg.apiKey).update(payload, 'utf8').digest('hex')
: crypto.createHash('md5').update(payload, 'utf8').digest('hex');
return digest.toUpperCase();
}
/**
* 校验微信回调/返回值签名(同时核对 appid、mch_id,防止串号)
* @param {object} params 解析后的字段表
* @return {{ ok: boolean, message?: string }}
*/
verifySign(params = {}) {
if (!this.enabled) return { ok: false, message: '微信支付未配置' };
if (params.appid && params.appid !== this.cfg.appId) return { ok: false, message: 'appid 不匹配' };
if (params.mch_id && params.mch_id !== this.cfg.mchId) return { ok: false, message: 'mch_id 不匹配' };
const actual = String(params.sign || '').toUpperCase();
const expected = this.signOf(params, params.sign_type || this.cfg.signType || 'MD5');
if (!actual || actual.length !== expected.length) return { ok: false, message: '签名不匹配' };
if (!crypto.timingSafeEqual(Buffer.from(actual), Buffer.from(expected))) {
return { ok: false, message: '签名不匹配' };
}
return { ok: true };
}
/**
* 调 v2 接口(XML 进出,自动补公共参数 + 签名 + 验签)
* @param {string} path 形如 `/pay/unifiedorder`
* @param {object} params 业务参数
* @return {Promise<object>} 微信返回的字段表(result_code 一定是 SUCCESS)
*/
async request(path, params = {}) {
this.assertEnabled();
const payload = Object.assign({}, params, {
appid: this.cfg.appId,
mch_id: this.cfg.mchId,
nonce_str: crypto.randomBytes(16).toString('hex'),
sign_type: this.cfg.signType || 'MD5',
});
payload.sign = this.signOf(payload);
let res = null;
try {
res = await this.app.curl(`${this.cfg.apiBase}${path}`, {
method: 'POST',
headers: { 'Content-Type': 'text/xml; charset=utf-8' },
data: buildXml(payload),
dataType: 'text',
timeout: Number(this.cfg.timeout || 8000),
});
} catch (err) {
this.ctx.logger.error('[wxpay] 请求 %s 失败: %s', path, err.message);
this.fail(502, '微信支付接口不可用,请稍后重试');
}
const status = Number(res && res.status) || 0;
if (status !== 200) {
this.ctx.logger.error('[wxpay] %s 返回 HTTP %s: %s', path, status, String(res && res.data).slice(0, 500));
this.fail(502, `微信支付接口异常(HTTP ${status})`);
}
const body = parseXml(res.data);
if (body.return_code !== 'SUCCESS') {
const message = body.return_msg || '通讯失败';
this.ctx.logger.error('[wxpay] %s 通讯失败: %s(配置自检:%s)',
path, message, this.configIssues().join(';') || '无');
// 「签名错误 / appid 与 mch_id 不匹配」这些必须让人看见,否则完全没法定位
this.fail(502, `微信支付:${message}`);
}
const sign = this.verifySign(body);
if (!sign.ok) {
this.ctx.logger.error('[wxpay] %s 返回验签失败(%s): %j', path, sign.message, body);
this.fail(502, '微信支付返回结果验签失败');
}
if (body.result_code !== 'SUCCESS') {
// 业务错误码(ORDERPAID / ORDERNOTEXIST / ORDERCLOSED / OUT_TRADE_NO_USED …)带给调用方判断
this.fail(502, `微信支付:${body.err_code_des || body.err_code || '业务处理失败'}`, body);
}
return body;
}
/**
* 统一下单(NATIVE)
*
* 同一 `out_trade_no` 重复下单且参数不变时微信返回同一个 `prepay_id` / `code_url`,
* 所以「复用原订单」时重复调用是安全的。
* @param {object} params { orderNo, totalFee(分), description, clientIp, expireAt, productId }
* @return {Promise<{ codeUrl: string, prepayId: string|null }>}
*/
async unifiedOrder({ orderNo, totalFee, description, clientIp, expireAt, productId } = {}) {
const fee = Math.round(Number(totalFee));
if (!Number.isFinite(fee) || fee <= 0) this.ctx.throw(422, '支付金额不合法');
const params = {
body: this.bodyOf(description),
out_trade_no: String(orderNo),
total_fee: String(fee),
spbill_create_ip: String(clientIp || '127.0.0.1'),
notify_url: this.notifyUrl,
trade_type: 'NATIVE',
product_id: String(productId || orderNo),
};
// 二维码与订单同时失效:超过 time_expire 微信侧也会拒绝支付
const expire = expireAt ? formatWxTime(expireAt) : null;
if (expire) params.time_expire = expire;
const res = await this.request('/pay/unifiedorder', params);
if (!res.code_url) this.fail(502, '微信支付没有返回二维码链接');
return { codeUrl: res.code_url, prepayId: res.prepay_id || null };
}
/**
* 查单(回调丢失时补单用)
* @param {object} params { orderNo }
* @return {Promise<object>} { tradeState, tradeStateText, transactionId, totalFee(分), paidAt }
*/
async queryOrder({ orderNo } = {}) {
const res = await this.request('/pay/orderquery', { out_trade_no: String(orderNo) });
return {
tradeState: res.trade_state || '',
tradeStateText: TRADE_STATE_TEXT[res.trade_state] || res.trade_state || '',
transactionId: res.transaction_id || null,
totalFee: res.total_fee === undefined ? null : Number(res.total_fee),
paidAt: parseWxTime(res.time_end),
};
}
/**
* 关闭订单(本地关单时同步关掉微信侧,避免已关订单还能被扫码支付)
* @param {object} params { orderNo }
* @return {Promise<{ closed: boolean, already?: boolean }>}
*/
async closeOrder({ orderNo } = {}) {
try {
await this.request('/pay/closeorder', { out_trade_no: String(orderNo) });
return { closed: true };
} catch (err) {
if (err.code === 'ORDERCLOSED') return { closed: true, already: true };
throw err;
}
}
/**
* 二维码内容画成 **SVG data URL**(零外链,前端直接塞 `<img :src>`)
*
* 自己拼 SVG 而不是用库的 `createSvgTag`:库会**每个格子一段 path**(一段 30 字节),
* 实测同一个码体积差 4 倍;这里把同一行连续的深色格子合并成一段,轮询时省流量。
* @param {string} content 二维码内容(`code_url`)
* @return {string|null} data URL;内容为空返回 null
*/
qrDataUrl(content) {
if (!content) return null;
const cellSize = Number(this.cfg.qrCellSize) || 6;
const marginCells = Number(this.cfg.qrMargin) || 4;
const qr = qrcode(0, 'M'); // 版本自动、纠错等级 M
qr.addData(String(content));
qr.make();
const size = qr.getModuleCount();
const total = (size + marginCells * 2) * cellSize;
const segments = [];
for (let row = 0; row < size; row++) {
let col = 0;
while (col < size) {
if (!qr.isDark(row, col)) {
col += 1;
continue;
}
let run = 1;
while (col + run < size && qr.isDark(row, col + run)) run += 1;
const x = (col + marginCells) * cellSize;
const y = (row + marginCells) * cellSize;
const width = run * cellSize;
segments.push(`M${x},${y}h${width}v${cellSize}h-${width}z`);
col += run;
}
}
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${total} ${total}" shape-rendering="crispEdges">`
+ `<rect width="${total}" height="${total}" fill="#ffffff"/>`
+ `<path d="${segments.join('')}" fill="#000000"/></svg>`;
return `data:image/svg+xml;base64,${Buffer.from(svg, 'utf8').toString('base64')}`;
}
}
module.exports = WxPayService;