@vobs/payment 0.3.0 → 1.2.0

package/src/wechat/notify.ts

@@ -0,0 +1,93 @@
+import { Aes, Formatter, Rsa } from 'wechatpay-axios-plugin'
+import type { WechatClient } from './client'
+import type {
+  WechatNotifyHeaders,
+  WechatNotifyRefund,
+  WechatNotifyResource,
+  WechatNotifyTransaction
+} from './types'
+
+/**
+ * 微信支付异步通知处理（APIv3）
+ *
+ * 完整流程：
+ * 1. verify()   — 用 certs（按 Wechatpay-Serial 查找平台证书/微信支付公钥）验证报文签名
+ * 2. decrypt()  — 用 apiv3Key 做 AES-256-GCM 解密 resource 得到业务数据
+ * 3. validate() — 比对商户侧期望值（订单号 / 金额），防错配
+ * 4. 处理业务后用 successResponse()/failResponse() 应答微信
+ */
+export function createNotifyHandler(client: WechatClient) {
+  return {
+    /**
+     * 验签异步通知
+     * @param headers 微信支付回调的 Wechatpay-* 系列 HTTP 头
+     * @param body 原始请求体字符串（必须是未解析的原文，不可先 JSON.parse 再序列化）
+     * @returns 验签是否通过
+     */
+    verify(headers: WechatNotifyHeaders, body: string): boolean {
+      const publicKey = client.config.options.certs[headers.serial]
+      if (!publicKey) {
+        return false
+      }
+      try {
+        const message = Formatter.response(headers.timestamp, headers.nonce, body)
+        return Rsa.verify(message, headers.signature, publicKey)
+      } catch {
+        return false
+      }
+    },
+
+    /**
+     * 解密通知 resource 字段（AES-256-GCM，apiv3Key）
+     * @param resource 回调 JSON 中的 resource 字段
+     */
+    decrypt<T extends WechatNotifyTransaction | WechatNotifyRefund = WechatNotifyTransaction>(
+      resource: WechatNotifyResource
+    ): T {
+      const plaintext = Aes.AesGcm.decrypt(
+        resource.ciphertext,
+        client.config.apiv3Key,
+        resource.nonce,
+        resource.associatedData ?? ''
+      )
+      return JSON.parse(plaintext) as T
+    },
+
+    /**
+     * 校验解密后的通知与商户侧订单是否一致。
+     * 验签只保证通知来自微信支付，不保证与你的订单一致。
+     * @param payload 解密后的通知数据
+     * @param expected 商户侧期望值：outTradeNo 订单号、total 订单金额（分）
+     */
+    validate(
+      payload: WechatNotifyTransaction | WechatNotifyRefund,
+      expected?: { outTradeNo?: string; total?: number }
+    ): { valid: boolean; errors: string[] } {
+      const errors: string[] = []
+
+      if (payload.mchid !== client.config.mchid) {
+        errors.push(`mchid 不匹配: 期望 ${client.config.mchid}，收到 ${payload.mchid}`)
+      }
+
+      if (expected?.outTradeNo && payload.outTradeNo !== expected.outTradeNo) {
+        errors.push(`out_trade_no 不匹配: 期望 ${expected.outTradeNo}，收到 ${payload.outTradeNo}`)
+      }
+
+      if (expected?.total !== undefined && payload.amount?.total !== expected.total) {
+        errors.push(`amount.total 不匹配: 期望 ${expected.total}，收到 ${payload.amount?.total}`)
+      }
+
+      return { valid: errors.length === 0, errors }
+    },
+
+    /** 通知处理成功应答（HTTP 200/201，body 恰为 {"code":"SUCCESS"}） */
+    successResponse(): { code: 'SUCCESS'; message?: undefined } {
+      return { code: 'SUCCESS' }
+    },
+
+    /** 通知处理失败应答（微信会按衰减频率重发通知） */
+    failResponse(message?: string): { code: 'FAIL'; message: string } {
+      return { code: 'FAIL', message: message ?? '处理失败' }
+    }
+  }
+}

package/src/wechat/payment.ts

