更新

server/app/common/service/ExpressTrackService.php

@@ -19,6 +19,8 @@ class ExpressTrackService
     private const KUAIDI_COM_JT = 'jtexpress'; // 极兔速递
 
     /**
+     * @param string $phoneTailOverride 手工填写的收件电话（仅数字；完整 11 位或与面单一致的后四位等），优先于订单收货手机
+     *
      * @return array{
      *   carrier: string,
      *   carrier_label: string,
@@ -31,11 +33,13 @@ class ExpressTrackService
      *   official_url: string
      * }
      */
-    public static function query(string $expressCompany, string $trackingNumber, string $recipientPhone = ''): array
+    public static function query(string $expressCompany, string $trackingNumber, string $recipientPhone = '', string $phoneTailOverride = ''): array
     {
         $num = trim($trackingNumber);
-        $phoneDigits = preg_replace('/\D/', '', $recipientPhone) ?? '';
-        $phoneLast4 = strlen($phoneDigits) >= 4 ? substr($phoneDigits, -4) : '';
+        $overrideDigits = preg_replace('/\D/', '', $phoneTailOverride) ?? '';
+        $recipientDigits = preg_replace('/\D/', '', $recipientPhone) ?? '';
+        // 快递100 文档：phone 为收/寄件人电话；顺丰等必填。示例为完整 11 位手机号，仅传后四位易触发 408「验证码错误」
+        $phoneForKuaidi = self::buildKuaidiPhoneParam($overrideDigits, $recipientDigits);
 
         $resolved = self::resolveCarrier($expressCompany, $num);
         $carrier = $resolved['carrier'];
@@ -64,13 +68,20 @@ class ExpressTrackService
             return $out;
         }
 
+        // 顺丰（及快递100 要求电话的承运商）无 phone 时不请求接口，避免无效调用
+        if ($phoneForKuaidi === '' && self::kuaidiPhoneRequired($kuaidiCom)) {
+            $out['hint'] = '顺丰查询需在快递100 中同时提交单号与收/寄件人电话（可与面单一致的完整手机号或后四位）。请填写收件电话后点「刷新轨迹」。';
+
+            return $out;
+        }
+
         $paramArr = [
             'com' => $kuaidiCom,
             'num' => $num,
             'resultv2' => '1',
         ];
-        if ($phoneLast4 !== '') {
-            $paramArr['phone'] = $phoneLast4;
+        if ($phoneForKuaidi !== '') {
+            $paramArr['phone'] = $phoneForKuaidi;
         }
 
         $paramJson = json_encode($paramArr, JSON_UNESCAPED_UNICODE);
@@ -154,6 +165,31 @@ class ExpressTrackService
         return $out;
     }
 
+    /**
+     * 快递100「phone」入参：有手动覆盖且不少于 4 位时用覆盖；否则用订单收货号码。
+     * 对 11 位及以上数字取后 11 位作为手机号（去掉可能的前缀符号位）。
+     */
+    private static function buildKuaidiPhoneParam(string $overrideDigits, string $recipientDigits): string
+    {
+        $d = strlen($overrideDigits) >= 4 ? $overrideDigits : $recipientDigits;
+        if ($d === '') {
+            return '';
+        }
+        if (strlen($d) >= 11) {
+            return substr($d, -11);
+        }
+
+        return $d;
+    }
+
+    /** 实时查询文档：顺丰速运、中通快递等 phone 必填 */
+    private static function kuaidiPhoneRequired(string $kuaidiCom): bool
+    {
+        $c = strtolower($kuaidiCom);
+
+        return $c === self::KUAIDI_COM_SF || $c === 'zhongtong';
+    }
+
     /**
      * @return array{carrier: string, kuaidi_com: string, label: string}
      */