# 微信支付配置说明

## 环境变量配置

在 `apps/server/.env.local` 文件中添加以下配置：

```env
# 微信小程序配置
WECHAT_APPID=你的小程序AppID
WECHAT_SECRET=你的小程序AppSecret

# 微信支付配置
WECHAT_MCHID=你的商户号
WECHAT_SERIAL_NO=你的API证书序列号
WECHAT_APIV3_KEY=你的APIv3密钥

# 微信支付私钥（需要转义换行符）
WECHAT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n你的私钥内容\n-----END PRIVATE KEY-----"

# 支付回调地址（需要配置为外网可访问的地址）
WECHAT_PAY_NOTIFY_URL=https://你的域名/api/app/payment/wechat/notify

# API基础地址
API_BASE_URL=https://你的域名
```

## 获取微信支付配置参数

### 1. 获取商户号 (WECHAT_MCHID)
- 登录微信支付商户平台：https://pay.weixin.qq.com
- 在"账户中心" -> "商户信息"中查看商户号

### 2. 获取API证书序列号 (WECHAT_SERIAL_NO)
- 在微信支付商户平台，进入"账户中心" -> "API安全"
- 下载API证书（apiclient_cert.pem）
- 使用以下命令查看证书序列号：
  ```bash
  openssl x509 -in apiclient_cert.pem -noout -serial
  ```

### 3. 获取APIv3密钥 (WECHAT_APIV3_KEY)
- 在微信支付商户平台，进入"账户中心" -> "API安全"
- 设置APIv3密钥（32位字符串）

### 4. 获取API私钥 (WECHAT_PRIVATE_KEY)
- 下载API证书后，会得到 `apiclient_key.pem` 文件
- 将文件内容复制到环境变量中，注意：
  - 需要将换行符替换为 `\n`
  - 整个内容用双引号包裹
  - 示例：`"-----BEGIN PRIVATE KEY-----\nMIIEvQI...\n-----END PRIVATE KEY-----"`

## 配置支付回调地址

### 1. 在微信支付商户平台配置
- 登录微信支付商户平台
- 进入"产品中心" -> "开发配置"
- 配置"JSAPI支付"回调地址：`https://你的域名/api/app/payment/wechat/notify`

### 2. 确保回调地址可访问
- 回调地址必须是外网可访问的HTTPS地址
- 本地开发可以使用内网穿透工具（如ngrok、frp）

## 小程序端使用

在小程序页面中调用支付：

```typescript
import { wxPay } from '@/api/user/order';

// 创建订单后调用支付
async function handlePay(orderNo: string) {
  try {
    uni.showLoading({ title: '正在支付...' });
    
    await wxPay(orderNo);
    
    uni.hideLoading();
    uni.showToast({ title: '支付成功', icon: 'success' });
    
    // 跳转到订单详情或订单列表
    uni.navigateTo({ url: `/pages/order/detail?orderNo=${orderNo}` });
  } catch (error) {
    uni.hideLoading();
    uni.showToast({ 
      title: error.message || '支付失败', 
      icon: 'none' 
    });
  }
}
```

## 支付流程

1. **用户创建订单**：调用 `POST /api/app/orders` 创建订单，订单状态为 `pending_pay`
2. **发起支付**：调用 `POST /api/app/orders/pay`，后端调用微信支付统一下单接口
3. **小程序调起支付**：使用返回的支付参数调用 `uni.requestPayment`
4. **支付回调**：微信支付成功后回调 `POST /api/app/payment/wechat/notify`
5. **更新订单状态**：后端验证签名后更新订单状态为 `pending_confirm`

## 注意事项

1. **证书安全**：
   - 不要将私钥提交到代码仓库
   - 使用 `.env.local` 文件存储敏感信息
   - `.env.local` 应该在 `.gitignore` 中

2. **回调验证**：
   - 后端会自动验证微信支付回调的签名
   - 确保回调地址配置正确且可访问

3. **订单幂等性**：
   - 支付回调可能会重复通知
   - 代码已处理订单状态判断，避免重复处理

4. **测试环境**：
   - 微信支付需要使用真实的商户号和证书
   - 可以使用微信支付的沙箱环境进行测试

## 退款功能

退款功能已集成在 `WechatPayService` 中，可以通过以下方式调用：

```typescript
await this.wechatPayService.refund({
  orderNo: '订单号',
  refundNo: '退款单号',
  totalAmount: 100, // 订单总金额（元）
  refundAmount: 100, // 退款金额（元）
  reason: '退款原因',
  notifyUrl: '退款回调地址（可选）',
});
```

退款回调地址：`POST /api/app/payment/wechat/refund-notify`