@@ -0,0 +1,177 @@
+import { Formatter, Rsa } from 'wechatpay-axios-plugin'
+import type { WechatClient } from './client'
+import { unwrapV3 } from './response'
+import type {
+  WechatAppPayResult,
+  WechatH5PayParams,
+  WechatH5PayResult,
+  WechatJsapiPayResult,
+  WechatNativePayResult,
+  WechatPayParams,
+  WechatQueryParams,
+  WechatQueryResult,
+  WechatTradeState
+} from './types'
+
+/**
+ * 微信支付下单（APIv3）
+ *
+ * 覆盖四种收款场景：
+ * - jsapiPay：公众号网页 / 小程序（wx.requestPayment）
+ * - appPay：APP 拉起微信支付
+ * - nativePay：PC 扫码支付（返回二维码链接）
+ * - h5Pay：微信外浏览器 H5 支付（返回收银台跳转链接）
+ *
+ * ⚠️ 支付结果以异步通知或 query() 为准。
+ */
+export function createPayment(client: WechatClient) {
+  return {
+    /**
+     * 公众号 / 小程序支付下单（POST /v3/pay/transactions/jsapi）
+     * @param params 下单参数，openid 必填
+     * @returns 调起 wx.requestPayment 所需的签名参数
+     */
+    async jsapiPay(params: WechatPayParams & { openid: string }): Promise<WechatJsapiPayResult> {
+      const { data } = await postTransaction(client, 'jsapi', params)
+      return buildInvokeParams(client, data.prepay_id ?? '')
+    },
+
+    /**
+     * APP 支付下单（POST /v3/pay/transactions/app）
+     * @param params 下单参数
+     * @returns 传给客户端 SDK 调起微信支付的签名参数
+     */
+    async appPay(params: WechatPayParams): Promise<WechatAppPayResult> {
+      const { data } = await postTransaction(client, 'app', params)
+      return buildInvokeParams(client, data.prepay_id ?? '')
+    },
+
+    /**
+     * Native 扫码支付下单（POST /v3/pay/transactions/native）
+     * @returns 二维码链接（前端渲染二维码，用户扫码支付）
+     */
+    async nativePay(params: WechatPayParams): Promise<WechatNativePayResult> {
+      const { data } = await postTransaction(client, 'native', params)
+      if (!data.code_url) {
+        throw new Error('WechatClient: 下单响应缺少 code_url')
+      }
+      return { codeUrl: data.code_url }
+    },
+
+    /**
+     * H5 支付下单（POST /v3/pay/transactions/h5）
+     * @param params 下单参数，payerClientIp 必填
+     * @returns 收银台跳转链接（302 重定向即可拉起微信支付）
+     */
+    async h5Pay(params: WechatH5PayParams): Promise<WechatH5PayResult> {
+      const body = buildTransactionBody(client, params)
+      body.scene_info = {
+        payer_client_ip: params.payerClientIp,
+        ...(params.sceneInfo?.deviceType ? { device_type: params.sceneInfo.deviceType } : {})
+      }
+      const { data } = await unwrapV3(client.sdk.v3.pay.transactions.h5.post(body))
+      return { h5Url: data.h5_url }
+    },
+
+    /**
+     * 交易查询（GET /v3/pay/transactions/out-trade-no/{no} 或 .../id/{id}）
+     * @throws {WechatApiError} 订单不存在等失败（RESOURCE_NOT_EXISTS）
+     */
+    async query(params: WechatQueryParams): Promise<WechatQueryResult> {
+      const mchid = client.config.mchid
+      const response = params.transactionId
+        ? await unwrapV3(
+            client.sdk.client.request(
+              `/v3/pay/transactions/id/${encodeURIComponent(params.transactionId)}`,
+              'GET',
+              undefined,
+              { params: { mchid } }
+            )
+          )
+        : await unwrapV3(
+            client.sdk.client.request(
+              `/v3/pay/transactions/out-trade-no/${encodeURIComponent(params.outTradeNo ?? '')}`,
+              'GET',
+              undefined,
+              { params: { mchid } }
+            )
+          )
+      return mapTransaction((response as { data: Record<string, any> }).data)
+    }
+  }
+}
+
+type TransactionChain = 'jsapi' | 'app' | 'native'
+
+async function postTransaction(
+  client: WechatClient,
+  chain: TransactionChain,
+  params: WechatPayParams
+): Promise<{ data: { prepay_id?: string; code_url?: string } }> {
+  const body = buildTransactionBody(client, params)
+  return unwrapV3(client.sdk.v3.pay.transactions[chain].post(body))
+}
+
+/** 构造下单请求体（camelCase -> snake_case，注入 appid/mchid/notify_url） */
+function buildTransactionBody(
+  client: WechatClient,
+  params: WechatPayParams
+): Record<string, any> {
+  const body: Record<string, any> = {
+    appid: client.config.appid,
+    mchid: client.config.mchid,
+    description: params.description,
+    out_trade_no: params.outTradeNo,
+    time_expire: params.timeExpire,
+    attach: params.attach,
+    goods_tag: params.goodsTag,
+    notify_url: client.config.notifyUrl,
+    amount: {
+      total: params.amount.total,
+      currency: params.amount.currency ?? 'CNY'
+    }
+  }
+  if (params.openid) {
+    body.payer = { openid: params.openid }
+  }
+  // 移除 undefined 字段
+  for (const key of Object.keys(body)) {
+    if (body[key] === undefined) delete body[key]
+  }
+  return body
+}
+
+/**
+ * 生成拉起支付的签名参数。
+ * 签名串：appid\ntimeStamp\nnonceStr\nprepay_id=xxx\n（SHA256withRSA，商户 API 私钥）
+ */
+function buildInvokeParams(client: WechatClient, prepayId: string): WechatJsapiPayResult {
+  if (!prepayId) {
+    throw new Error('WechatClient: 下单响应缺少 prepay_id')
+  }
+  const appId = client.config.appid
+  const timeStamp = `${Formatter.timestamp()}`
+  const nonceStr = Formatter.nonce(32)
+  const pkg = `prepay_id=${prepayId}`
+  const message = `${appId}\n${timeStamp}\n${nonceStr}\n${pkg}\n`
+  const paySign = Rsa.sign(message, client.config.options.privateKey)
+  return { appId, timeStamp, nonceStr, package: pkg, signType: 'RSA', paySign }
+}
+
+/** snake_case 响应映射 */
+function mapTransaction(data: Record<string, any>): WechatQueryResult {
+  return {
+    appid: data.appid,
+    mchid: data.mchid,
+    outTradeNo: data.out_trade_no,
+    transactionId: data.transaction_id,
+    tradeType: data.trade_type,
+    tradeState: data.trade_state as WechatTradeState,
+    tradeStateDesc: data.trade_state_desc,
+    bankType: data.bank_type,
+    attach: data.attach,
+    successTime: data.success_time,
+    total: data.amount?.total,
+    payerTotal: data.amount?.payer_total
+  }
+}

