Kamixitong/docs/alipay_configuration_guide.md

# 支付宝支付功能配置完整指南

## 概述

本文档详细介绍了如何在本系统中配置和使用支付宝支付功能。系统支持PC网站支付和手机网站支付，支付成功后会自动生成相应的许可证。

## 功能特性

- ✅ 支持PC网站支付（电脑端）
- ✅ 支持手机网站支付（移动端）
- ✅ 支付成功后自动生成许可证
- ✅ 异步通知处理，确保支付状态准确
- ✅ 订单状态实时查询
- ✅ 完整的支付结果页面

## 配置前提

在开始配置支付宝支付功能之前，请确保：

1. 已经申请了支付宝商户账号
2. 在支付宝开放平台创建了应用
3. 获取了必要的应用凭证信息
4. 系统已经正确部署并可以访问

## 第一步：获取支付宝应用信息

### 1. 登录支付宝开放平台

访问 [支付宝开放平台](https://open.alipay.com/) 并使用您的商户账号登录。

### 2. 创建应用

如果您还没有创建应用，请按照以下步骤操作：

1. 在控制台点击"创建应用"
2. 选择应用类型为"网站支付"
3. 填写应用基本信息：
   - 应用名称
   - 应用英文名称
   - 应用类型（选择"网站支付"）
   - 授权回调地址（可暂时填写占位符，后续会配置）

### 3. 获取必要信息

创建应用后，您需要获取以下信息：

- **APP_ID（应用ID）**：应用的唯一标识
- **应用私钥（APP_PRIVATE_KEY）**：由您自己生成的私钥
- **应用公钥（APP_PUBLIC_KEY）**：与私钥配对的公钥，需要上传到支付宝平台
- **支付宝公钥（ALIPAY_PUBLIC_KEY）**：支付宝平台提供的公钥，用于验证支付宝返回的数据

### 4. 生成密钥对

您可以使用支付宝官方工具或 OpenSSL 生成 RSA2 密钥对：

#### 使用 OpenSSL 生成密钥对

```bash
# 生成私钥
openssl genrsa -out app_private_key.pem 2048

# 从私钥导出公钥
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem

# 查看私钥内容（需要去除换行符）
cat app_private_key.pem | tr '\n' '#'

# 查看公钥内容（需要去除换行符）
cat app_public_key.pem | tr '\n' '#'
```

将获取到的密钥内容按如下格式整理：

**应用私钥格式：**
```
-----BEGIN PRIVATE KEY-----
你的私钥内容...
-----END PRIVATE KEY-----
```

**应用公钥格式：**
```
-----BEGIN PUBLIC KEY-----
你的公钥内容...
-----END PUBLIC KEY-----
```

## 第二步：配置支付宝参数

系统提供了两种方式来配置支付宝参数：

### 方式一：通过后台管理界面配置（推荐）

1. 登录后台管理系统
2. 导航到"系统设置"页面
3. 找到"支付配置"区块
4. 启用支付功能开关
5. 填写以下支付宝配置信息：
   - **支付宝应用ID (APP_ID)**：从支付宝开放平台获取的应用ID
   - **应用私钥**：您生成的应用私钥（完整PEM格式）
   - **支付宝公钥**：您生成的应用公钥（完整PEM格式）
   - **支付宝平台公钥**：从支付宝开放平台获取的支付宝公钥（完整PEM格式）
   - **异步通知URL**：支付宝异步通知地址，格式为：`https://你的域名/api/v1/pay/alipay/notify`
   - **同步返回URL**：支付完成后的返回地址，格式为：`https://你的域名/payment/result`
   - **支付宝网关地址**：
     - 正式环境：`https://openapi.alipay.com/gateway.do`
     - 沙箱环境：`https://openapi.alipaydev.com/gateway.do`
   - **支付超时时间**：建议设置为30分钟（可调整5-120分钟）
6. 点击"测试支付宝配置"验证参数
7. 点击"保存设置"

### 方式二：通过环境变量配置

在生产环境中，建议通过环境变量配置支付宝参数以提高安全性：

```bash
export PAYMENT_ENABLED=true
export ALIPAY_APP_ID="your_app_id"
export ALIPAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nyour_private_key_content\n-----END PRIVATE KEY-----"
export ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nyour_public_key_content\n-----END PUBLIC KEY-----"
export ALIPAY_ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nalipay_public_key_content\n-----END PUBLIC KEY-----"
export ALIPAY_GATEWAY="https://openapi.alipay.com/gateway.do"
export ALIPAY_NOTIFY_URL="https://your-domain.com/api/v1/pay/alipay/notify"
export ALIPAY_RETURN_URL="https://your-domain.com/payment/result"
export ALIPAY_TIMEOUT_EXPRESS=30
```

或者在 `.env` 文件中配置：

```env
# 是否启用支付功能
PAYMENT_ENABLED=true

# 支付宝配置
ALIPAY_APP_ID=your_app_id
ALIPAY_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----
your_private_key_content
-----END PRIVATE KEY-----
ALIPAY_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----
your_public_key_content
-----END PUBLIC KEY-----
ALIPAY_ALIPAY_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----
alipay_public_key_content
-----END PUBLIC KEY-----

# 支付宝网关地址
ALIPAY_GATEWAY=https://openapi.alipay.com/gateway.do

# 异步通知URL
ALIPAY_NOTIFY_URL=https://your-domain.com/api/v1/pay/alipay/notify

# 同步返回URL
ALIPAY_RETURN_URL=https://your-domain.com/payment/result

# 支付超时时间（分钟）
ALIPAY_TIMEOUT_EXPRESS=30
```

## 第三步：配置异步通知和同步返回地址

### 异步通知URL

这是支付宝在用户支付完成后主动通知您的系统的地址。支付宝会向该地址发送POST请求，通知支付结果。

URL格式：`https://你的域名/api/v1/pay/alipay/notify`

### 同步返回URL

这是用户支付完成后，支付宝浏览器会跳转到的页面地址。

URL格式：`https://你的域名/payment/result`

## 第四步：测试支付宝配置

### 1. 测试配置参数

在后台管理界面点击"测试支付宝配置"按钮，系统会验证您输入的配置参数是否正确。

### 2. 测试支付功能

在后台管理界面点击"测试支付功能"按钮，系统会创建一个测试订单并生成支付链接，您可以点击链接进行支付测试。

## 第五步：上线生产环境

当您在测试环境中确认支付宝支付功能正常工作后，可以将其部署到生产环境：

1. 将支付宝网关地址改为正式环境地址：`https://openapi.alipay.com/gateway.do`
2. 使用正式环境的APP_ID和密钥
3. 配置正确的异步通知URL和返回URL
4. 确保您的网站已启用HTTPS
5. 再次测试支付功能
6. 确认无误后正式启用支付功能

## 支付流程说明

```
用户选择产品 → 创建订单 → 创建支付链接 → 跳转到支付宝 → 支付完成
                                                               ↓
生成许可证 ← 更新订单状态 ← 支付宝异步通知 ← ← ← ← ← ← ← ← ← ← ← ← ← ←
```

## 重要说明

### 异步通知处理

支付宝异步通知是支付状态更新的主要方式，系统会：

- 验证通知的签名
- 检查订单状态
- 更新订单状态为"已支付"
- 自动生成许可证
- 记录操作日志

### 支付链接生成

根据客户端类型自动选择支付方式：

- PC端：使用 `alipay.trade.page.pay` 接口
- 移动端：使用 `alipay.trade.wap.pay` 接口

### 许可证生成

支付成功后系统会自动：

- 查询订单信息
- 根据套餐配置生成许可证
- 设置有效期和最大设备数
- 保存许可证到数据库

## 常见问题和解决方案

### 1. 支付链接无法打开

**可能原因：**
- 支付宝配置错误
- 订单状态不正确
- 支付金额格式错误

**解决方法：**
- 检查支付宝配置
- 确认订单状态为"待支付"
- 检查订单金额是否为有效数字

### 2. 支付成功但订单状态未更新

**可能原因：**
- 异步通知未收到
- 异步通知处理失败

**解决方法：**
- 查看日志文件，检查异步通知记录
- 可以通过订单查询接口手动检查状态
- 联系支付宝客服查询支付记录

### 3. 许可证未生成

**可能原因：**
- 许可证生成逻辑出错
- 数据库连接异常

**解决方法：**
- 查看日志文件中的错误信息
- 检查数据库连接
- 手动重新触发许可证生成（需要管理员操作）

## 安全建议

1. **生产环境配置**
   - 使用HTTPS协议
   - 设置 `SESSION_COOKIE_SECURE=True`
   - 定期更换密钥

2. **签名验证**
   - 系统会自动验证支付宝通知签名
   - 签名验证失败的通知会被拒绝

3. **订单金额验证**
   - 系统会验证通知中的金额与订单金额一致
   - 不匹配的订单会被拒绝

## 技术支持

如有技术问题，请：

1. 查看日志文件：`logs/kamaxitong.log`
2. 检查支付宝配置是否正确
3. 确认网络连接和防火墙设置
4. 联系开发团队

## 附录：API接口说明

### 1. 创建订单

**接口：** `POST /api/v1/user/orders`

**请求参数：**
```json
{
    "product_id": "产品ID",
    "package_id": "套餐ID",
    "contact_person": "联系人姓名",
    "phone": "手机号",
    "quantity": 1
}
```

**响应示例：**
```json
{
    "success": true,
    "message": "订单创建成功",
    "data": {
        "order_number": "ORD123456789",
        "amount": 99.00
    }
}
```

### 2. 创建支付宝支付

**接口：** `POST /api/v1/user/pay/alipay`

**请求参数：**
```json
{
    "order_number": "订单号",
    "payment_type": "pc"  // 或 "wap"
}
```

**响应示例：**
```json
{
    "success": true,
    "message": "支付链接创建成功",
    "data": {
        "payment_url": "https://openapi.alipay.com/...",
        "order_number": "ORD123456789",
        "amount": 99.00
    }
}
```

### 3. 查询订单

**接口：** `GET /api/v1/user/orders/query?order_number=订单号&phone=手机号`

**响应示例：**
```json
{
    "success": true,
    "data": {
        "order_number": "ORD123456789",
        "status": 1,
        "status_name": "已支付",
        "amount": 99.00,
        "payment_time": "2024-01-01 12:00:00"
    }
}
```

### 4. 支付宝异步通知

**接口：** `POST /api/v1/pay/alipay/notify`

支付宝会向此接口发送异步通知，系统会自动处理支付状态更新和许可证生成。