🔖 发布 4.7.9.B 测试版本
This commit is contained in:
Binary Wang
80
docs/MINIAPP_KEFU_SERVICE.md
Normal file
80
docs/MINIAPP_KEFU_SERVICE.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# WeChat Mini Program Customer Service Management
|
||||
|
||||
This document describes the new customer service management functionality added to the WxJava Mini Program SDK.
|
||||
|
||||
## Overview
|
||||
|
||||
Previously, the mini program module only had:
|
||||
- `WxMaCustomserviceWorkService` - For binding mini programs to enterprise WeChat customer service
|
||||
- `WxMaMsgService.sendKefuMsg()` - For sending customer service messages
|
||||
|
||||
The new `WxMaKefuService` adds comprehensive customer service management capabilities:
|
||||
|
||||
## Features
|
||||
|
||||
### Customer Service Account Management
|
||||
- `kfList()` - Get list of customer service accounts
|
||||
- `kfAccountAdd()` - Add new customer service account
|
||||
- `kfAccountUpdate()` - Update customer service account
|
||||
- `kfAccountDel()` - Delete customer service account
|
||||
|
||||
### Session Management
|
||||
- `kfSessionCreate()` - Create customer service session
|
||||
- `kfSessionClose()` - Close customer service session
|
||||
- `kfSessionGet()` - Get customer session status
|
||||
- `kfSessionList()` - Get customer service session list
|
||||
|
||||
## Usage Example
|
||||
|
||||
```java
|
||||
// Get the customer service management service
|
||||
WxMaKefuService kefuService = wxMaService.getKefuService();
|
||||
|
||||
// Add a new customer service account
|
||||
WxMaKfAccountRequest request = WxMaKfAccountRequest.builder()
|
||||
.kfAccount("service001@example")
|
||||
.kfNick("Customer Service 001")
|
||||
.kfPwd("password123")
|
||||
.build();
|
||||
boolean result = kefuService.kfAccountAdd(request);
|
||||
|
||||
// Create a session between user and customer service
|
||||
boolean sessionResult = kefuService.kfSessionCreate("user_openid", "service001@example");
|
||||
|
||||
// Get customer service list
|
||||
WxMaKfList kfList = kefuService.kfList();
|
||||
```
|
||||
|
||||
## Bean Classes
|
||||
|
||||
### Request Objects
|
||||
- `WxMaKfAccountRequest` - For customer service account operations
|
||||
- `WxMaKfSessionRequest` - For session operations
|
||||
|
||||
### Response Objects
|
||||
- `WxMaKfInfo` - Customer service account information
|
||||
- `WxMaKfList` - List of customer service accounts
|
||||
- `WxMaKfSession` - Session information
|
||||
- `WxMaKfSessionList` - List of sessions
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The service uses the following WeChat Mini Program API endpoints:
|
||||
- `https://api.weixin.qq.com/cgi-bin/customservice/getkflist` - Get customer service list
|
||||
- `https://api.weixin.qq.com/customservice/kfaccount/add` - Add customer service account
|
||||
- `https://api.weixin.qq.com/customservice/kfaccount/update` - Update customer service account
|
||||
- `https://api.weixin.qq.com/customservice/kfaccount/del` - Delete customer service account
|
||||
- `https://api.weixin.qq.com/customservice/kfsession/create` - Create session
|
||||
- `https://api.weixin.qq.com/customservice/kfsession/close` - Close session
|
||||
- `https://api.weixin.qq.com/customservice/kfsession/getsession` - Get session
|
||||
- `https://api.weixin.qq.com/customservice/kfsession/getsessionlist` - Get session list
|
||||
|
||||
## Integration
|
||||
|
||||
The service is automatically available through the main `WxMaService` interface:
|
||||
|
||||
```java
|
||||
WxMaKefuService kefuService = wxMaService.getKefuService();
|
||||
```
|
||||
|
||||
This fills the gap mentioned in the original issue and provides full customer service management capabilities for WeChat Mini Programs.
|
||||
129
docs/NEW_TRANSFER_API_SUPPORT.md
Normal file
129
docs/NEW_TRANSFER_API_SUPPORT.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 微信支付新版商户转账API支持
|
||||
|
||||
## 问题解答
|
||||
|
||||
**问题**: 新开通的商户号只能使用最新版本的商户转账接口，WxJava是否支持？
|
||||
|
||||
**答案**: **WxJava 已经完整支持新版商户转账API！** 从2025年1月15日开始生效的新版转账API已在WxJava中实现。
|
||||
|
||||
## 新版转账API特性
|
||||
|
||||
### 1. API接口对比
|
||||
|
||||
| 特性 | 传统转账API | 新版转账API (2025.1.15+) |
|
||||
|------|-------------|-------------------------|
|
||||
| **服务类** | `MerchantTransferService` | `TransferService` |
|
||||
| **API路径** | `/v3/transfer/batches` | `/v3/fund-app/mch-transfer/transfer-bills` |
|
||||
| **转账方式** | 批量转账 | 单笔转账 |
|
||||
| **场景支持** | 基础场景 | 丰富场景（如佣金报酬等） |
|
||||
| **撤销功能** | ❌ 不支持 | ✅ 支持 |
|
||||
| **适用范围** | 所有商户 | **新开通商户必须使用** |
|
||||
|
||||
### 2. 新版API功能列表
|
||||
|
||||
✅ **发起转账** - `transferBills()`
|
||||
✅ **查询转账** - `getBillsByOutBillNo()` / `getBillsByTransferBillNo()`
|
||||
✅ **撤销转账** - `transformBillsCancel()`
|
||||
✅ **回调通知** - `parseTransferBillsNotifyResult()`
|
||||
✅ **RSA加密** - 自动处理用户姓名加密
|
||||
✅ **场景支持** - 支持多种转账场景ID
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 获取服务实例
|
||||
|
||||
```java
|
||||
// 获取WxPayService实例
|
||||
WxPayService wxPayService = new WxPayServiceImpl();
|
||||
wxPayService.setConfig(config);
|
||||
|
||||
// 获取新版转账服务 - 这就是新开通商户需要使用的服务！
|
||||
TransferService transferService = wxPayService.getTransferService();
|
||||
```
|
||||
|
||||
### 2. 发起转账（新版API）
|
||||
|
||||
```java
|
||||
// 构建转账请求
|
||||
TransferBillsRequest request = TransferBillsRequest.newBuilder()
|
||||
.appid("your_appid") // 应用ID
|
||||
.outBillNo("T" + System.currentTimeMillis()) // 商户转账单号
|
||||
.transferSceneId("1005") // 转账场景ID（佣金报酬）
|
||||
.openid("user_openid") // 用户openid
|
||||
.userName("张三") // 收款用户姓名（可选，自动加密）
|
||||
.transferAmount(100) // 转账金额（分）
|
||||
.transferRemark("佣金报酬") // 转账备注
|
||||
.build();
|
||||
|
||||
// 发起转账
|
||||
TransferBillsResult result = transferService.transferBills(request);
|
||||
System.out.println("转账成功，微信转账单号：" + result.getTransferBillNo());
|
||||
```
|
||||
|
||||
### 3. 查询转账结果
|
||||
|
||||
```java
|
||||
// 通过商户单号查询
|
||||
TransferBillsGetResult result = transferService.getBillsByOutBillNo("T1642567890123");
|
||||
|
||||
// 通过微信转账单号查询
|
||||
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo("wx_transfer_bill_no");
|
||||
|
||||
System.out.println("转账状态：" + result.getState());
|
||||
```
|
||||
|
||||
### 4. 撤销转账（新功能）
|
||||
|
||||
```java
|
||||
// 撤销转账
|
||||
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel("T1642567890123");
|
||||
System.out.println("撤销状态：" + cancelResult.getState());
|
||||
```
|
||||
|
||||
## 重要说明
|
||||
|
||||
### 转账场景ID (transfer_scene_id)
|
||||
- **1005**: 佣金报酬（常用场景）
|
||||
- 其他场景需要在微信商户平台申请
|
||||
|
||||
### 转账状态说明
|
||||
- **ACCEPTED**: 转账已受理
|
||||
- **PROCESSING**: 转账处理中
|
||||
- **SUCCESS**: 转账成功
|
||||
- **FAIL**: 转账失败
|
||||
- **CANCELLED**: 转账撤销完成
|
||||
|
||||
### 新开通商户使用建议
|
||||
|
||||
1. **优先使用** `TransferService` （新版API）
|
||||
2. **不要使用** `MerchantTransferService` （可能不支持）
|
||||
3. **必须设置** 转账场景ID (`transfer_scene_id`)
|
||||
4. **建议开启** 回调通知以实时获取转账结果
|
||||
|
||||
## 完整示例代码
|
||||
|
||||
详细的使用示例请参考：
|
||||
- 📄 [NEW_TRANSFER_API_USAGE.md](./NEW_TRANSFER_API_USAGE.md) - 详细使用指南
|
||||
- 💻 [NewTransferApiExample.java](./weixin-java-pay/src/main/java/com/github/binarywang/wxpay/example/NewTransferApiExample.java) - 完整代码示例
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 我是新开通的商户，应该使用哪个服务？**
|
||||
A: 使用 `TransferService`，这是专为新版API设计的服务。
|
||||
|
||||
**Q: 新版API和旧版API有什么区别？**
|
||||
A: 新版API使用单笔转账模式，支持更丰富的转账场景，并且支持撤销功能。
|
||||
|
||||
**Q: 如何设置转账场景ID？**
|
||||
A: 在商户平台申请相应场景，常用的佣金报酬场景ID是"1005"。
|
||||
|
||||
**Q: 用户姓名需要加密吗？**
|
||||
A: WxJava会自动处理RSA加密，您只需要传入明文姓名即可。
|
||||
|
||||
## 版本要求
|
||||
|
||||
- WxJava 版本：4.7.0+
|
||||
- 支持时间：2025年1月15日+
|
||||
- 适用商户：所有商户（新开通商户强制使用）
|
||||
|
||||
通过以上说明，新开通的微信支付商户可以放心使用WxJava进行商户转账操作！
|
||||
148
docs/NEW_TRANSFER_API_USAGE.md
Normal file
148
docs/NEW_TRANSFER_API_USAGE.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 微信支付新版商户转账API使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
从2025年1月15日开始，微信支付推出了新版的商户转账API。新开通的商户号只能使用最新版本的商户转账接口。WxJava 已经完整支持新版转账API。
|
||||
|
||||
## API对比
|
||||
|
||||
### 传统转账API (仍然支持)
|
||||
- **服务类**: `MerchantTransferService`
|
||||
- **API前缀**: `/v3/transfer/batches`
|
||||
- **特点**: 支持批量转账，一次可以转账给多个用户
|
||||
|
||||
### 新版转账API (2025.1.15+)
|
||||
- **服务类**: `TransferService`
|
||||
- **API前缀**: `/v3/fund-app/mch-transfer/transfer-bills`
|
||||
- **特点**: 单笔转账，支持更丰富的转账场景
|
||||
|
||||
## 使用新版转账API
|
||||
|
||||
### 1. 获取服务实例
|
||||
|
||||
```java
|
||||
// 获取WxPayService实例
|
||||
WxPayService wxPayService = new WxPayServiceImpl();
|
||||
wxPayService.setConfig(config);
|
||||
|
||||
// 获取新版转账服务
|
||||
TransferService transferService = wxPayService.getTransferService();
|
||||
```
|
||||
|
||||
### 2. 发起转账
|
||||
|
||||
```java
|
||||
// 构建转账请求
|
||||
TransferBillsRequest request = TransferBillsRequest.newBuilder()
|
||||
.appid("your_appid") // 应用ID
|
||||
.outBillNo("T" + System.currentTimeMillis()) // 商户转账单号
|
||||
.transferSceneId("1005") // 转账场景ID（佣金报酬）
|
||||
.openid("user_openid") // 用户openid
|
||||
.userName("张三") // 收款用户姓名（可选，需要加密）
|
||||
.transferAmount(100) // 转账金额（分）
|
||||
.transferRemark("佣金报酬") // 转账备注
|
||||
.notifyUrl("https://your-domain.com/notify") // 回调地址（可选）
|
||||
.userRecvPerception("Y") // 用户收款感知（可选）
|
||||
.build();
|
||||
|
||||
try {
|
||||
TransferBillsResult result = transferService.transferBills(request);
|
||||
System.out.println("转账成功，微信转账单号：" + result.getTransferBillNo());
|
||||
System.out.println("状态：" + result.getState());
|
||||
} catch (WxPayException e) {
|
||||
System.err.println("转账失败：" + e.getMessage());
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 查询转账结果
|
||||
|
||||
```java
|
||||
// 通过商户单号查询
|
||||
String outBillNo = "T1642567890123";
|
||||
TransferBillsGetResult result = transferService.getBillsByOutBillNo(outBillNo);
|
||||
|
||||
// 通过微信转账单号查询
|
||||
String transferBillNo = "1000000000000000000000000001";
|
||||
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo(transferBillNo);
|
||||
|
||||
System.out.println("转账状态：" + result.getState());
|
||||
System.out.println("转账金额：" + result.getTransferAmount());
|
||||
```
|
||||
|
||||
### 4. 撤销转账
|
||||
|
||||
```java
|
||||
// 撤销转账（仅在特定状态下可撤销）
|
||||
String outBillNo = "T1642567890123";
|
||||
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel(outBillNo);
|
||||
System.out.println("撤销结果：" + cancelResult.getState());
|
||||
```
|
||||
|
||||
### 5. 处理回调通知
|
||||
|
||||
```java
|
||||
// 在回调接口中处理通知
|
||||
@PostMapping("/transfer/notify")
|
||||
public String handleTransferNotify(HttpServletRequest request) throws Exception {
|
||||
String notifyData = StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8);
|
||||
|
||||
// 构建签名头
|
||||
SignatureHeader header = new SignatureHeader();
|
||||
header.setTimeStamp(request.getHeader("Wechatpay-Timestamp"));
|
||||
header.setNonce(request.getHeader("Wechatpay-Nonce"));
|
||||
header.setSignature(request.getHeader("Wechatpay-Signature"));
|
||||
header.setSerial(request.getHeader("Wechatpay-Serial"));
|
||||
|
||||
try {
|
||||
TransferBillsNotifyResult notifyResult = transferService.parseTransferBillsNotifyResult(notifyData, header);
|
||||
|
||||
// 处理业务逻辑
|
||||
String outBillNo = notifyResult.getOutBillNo();
|
||||
String state = notifyResult.getState();
|
||||
|
||||
System.out.println("转账单号：" + outBillNo + "，状态：" + state);
|
||||
|
||||
return "SUCCESS";
|
||||
} catch (WxPayException e) {
|
||||
System.err.println("验签失败：" + e.getMessage());
|
||||
return "FAIL";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 重要参数说明
|
||||
|
||||
### 转账场景ID (transfer_scene_id)
|
||||
- **1005**: 佣金报酬（常用）
|
||||
- 其他场景ID需要在商户平台申请
|
||||
|
||||
### 转账状态
|
||||
- **PROCESSING**: 转账中
|
||||
- **SUCCESS**: 转账成功
|
||||
- **FAILED**: 转账失败
|
||||
- **REFUNDED**: 已退款
|
||||
|
||||
### 用户收款感知 (user_recv_perception)
|
||||
- **Y**: 用户会收到微信转账通知
|
||||
- **N**: 用户不会收到微信转账通知
|
||||
|
||||
## 新旧API对比总结
|
||||
|
||||
| 特性 | 传统API (MerchantTransferService) | 新版API (TransferService) |
|
||||
|------|----------------------------------|---------------------------|
|
||||
| 发起方式 | 批量转账 | 单笔转账 |
|
||||
| API路径 | `/v3/transfer/batches` | `/v3/fund-app/mch-transfer/transfer-bills` |
|
||||
| 场景支持 | 基础转账场景 | 丰富的转账场景 |
|
||||
| 回调通知 | 支持 | 支持 |
|
||||
| 撤销功能 | 不支持 | 支持 |
|
||||
| 适用商户 | 所有商户 | 新开通商户必须使用 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **新开通的商户号**: 必须使用新版API (`TransferService`)
|
||||
2. **转账场景ID**: 需要在商户平台申请相应的转账场景
|
||||
3. **用户姓名加密**: 如果传入用户姓名，会自动进行RSA加密
|
||||
4. **回调验签**: 建议开启回调验签以确保安全性
|
||||
5. **错误处理**: 妥善处理各种异常情况
|
||||
|
||||
通过以上指南，您可以轻松使用WxJava的新版商户转账API功能。
|
||||
112
docs/QUARKUS_SUPPORT.md
Normal file
112
docs/QUARKUS_SUPPORT.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# WxJava Quarkus/GraalVM Native Image Support
|
||||
|
||||
## 概述
|
||||
|
||||
从 4.7.8.B 版本开始，WxJava 提供了对 Quarkus 和 GraalVM Native Image 的支持。这允许您将使用 WxJava 的应用程序编译为原生可执行文件，从而获得更快的启动速度和更低的内存占用。
|
||||
|
||||
## 问题背景
|
||||
|
||||
在之前的版本中，使用 Quarkus 构建 Native Image 时会遇到以下错误：
|
||||
|
||||
```
|
||||
Error: Unsupported features in 3 methods
|
||||
Detailed message:
|
||||
Error: Detected an instance of Random/SplittableRandom class in the image heap.
|
||||
Instances created during image generation have cached seed values and don't behave as expected.
|
||||
The culprit object has been instantiated by the 'org.apache.http.impl.auth.NTLMEngineImpl' class initializer
|
||||
```
|
||||
|
||||
## 解决方案
|
||||
|
||||
为了解决这个问题，WxJava 进行了以下改进：
|
||||
|
||||
### 1. Random 实例的延迟初始化
|
||||
|
||||
所有 `java.util.Random` 实例都已改为延迟初始化，避免在类加载时创建：
|
||||
|
||||
- `RandomUtils` - 使用双重检查锁定模式延迟初始化
|
||||
- `SignUtils` - 使用双重检查锁定模式延迟初始化
|
||||
- `WxCryptUtil` - 使用双重检查锁定模式延迟初始化
|
||||
|
||||
### 2. Native Image 配置
|
||||
|
||||
在 `weixin-java-common` 模块中添加了 GraalVM Native Image 配置文件：
|
||||
|
||||
- `META-INF/native-image/com.github.binarywang/weixin-java-common/native-image.properties`
|
||||
- 配置 Apache HttpClient 相关类在运行时初始化，避免在构建时创建 SecureRandom 实例
|
||||
|
||||
- `META-INF/native-image/com.github.binarywang/weixin-java-common/reflect-config.json`
|
||||
- 配置反射访问的类和方法
|
||||
|
||||
## 使用方式
|
||||
|
||||
### Quarkus 项目配置
|
||||
|
||||
在您的 Quarkus 项目中使用 WxJava，只需正常引入依赖即可：
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.github.binarywang</groupId>
|
||||
<artifactId>weixin-java-miniapp</artifactId> <!-- 或其他模块 -->
|
||||
<version>4.7.8.B</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
### 构建 Native Image
|
||||
|
||||
使用 Quarkus 构建原生可执行文件：
|
||||
|
||||
```bash
|
||||
./mvnw package -Pnative
|
||||
```
|
||||
|
||||
或使用容器构建：
|
||||
|
||||
```bash
|
||||
./mvnw package -Pnative -Dquarkus.native.container-build=true
|
||||
```
|
||||
|
||||
### GraalVM Native Image
|
||||
|
||||
如果直接使用 GraalVM Native Image 工具：
|
||||
|
||||
```bash
|
||||
native-image --no-fallback \
|
||||
-H:+ReportExceptionStackTraces \
|
||||
-jar your-application.jar
|
||||
```
|
||||
|
||||
WxJava 的配置文件会自动被 Native Image 工具识别和应用。
|
||||
|
||||
## 测试验证
|
||||
|
||||
建议在构建 Native Image 后进行以下测试：
|
||||
|
||||
1. 验证应用程序可以正常启动
|
||||
2. 验证微信 API 调用功能正常
|
||||
3. 验证随机字符串生成功能正常
|
||||
4. 验证加密/解密功能正常
|
||||
|
||||
## 已知限制
|
||||
|
||||
- 本配置主要针对 Quarkus 3.x 和 GraalVM 22.x+ 版本进行测试
|
||||
- 如果使用其他 Native Image 构建工具（如 Spring Native），可能需要额外配置
|
||||
- 部分反射使用可能需要根据实际使用的 WxJava 功能进行调整
|
||||
|
||||
## 问题反馈
|
||||
|
||||
如果在使用 Quarkus/GraalVM Native Image 时遇到问题，请通过以下方式反馈：
|
||||
|
||||
1. 在 [GitHub Issues](https://github.com/binarywang/WxJava/issues) 提交问题
|
||||
2. 提供详细的错误信息和 Native Image 构建日志
|
||||
3. 说明使用的 Quarkus 版本和 GraalVM 版本
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Quarkus 官方文档](https://quarkus.io/)
|
||||
- [GraalVM Native Image 文档](https://www.graalvm.org/latest/reference-manual/native-image/)
|
||||
- [Quarkus Tips for Writing Native Applications](https://quarkus.io/guides/writing-native-applications-tips)
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎提交 PR 完善 Quarkus/GraalVM 支持！如果您发现了新的兼容性问题或有改进建议，请参考 [代码贡献指南](CONTRIBUTING.md)。
|
||||
Reference in New Issue
Block a user