# 微信小程序支付集成文档

## 概述

本文档总结了套餐订购模块中的微信支付完整实现流程，可复用到其他项目中。

## 一、核心文件结构

```
miniprogram/
├── utils/
│   └── payment.ts          # 微信支付工具类
├── api/
│   └── order.ts            # 订单API接口
├── types/
│   └── api.ts              # API类型定义
└── pages/
    └── package/
        └── package.ts      # 套餐订购页面（业务实现）
```

## 二、支付流程

### 2.1 标准套餐支付流程（三步走）

```
1. 创建订单 → 2. 获取支付参数 → 3. 调起微信支付
```

#### 第一步：创建订单

**接口：** `POST /api/c/v1/orders/create`

**请求参数：**
```typescript
{
  app_type: 'miniapp',              // 应用类型：miniapp(小程序) | official_account(公众号)
  identifier: string,                // 资产标识符（设备ID/ICCID等）
  package_ids: number[]              // 套餐ID列表
}
```

**响应数据：**
```typescript
{
  order_type: 'package' | 'recharge',  // 订单类型
  order: {
    order_id: number,                   // 订单ID（用于后续支付）
    order_no: string,
    payment_status: 1,                  // 1:待支付
    total_amount: number,               // 总金额（分）
    created_at: string
  },
  pay_config?: {...}                    // 强充订单才返回（见2.2）
}
```

#### 第二步：获取支付参数

**接口：** `POST /api/c/v1/orders/:id/pay`

**请求参数：**
```typescript
{
  payment_method: 'wechat',           // 支付方式：wechat | wallet
  app_type: 'miniapp'                 // 应用类型（微信支付必传）
}
```

**响应数据：**
```typescript
{
  payment_method: 'wechat',
  pay_config: {
    app_id: string,          // 微信AppID
    timestamp: string,        // 时间戳
    nonce_str: string,        // 随机字符串
    package: string,          // 预支付ID，格式：prepay_id=wx...
    sign_type: string,        // 签名类型（RSA/MD5/HMAC-SHA256）
    pay_sign: string          // 支付签名
  }
}
```

#### 第三步：调起微信支付

使用 `wx.requestPayment()` 调起支付：

```typescript
wx.requestPayment({
  timeStamp: pay_config.timestamp,
  nonceStr: pay_config.nonce_str,
  package: pay_config.package,
  signType: pay_config.sign_type,
  paySign: pay_config.pay_sign,
  success: (res) => {
    // 支付成功
  },
  fail: (err) => {
    // 支付失败或取消
  }
})
```

### 2.2 强充订单支付流程（一步走）

当订单返回 `order_type === 'recharge'` 且有 `pay_config` 时，表示强充订单：

```
创建订单（直接返回支付参数） → 调起微信支付
```

**特点：**
- 创建订单时已返回完整 `pay_config`
- 无需再调用 `/orders/:id/pay` 接口
- 直接使用返回的 `pay_config` 调起支付

**判断逻辑：**
```typescript
if (orderResult.order_type === 'recharge' && orderResult.pay_config) {
  // 强充订单，直接支付
  await WxPayment.payWithCallback(orderResult.pay_config, callbacks);
} else {
  // 普通订单，需要获取支付参数
  const payResult = await OrderApi.payOrder(orderId, {...});
  await WxPayment.payWithCallback(payResult.pay_config, callbacks);
}
```

## 三、核心代码实现

### 3.1 微信支付工具类（payment.ts）

