feat(alibaba): 添加1688订单退款原因查询功能

- 新增 refundReasonList 方法用于查询退款退货原因列表
- 集成 alibaba.trade.getRefundReasonList-1 API 接口
- 实现订单号和子订单号参数验证及传递逻辑
- 添加退款原因数据格式化处理功能
- 在路由配置中注册新的退款原因查询接口
- 完善错误处理和日志记录机制

app/controller/api/store/order/AlibabaOrder.php

@@ -56,4 +56,34 @@ class AlibabaOrder
         }
         return app('json')->success(['postagePrice' => $res['preview']['sumCarriage'] / 100, 'flow' => $res['preview']['flowFlag']]);
     }
+
+    /**
+     * 查询退款退货原因列表
+     *
+     * API: alibaba.trade.getRefundReasonList-1
+     *
+     * @return \think\Response
+     */
+    public function refundReasonList()
+    {
+        $orderId = request()->param('order_id');
+        $orderEntryIds = request()->param('order_entry_ids', '');
+
+        if (empty($orderId)) {
+            return app('json')->fail('订单号不能为空');
+        }
+
+        $orderService = new OrderService();
+        $params = ['orderId' => $orderId];
+        if (!empty($orderEntryIds)) {
+            $params['orderEntryIds'] = $orderEntryIds;
+        }
+
+        $result = $orderService->getRefundReasonList($params);
+        if ($result === false) {
+            return app('json')->fail('获取退款原因失败');
+        }
+
+        return app('json')->success($result);
+    }
 }

app/services/ThirdParty/AlibabaAgent/OrderService.php

@@ -507,4 +507,110 @@ class OrderService extends AlibabaAgentBaseService
             'rawData'         => $result,
         ];
     }
+
+    /**
+     * 查询退款退货原因列表
+     *
+     * API: com.alibaba.trade:alibaba.trade.getRefundReasonList-1
+     *
+     * 接口文档: https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade%3Aalibaba.trade.getRefundReasonList-1
+     *
+     * 请求参数:
+     *   - orderId: 订单号（必填）
+     *   - orderEntryIds: 子订单号（可选，多个用逗号分隔）
+     *
+     * 返回示例:
+     * {
+     *   "result": [
+     *     {
+     *       "refundId": "REFUND123456",
+     *       "refundType": "退货退款",
+     *       "refundStatus": "waitSellerAgree",
+     *       "refundReasonList": [
+     *         {
+     *           "reasonId": 1,
+     *           "reasonText": "质量问题"
+     *         }
+     *       ]
+     *     }
+     *   ],
+     *   "success": true
+     * }
+     *
+     * @param array $params 请求参数（orderId 必填）
+     * @return array|false
+     */
+    public function getRefundReasonList(array $params = [])
+    {
+        // --- 参数校验 ---
+        if (empty($params['orderId'])) {
+            Log::channel('alibaba')->error('[获取退款原因] orderId不能为空');
+            return false;
+        }
+
+        $businessParams = [
+            'orderId' => (string)$params['orderId'],
+        ];
+
+        // 可选参数：子订单号
+        if (!empty($params['orderEntryIds'])) {
+            $businessParams['orderEntryIds'] = (string)$params['orderEntryIds'];
+        }
+
+        // --- 调用API ---
+        $result = $this->executeParam2(
+            self::NAMESPACE,
+            'alibaba.trade.getRefundReasonList',
+            1,
+            $businessParams
+        );
+
+        if ($result === false) {
+            Log::channel('alibaba')->error('[获取退款原因] API请求失败, params:' . json_encode($businessParams, JSON_UNESCAPED_UNICODE));
+            return false;
+        }
+
+        Log::channel('alibaba')->info('[获取退款原因] API请求成功, result:' . json_encode($result, JSON_UNESCAPED_UNICODE));
+
+        return $this->formatRefundReasonListResult($result);
+    }
+
+    /**
+     * 格式化退款退货原因列表返回结果
+     *
+     * @param array $result API原始返回数据
+     * @return array
+     */
+    protected function formatRefundReasonListResult(array $result): array
+    {
+        $success = $result['success'] ?? false;
+        $refundList = [];
+
+        if (isset($result['result']) && is_array($result['result'])) {
+            foreach ($result['result'] as $item) {
+                $reasons = [];
+                if (isset($item['refundReasonList']) && is_array($item['refundReasonList'])) {
+                    foreach ($item['refundReasonList'] as $reason) {
+                        $reasons[] = [
+                            'reasonId'   => $reason['reasonId'] ?? '',
+                            'reasonText' => $reason['reasonText'] ?? '',
+                        ];
+                    }
+                }
+
+                $refundList[] = [
+                    'refundId'         => $item['refundId'] ?? '',
+                    'refundType'       => $item['refundType'] ?? '',
+                    'refundStatus'     => $item['refundStatus'] ?? '',
+                    'refundReasonList' => $reasons,
+                ];
+            }
+        }
+
+        return [
+            'success'    => $success,
+            'refundList' => $refundList,
+            'rawData'    => $result,
+        ];
+    }
 }

route/api.php

@@ -142,6 +142,7 @@ Route::group('api/', function () {
         // 1688
         Route::group('alibaba',function (){
             Route::post('checkOrder','/checkOrder');
+            Route::get('refundReasonList','/refundReasonList');
         })->prefix('api.store.order.AlibabaOrder');