ضع تدقيق SEO في خط أنابيب النشر الخاص بك: API، رموز الخروج، ووصفات CI

الانحدارات التقنية التي تكلف أكثر رؤية غير مرئية في مراجعة الكود. علامة canonical التي تبدأ بالإشارة إلى المضيف الخطأ، كتلة hreflang تفقد مرجعيتها، رأس Content-Security-Policy الذي يُزال من إعداد reverse-proxy، مسار يضع محتواه خلف التهيئة — كل واحد منها يُرسل في diff يبدو جيدًا ويجتاز كل اختبار لديك. تظهر بعد أسابيع، في مخطط حركة المرور، بعد فترة طويلة من الالتزام الذي تسبب فيها وتتم تمريرها من الرؤية. الإصلاح هيكلية: نفّذ التدقيق عند النشر، وليس في اليوم الذي يتذكر فيه شخص ما. كل تقرير SEOReport متاح عبر REST، يحمل الرد كتلة نتيجة رقمية، ويمكن لسكريبت shell تحويل تلك الكتلة إلى رمز خروج. هذا هو الآلية الكاملة.

أربع فئات انحدار لا يلتقطها سوى الآلة في الوقت المناسب

خرائط فحوصات محركنا بوضوح على أوضاع الفشل التي تتجاوز المراجعة البشرية، ويستحق تسميتها بشكل ملموس، لأنها ما تحميه البوابة فعليًا. Hreflang. يغطي مجموعة الفحص المرجعية الذاتية، روابط العودة، x-default الدقة، عناوين URL الصحيحة، ما إذا كان كل هدف بديل قابل للفهرسة، وما إذا كان canonical للهدف متوافقًا. ترحيل CMS يعيد كتابة أنماط URL يمكن أن يكسر روابط العودة عبر كل لغة في وقت واحد، ولا تبدو أي لغة مكسورة بمعزل. Canonicalization. الوجود، قابلية فهرسة الهدف، أهداف خالية من إعادة التوجيه، وcanonical خارج الموقع. أسوأ نسخة من هذا الفشل هي canonical في مرحلة الاختبار يُرسل إلى الإنتاج — صفحة تُنادي بهدوء مضيفًا لا تريد فهرسته. Security headers. Content-Security-Policy، HSTS، Referrer-Policy، X-Frame-Options، X-Content-Type-Options، وPermissions-Policy. هذه موجودة في إعداد البنية التحتية، وليس في كود التطبيق، وهو بالضبط السبب في اختفائها أثناء تغيير proxy أو edge-config ولا يلاحظ أحد. Render parity. كل تدقيق يجلب الصفحة الرئيسية مرتين — plain HTTP، ثم متصفح حقيقي — ويقارن العنوان، H1s، canonical، meta description، JSON-LD، وحجم نص الجسم عبر الاثنين. عندما وصلت بيانات render-parity المنشورة إلى حكم، كانت معظم المواقع تقدم صفحة أكثر نحافة بشكل مادي لأي شيء يقرأ HTML كما تم تسليمه. ssr: false واحدة في ملف التكوين كافية لنقل موقع إلى تلك المجموعة. جميع الأربعة حاسمة، جميع الأربعة رخيصة للتحقق، وجميع الأربعة نوع من الأشياء التي يفتحص عليها الشخص فقط عندما يكون مشكوكًا بالفعل.

ثلاث نقاط نهاية وحلقة واحدة

السطح API الذي يحتاجه خط الأنابيب صغير. المصادقة هي رمز حامل: أنشئ حسابًا، أصدر مفتاحًا من dashboard، وأرسله كـ Authorization: Bearer sr__live_your_api_key. المفتاح نفسه يفتح REST وMCP؛ الإشارة الكاملة موجودة على صفحة المطورين.

إرسال تقرير هو POST واحد:

JOB_ID=$(curl -sS -X POST https://seoreport.dev/api/v1/reports \
  -H "Authorization: Bearer $SEOREPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "forceRerun": true}' \
  | jq -r '.report.jobId')

شيئين حول ذلك الموضوع الجسدي في CI تحديدًا. forceRerun موجود لأن API يعيد استخدام لقطة موجودة عندما تكون متاحة — معقول لشخص يضغط زر، خاطئ لبوابة النشر، التي ستقيم الإصدار السابق خلاف ذلك. الرد يخبرك بما حدث في submission.reusedSnapshot. تُعدّ الجريّات الجديدة القسريّة ميزةً لحساب مدفوع؛ المفتاح الذي لا يملك ذلك الحق يَحصل على 403 يذكر السبب بدلًا من إرجاع بيانات قديمة بصمت. يتم استنتاج نطاق التدقيق من مسار URL يُجري الأصل البسيط تدقيقًا كاملًا للموقع؛ بينما يقوم URL مع مسار بتدقيق تلك الصفحة بمعزل. لذلك يمكن أن يحدّث خط الأنابيب الصفحة الرئيسية في كل نشر ويضيف المسار المحدد الذي لمس تغييره، دون أي معلمة إضافية. ثم استفتاء. GET /api/v1/reports/:id/ready هو نقطة النهاية الاقتصادية للحالة — يعيد ready، status، stage، pollAfterMs، وعند فشل التشغيل، كائن error:

for _ in $(seq 1 60); do
  READY=$(curl -sS -H "Authorization: Bearer $SEOREPORT_API_KEY" \
    "https://seoreport.dev/api/v1/reports/$JOB_ID/ready")

  CODE=$(echo "$READY" | jq -r '.error.code // empty')
  if [ -n "$CODE" ]; then
    echo "audit did not complete: $CODE"
    exit 75
  fi

  [ "$(echo "$READY" | jq -r '.ready')" = "true" ] && break
  sleep 5
done

ذلك exit 75 هو مقصود، وهو الجزء الذي تخطئ فيه معظم التكاملات.

افرّق بين الانحدار وتشغيل لم يحدث أبداً

error.code يحمل سبباً قابلاً للقراءة الآلية وretryable بولياني. DNS_FAILURE، CRAWLER_BLOCKED، REDIRECT_LOOP، TLS_ERROR، NO_CONTENT، وSTALE_ENGINE_VERSION معلمة بأنها غير قابلة لإعادة المحاولة، لأن إعادة المحاولة تنتج نفس الإجابة. معظم تلك القائمة تصف شرطاً على الموقع، وعدة مدخلات — حلقة إعادة توجيه، خطأ TLS، قاعدة بوت تمنع الآن الزواحف — هي عيوب نشر حقيقية تستحق فشل البناء. الرموز خارج ذلك المجموع transient وتستحق محاولة أخرى. البوابة التي تدمج "انحدر الموقع" و"لم يتم تشغيل التدقيق" في بناء أحمر واحد تُعطل خلال شهر. احتفظ بهم منفصلين في رموز الخروج: 1 للقرار الذي طلبت من البوابة تنفيذه، 75 — الـ EX_TEMPFAIL التقليدي — لتشغيل لم يُنتج أي قرار على الإطلاق. معظم أنظمة CI يمكن تكوينها لإعادة المحاولة للثانية وتوجيه إنسان للأولى.

قراءة كتلة الدرجات

بمجرد أن يكون ready صحيحاً، يُعيد GET /api/v1/reports/:id كائن التقرير. كتلة score هي الجزء الذي تقرأه البوابة:

REPORT=$(curl -sS -H "Authorization: Bearer $SEOREPORT_API_KEY" \
  "https://seoreport.dev/api/v1/reports/$JOB_ID")

echo "$REPORT" | jq '.report.score
  | {overall, totalChecks, passedChecks, failedChecks,
     warnChecks, inconclusiveChecks, failingCriticalChecks}'

ثلاثة من تلك الحقول تحمل معظم الإشارة. failingCriticalChecks هو عدد الفشل الذي تصنفه المحرك كحرجة — تلك القادرة على إزالة الصفحات من الفهرس أو إخفاء المحتوى عن الزاحف بالكامل. للبوابة الأولى، هذا هو الرقم الوحيد الذي تحتاجه، و> 0 هو عتبة دفاعية في اليوم الأول. overall هو الدرجة المركبة، مفيدة كقفل: احفظ قيمة النشر السابق وفشل عندما ينخفض الجديد بأكثر من التحمُّل الذي تختاره. هذا يلتقط التآكل البطيء الذي لا يحدده أي فحص واحد. domainScores يقسم الدرجة حسب seo، ai، performance، security، وbrand، كل منها مع pass، fail، وwarn الخاصة به. الأسقف حسب النطاق تسمح لفرق مختلفة بامتلاك ميزانيات مختلفة — الدرجة الأمنية هي بوابة ذات مغزى لمن يملك إعداد الحافة، مستقلة عن أي شيء يقدمه فريق المحتوى. inconclusiveChecks تستحق قاعدة خاصة: لا تقم بوابة عليها أبداً. يبلّغ الفحص بأنه غير حاسم عندما لا يستطيع المحرك الوصول إلى قرار دفاعي، ومعالجة ذلك كفشل تدرب الجميع على تجاهل البوابة. كتلة الدرجات تأتي من قسم البطل المجاني في التقرير، لذا تقرأ بوابة البناء منها دون فتح النتائج الكاملة. عندما تريد الحمولة الكاملة للارشفة، يُعيد GET /api/v1/reports/:id/result النتائج الكاملة لتقرير غير مقفل، ويُعيد GET /api/v1/reports/:id/download?format=json نفس الكائن كأصل قابل للتنزيل — يستحق إرفاقه بالبناء حتى يكون الفرق بين نشرين قابلًا للفحص لاحقاً.

توصيله في سير العمل

لا شيء أعلاه هو محدد لمزود CI. في GitHub Actions البوابة بأكملها خطوة واحدة تستدعي السكربت الذي لديك بالفعل:

- name: SEO audit gate
  env:
    SEOREPORT_API_KEY: ${{ secrets.SEOREPORT_API_KEY }}
    AUDIT_URL: https://example.com
  run: ./scripts/seo-gate.sh

حيث يُقدِّم seo-gate.sh، يُجري الاستطلاعات، ويختتم بالقرار:

CRITICAL=$(echo "$REPORT" | jq -r '.report.score.failingCriticalChecks // 0')
SECURITY=$(echo "$REPORT" | jq -r \
  '.report.score.domainScores[] | select(.domain == "security") | .score')

if [ "$CRITICAL" -gt 0 ]; then
  echo "::error::$CRITICAL critical checks failing"
  exit 1
fi

echo "clean — security domain at $SECURITY"

نفّذها بعد انتهاء النشر بدلاً من اختبارها على بيئة معاينة. غالباً ما يكون معاينة URL خلف مصادقة أساسية أو تحدٍ بوت، وتقرير تدقيق لا يمكنه جلب الصفحة يُبلغ بـ CRAWLER_BLOCKED بدلًا من درجة. النشر بعد التوزيع على الأصل الحقيقي أبسط وأقرب لتجربة الزاحف. شكلان متجاوران يستحقان المعرفة. إذا كان تنسيقك بالفعل على منصة استخراج، فإن ممثل Apify يُشغِّل نفس المحرك وفق جدول دون أي من هذه الروابط. وللأجهزة، نفس مفتاح الحامل يُوثِّق اتصال MCP عند https://seoreport.dev/mcp، حيث تُعلن أدوات التقرير على الاتصال — يمكن لجهاز التحقيق في انخفاض حركة المرور تشغيل التدقيق وقراءة النتائج بنفسه، وهو موثق بجانب سطح REST على صفحة المطورين.

ما لا يغطيه البوابة

تُجيب بوابة النشر على سؤال واحد: هل أدخل هذا الإصدار رجعة. إنها صامتة عن كل ما يتغير دون نشر — شهادة تنتهي صلاحيّتها، إعداد CDN مُحرّر في لوحة القيادة، نص طرف ثالث يبدأ بحظر العرض، أو هجرة منافس تغير ما يتصادم مع الكانوني الخاص بك. المراقبة حسب النطاق هي التكملة الدائمة للبوابة، وتقرأ من نفس الحساب ونفس المفتاح الموضح على صفحة المطورين. ابدأ بالنسخة الضيقة. نقطة نهاية واحدة، حقل واحد، failingCriticalChecks > 0، وexit 75 صادق عندما لا يمكن تشغيل التدقيق على الإطلاق. بوابة تُطلق مرتين في السنة وتُعتمد في كلا المرة تُستَحِق أكثر من واحدة شاملة يتعلم الجميع تخطيها.