```typescript
/**
 * 微信支付工具类
 */
import { Logger } from './logger';

/** 微信支付配置 */
export interface WxPayConfig {
  timeStamp: string;
  nonceStr: string;
  package: string;
  signType: 'RSA' | 'MD5' | 'HMAC-SHA256';
  paySign: string;
}

/** 支付结果 */
export interface PaymentResult {
  success: boolean;
  errMsg?: string;
  userCancelled?: boolean;
}

export class WxPayment {
  /**
   * 发起微信支付
   * @param payConfig 后端返回的支付配置
   * @returns 支付结果
   */
  static async pay(payConfig: {
    app_id: string;
    timestamp: string;
    nonce_str: string;
    package: string;
    sign_type: string;
    pay_sign: string;
  }): Promise<PaymentResult> {
    return new Promise((resolve) => {
      // 1. 验证 package 参数格式
      if (!payConfig.package || !payConfig.package.startsWith('prepay_id=')) {
        Logger.error('微信支付参数错误：package 格式不正确', {
          package: payConfig.package,
          expected: 'prepay_id=wx...'
        });
        resolve({
          success: false,
          errMsg: '支付参数获取失败，请稍后重试'
        });
        return;
      }

      Logger.info('发起微信支付', {
        ...payConfig,
        pay_sign: payConfig.pay_sign.substring(0, 10) + '...'  // 脱敏
      });

      // 2. 调用微信支付API
      wx.requestPayment({
        timeStamp: payConfig.timestamp,
        nonceStr: payConfig.nonce_str,
        package: payConfig.package,
        signType: payConfig.sign_type as any,
        paySign: payConfig.pay_sign,
        success: (res) => {
          Logger.info('微信支付成功', res);
          resolve({ success: true });
        },
        fail: (err) => {
          Logger.error('微信支付失败', err);

          // 判断是否为用户取消
          const userCancelled = err.errMsg?.includes('cancel') ||
                               err.errMsg?.includes('用户取消');

          resolve({
            success: false,
            errMsg: err.errMsg,
            userCancelled
          });
        }
      });
    });
  }

  /**
   * 支付并使用回调处理结果
   * @param payConfig 支付配置
   * @param callbacks 回调函数
   */
  static async payWithCallback(
    payConfig: {
      app_id: string;
      timestamp: string;
      nonce_str: string;
      package: string;
      sign_type: string;
      pay_sign: string;
    },
    callbacks?: {
      onSuccess?: () => void;
      onFail?: (errMsg: string) => void;
      onCancel?: () => void;
    }
  ): Promise<PaymentResult> {
    const result = await this.pay(payConfig);

    // 根据结果调用相应回调
    if (result.success) {
      callbacks?.onSuccess?.();
    } else if (result.userCancelled) {
      callbacks?.onCancel?.();
    } else {
      callbacks?.onFail?.(result.errMsg || '支付失败');
    }

    return result;
  }
}
```

### 3.2 订单API封装（order.ts）

```typescript
import { Request } from '../utils/request';
import type {
  CreateOrderRequest,
  CreateOrderResponse,
  PayOrderRequest,
  PayOrderResponse
} from '../types/api';

export class OrderApi {
  /**
   * 创建订单
   * POST /api/c/v1/orders/create
   */
  static async createOrder(data: CreateOrderRequest): Promise<CreateOrderResponse> {
    return Request.post<CreateOrderResponse>(
      '/api/c/v1/orders/create',
      data
    );
  }

  /**
   * 订单支付
   * POST /api/c/v1/orders/:id/pay
   */
  static async payOrder(orderId: number, data: PayOrderRequest): Promise<PayOrderResponse> {
    return Request.post<PayOrderResponse>(
      `/api/c/v1/orders/${orderId}/pay`,
      data
    );
  }
}
```

### 3.3 业务层实现示例（package.ts）

