# 微信支付退款配置指南

## 概述

本项目已集成微信支付V3版本的退款功能，支持用户取消订单后自动退款到微信账户。

## 前置条件

1. 已开通微信支付商户号
2. 已获取微信支付API证书
3. 已配置微信支付API密钥

## 配置步骤

### 1. 获取微信支付配置信息

登录 [微信支付商户平台](https://pay.weixin.qq.com/)，获取以下信息：

- **WECHAT_APPID**: 小程序AppID（已有）
- **WECHAT_MCHID**: 商户号
- **WECHAT_SERIAL_NO**: API证书序列号
- **WECHAT_APIV3_KEY**: APIv3密钥
- **WECHAT_PRIVATE_KEY**: API证书私钥内容

### 2. 下载API证书

1. 进入 **账户中心 > API安全 > 申请API证书**
2. 下载证书文件（apiclient_key.pem）
3. 复制私钥内容到环境变量

### 3. 配置环境变量

编辑 `apps/server/.env.local` 文件，添加以下配置：

```bash
# 微信支付配置
WECHAT_MCHID=1234567890
WECHAT_SERIAL_NO=3B2XXXXXXXXXXXXXXXXXXXXXXXXX
WECHAT_APIV3_KEY=your_apiv3_key_32_characters
WECHAT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----"
WECHAT_REFUND_NOTIFY_URL=https://your-domain.com/api/payment/wechat/refund-notify
```

**注意事项**：
- `WECHAT_PRIVATE_KEY` 需要包含完整的私钥内容（包括头尾标记）
- 私钥内容可以使用换行符，也可以使用 `\n` 转义
- `WECHAT_REFUND_NOTIFY_URL` 需要替换为实际的域名

### 4. 配置退款回调地址

在微信支付商户平台配置退款通知URL：

1. 进入 **产品中心 > 开发配置**
2. 设置退款通知URL: `https://your-domain.com/api/payment/wechat/refund-notify`

## 功能说明

### 退款流程

1. **用户发起退款**：在订单详情页点击"取消订单"
2. **状态检查**：只有 `pending_confirm`（待确认）和 `pending_checkin`（待入住）状态的订单可退款
3. **调用微信退款API**：系统自动调用微信支付退款接口
4. **更新订单状态**：退款成功后，订单状态变更为 `refunded`
5. **恢复库存**：自动恢复房态库存
6. **记录平台账户**：记录退款支出交易（仅记账）

### 退款时间

- 微信支付退款：1-3个工作日到账
- 退款原路返回至用户微信账户

### 退款重试

如果退款失败，订单会保持 `refunding` 状态，可以通过管理后台手动重试：

```typescript
// 调用重试接口
await refundService.retryRefund(orderId);
```

## 测试模式

如果未配置微信支付参数，系统会自动进入**模拟模式**：

- 退款接口调用会被模拟（仅打印日志）
- 订单状态正常更新
- 库存正常恢复
- 适用于开发和测试环境

## 数据库变更

需要执行以下迁移脚本：

```bash
mysql -u root -p rent_platform < database/migrations/002_add_transaction_id_to_orders.sql
```

该脚本会在 `orders` 表添加 `transaction_id` 字段，用于存储微信支付交易号。

## API文档

### 退款接口

**接口**: `POST /api/orders/:id/refund`

**请求参数**:
```json
{
  "reason": "用户主动取消"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "退款成功，款项将原路返回",
  "data": null
}
```

### 退款重试接口（管理员）

**接口**: `POST /api/admin/orders/:id/retry-refund`

**响应**:
```json
{
  "code": 200,
  "message": "退款重试成功",
  "data": null
}
```

## 常见问题

### 1. 退款失败：签名验证失败

**原因**：私钥配置错误或证书序列号不匹配

**解决**：
- 检查 `WECHAT_PRIVATE_KEY` 是否包含完整内容
- 确认 `WECHAT_SERIAL_NO` 与证书匹配

### 2. 退款失败：商户号不匹配

**原因**：`WECHAT_MCHID` 配置错误

**解决**：登录商户平台确认商户号

### 3. 退款失败：订单缺少交易号

**原因**：订单的 `transaction_id` 字段为空

**解决**：
- 确保支付成功后保存了微信支付交易号
- 检查支付回调逻辑是否正确

## 相关文档

- [微信支付退款API文档](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_5_9.shtml)
- [微信支付开发指引](https://pay.weixin.qq.com/wiki/doc/apiv3/index.shtml)

## 技术支持

如有问题，请联系技术团队或查看微信支付官方文档。