AIGC/demo/ALIPAY_SETUP_GUIDE.md

# 支付宝支付集成准备指南

## 一、必需准备项

### 1. 支付宝商户账号
- **个人开发者**：注册支付宝开放平台账号（https://open.alipay.com）
- **企业用户**：需要营业执照等企业资质，申请企业支付宝账号

### 2. 创建应用并获取配置信息
登录支付宝开放平台后，需要创建应用并获取以下配置：

#### 开发环境（沙箱测试）
- **APPID（应用ID）**：`alipay.app-id`
- **应用私钥（Private Key）**：`alipay.private-key`
- **支付宝公钥（Public Key）**：`alipay.public-key`
- **网关地址**：`https://openapi.alipaydev.com/gateway.do`（沙箱）
- **字符集**：`UTF-8`
- **签名方式**：`RSA2`

#### 生产环境
- **网关地址**：`https://openapi.alipay.com/gateway.do`
- 其他配置同开发环境

### 3. 密钥生成和配置
支付宝使用RSA2签名，需要生成密钥对：

#### 方法1：使用支付宝密钥生成工具
- 下载支付宝官方密钥生成工具
- 生成密钥对（RSA2，2048位）
- 保存私钥（用于配置 `alipay.private-key`）
- 将公钥上传到支付宝开放平台，获取支付宝公钥（用于配置 `alipay.public-key`）

#### 方法2：使用OpenSSL生成
```bash
# 生成私钥
openssl genrsa -out app_private_key.pem 2048

# 生成公钥
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem

# 查看私钥内容（去除头尾，保留中间部分配置到private-key）
cat app_private_key.pem

# 将app_public_key.pem内容上传到支付宝开放平台
```

**重要**：
- 私钥需要去除 `-----BEGIN RSA PRIVATE KEY-----` 和 `-----END RSA PRIVATE KEY-----`
- 私钥和公钥配置在配置文件中时，需要去掉换行符或使用转义

### 4. 配置回调地址
需要配置两个回调地址：

#### 异步通知地址（notify-url）
- 用于接收支付宝的支付结果异步通知
- 必须是公网可访问的HTTPS地址
- 示例：`https://yourdomain.com/api/payments/alipay/notify`
- **注意**：开发环境可以使用ngrok等内网穿透工具

#### 同步返回地址（return-url）
- 用户支付完成后跳转的页面
- 可以是HTTP或HTTPS地址
- 示例：`https://yourdomain.com/api/payments/alipay/return`

### 5. 数据库表准备
项目已经包含了Payment相关表，确保数据库已创建：
- `payments` 表
- `orders` 表

### 6. Maven依赖（已配置）
项目已包含支付宝SDK依赖：
```xml
<dependency>
    <groupId>com.github.javen205</groupId>
    <artifactId>IJPay-AliPay</artifactId>
    <version>2.9.12.1</version>
</dependency>
```

## 二、配置文件设置

### 开发环境配置（application-dev.properties）
```properties
# 支付宝配置 (开发环境 - 沙箱测试)
alipay.app-id=你的沙箱APPID
alipay.private-key=你的应用私钥（去除头尾和换行）
alipay.public-key=支付宝公钥（从开放平台获取）
alipay.gateway-url=https://openapi.alipaydev.com/gateway.do
alipay.charset=UTF-8
alipay.sign-type=RSA2
alipay.notify-url=https://your-ngrok-url.ngrok-free.dev/api/payments/alipay/notify
alipay.return-url=https://your-ngrok-url.ngrok-free.dev/api/payments/alipay/return
```

### 生产环境配置（application-prod.properties）
```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.charset=UTF-8
alipay.sign-type=RSA2
alipay.notify-url=${ALIPAY_NOTIFY_URL}
alipay.return-url=${ALIPAY_RETURN_URL}
```

## 三、测试步骤

### 1. 沙箱测试环境准备
1. 登录支付宝开放平台：https://open.alipay.com
2. 进入"沙箱环境"
3. 获取沙箱APPID
4. 下载"支付宝密钥生成工具"，生成密钥对
5. 上传公钥到支付宝，获取支付宝公钥
6. 配置沙箱测试账号（买家账号和卖家账号）

### 2. 内网穿透配置（开发测试）
如果本地开发，需要使用ngrok等工具暴露本地服务：
```bash
# 安装ngrok
# 启动本地服务（端口8080）
# 使用ngrok暴露
ngrok http 8080
# 获取https地址，配置到notify-url和return-url
```

### 3. 功能测试
- 创建支付订单
- 生成支付宝二维码
- 使用沙箱账号扫码支付
- 验证异步通知接收
- 验证支付状态更新

## 四、已实现的功能

### 后端接口
✅ `POST /api/payments/alipay/create` - 创建支付宝支付并生成二维码
✅ `POST /api/payments/alipay/notify` - 接收支付宝异步通知
✅ `GET /api/payments/alipay/return` - 处理支付宝同步返回

### 前端页面
✅ 支付模态框组件（PaymentModal.vue）
✅ 订阅页面支付集成（Subscription.vue）

### 核心服务
✅ `AlipayService` - 支付宝服务封装
  - `createPayment()` - 创建支付订单
  - `handleNotify()` - 处理异步通知
  - `handleReturn()` - 处理同步返回

## 五、常见问题

### 1. 签名验证失败
- 检查私钥和公钥是否正确配置
- 确认私钥格式正确（去除头尾和换行）
- 确认使用RSA2签名方式

### 2. 回调地址无法访问
- 确保回调地址是公网可访问的HTTPS地址
- 开发环境可以使用ngrok等内网穿透工具
- 检查防火墙和服务器配置

### 3. 沙箱测试账号
- 在支付宝开放平台沙箱环境中获取测试账号
- 使用"沙箱买家"账号进行支付测试
- 注意：沙箱环境有金额限制

### 4. 生产环境上线
- 申请正式应用（需要审核）
- 配置正式环境的APPID和密钥
- 确保回调地址使用正式域名
- 完成商户资质认证

## 六、安全检查

1. **密钥安全**
   - 私钥绝对不能泄露
   - 生产环境使用环境变量或密钥管理服务
   - 不要将密钥提交到代码仓库

2. **回调验证**
   - 所有回调必须验证签名
   - 验证订单金额和状态
   - 防止重复处理

3. **HTTPS要求**
   - 生产环境必须使用HTTPS
   - 回调地址必须是HTTPS

## 七、当前项目状态

✅ 代码已实现
✅ Maven依赖已配置
⚠️ 需要配置支付宝账号和密钥
⚠️ 需要配置回调地址（开发环境可用ngrok）

## 八、快速开始

1. **注册支付宝开放平台账号**
2. **创建应用获取APPID**
3. **生成密钥对并配置**
4. **配置回调地址（开发环境使用ngrok）**
5. **更新application-dev.properties配置文件**
6. **启动项目测试支付功能**

## 九、参考文档

- 支付宝开放平台：https://open.alipay.com
- 支付宝开发者文档：https://opendocs.alipay.com
- IJPay文档：https://github.com/Javen205/IJPay