更新

server/app/adminapi/logic/qywx/CustomerLogic.php

@@ -595,9 +595,36 @@ class CustomerLogic extends BaseLogic
         }
 
         $service = new WechatWorkService();
-        $detail = $service->getExternalContactDetail($externalUserId);
+        $detail = [];
+        $lastError = null;
+        // 接口偶发抖动：最多重试 1 次（共 2 次请求），间隔 1.2s。仅对「非预期错误 / 空响应」重试，
+        // 业务预期错误（如 84061 客户未通过、60011/60111 无权限、41068 非法 ID）不重试，避免无谓压力。
+        $maxAttempts = 2;
+        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
+            $err = null;
+            $detail = $service->getExternalContactDetail($externalUserId, $err);
+            if (!empty($detail['external_contact']) && is_array($detail['external_contact'])) {
+                break;
+            }
+            $lastError = $err;
+            $errcode = is_array($err) ? ($err['errcode'] ?? null) : null;
+            $shouldRetry = $attempt < $maxAttempts
+                && !in_array($errcode, [84061, 41068, 60011, 60111], true);
+            if (!$shouldRetry) {
+                break;
+            }
+            usleep(1_200_000);
+        }
+
         if (empty($detail['external_contact']) || !is_array($detail['external_contact'])) {
-            Log::warning('qywx external contact callback: 拉取详情为空', ['external_userid' => $externalUserId]);
+            $errcode = is_array($lastError) ? ($lastError['errcode'] ?? null) : null;
+            $errmsg = is_array($lastError) ? (string) ($lastError['errmsg'] ?? '') : '';
+            Log::warning(sprintf(
+                'qywx external contact callback: 拉取详情为空，跳过 UPSERT errcode=%s errmsg=%s ext=%s',
+                $errcode === null ? '?' : (string) $errcode,
+                $errmsg !== '' ? $errmsg : '-',
+                $externalUserId
+            ));
 
             return;
         }