Kamixitong/docs/alipay_integration.md

# 支付宝支付功能集成指南

## 概述

本系统已集成支付宝支付功能，支持PC网站支付和手机网站支付。支付成功后系统会自动生成许可证。

## 功能特性

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

## 依赖安装

```bash
pip install -r requirements.txt
```

需要安装 `alipay-sdk-python3==3.7.4`

## 配置支付宝参数

### 1. 获取支付宝应用信息

1. 登录[支付宝开放平台](https://open.alipay.com/)
2. 创建应用（网站支付类型）
3. 获取以下信息：
   - APP_ID（应用ID）
   - 应用私钥（APP_PRIVATE_KEY）
   - 支付宝公钥（ALIPAY_PUBLIC_KEY）
   - 支付宝平台公钥（ALIPAY_ALIPAY_PUBLIC_KEY）

### 2. 配置环境变量

在生产环境中，建议通过环境变量配置支付宝参数：

```bash
export ALIPAY_APP_ID="your_app_id"
export ALIPAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
export ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
export ALIPAY_ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
```

### 3. 配置文件（开发环境）

也可以在 `.env` 文件中配置：

```env
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-----
```

## 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/alipay1/user/notify`

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

## 前端页面

### 1. 购买页面

用户访问 `/user/licenses/purchase` 页面购买许可证。

页面功能：
- 选择产品和套餐
- 填写联系信息
- 选择支付方式（支付宝/微信）
- 创建订单并跳转到支付

### 2. 支付结果页面

支付完成后跳转到 `/payment/result?order_number=订单号`

页面功能：
- 显示支付结果
- 显示订单信息
- 显示生成的许可证密钥
- 支持复制许可证密钥

## 支付流程

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

## 重要说明

### 1. 异步通知处理

支付宝异步通知是支付状态更新的主要方式，系统会：
- 验证通知的签名
- 检查订单状态
- 更新订单状态为"已支付"
- 自动生成许可证
- 记录操作日志

### 2. 支付链接生成

根据客户端类型自动选择支付方式：
- PC端：使用 `alipay.trade.page.pay` 接口
- 移动端：使用 `alipay.trade.wap.pay` 接口

### 3. 许可证生成

支付成功后系统会自动：
- 查询订单信息
- 根据套餐配置生成许可证
- 设置有效期和最大设备数
- 保存许可证到数据库

## 错误处理

### 1. 常见错误

| 错误信息 | 原因 | 解决方法 |
|---------|------|----------|
| 支付配置错误 | 支付宝参数未配置 | 检查环境变量和配置文件 |
| 订单不存在 | 订单号错误 | 检查订单号是否正确 |
| 套餐库存不足 | 套餐库存为0 | 联系管理员补充库存 |
| 订单金额不匹配 | 金额被篡改 | 检查订单和支付金额 |

### 2. 日志查看

系统会在 `logs/kamaxitong.log` 中记录：
- 订单创建日志
- 支付流程日志
- 支付宝通知日志
- 许可证生成日志

## 安全建议

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

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

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

## 故障排除

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

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

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

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

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

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

### 3. 许可证未生成

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

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

## 技术支持

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

## 更新日志

### v1.0.0 (2024-12-11)
- 初始版本
- 支持支付宝PC网站支付和手机网站支付
- 自动生成许可证
- 异步通知处理
- 支付结果页面