# بدء التنفيذ واختبارات القبول المشتركة

## ما يحتاجه فريق المنصة

يرجى الرد بالمعلومات التالية، دون إرسال كلمات مرور أو بيانات طلاب:

- اسم التقنية أو لغة الخادم، والجهة التقنية المسؤولة عن تنفيذ الربط.
- الخيار المفضل: منح Gradally وصول قراءة لجدول الإجابات وجدول نتائج للكتابة (الخيار أ، بلا تطوير عندكم)، أم إرسال كل إجابة بطلب HTTPS مخصص بجسم JSON ورمز Bearer (الخياران ب وج)؟
- للخيار أ: نوع قاعدة البيانات، وأسماء الجدول أو العرض وأعمدته الستة (معرّف الصف، المحاولة، السؤال، النص، وقت التحديث، الامتحان)، وهل تتاح نسخة replica.
- طريقة تعريف الامتحان والسؤال ومحاولة الطالب وخانة الإجابة؛ يكفي مثال مصطنع.
- هل يحتفظ الخادم بحدث إرسال دائم وطابور مهام وإعادة محاولات؟ وهل يستطيع متابعة نتائج بالخلفية؟
- حجم الاندفاع المتوقع بعد الكويز: عدد الإجابات في الدقيقة ونطاق التأخير المقبول، لا المتوسط الشهري فقط.
- طريقة تخزين نتيجة ظل منفصلة عن الدرجة الظاهرة للطالب، ومن يستطيع اعتماد عقد النشر لاحقًا.
- عنوان بيئة الاختبار وعناوين الخروج الشبكية إن كانت هناك حاجة إلى قوائم سماح. للخيار ب: عنوان استقبال الـwebhook (HTTPS) وعنوان IPv4 العام له؛ سر التوقيع يُسلَّم منفصلًا.

## ما يقدمه فريق Gradally قبل تجربة الاتصال الفعلية

عنوان المنصة الخاص `https://<رمزكم>.gradally.io` (عملية وقاعدة بيانات مستقلتان على خادم Gradally الإنتاجي)، وامتحان تجريبي بمفتاح مُجهز، وربط أسئلة متفق عليه، و`stream_id` وسر ربط عشوائي يُسلَّمان مرة واحدة عبر قناة منفصلة، وجهة تواصل تشغيلية: contact@gradally.io. لا تحتوي هذه الحزمة تلك الأسرار. إعداد الامتحان والربط يتم بواسطة فريق Gradally؛ إنشاء الامتحان بالـAPI ليس جزءًا من الإصدار.

## المرحلة الأولى — النقل واستلام النتائج

تُجرى كلها على إجابات مصطنعة، دون تعديل الدرجة الظاهرة للطالب.

| الحالة | النتيجة المتوقعة |
|---|---|
| Manifest برمز صحيح | معرفات الأسئلة وبصماتها دون تسريب المفتاح |
| رمز ناقص أو غير صالح أو موقوف | 401؛ جلسة المدرس لا تعوض الرمز |
| إرسال إجابة الإصدار 1 | 202 وإيصال؛ ليس وعدًا بدرجة فورية |
| إعادة نفس الطلب بعد افتراض انقطاع | 200 ونفس الإيصال، دون تكرار |
| نفس الهوية والإصدار مع نص مختلف | 409 والإجابة السابقة محفوظة |
| الإصدار 3 قبل 2 | 409؛ لا يتجاوز نسخة مفقودة |
| بصمة سؤال خاطئة أو نقل هوية الإجابة لسؤال آخر | 409 |
| مرفق أو حقل إضافي أو JSON غير صالح | رفض، دون إجابة جديدة |
| اندفاع يتجاوز حصة الاختبار | 429 وRetry-After؛ العودة لاحقًا بالطلب نفسه آمنة |
| استنفاد حصة قراءة النتائج والتأكيدات | 429 وRetry-After على مسارات التسليم؛ تبقى حصة استقبال الإجابات منفصلة |
| متابعة إجابة بعد استلامها | حالة processing ثم الحالة الحالية عند توفرها |
| نتيجة غير متاحة | حالة unavailable دون تحويلها إلى صفر أو إنشاء درجة نهائية |
| سحب أكثر من صفحة | لا تخطي للإيصالات؛ مؤشرا النتائج والتغييرات منفصلان |
| توقف مستهلك التغييرات ثم عودته | يعيد من مؤشر محفوظ مع منع تكرار التخزين |
| نتيجة جاهزة محفوظة في الظل ثم إقرار | 201؛ إعادة الإقرار نفسه 200 |
| إقرار منتهي أو نتيجة تغيرت | 409، ثم جلب الحالي وتحديث تخزين الظل |
| تعديل إجابة الطالب إلى الإصدار 2 | إيصال جديد؛ السابق superseded ولا يكتب فوق الجديد |
| تعديل المفتاح أو بطلان دليل | يتغير السياق/الحالة، وتبطل صلاحية القيمة السابقة عند المزامنة |
| رمز أو مؤشر أو إيصال من ربط آخر | لا يحصل العميل على بيانات الربط الآخر |
| الخيار أ: خطة الموصّل | تعرض الجدول والأعمدة والخريطة المتفق عليها دون كتابة |
| الخيار أ: أول تشغيل | إيصال لكل إجابة مربوطة؛ لا شيء لامتحان آخر أو سؤال غير مربوط؛ لا يُقرأ أي عمود شخصي |
| الخيار أ: تعديل إجابة | صف الإصدار 2 في جدول النتائج والإصدار 1 يصبح superseded |
| الخيار ب: webhook بتوقيع خاطئ أو زمن قديم | يُرفض دون تخزين |
| الخيار ب: webhook صحيح ثم تكراره | يُخزَّن مرة واحدة والرد 2xx في الحالتين |
| أي نجاح في الاختبار | publishable=false؛ لا نشر نهائي |

اختبارات Gradally المحلية تغطي أجزاء من هذه الحالات. قبول المنصة يحتاج تنفيذها عبر خادمها ومخزنها وطوابيرها، خصوصًا حفظ المؤشر والإقرار وإعادة الإرسال؛ لا يثبته Postman وحده.

## المرحلة الثانية — تجربة ظل متفق عليها

بعد نجاح النقل، تُحدَّد عينة مخوّلة، وسياسة البيانات، ومعايير قبول جودة النتائج والزمن. يتفق الطرفان على نطاق الخدمة قبل توسيع التجربة؛ اختبارات النقل لا تمثل وحدها قبولًا لجودة التصحيح أو سعة التشغيل.

## المرحلة الثالثة — عقد النشر

يتفق الطرفان على من يملك صلاحية النشر، وكيف يعالج تعديل الطالب أو المفتاح بعد النشر، والاسترجاع والتعليق والمراجعة التشغيلية، ومسؤولية كل طرف. يظل `publishable=false` حتى تنفيذ واعتماد هذا العقد. لا تُغيّر المنصة هذه القيمة محليًا لتجاوز المرحلة.