From 5c74c1d930a5af673726d293d16524f4577bf8ff Mon Sep 17 00:00:00 2001
From: Binary Wang <a@binarywang.com>
Date: Wed, 2 Jul 2025 10:21:27 +0800
Subject: [PATCH] =?UTF-8?q?:art:=20=E4=B8=BA=E5=BE=AE=E4=BF=A1=E5=B0=8F?=
 =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E7=89=A9=E6=B5=81=E9=80=80=E8=B4=A7=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6=E6=8E=A5=E5=8F=A3=E5=A2=9E=E5=8A=A0=E6=B3=A8=E9=87=8A?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../api/WxMaExpressDeliveryReturnService.java | 37 +++++++++++++++++--
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaExpressDeliveryReturnService.java b/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaExpressDeliveryReturnService.java
index 4254d18df..6d950f680 100644
--- a/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaExpressDeliveryReturnService.java
+++ b/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaExpressDeliveryReturnService.java
@@ -5,18 +5,47 @@ import cn.binarywang.wx.miniapp.bean.express.result.WxMaExpressReturnInfoResult;
 import me.chanjar.weixin.common.error.WxErrorException;
 
 /**
- * 退货组件
+ * 微信小程序物流退货组件接口。
+ * 用于处理退货单相关操作，包括新增、查询和取消退货单。
+ * 文档：https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/express/express.html
+ *
  */
 public interface WxMaExpressDeliveryReturnService {
 
-    /**
-     * 获取支持的快递公司列表
-     */
+    /** 新增退货单接口地址 */
     String ADD_DELIVERY_RETURN_URL = "https://api.weixin.qq.com/cgi-bin/express/delivery/return/add";
+    /** 获取退货单接口地址 */
     String GET_DELIVERY_RETURN_URL = "https://api.weixin.qq.com/cgi-bin/express/delivery/return/get";
+    /** 取消退货单接口地址 */
     String UNBIND_DELIVERY_RETURN_URL = "https://api.weixin.qq.com/cgi-bin/express/delivery/return/unbind";
 
+    /**
+     * 新增退货单。
+     * 用于创建新的退货单，返回退货单信息。
+     *
+     * @param wxMaExpressDeliveryReturnAddRequest 退货单新增请求对象
+     * @return                                    退货单信息结果
+     * @throws WxErrorException                   新增失败时抛出
+     */
     WxMaExpressReturnInfoResult addDeliveryReturn(WxMaExpressDeliveryReturnAddRequest wxMaExpressDeliveryReturnAddRequest) throws WxErrorException;
+
+    /**
+     * 获取退货单信息。
+     * 根据退货单ID查询退货单的详细信息。
+     *
+     * @param returnId          退货单ID
+     * @return                  退货单信息结果
+     * @throws WxErrorException 获取失败时抛出
+     */
     WxMaExpressReturnInfoResult getDeliveryReturn(String returnId) throws WxErrorException;
+
+    /**
+     * 取消退货单。
+     * 取消指定的退货单，取消后的退货单将无法继续使用。
+     *
+     * @param returnId          退货单ID
+     * @return                  操作结果
+     * @throws WxErrorException 取消失败时抛出
+     */
     WxMaExpressReturnInfoResult unbindDeliveryReturn(String returnId) throws WxErrorException;
 }