package/src/wechat/plugin.ts

@@ -0,0 +1,59 @@
+import { createInjectionKey, inject, type VobsContext, type VobsPlugin } from '@vobs/vobs'
+import { WechatClient } from './client'
+import type { WechatClientOptions } from './types'
+
+export const WECHAT_KEY = createInjectionKey<WechatClient>('vobs.payment.wechat')
+
+export interface WechatPluginOptions {
+  /** 微信支付客户端配置（未传入 client 时必填） */
+  config?: WechatClientOptions
+  /** 可选的已有客户端实例（指定后忽略 config） */
+  client?: WechatClient
+}
+
+/** 从 vobs 插件上下文获取微信支付客户端 */
+export function useWechat(): WechatClient {
+  const client = inject(WECHAT_KEY)
+  if (!client) {
+    throw new Error('Vobs Payment: 找不到 WechatClient，请安装 wechatPlugin')
+  }
+  return client
+}
+
+/**
+ * 微信支付插件
+ *
+ * @example
+ * ```ts
+ * createVobs({
+ *   plugins: [
+ *     wechatPlugin({
+ *       config: {
+ *         mchid: '1900000000',
+ *         serial: '...',
+ *         privateKey: '...',
+ *         certs: { 'PUB_KEY_ID_xxx': '...' },
+ *         appid: 'wx1234567890',
+ *         apiv3Key: '...'
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+export function wechatPlugin(options: WechatPluginOptions): VobsPlugin {
+  return {
+    name: '@vobs/payment/wechat',
+    version: '0.1.0',
+    install(context: VobsContext) {
+      if (!options.client && !options.config) {
+        throw new Error('Vobs Payment: wechatPlugin 需要提供 config 或 client 之一')
+      }
+      // 仅销毁插件自建的客户端；外部传入的实例由其所有者负责生命周期。
+      const ownClient = !options.client
+      const client = options.client ?? new WechatClient(options.config!)
+      context.provide(WECHAT_KEY, client)
+      return ownClient ? () => client.dispose() : undefined
+    }
+  }
+}

package/src/wechat/refund.ts

@@ -0,0 +1,80 @@
+import type { WechatClient } from './client'
+import { unwrapV3 } from './response'
+import type {
+  WechatRefundParams,
+  WechatRefundQueryParams,
+  WechatRefundResult,
+  WechatRefundStatus
+} from './types'
+
+/**
+ * 微信退款（APIv3）
+ *
+ * 覆盖申请退款与退款状态查询。
+ * ⚠️ 退款结果以异步通知（refund.irqevent）或 queryRefund 为准。
+ */
+export function createRefund(client: WechatClient) {
+  return {
+    /**
+     * 申请退款（POST /v3/refund/domestic/refunds）
+     * @param params 退款参数（outTradeNo 与 transactionId 二选一）
+     * @throws {WechatApiError} 参数错误、余额不足、订单不可退等失败
+     */
+    async refund(params: WechatRefundParams): Promise<WechatRefundResult> {
+      const body: Record<string, any> = {
+        out_trade_no: params.outTradeNo,
+        transaction_id: params.transactionId,
+        out_refund_no: params.outRefundNo,
+        reason: params.reason,
+        notify_url: params.notifyUrl ?? client.config.notifyUrl,
+        funds_account: params.fundsAccount,
+        amount: {
+          refund: params.amount.refund,
+          total: params.amount.total,
+          currency: params.amount.currency ?? 'CNY'
+        }
+      }
+      // 移除 undefined 字段
+      for (const key of Object.keys(body)) {
+        if (body[key] === undefined) delete body[key]
+      }
+      for (const key of Object.keys(body.amount)) {
+        if ((body.amount as any)[key] === undefined) delete (body.amount as any)[key]
+      }
+
+      const { data } = await unwrapV3(client.sdk.v3.refund.domestic.refunds.post(body))
+      return mapRefund(data)
+    },
+
+    /**
+     * 查询退款（GET /v3/refund/domestic/refunds/{out_refund_no | refund_id}）
+     * @throws {WechatApiError} 退款单不存在等失败
+     */
+    async queryRefund(params: WechatRefundQueryParams): Promise<WechatRefundResult> {
+      const id = params.refundId ?? params.outRefundNo
+      if (!id) {
+        throw new Error('WechatClient: queryRefund 需要 outRefundNo 或 refundId')
+      }
+      const { data } = await unwrapV3(
+        client.sdk.client.request(`/v3/refund/domestic/refunds/${encodeURIComponent(id)}`, 'GET')
+      )
+      return mapRefund(data)
+    }
+  }
+}
+
+/** snake_case 响应映射 */
+function mapRefund(data: Record<string, any>): WechatRefundResult {
+  return {
+    refundId: data.refund_id,
+    outRefundNo: data.out_refund_no,
+    outTradeNo: data.out_trade_no,
+    transactionId: data.transaction_id,
+    status: data.status as WechatRefundStatus,
+    refundAmount: data.amount?.refund,
+    total: data.amount?.total,
+    userReceivedAmount: data.amount?.user_received_amount,
+    successTime: data.success_time,
+    reason: data.reason
+  }
+}