```typescript
import { OrderApi } from '../../api/order';
import { WxPayment } from '../../utils/payment';
import { Logger } from '../../utils/logger';

/**
 * 创建订单并支付（微信支付）
 */
async createOrderAndPay() {
  try {
    const selectedPackage = this.data.packages[this.data.selectedIdx];

    // 第一步：创建订单
    wx.showLoading({ title: '创建订单...', mask: true });

    const orderResult = await OrderApi.createOrder({
      app_type: 'miniapp',
      identifier: this.getIdentifier(),
      package_ids: [selectedPackage.package_id]
    });

    // 判断是否为强充订单
    if (orderResult.order_type === 'recharge' && orderResult.pay_config) {
      // 强充订单：直接使用返回的 pay_config 支付

      // 验证 pay_config 有效性
      if (!orderResult.pay_config.package) {
        Logger.error('强充订单支付配置无效', {
          recharge_id: orderResult.recharge?.recharge_id
        });
        wx.hideLoading();
        wx.showToast({ title: '支付参数获取失败', icon: 'none' });
        return;
      }

      wx.hideLoading();
      this.closeModal();

      // 调起支付
      await WxPayment.payWithCallback(
        orderResult.pay_config,
        {
          onSuccess: () => {
            this.handlePaySuccess();
          },
          onFail: (errMsg) => {
            wx.showToast({ title: '支付失败', icon: 'none' });
          },
          onCancel: () => {
            wx.showToast({ title: '已取消支付', icon: 'none' });
          }
        }
      );
      return;
    }

    // 普通套餐订单：需要获取支付参数
    const orderId = orderResult.order.order_id;

    // 第二步：获取支付参数
    wx.showLoading({ title: '准备支付...', mask: true });

    const payResult = await OrderApi.payOrder(orderId, {
      payment_method: 'wechat',
      app_type: 'miniapp'
    });

    Logger.info('订单支付接口返回:', {
      order_id: orderId,
      has_pay_config: !!payResult.pay_config
    });

    wx.hideLoading();
    this.closeModal();

    // 验证 pay_config
    if (!payResult.pay_config || !payResult.pay_config.package) {
      Logger.error('订单支付接口返回配置无效', {
        order_id: orderId
      });
      wx.showToast({ title: '支付参数获取失败', icon: 'none' });
      return;
    }

    // 第三步：调起微信支付
    await WxPayment.payWithCallback(
      payResult.pay_config,
      {
        onSuccess: () => {
          this.handlePaySuccess();
        },
        onFail: (errMsg) => {
          wx.showToast({ title: '支付失败', icon: 'none' });
        },
        onCancel: () => {
          wx.showToast({ title: '已取消支付', icon: 'none' });
        }
      }
    );

  } catch (error: any) {
    wx.hideLoading();
    this.closeModal();

    Logger.error('创建订单或支付失败:', error);

    // 特殊错误处理：订单正在创建中
    if (error.code === 1008) {
      wx.showModal({
        title: '提示',
        content: '订单正在创建中，是否跳转到我的订单页面进行支付？',
        confirmText: '去支付',
        success: (res) => {
          if (res.confirm) {
            wx.navigateTo({ url: '/pages/orders/orders' });
          }
        }
      });
      return;
    }

    // 其他错误提示
    const errorMsg = error.message || error.msg || '操作失败，请稍后重试';
    wx.showToast({ title: errorMsg, icon: 'none' });
  }
}

/**
 * 支付成功处理
 */
handlePaySuccess() {
  const pkg = this.data.packages[this.data.selectedIdx];
  this.setData({ selectedIdx: -1 });
  wx.showToast({
    title: `「${pkg.name}」支付成功`,
    icon: 'success'
  });
  // 可选：刷新数据、跳转页面等
}
```

## 四、类型定义（api.ts）

```typescript
/** 创建订单 - 请求 */
export interface CreateOrderRequest {
  app_type?: 'official_account' | 'miniapp';  // 应用类型（强充必传）
  identifier: string;                          // 资产标识符
  package_ids: number[];                       // 套餐ID列表
}

/** 创建订单 - 响应 */
export interface CreateOrderResponse {
  order_type: 'package' | 'recharge';  // 订单类型
  order: {
    order_id: number;
    order_no: string;
    payment_status: 1 | 2 | 3 | 4;     // 1:待支付 2:已支付 3:已取消 4:已退款
    total_amount: number;               // 总金额（分）
    created_at: string;
  };
  pay_config?: {                        // 强充订单才返回
    app_id: string;
    timestamp: string;
    nonce_str: string;
    package: string;                    // prepay_id=wx...
    sign_type: string;
    pay_sign: string;
  } | null;
  recharge?: {                          // 充值订单信息
    recharge_id: number;
    recharge_no: string;
    amount: number;
    status: 0 | 1 | 2;                  // 0:待支付 1:已支付 2:已关闭
    auto_purchase_status: string;
  };
  linked_package_info?: {               // 强充关联套餐信息
    package_names: string[];
    total_package_amount: number;
    wallet_credit: number;
    force_recharge_amount: number;
  };
}

/** 订单支付 - 请求 */
export interface PayOrderRequest {
  payment_method: 'wallet' | 'wechat';  // 支付方式
  app_type?: 'official_account' | 'miniapp';  // 微信支付必传
  password?: string;                    // 钱包支付必传
}

/** 订单支付 - 响应 */
export interface PayOrderResponse {
  payment_method: 'wallet' | 'wechat';
  pay_config?: {                        // 微信支付时返回
    app_id: string;
    timestamp: string;
    nonce_str: string;
    package: string;
    sign_type: string;
    pay_sign: string;
  };
}
```

