AIGC/demo/IJPAY_USAGE_GUIDE.md

# IJPay 使用指南

## 一、IJPay 简介

IJPay 是一个简洁易用的 Java 聚合支付 SDK，支持微信支付、支付宝支付、银联支付等多种支付方式。

项目已集成 IJPay-AliPay 模块，用于支付宝支付功能。

## 二、项目中的 IJPay 使用方式

### 1. 依赖配置

在 `pom.xml` 中已添加 IJPay 依赖：

```xml
<dependency>
    <groupId>com.github.javen205</groupId>
    <artifactId>IJPay-AliPay</artifactId>
    <version>2.9.12.1</version>
</dependency>
```

### 2. 代码使用方式

项目中主要通过 `AlipayController.java` 使用 IJPay 的 `AliPayApi` 类进行支付操作。

#### 2.1 扫码支付（QR码支付）

```java
@PostMapping("/qr-pay")
public ResponseEntity<Map<String, Object>> qrPay(...) {
    AlipayTradePrecreateModel model = new AlipayTradePrecreateModel();
    model.setOutTradeNo(outTradeNo);
    model.setTotalAmount(totalAmount);
    model.setSubject(subject);
    model.setBody(body);
    
    // 使用 IJPay 的 AliPayApi 调用预创建接口
    String qrCode = AliPayApi.tradePrecreatePayToResponse(model, notifyUrl).getBody();
    // 返回二维码字符串
}
```

#### 2.2 PC网页支付

```java
@PostMapping("/pc-pay")
public void pcPay(...) {
    AlipayTradePagePayModel model = new AlipayTradePagePayModel();
    model.setOutTradeNo(outTradeNo);
    model.setProductCode("FAST_INSTANT_TRADE_PAY");
    model.setTotalAmount(totalAmount);
    model.setSubject(subject);
    
    // 使用 IJPay 的 AliPayApi 进行页面跳转
    AliPayApi.tradePage(response, model, notifyUrl, returnUrl);
}
```

#### 2.3 手机网页支付

```java
@PostMapping("/wap-pay")
public void wapPay(...) {
    AlipayTradeWapPayModel model = new AlipayTradeWapPayModel();
    model.setOutTradeNo(outTradeNo);
    model.setProductCode("QUICK_WAP_PAY");
    model.setTotalAmount(totalAmount);
    
    // 使用 IJPay 的 AliPayApi 进行手机支付
    AliPayApi.wapPay(response, model, returnUrl, notifyUrl);
}
```

#### 2.4 APP支付

```java
@PostMapping("/app-pay")
public ResponseEntity<Map<String, Object>> appPay(...) {
    AlipayTradeAppPayModel model = new AlipayTradeAppPayModel();
    model.setOutTradeNo(outTradeNo);
    model.setProductCode("QUICK_MSECURITY_PAY");
    model.setTotalAmount(totalAmount);
    
    // 使用 IJPay 的 AliPayApi 获取 APP 支付订单信息
    String orderInfo = AliPayApi.appPayToResponse(model, notifyUrl).getBody();
    // 返回订单信息给 APP
}
```

#### 2.5 订单查询

```java
@GetMapping("/query")
public ResponseEntity<Map<String, Object>> queryOrder(...) {
    AlipayTradeQueryModel model = new AlipayTradeQueryModel();
    model.setOutTradeNo(outTradeNo);
    
    // 使用 IJPay 的 AliPayApi 查询订单
    String result = AliPayApi.tradeQueryToResponse(model).getBody();
    // 返回查询结果
}
```

#### 2.6 退款

```java
@PostMapping("/refund")
public ResponseEntity<Map<String, Object>> refund(...) {
    AlipayTradeRefundModel model = new AlipayTradeRefundModel();
    model.setOutTradeNo(outTradeNo);
    model.setRefundAmount(refundAmount);
    model.setRefundReason(refundReason);
    
    // 使用 IJPay 的 AliPayApi 发起退款
    String result = AliPayApi.tradeRefundToResponse(model).getBody();
    // 返回退款结果
}
```

#### 2.7 异步通知处理

```java
@PostMapping("/notify")
public String notifyUrl(HttpServletRequest request) {
    // 使用 IJPay 的 AliPayApi 将请求参数转换为 Map
    Map<String, String> params = AliPayApi.toMap(request);
    
    // 验证签名
    boolean verifyResult = AlipaySignature.rsaCertCheckV1(
        params, aliPayConfig.getAliPayCertPath(), "UTF-8", "RSA2");
    
    if (verifyResult) {
        // 处理支付成功逻辑
        return "success";
    } else {
        return "failure";
    }
}
```

## 三、IJPay 配置说明

### 3.1 配置方式

IJPay 的 `AliPayApi` 类内部会自动读取系统属性或配置文件中的支付宝配置。

需要配置的参数包括：
- `appId`: 支付宝应用ID
- `privateKey`: 应用私钥
- `publicKey`: 支付宝公钥
- `gatewayUrl`: 支付宝网关地址
- `charset`: 字符编码（通常为 UTF-8）
- `signType`: 签名类型（通常为 RSA2）

### 3.2 配置文件

配置在 `application-dev.properties` 或 `application-prod.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=回调通知地址
alipay.return-url=同步返回地址
```

### 3.3 IJPay 初始化（可选）

如果需要显式初始化 IJPay，可以在应用启动时配置：

```java
@Configuration
public class IJPayConfig {
    
    @Autowired
    private AliPayConfig aliPayConfig;
    
    @PostConstruct
    public void init() {
        // IJPay 的 AliPayApi 会自动读取配置
        // 如果需要显式配置，可以使用 AliPayApiConfigKit
        // 注意：具体初始化方式取决于 IJPay 版本
    }
}
```

## 四、IJPay vs 原生 Alipay SDK

项目中同时使用了两种方式：

1. **IJPay (AliPayApi)** - 在 `AlipayController.java` 中使用
   - 优点：封装更简洁，使用更方便
   - 缺点：需要额外依赖 IJPay 库

2. **原生 Alipay SDK (DefaultAlipayClient)** - 在 `AlipayService.java` 中使用
   - 优点：官方 SDK，功能完整
   - 缺点：需要手动创建客户端和处理响应

## 五、常见问题

### Q1: IJPay 如何初始化？

A: IJPay 的 `AliPayApi` 类内部会自动读取配置，通常不需要显式初始化。如果遇到配置问题，可以检查：
1. 配置文件中的参数是否正确
2. 系统属性是否设置
3. 环境变量是否配置

### Q2: 如何切换到 IJPay？

A: 如果当前使用原生 Alipay SDK，可以：
1. 修改 `AlipayService.java`，使用 `AliPayApi` 替代 `DefaultAlipayClient`
2. 或者直接使用 `AlipayController` 中的接口

### Q3: IJPay 和原生 SDK 的区别？

A: IJPay 是对原生 SDK 的封装，提供了更简洁的 API。底层实现仍然使用支付宝官方 SDK。

## 六、参考文档

- IJPay 官方文档：https://github.com/Javen205/IJPay
- IJPay 示例项目：https://github.com/Javen205/IJPay-Demo
- 支付宝开放平台：https://open.alipay.com