package/src/wechat/response.ts

@@ -0,0 +1,54 @@
+/**
+ * 微信支付 APIv3 错误归一化。
+ *
+ * v3 接口没有"业务体 code"约定：HTTP 2xx 即成功，失败以
+ * 非 2xx 状态码 + JSON body {code, message} 表达（axios 会抛错）。
+ * 本模块把 axios 错误统一转换为 WechatApiError。
+ */
+export class WechatApiError extends Error {
+  /** HTTP 状态码（网络层错误时为 undefined） */
+  readonly status?: number
+  /** 错误码，如 PARAM_ERROR / RESOURCE_NOT_EXISTS / NETWORK_ERROR */
+  readonly code: string
+
+  constructor(message: string, status: number | undefined, code: string) {
+    super(message)
+    this.name = 'WechatApiError'
+    this.status = status
+    this.code = code
+  }
+}
+
+/** 将任意请求异常归一化为 WechatApiError */
+export function toWechatApiError(error: unknown): WechatApiError {
+  if (error instanceof WechatApiError) return error
+  const axiosError = error as {
+    response?: { status?: number; data?: { code?: string; message?: string } }
+    code?: string
+    message?: string
+  }
+  const status = axiosError?.response?.status
+  const bizCode = axiosError?.response?.data?.code
+  const bizMessage = axiosError?.response?.data?.message
+  if (status !== undefined) {
+    return new WechatApiError(
+      `微信支付接口调用失败: ${bizMessage ?? axiosError?.message ?? '未知错误'} (${status}${bizCode ? `, ${bizCode}` : ''})`,
+      status,
+      bizCode ?? String(status)
+    )
+  }
+  return new WechatApiError(
+    `微信支付请求失败: ${axiosError?.message ?? '未知错误'}${axiosError?.code ? ` (${axiosError.code})` : ''}`,
+    undefined,
+    axiosError?.code ?? 'NETWORK_ERROR'
+  )
+}
+
+/** 包装请求 promise：失败时抛出 WechatApiError */
+export async function unwrapV3<T>(promise: PromiseLike<T>): Promise<T> {
+  try {
+    return await promise
+  } catch (error) {
+    throw toWechatApiError(error)
+  }
+}

