技能介绍

为什么需要这套规范

微信支付 v3 的接口路径固定，但真正容易出事故的是安全与状态机：前端 wx.requestPayment 成功不等于已收款，回调可能被重放，密钥一旦进 Git 或日志就不可逆。很多项目卡在「paySign 怎么算」「回调怎么验签」「同一笔通知来了两次怎么办」——本技能把这些写成 P0 清单，而不是散落在各篇教程里。

技能能帮你做什么

接入清单：商户号、APIv3 密钥、商户证书、AppID、回调域名等开发前必选项，以及 JSAPI / Native / H5 / 查询 / 关单 / 退款 / 回调各接口的关键注意点。
FastAPI 骨架生成：产出 wechat_pay_client.py（统一下单、查询、关单、退款、平台证书拉取与验签、回调 AES-256-GCM 解密、build_jsapi_payment() 直接给出前端所需的 paySign）、router.py（创建订单、带验签与幂等的 notify、退款）、.env.example 与接入说明。
可验证的密码学：脚本带 --self-test，用临时 RSA 与随机 APIv3 密钥跑通签名/验签与回调报文加解密往返，避免盲信生成代码。

边界与注意

生成代码是骨架：订单表与「已处理」标记（幂等落地）需你自行实现；金额必须由服务端计算。apiv3_key 与私钥只放 .env，验签失败不得改订单状态。小程序端只需对 /api/pay/create 返回的 payment 调用 wx.requestPayment；可与小程序安全边界、验收类技能配合使用。