AIGC/demo/PAYMENT_CONFIGURATION_CHECKLIST.md

# 支付功能模块配置清单

## 一、已配置项 ✅

### 1. 支付宝基础配置（开发环境）
- ✅ `alipay.app-id` - 应用ID
- ✅ `alipay.private-key` - 应用私钥
- ✅ `alipay.public-key` - 支付宝公钥
- ✅ `alipay.gateway-url` - 网关地址（沙箱）
- ✅ `alipay.charset` - 字符集（UTF-8）
- ✅ `alipay.sign-type` - 签名方式（RSA2）
- ✅ `alipay.notify-url` - 异步通知地址（当前使用ngrok）
- ✅ `alipay.return-url` - 同步返回地址（当前使用ngrok）

### 2. 后端代码实现
- ✅ 支付宝服务（AlipayService）
- ✅ 支付API控制器（PaymentApiController）
- ✅ 支付服务（PaymentService）
- ✅ 支付数据模型（Payment, PaymentStatus, PaymentMethod）

### 3. 前端代码实现
- ✅ 支付API封装（payments.js）
- ✅ 支付模态框组件（PaymentModal.vue）
- ✅ 订阅页面（Subscription.vue）

---

## 二、需要检查/更新项 ⚠️

### 1. 支付宝回调地址配置

**当前状态：**
- 开发环境使用 ngrok 地址：`https://curtly-aphorismatic-ginger.ngrok-free.dev`

**需要操作：**
- [ ] **如果 ngrok 地址已过期**，需要：
  1. 重新运行 `ngrok http 8080` 获取新地址
  2. 更新 `application-dev.properties` 中的 `alipay.notify-url` 和 `alipay.return-url`
  3. 在支付宝开放平台配置新的回调地址

- [ ] **如果部署到生产环境**，需要：
  1. 使用正式域名替换 ngrok 地址
  2. 确保回调地址是 HTTPS（支付宝要求）
  3. 在支付宝开放平台配置生产环境的回调地址

**配置文件位置：**
```
demo/src/main/resources/application-dev.properties (开发环境)
demo/src/main/resources/application-prod.properties (生产环境)
```

---

### 2. 支付宝开放平台配置

**需要在支付宝开放平台配置：**

- [ ] **应用回调地址**
  - 登录支付宝开放平台：https://open.alipay.com
  - 进入"我的应用" → 选择应用
  - 配置"应用网关"和"回调地址"
  - 添加 `notify-url` 和 `return-url`

- [ ] **公钥配置**
  - 确认应用公钥已上传到支付宝平台
  - 确认支付宝公钥已配置在 `alipay.public-key`

- [ ] **沙箱测试账号**
  - 获取沙箱买家账号和密码
  - 用于测试支付流程

---

### 3. 生产环境配置（如需上线）

**需要配置环境变量或更新配置文件：**

```properties
# 生产环境支付宝配置
alipay.app-id=${ALIPAY_APP_ID}              # 需要在环境变量中配置
alipay.private-key=${ALIPAY_PRIVATE_KEY}    # 需要在环境变量中配置
alipay.public-key=${ALIPAY_PUBLIC_KEY}      # 需要在环境变量中配置
alipay.gateway-url=https://openapi.alipay.com/gateway.do
alipay.notify-url=${ALIPAY_NOTIFY_URL}      # 需要配置正式域名
alipay.return-url=${ALIPAY_RETURN_URL}      # 需要配置正式域名
```

**操作步骤：**
1. [ ] 在服务器环境变量中设置上述变量
2. [ ] 或创建 `application-prod.properties` 并填写实际值
3. [ ] 确保使用正式环境的 APPID 和密钥（不是沙箱）
4. [ ] 确保回调地址使用 HTTPS 协议

---

### 4. PayPal 配置（如果使用）

**当前状态：** PayPal 配置存在但可能需要更新

**需要配置项：**

```properties
# PayPal配置（在 application-dev.properties 或 application-prod.properties）
paypal.client-id=你的PayPal客户端ID
paypal.client-secret=你的PayPal客户端密钥
paypal.mode=sandbox  # 或 live（生产环境）
paypal.return-url=http://yourdomain.com/api/payments/paypal/return
paypal.cancel-url=http://yourdomain.com/api/payments/paypal/cancel
```

