MockForward — خادم محاكاة التكامل الخارجي غير المتزامن

01 · البداية السريعة

ثلاثة أوامر، والخادم يعمل

يستخدم MockForward قاعدة بيانات SQLite جاهزة مسبقاً — لا حاجة لأي إعداد إضافي.

$composer installتثبيت الاعتماديات

$php artisan migrateإنشاء جداول المحاكاة

$php artisan serve

الخادم يعمل الآن على http://localhost:8000 — والمفتاح الثابت للمصادقة test-api-key-2024

02 · المصادقة

أربعة أنماط، مفتاح واحد

أرسل المفتاح الثابت test-api-key-2024 بأي نمط من الأنماط الأربعة. أي مفتاح خاطئ يعيد 401 Unauthorized.

Type 01

بدون مصادقة

أي طلب يصل بدون ترويسة مصادقة يُقبل مباشرة — مناسب للاختبار السريع.

# لا ترويسات مطلوبة POST /api/v1/track

Type 02

Bearer Token

المفتاح يُرسل كرمز Bearer في ترويسة Authorization.

Authorization: Bearer test-api-key-2024

Type 03

API Key

المفتاح يُرسل مباشرة في ترويسة مخصصة X-API-Key.

X-API-Key: test-api-key-2024

Type 04

Basic Auth

المفتاح مُرمّز بـ Base64 بصيغة apiKey: ثم يُرسل في الترويسة.

Authorization: Basic base64(apiKey:)

03 · أنماط التكامل

ثلاثة أنماط تحاكي الواقع

أنظمة التكامل الخارجية تختلف في بنيتها — MockForward يغطي الأنماط الثلاثة الأكثر شيوعاً.

PATTERN 1

نقطة واحدة

نفس النقطة للإرسال والاستعلام — الرد المباشر بدون ticketId.

POST/api/v1/track

↳ يرد بالحالة مباشرة: completed / processing / error

PATTERN 2

نقطتان

إرسال أولي يعيد ticketId، ثم نقطة منفصلة للتحقق من الحالة.

POST/api/v1/submit

↳ يعيد: TKT-XXXXX

GET/api/v1/status/{ticketId}

↳ state: done / pending / error

PATTERN 3

ثلاث نقاط

كالنمط الثاني، لكن النتيجة النهائية تُجلب من نقطة ثالثة مستقلة.

POST/api/v1/submit

↳ TKT-XXXXX

GET/api/v1/status/{ticketId}

↳ عند completed ننتقل للنتيجة

GET/api/v1/result/{ticketId}

04 · النقاط الطرفية

ست نقاط تغطي كل شيء

جميع الردود بصيغة JSON، وكل رد يحمل ترويسة X-Request-Id للتتبع.

POST/api/v1/trackPattern 1 — إرسال واستعلام

POST/api/v1/submitPatterns 2 & 3 — الإرسال الأولي

GET/api/v1/status/{ticketId}التحقق من حالة التذكرة

GET/api/v1/result/{ticketId}جلب الرد النهائي

POST/api/v1/auth-testاختبار نوع المصادقة المُرسلة

GET/api/v1/scenariosقائمة السيناريوهات المدعومة

X-Idempotency-Key

أرسل مفتاحاً فريداً مع الطلب — الطلب المكرر بنفس المفتاح يعيد نفس الرد المخزّن دون معالجة جديدة.

X-Test-Scenario

ترويسة واحدة تتحكم في سلوك الخادم بالكامل — نجاح فوري، تأخير، فشل شبكة، أو JSON معطوب.

05 · السيناريوهات

سبعة سيناريوهات، كل الحالات الواقعية

حدّد السيناريو عبر ترويسة X-Test-Scenario — اللون يعكس الحالة النهائية في نظامك.

success-immediate

يرد فوراً بالنجاح — الطلب يكتمل من أول محاولة.

Completed200 OK

success-delayed

processing في البداية، ثم يكتمل بعد 3 دورات تحقق — نجاح متأخر.

InProgress → Completed200 OK

pending-loop

يبقى في حالة processing للأبد — لاختبار مهلة الانتظار في نظامك.

InProgress ∞200 OK

logical-failure

فشل منطقي في كل مرة — الحالة error ويُعاد الطلب.

Failedstate: error

network-failure

انقطاع الخدمة تماماً — يرد 503 مع Retry-After وبدون JSON.

Failed ⚠503 · Retry-After: 30

logical-then-fix

ثلاثة أخطاء متتالية ثم ينجح — يختبر عدّاد المحاولات و FailedFinal.

Failed → Completed3 × error

wrong-json

يرد 200 لكن ببنية JSON غير متوقعة — الـ JSON Path لا يجد قيمته.

Failed200 · bad payload

06 · أمثلة جاهزة

انسخ والصق — يعمل مباشرة

أمثلة curl حقيقية لكل نمط مصادقة. شغّل الخادم ثم جرّب أي مثال.

# بدون مصادقة — نجاح فوري (Pattern 1)
curl -X POST http://localhost:8000/api/v1/track \
  -H "Content-Type: application/json" \
  -H "X-Test-Scenario: success-immediate" \
  -d '{"customerName":"أحمد","amount":1500}'

# ← { "status": "completed", "data": { "transactionId": "TRX-12345", "amount": 1500 } }
# Bearer Token — نجاح متأخر (Pattern 2)
curl -X POST http://localhost:8000/api/v1/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-api-key-2024" \
  -H "X-Test-Scenario: success-delayed" \
  -d '{"customerName":"أحمد"}'

# ← { "data": { "ticketId": "TKT-12345" }, "status": "processing" }
# API Key + Idempotency — أخطاء ثم نجاح
curl -X POST http://localhost:8000/api/v1/track \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-api-key-2024" \
  -H "X-Idempotency-Key: log-abc-123" \
  -H "X-Test-Scenario: logical-then-fix" \
  -d '{"customerName":"أحمد","amount":1500}'

# كرر نفس الطلب ← نفس الرد المخزّن، بدون معالجة جديدة
# Basic Auth — انتظار لا نهائي (base64 للصيغة "test-api-key-2024:")
curl -X POST http://localhost:8000/api/v1/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic dGVzdC1hcGkta2V5LTIwMjQ6" \
  -H "X-Test-Scenario: pending-loop" \
  -d '{"customerName":"أحمد"}'
# التحقق من الحالة (Patterns 2 & 3)
curl http://localhost:8000/api/v1/status/TKT-12345 \
  -H "Authorization: Bearer test-api-key-2024"

# جلب النتيجة النهائية (Pattern 3)
curl http://localhost:8000/api/v1/result/TKT-12345 \
  -H "Authorization: Bearer test-api-key-2024"

# اختبار نوع المصادقة
curl -X POST http://localhost:8000/api/v1/auth-test \
  -H "Authorization: Bearer test-api-key-2024"
# ← { "authType": "bearer", "valid": true }