package/src/wechat/types.ts

@@ -0,0 +1,223 @@
+/** 微信支付 APIv3 交易状态 */
+export type WechatTradeState =
+  | 'SUCCESS'
+  | 'REFUND'
+  | 'NOTPAY'
+  | 'CLOSED'
+  | 'REVOKED'
+  | 'USERPAYING'
+  | 'PAYERROR'
+
+/** 微信支付 APIv3 退款状态 */
+export type WechatRefundStatus = 'SUCCESS' | 'CLOSED' | 'PROCESSING' | 'ABNORMAL'
+
+export interface WechatPayParams {
+  /** 商户订单号（6-32 位，商户侧唯一） */
+  outTradeNo: string
+  /** 商品描述 */
+  description: string
+  /** 订单金额（单位：分） */
+  amount: WechatOrderAmount
+  /** 支付者 openid（jsapi / 小程序支付必填） */
+  openid?: string
+  /** 附加数据，回调时原样返回 */
+  attach?: string
+  /** 优惠标记 */
+  goodsTag?: string
+  /** 订单过期时间（RFC 3339，如 2018-06-08T10:34:56+08:00） */
+  timeExpire?: string
+}
+
+/** H5 支付参数（额外要求支付者 IP） */
+export interface WechatH5PayParams extends WechatPayParams {
+  /** 用户客户端 IP */
+  payerClientIp: string
+  /** 场景信息 */
+  sceneInfo?: {
+    payerClientIp?: string
+    deviceType?: string
+  }
+}
+
+/** JSAPI / 小程序调起支付所需参数（wx.requestPayment / WeixinJSBridge） */
+export interface WechatJsapiPayResult {
+  appId: string
+  timeStamp: string
+  nonceStr: string
+  package: string
+  signType: 'RSA'
+  paySign: string
+}
+
+/** APP 调起支付所需参数（与 JSAPI 同构） */
+export interface WechatAppPayResult extends WechatJsapiPayResult {}
+
+/** Native 下单结果：二维码链接 */
+export interface WechatNativePayResult {
+  codeUrl: string
+}
+
+/** H5 下单结果：收银台跳转链接 */
+export interface WechatH5PayResult {
+  h5Url: string
+}
+
+/** 交易查询参数（outTradeNo 与 transactionId 二选一） */
+export interface WechatQueryParams {
+  outTradeNo?: string
+  transactionId?: string
+}
+
+/** 交易查询结果（snake_case 已映射为 camelCase） */
+export interface WechatQueryResult {
+  appid: string
+  mchid: string
+  outTradeNo: string
+  transactionId: string
+  tradeType?: string
+  tradeState: WechatTradeState
+  tradeStateDesc?: string
+  bankType?: string
+  attach?: string
+  successTime?: string
+  /** 订单总金额（分） */
+  total: number
+  /** 用户实付金额（分） */
+  payerTotal?: number
+}
+
+/** 退款金额 */
+export interface WechatRefundParams {
+  outTradeNo?: string
+  transactionId?: string
+  /** 商户退款单号（商户侧唯一） */
+  outRefundNo: string
+  /** 退款金额（单位：分） */
+  amount: WechatRefundAmount
+  /** 退款原因 */
+  reason?: string
+  /** 退款结果回调地址 */
+  notifyUrl?: string
+  /** 退款资金来源：AVAILABLE（可用余额）| UNSETTLED（待结算资金），默认 AVAILABLE */
+  fundsAccount?: 'AVAILABLE' | 'UNSETTLED'
+}
+
+/** 退款申请结果 */
+export interface WechatRefundResult {
+  refundId: string
+  outRefundNo: string
+  outTradeNo: string
+  transactionId: string
+  status: WechatRefundStatus
+  /** 退款金额（分） */
+  refundAmount: number
+  /** 订单总金额（分） */
+  total: number
+  /** 退款入账账户金额（分） */
+  userReceivedAmount?: number
+  successTime?: string
+  reason?: string
+}
+
+/** 退款查询参数（outRefundNo 与 refundId 二选一） */
+export interface WechatRefundQueryParams {
+  outRefundNo?: string
+  refundId?: string
+}
+
+/** 异步通知报文 resource 字段（AES-256-GCM 加密） */
+export interface WechatNotifyResource {
+  originalType?: string
+  algorithm?: string
+  ciphertext: string
+  associatedData?: string
+  nonce: string
+}
+
+/** 异步通知验签所需的 HTTP 头 */
+export interface WechatNotifyHeaders {
+  /** Wechatpay-Timestamp */
+  timestamp: string
+  /** Wechatpay-Nonce */
+  nonce: string
+  /** Wechatpay-Serial（平台证书序列号 / 微信支付公钥 ID） */
+  serial: string
+  /** Wechatpay-Signature */
+  signature: string
+}
+
+/** 解密后的支付成功/状态变更通知 */
+export interface WechatNotifyTransaction {
+  mchid: string
+  appid: string
+  outTradeNo: string
+  transactionId: string
+  tradeType?: string
+  tradeState: WechatTradeState
+  tradeStateDesc?: string
+  bankType?: string
+  attach?: string
+  successTime?: string
+  amount: {
+    total: number
+    payerTotal?: number
+    currency?: string
+    payerCurrency?: string
+  }
+}
+
+/** 解密后的退款结果通知 */
+export interface WechatNotifyRefund {
+  mchid: string
+  outTradeNo: string
+  transactionId: string
+  outRefundNo: string
+  refundId: string
+  refundStatus: WechatRefundStatus
+  successTime?: string
+  amount: {
+    total: number
+    refund: number
+    payerTotal?: number
+    userReceivedAmount?: number
+    currency?: string
+  }
+  userAccount?: string
+}
+
+/** 微信支付客户端配置 */
+export interface WechatClientOptions {
+  /** 商户号 */
+  mchid: string
+  /** 商户 API 证书序列号 */
+  serial: string
+  /** 商户 API 私钥（PEM 字符串） */
+  privateKey: string
+  /** 平台证书 / 微信支付公钥，{序列号(或公钥ID): PEM} 映射；通知验签按 Wechatpay-Serial 查找 */
+  certs: Record<string, string>
+  /** 应用 ID（公众号 / 小程序 / APP），用于下单与调起签名 */
+  appid: string
+  /** APIv3 密钥（32 字节，回调解密用） */
+  apiv3Key: string
+  /** 异步通知地址（下单时可被 params.notifyUrl 覆盖） */
+  notifyUrl?: string
+  /** 请求超时（毫秒） */
+  timeout?: number
+}
+
+/** 订单金额（单位：分） */
+export interface WechatOrderAmount {
+  /** 订单总金额（分） */
+  total: number
+  /** 币种，默认 CNY */
+  currency?: string
+}
+
+/** 退款金额（单位：分） */
+export interface WechatRefundAmount {
+  /** 退款金额（分） */
+  refund: number
+  /** 原订单金额（分），分账等场景必填 */
+  total?: number
+  currency?: string
+}