java-10561/docs/WECHAT_PAY_PUBLIC_KEY_CONFIG.md

# 微信支付公钥模式配置指南

## 概述

如果您的后台系统使用了微信支付公钥模式，系统现在支持自动检测并优先使用公钥配置。这种模式比自动证书配置更稳定，不依赖网络下载平台证书。

## 配置步骤

### 1. 获取公钥文件

从微信商户平台下载或获取以下文件：
- 微信支付平台公钥文件（通常以 `.pem` 结尾）
- 公钥ID（一个字符串标识符）

### 2. 放置公钥文件

将公钥文件放置到对应租户的证书目录：

```
src/main/resources/dev/wechat/{tenantId}/
├── apiclient_key.pem          # 商户私钥（必需）
├── apiclient_cert.pem         # 商户证书（可选）
└── wechatpay_public_key.pem   # 微信支付平台公钥（新增）
```

例如，租户ID为10547的目录结构：
```
src/main/resources/dev/wechat/10547/
├── apiclient_key.pem
├── apiclient_cert.pem
└── wechatpay_public_key.pem
```

### 3. 数据库配置

在 `sys_payment` 表中配置公钥相关字段：

```sql
UPDATE sys_payment SET 
  pub_key = 'wechatpay_public_key.pem',
  pub_key_id = 'YOUR_PUBLIC_KEY_ID'
WHERE tenant_id = 10547 AND type = 0;
```

**字段说明**：
- `pub_key`: 公钥文件名
- `pub_key_id`: 微信支付平台提供的公钥ID

### 4. 验证配置

运行测试来验证配置是否正确：

```bash
# 运行公钥配置测试
mvn test -Dtest=WechatPayPublicKeyTest#testPublicKeyConfiguration
```

## 配置优先级

系统会按以下优先级选择配置方式：

1. **RSA公钥配置**（最高优先级）
   - 条件：数据库中配置了 `pub_key` 和 `pub_key_id`
   - 优势：稳定、不依赖网络、配置简单

2. **RSA自动证书配置**
   - 条件：公钥配置不可用时
   - 优势：自动管理平台证书
   - 劣势：依赖网络连接和商户平台API安全设置

3. **RSA手动证书配置**（回退方案）
   - 条件：自动配置失败时
   - 需要：商户证书文件

## 示例配置

### 开发环境示例

**目录结构**：
```
src/main/resources/dev/wechat/10547/
├── apiclient_key.pem
├── apiclient_cert.pem
└── wechatpay_public_key.pem
```

**数据库配置**：
```sql
-- 查看当前配置
SELECT id, tenant_id, mch_id, app_id, merchant_serial_number, 
       pub_key, pub_key_id, api_key
FROM sys_payment 
WHERE tenant_id = 10547 AND type = 0;

-- 更新公钥配置
UPDATE sys_payment SET 
  pub_key = 'wechatpay_public_key.pem',
  pub_key_id = 'PUB_KEY_ID_0112422897022025011300326200001208'
WHERE tenant_id = 10547 AND type = 0;
```

### 生产环境示例

**证书文件路径**：
```
/www/wwwroot/file.ws/file/wechat/10547/
├── apiclient_key.pem
├── apiclient_cert.pem
└── wechatpay_public_key.pem
```

**数据库配置**：
```sql
UPDATE sys_payment SET 
  apiclient_key = '/wechat/10547/apiclient_key.pem',
  apiclient_cert = '/wechat/10547/apiclient_cert.pem',
  pub_key = '/wechat/10547/wechatpay_public_key.pem',
  pub_key_id = 'PUB_KEY_ID_0112422897022025011300326200001208'
WHERE tenant_id = 10547 AND type = 0;
```

## 日志输出

配置成功后，您会在日志中看到：

```
=== 检测到公钥配置，使用RSA公钥模式 ===
公钥文件: wechatpay_public_key.pem
公钥ID: PUB_KEY_ID_0112422897022025011300326200001208
公钥文件路径: /path/to/wechatpay_public_key.pem
✅ 开发环境RSA公钥配置成功
```

如果没有公钥配置，系统会尝试自动证书配置：

```
=== 尝试创建自动证书配置 ===
商户号: 1723321338
私钥路径: /path/to/apiclient_key.pem
序列号: 2B933F7C35014A1C363642623E4A62364B34C4EB
API密钥长度: 32
```

## 故障排除

### 1. 公钥文件不存在

**错误信息**：
```
❌ 公钥文件不存在: dev/wechat/10547/wechatpay_public_key.pem
```

**解决方案**：
- 检查文件路径是否正确
- 确认文件已放置在正确位置
- 验证文件名与数据库配置一致

### 2. 公钥ID错误

**错误信息**：
```
❌ RSA公钥配置失败: Invalid public key ID
```

**解决方案**：
- 检查公钥ID是否正确
- 确认公钥ID与公钥文件匹配
- 联系微信支付技术支持获取正确的公钥ID

### 3. 数据库配置缺失

**现象**：系统跳过公钥配置，直接尝试自动证书配置

**解决方案**：
```sql
-- 检查当前配置
SELECT pub_key, pub_key_id FROM sys_payment WHERE tenant_id = 10547 AND type = 0;

-- 如果字段为空，进行配置
UPDATE sys_payment SET 
  pub_key = 'wechatpay_public_key.pem',
  pub_key_id = 'YOUR_PUBLIC_KEY_ID'
WHERE tenant_id = 10547 AND type = 0;
```

## 优势对比

| 配置方式 | 稳定性 | 网络依赖 | 配置复杂度 | 推荐度 |
|---------|--------|----------|------------|--------|
| RSA公钥配置 | 高 | 无 | 低 | ⭐⭐⭐⭐⭐ |
| RSA自动证书配置 | 中 | 高 | 低 | ⭐⭐⭐ |
| RSA手动证书配置 | 中 | 无 | 高 | ⭐⭐ |

## 总结

使用公钥模式可以有效避免 `X509Certificate.getSerialNumber() null` 错误，因为它不依赖自动下载平台证书。建议优先使用此配置方式。

如果您已经有公钥文件和公钥ID，按照本指南配置后，系统会自动使用更稳定的公钥模式。