نتيجة الطالب

ملخص تقني شامل: نظام استعلام نتائج الطلاب (Google Apps Script) للتجريب أدخل الرقم القومي هذا "12345678912345"

1. نظرة عامة على المشروع

هذا المشروع عبارة عن تطبيق ويب تفاعلي (Interactive Web App) تم بناؤه بالكامل ضمن بيئة Google (Google Workspace). الهدف الأساسي هو توفير واجهة آمنة، سريعة، ومجانية الاستضافة، تتيح للطلاب الاستعلام عن نتائجهم التفصيلية باستخدام الرقم القومي فقط.

يعالج النظام مشكلة عرض النتائج الفردية بخصوصية تامة، مع التغلب على تحديات الأداء الشائعة في التطبيقات المعتمدة على Google Sheets.

2. البنية التقنية (System Architecture)

تم تصميم النظام بفصل واضح بين الواجهة (Frontend)، والمنطق (Backend)، وقاعدة البيانات (Database)، مما يضمن سهولة الصيانة والتطوير:

قاعدة البيانات (Data Layer): Google Sheet

يُستخدم ملف Google Sheet كقاعدة بيانات علائقية بسيطة.

تم تصميم الأعمدة (Schema) لتكون قابلة للتطوير، مع تحديد أعمدة أساسية (الرقم القومي، الاسم، المدرسة،...) وأعمدة ديناميكية للمواد (اللغة العربية، الرياضيات،...).

تمت معالجة تنسيق عمود "الرقم القومي" كـ "نص عادي" (Plain Text) لتجنب أخطاء تحويل الأرقام الطويلة (Scientific Notation).

الواجهة الأمامية (Frontend): ملف index.html

هي واجهة مستخدم (UI) نظيفة ومتجاوبة (Responsive) مبنية بـ HTML, CSS, و JavaScript.

تستخدم الدالة google.script.run كجسر (Bridge) للتواصل غير المتزامن (Asynchronously) مع الخادم (Backend) دون الحاجة لإعادة تحميل الصفحة.

تتولى عرض رسائل الخطأ، ومؤشر التحميل (Spinner)، وتنسيق النتيجة النهائية في هيكل احترافي (بطاقات وجدول) عند استلام البيانات بنجاح.

المنطق الخلفي (Backend): ملف Code.gs

يحتوي على دالتين رئيسيتين:

doGet(): هي نقطة الدخول (Entry Point) للتطبيق. وظيفتها هي تقديم ملف index.html للمستخدم عند زيارة رابط النشر.

getStudentResult(nationalId): هي واجهة برمجة التطبيقات (API) الخاصة بنا. تستقبل الرقم القومي، وتقوم بعملية البحث، ثم تُرجع كائن (Object) يحتوي على بيانات الطالب أو رسالة خطأ.

3. استراتيجية الأداء الفائق (Performance & Optimization Strategy)

هذا هو الجزء الجوهري الذي يُميّز المشروع. إدراكاً للبطء المتأصل في عمليات القراءة المتكررة من Google Sheets (خاصة دالة getValues() مع آلاف الصفوف)، تم تطبيق استراتيجية تخزين مؤقت (Caching) مُحكمة من مستويين:

المستوى الأول: التخزين المؤقت (Caching)

المشكلة: كل عملية بحث كانت تتطلب قراءة كاملة للملف (I/O Operation)، مما يسبب بطئاً شديداً.

الحل: استخدام خدمة CacheService المدمجة في Apps Script.

آلية العمل:

عندما يتم طلب البيانات، يقوم الكود أولاً بالتحقق من CacheService.

إذا كانت البيانات موجودة في الذاكرة (Cache Hit)، يتم إرجاعها فوراً (استجابة في أجزاء من الثانية).

إذا لم تكن موجودة (Cache Miss)، يتم تنفيذ القراءة البطيئة من الـ Sheet لمرة واحدة فقط، ثم تخزين النتيجة في الـ Cache (بمفتاح CACHE_KEY) لمدة 10 دقائق (CACHE_EXPIRATION_SECONDS).

المستوى الثاني: التجهيز المسبق للذاكرة (Cache Warming)

المشكلة: الطالب الأول الذي يبحث بعد انتهاء مدة الـ Cache (كل 10 دقائق) سيواجه البطء (لأنه هو من يقوم بملء الذاكرة).

الحل: ضمان أن الـ Cache "دافئ" (Warm) وممتلئ بالبيانات دائماً، حتى قبل وصول أول زائر.

آلية العمل:

تم إنشاء دالة مخصصة primeCache().

تم ربط هذه الدالة بـ "مشغل زمني" (Time-based Trigger) يعمل آلياً كل 10 دقائق.

يقوم هذا المشغل بتشغيل primeCache() في الخلفية، والتي بدورها تستدعي getAllStudentData()، مما يضمن تجديد الـ Cache بانتظام.

النتيجة: استجابة شبه فورية (Instant Response) لجميع المستخدمين، بما في ذلك المستخدم الأول.

4. آلية الصيانة وتحديث البيانات (Maintainability)

لتسهيل عملية تحديث النتائج على مدير النظام (Admin) دون الحاجة للمس الكود:

المشكلة: عند إضافة أو تعديل درجات في الـ Sheet، ستظل البيانات القديمة في الـ Cache لمدة تصل إلى 10 دقائق.

الحل: تم إضافة قائمة مخصصة (Custom Menu) في واجهة Google Sheet نفسها باستخدام دالة onOpen().

آلية العمل:

يقوم المدير بتحديث الدرجات كالمعتاد.

يضغط على القائمة الجديدة (" قائمة النتائج").

يختار "مسح الذاكرة المؤقتة (Cache) الآن" (التي تستدعي دالة clearCache()).

في غضون 10 دقائق (أو أقل)، سيقوم "المشغل الزمني" بإعادة ملء الـ Cache بالبيانات الجديدة المحدثة، أو سيقوم أول باحث بعد المسح بجلبها.

5. المزايا الرئيسية

مجاني 100%: لا توجد تكاليف استضافة (Serverless).

آمن: لا يمكن لطالب رؤية نتيجة طالب آخر.

فائق السرعة: بفضل نظام الـ Cache المزدوج (Caching + Cache Warming).

سهل الصيانة: يمكن لأي شخص تحديث النتائج من Google Sheet مباشرة.

احترافي: الواجهة تضاهي المواقع المدفوعة.