**操作步骤：**
1. [ ] 如果使用 PayPal，需要：
   - 在 PayPal 开发者控制台创建应用
   - 获取 Client ID 和 Client Secret
   - 配置回调地址

---

### 5. 数据库表检查

**需要确认以下表已创建：**

- [ ] `payments` 表
- [ ] `orders` 表（支付成功后创建订单）
- [ ] 相关外键和索引

**检查方法：**
```sql
SHOW TABLES LIKE 'payments';
SHOW TABLES LIKE 'orders';
```

---

### 6. 网络安全配置

**回调地址安全要求：**

- [ ] **开发环境：**
  - 确保 ngrok 服务运行
  - 回调地址必须是公网可访问的 HTTPS

- [ ] **生产环境：**
  - 配置 SSL 证书
  - 确保回调地址使用 HTTPS
  - 配置防火墙规则，允许支付宝服务器访问回调接口

---

### 7. 支付测试配置

**测试前需要确认：**

- [ ] 支付宝沙箱账号已配置
- [ ] 沙箱买家账号可用于测试支付
- [ ] 回调地址在支付宝平台已配置
- [ ] 本地或服务器可以接收到支付宝回调

**测试步骤：**
1. [ ] 创建测试支付订单
2. [ ] 使用沙箱账号扫码支付
3. [ ] 验证异步通知是否接收
4. [ ] 验证支付状态是否正确更新

---

## 三、配置优先级

### 🔴 紧急（必须配置）
1. **支付宝回调地址** - 如果 ngrok 地址已过期，需要立即更新
2. **支付宝开放平台回调配置** - 必须配置才能接收支付通知

### 🟡 重要（建议配置）
3. **生产环境配置** - 如需上线必须配置
4. **数据库表检查** - 确保表结构完整

### 🟢 可选（按需配置）
5. **PayPal 配置** - 如果使用 PayPal 支付
6. **支付测试环境** - 用于测试支付功能

---

## 四、快速检查命令

### 检查配置文件是否存在
```bash
# Windows PowerShell
Test-Path demo/src/main/resources/application-dev.properties
Test-Path demo/src/main/resources/application-prod.properties
```

### 检查支付宝配置是否完整
查看配置文件中的以下项是否都已填写：
- `alipay.app-id`
- `alipay.private-key`
- `alipay.public-key`
- `alipay.gateway-url`
- `alipay.notify-url`
- `alipay.return-url`

### 测试回调地址可访问性
```bash
# 测试 notify-url 是否可访问
curl -X POST https://your-notify-url/api/payments/alipay/notify

# 测试 return-url 是否可访问
curl https://your-return-url/api/payments/alipay/return
```

---

## 五、常见问题

### Q1: ngrok 地址已过期怎么办？
**A:** 
1. 重新运行 `ngrok http 8080`
2. 获取新的 HTTPS 地址
3. 更新 `application-dev.properties` 中的回调地址
4. 在支付宝开放平台更新回调地址配置

### Q2: 生产环境如何配置回调地址？
**A:**
1. 使用正式域名（必须是 HTTPS）
2. 在支付宝开放平台配置生产环境回调地址
3. 确保服务器防火墙允许支付宝 IP 访问

### Q3: 如何验证配置是否正确？
**A:**
1. 创建测试支付订单
2. 使用沙箱账号支付
3. 检查日志是否收到支付宝回调
4. 验证支付状态是否正确更新

---

## 六、下一步操作建议

根据当前配置状态，建议按以下顺序操作：

1. ✅ **检查 ngrok 地址是否有效**
   - 如果无效，更新回调地址配置

2. ✅ **验证支付宝开放平台配置**
   - 确认回调地址已在平台配置
   - 确认公钥配置正确

3. ✅ **测试支付流程**
   - 创建测试订单
   - 完成支付测试
   - 验证回调接收

4. ✅ **准备生产环境配置**
   - 配置生产环境变量
   - 申请正式支付宝应用（如需）

---

**最后更新：** 请根据实际部署环境调整上述配置项。