## 五、关键要点

### 5.1 支付参数验证

**必须验证 `package` 参数格式：**
```typescript
if (!payConfig.package || !payConfig.package.startsWith('prepay_id=')) {
  // 参数无效，停止支付
  return;
}
```

### 5.2 支付结果判断

```typescript
// 成功
success: (res) => { /* 支付成功 */ }

// 失败/取消
fail: (err) => {
  // 判断是否用户取消
  const userCancelled = err.errMsg?.includes('cancel') ||
                       err.errMsg?.includes('用户取消');

  if (userCancelled) {
    // 用户主动取消
  } else {
    // 支付失败
  }
}
```

### 5.3 错误处理

1. **参数验证失败** - 提示用户并停止支付
2. **用户取消支付** - 友好提示，不作为错误
3. **支付失败** - 提示错误信息
4. **订单创建中（1008）** - 引导用户到订单页

### 5.4 日志记录

关键节点必须记录日志：
- 支付参数（脱敏）
- 支付成功/失败
- 参数验证失败
- 异常情况

```typescript
Logger.info('发起微信支付', {
  ...payConfig,
  pay_sign: payConfig.pay_sign.substring(0, 10) + '...'  // 脱敏
});
```

### 5.5 Loading状态管理

```typescript
// 创建订单前
wx.showLoading({ title: '创建订单...', mask: true });

// 获取支付参数前
wx.showLoading({ title: '准备支付...', mask: true });

// 调起支付前
wx.hideLoading();  // 必须关闭，否则遮挡支付界面
```

## 六、常见问题

### Q1: 为什么有两种支付流程？

**A:**
- **标准流程（三步）**：普通套餐订购
- **快捷流程（一步）**：强充订单，后端已预创建支付参数

### Q2: package 参数为什么要验证？

**A:** 后端可能返回空值或格式错误，直接传给微信会导致支付崩溃。必须验证格式为 `prepay_id=wx...`

### Q3: 如何区分用户取消和支付失败？

**A:** 检查 `errMsg` 是否包含 `'cancel'` 或 `'用户取消'` 关键字。

### Q4: 为什么调起支付前要 hideLoading？

**A:** Loading 遮罩会挡住微信支付界面，导致用户无法操作。

## 七、快速集成清单

要在新项目中集成微信支付，需要：

- [ ] 复制 `utils/payment.ts` 工具类
- [ ] 创建订单API接口（`createOrder`、`payOrder`）
- [ ] 定义类型文件（`api.ts`）
- [ ] 实现业务逻辑（参考 `createOrderAndPay`）
- [ ] 添加 Logger 日志工具（可选）
- [ ] 处理支付回调（成功、失败、取消）
- [ ] 添加错误处理逻辑

## 八、注意事项

1. **安全性**
   - 日志中敏感信息（pay_sign）要脱敏
   - 永远不要在前端生成支付签名
   - 所有支付参数由后端返回

2. **用户体验**
   - 支付过程中显示 Loading 提示
   - 调起支付前必须关闭 Loading
   - 区分取消和失败，给出不同提示
   - 支付失败时保留订单，允许用户重试

3. **异常处理**
   - 参数验证失败时友好提示
   - 网络错误时允许重试
   - 订单创建中（1008）引导到订单页
   - 所有异常都要记录日志

4. **测试要点**
   - 正常支付流程
   - 用户取消支付
   - 网络异常
   - 参数异常
   - 强充订单流程
   - 普通订单流程

---

**文档版本：** v1.0
**更新日期：** 2026-04-14
**适用范围：** 微信小程序支付