نظرة عامة على خط المعالجة

يعمل خط المعالجة يوميًا في الساعة 6 صباحًا بتوقيت UTC عبر GitHub Actions (validate-and-release.yml) وعند كل دفع إلى main يمس scripts/ أو config/ أو pyproject.toml. يمكن أيضًا تشغيله يدويًا مع خيارات لفرض إصدار أو تخطي اختبارات واجهة برمجة التطبيقات المباشرة.

مراحل خط المعالجة

 Download         Validate          Spectral Lint
 ┌──────┐        ┌──────────┐      ┌─────────────┐
 │ Fetch │───────▶│Schemathesis│────▶│  Discover   │
 │ specs │        │Constraints│     │  violations │
 └──────┘        └──────────┘      └─────────────┘
                                          │
                 Spectral Gate       Reconcile
                ┌─────────────┐    ┌──────────┐
                │  Enforce    │◀───│Apply fixes│
                │  thresholds │    │to specs   │
                └─────────────┘    └──────────┘
                       │
                    Release
                 ┌──────────┐
                 │  Package  │
                 │  & tag    │
                 └──────────┘

1. التنزيل

يقوم scripts/download.py بجلب ملف ZIP الخاص بمواصفات F5 XC OpenAPI الرسمية من docs.cloud.f5.com. يستخدم ترويسات HTTP ETag لطلبات GET المشروطة — إذا لم تتغير الحزمة المصدرية، يتم تخطي التنزيل. تُوضع ملفات JSON المستخرجة في specs/original/.

2. التحقق

يُنظم scripts/validate.py نوعين من الاختبارات مقابل واجهة برمجة تطبيقات F5 XC المباشرة:

• Schemathesis — اختبار قائم على الخصائص يولّد حمولات عشوائية صالحة/غير صالحة وفقًا للمواصفة ويتحقق مما إذا كانت واجهة برمجة التطبيقات تتوافق مع قيود المواصفة.
• التحقق من القيود — اختبارات موجهة لجميع فئات قيود OpenAPI العشر (طول السلسلة النصية، النمط، الحدود الرقمية، الحقول المطلوبة، التعدادات، حدود المصفوفات، بنية الكائنات، التركيب، التبعيات، أنواع البيانات).

تُكتب التناقضات في reports/validation_report.json.

3. فحص Spectral (الاكتشاف)

يُشغّل scripts/spectral_lint.py --mode discover واجهة سطر أوامر Spectral مقابل المواصفات الأصلية باستخدام spectral-pipeline.yaml. يكتشف هذا مشاكل جودة OAS3 — كتل الخوادم المفقودة، معلومات الاتصال المفقودة، العمليات غير المُعلَّمة، مخططات المكونات غير المستخدمة، معرّفات العمليات المكررة، الأمثلة غير الصالحة، ووسوم البرمجة النصية في الأوصاف.

تُحوَّل الانتهاكات إلى كائنات Discrepancy وتُكتب في reports/spectral_report.json. راجع قواعد Spectral للاطلاع على مجموعة القواعد الكاملة.

4. التسوية

يستهلك scripts/reconcile.py ملفي التقارير ويطبق الإصلاحات على كل مواصفة:

• إصلاحات القيود تُعدّل قيود المخطط (تخفيف، تشديد، إضافة، إزالة) بناءً على سلوك واجهة برمجة التطبيقات المُلاحَظ. راجع الإصلاحات المُطبَّقة.
• إصلاحات Spectral تُثري المواصفات بالخوادم ومعلومات الاتصال والعلامات وبيانات الأمان الوصفية وتزيل المكونات الميتة.
• بيانات الأمان الوصفية تُحقن دائمًا إذا كان تكوين security_scheme موجودًا، حتى عندما لا يُبلّغ Spectral عنها.

تُكتب المواصفات المُصلَحة في release/specs/ وتُتحقق باستخدام openapi-spec-validator قبل الحفظ. إذا فشلت مواصفة مُصلَحة في التحقق، تُستخدم المواصفة الأصلية كبديل.

5. بوابة Spectral

يُعيد scripts/spectral_lint.py --mode gate تشغيل Spectral مقابل المواصفات المُسوَّاة في release/specs/. تتحقق البوابة من عدد الأخطاء والتحذيرات مقابل عتبات قابلة للتكوين (spectral.gate.max_errors و spectral.gate.max_warnings في validation.yaml).

ملاحظة

المرحلة 1 (الحالية): العتبات هي null (تحذير فقط). عيّن max_errors: 0 لفرض بوابة خالية من الأخطاء.

6. الإصدار

يُعبّئ scripts/release.py المواصفات المُسوَّاة في أرشيف ZIP مُرقَّم. تستخدم الإصدارات التنسيق YYYY.MM.DD-<patch> المُشتق من تاريخ بيانات المواصفة المصدرية الوصفية. يتضمن الإصدار:

• ملفات مواصفات النطاقات الفردية (268 ملف JSON)
• ملف openapi.json مدمج يجمع جميع النطاقات
• ملف CHANGELOG.md يسرد كل إصلاح مُطبَّق
• ملخص VALIDATION_REPORT.md

تُنشئ مهمة CI إصدار GitHub مع ملف ZIP المُرفق، مُعلَّمًا بـ v<version>. يمنع تجزئة المحتوى الإصدارات المكررة عندما لا يتغير شيء.

تحديث التوثيق

تولّد مهمة CI موازية ملف docs/01-validation-report.mdx من تقارير التحقق باستخدام scripts/generate_docs.py، ثم تفتح طلب سحب إذا تغير المحتوى.