https://github.com/shekohex/waq3-natiga

waq3
https://github.com/shekohex/waq3-natiga

Last synced: 12 months ago
JSON representation

waq3

• Host: GitHub
• URL: https://github.com/shekohex/waq3-natiga
• Owner: shekohex
• License: gpl-3.0
• Created: 2025-06-11T16:06:50.000Z (12 months ago)
• Default Branch: main
• Last Pushed: 2025-06-11T16:56:46.000Z (12 months ago)
• Last Synced: 2025-06-11T18:13:43.584Z (12 months ago)
• Language: TypeScript
• Homepage: https://natiga.waq3.net
• Size: 35.2 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.ar.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# اللغة: العربية

# واقع نتيجة - نظام البحث عن نتائج الطلاب

## مقدمة

واقع نتيجة هو تطبيق ويب حديث يوفر واجهة بحث موحدة لنتائج امتحانات الطلاب المصريين. يتيح النظام للطلاب وأولياء الأمور البحث عن نتائج امتحانات المرحلة الابتدائية والإعدادية من جميع المحافظات المصرية من خلال منصة واحدة وسهلة الاستخدام.

## الهدف

يعمل التطبيق كبوابة مركزية للوصول إلى نتائج امتحانات الطلاب من قاعدة بيانات الأزهر التابعة لوزارة التربية والتعليم المصرية. يبسط عملية استرجاع النتائج من خلال توفير:

- واجهة بحث موحدة للمرحلتين الابتدائية والإعدادية

- دعم جميع المحافظات المصرية

- استرجاع النتائج في الوقت الفعلي مع آليات إعادة المحاولة

- تصميم متجاوب للهواتف المحمولة وأجهزة سطح المكتب

- دعم اللغة العربية مع تخطيط من اليمين إلى اليسار

## التقنيات المستخدمة

### الخادم الخلفي

- **بيئة التشغيل**: Bun.js - بيئة تشغيل JavaScript عالية الأداء

- **إطار العمل**: Hono - إطار عمل ويب خفيف للحوسبة الطرفية

- **اللغة**: TypeScript مع دعم JSX

### الواجهة الأمامية

- **التنسيق**: Tailwind CSS - إطار عمل CSS يعتمد على الأدوات المساعدة

- **التفاعل**: HTMX - أدوات قوية لـ HTML

- **البرمجة النصية**: Hyperscript - لغة برمجة نصية مدفوعة بالأحداث

- **الأيقونات**: Lucide Icons - مكتبة أيقونات جميلة ومتسقة

### البنية التحتية

- **الحاويات**: Docker مع بناء متعدد المراحل

- **مراقبة الصحة**: نقاط نهاية مدمجة لفحص الصحة

- **الإغلاق السليم**: معالجة الإشارات للإنهاء النظيف

## نقاط النهاية

### المسارات الرئيسية

- `GET /` - الصفحة الرئيسية مع واجهة الترحيب

- `GET /search` - نموذج البحث الموحد لجميع المستويات التعليمية

- `GET /health` - نقطة نهاية فحص الصحة للمراقبة

- `POST /search-results` - معالجة طلبات البحث وإرجاع النتائج

### المسارات القديمة (إعادة التوجيه)

- `GET /indexprimary` - إعادة توجيه إلى `/search` للتوافق مع الإصدارات السابقة

- `GET /indexsecondary` - إعادة توجيه إلى `/search` للتوافق مع الإصدارات السابقة

## الميزات الرئيسية

### وظائف البحث

- **دعم متعدد المستويات**: البحث عن نتائج المرحلة الابتدائية والإعدادية

- **اختيار المحافظة**: تغطية كاملة لجميع المحافظات المصرية الـ27

- **التحقق من رقم الجلوس**: التحقق من صحة الإدخال مع متطلبات الحد الأدنى للطول

- **البحث في الوقت الفعلي**: استرجاع النتائج الفوري مع مؤشرات التحميل

### تجربة المستخدم

- **التصميم المتجاوب**: نهج يركز على الهواتف المحمولة مع تخطيطات متجاوبة

- **واجهة عربية**: دعم كامل للغة العربية مع تخطيط من اليمين إلى اليسار

- **حالات التحميل**: رسائل تحميل ديناميكية مع التناوب

- **معالجة الأخطاء**: رسائل خطأ شاملة مع اقتراحات إعادة المحاولة

### الميزات التقنية

- **آلية إعادة المحاولة**: إعادة محاولة تلقائية مع تأخير تصاعدي للطلبات الفاشلة

- **مهلة الطلب**: حماية مهلة 20 ثانية ضد الطلبات المعلقة

- **تجاوز SSL**: مكون للاتصال الداخلي للشبكة

- **الإغلاق السليم**: معالجة إشارات مناسبة للنشر الإنتاجي

### عرض النتائج

- **نتائج منظمة**: تخطيط جدول نظيف لمعلومات النتيجة

- **مؤشرات الحالة**: مؤشرات بصرية للنجاح/الرسوب مع ترميز لوني

- **التحقق الرسمي**: إشارة واضحة لمصدر النتيجة الرسمي

- **تفاصيل شاملة**: اسم الطالب والمدرسة والمحافظة والدرجات الإجمالية والحالة

## تعليمات الإعداد

### المتطلبات المسبقة

- بيئة تشغيل Bun.js مثبتة

- Docker (اختياري، للنشر المحتوى)

### التطوير المحلي

1. **تثبيت التبعيات**

   ```bash

   bun install

   ```

2. **تشغيل خادم التطوير**

   ```bash

   bun run dev

   ```

3. **الوصول للتطبيق**

   افتح http://localhost:3000 في متصفحك

### نشر Docker

1. **بناء صورة Docker**

   ```bash

   docker build -t waq3-natiga .

   ```

2. **تشغيل الحاوية**

   ```bash

   docker run -p 3000:3000 waq3-natiga

   ```

### تكوين البيئة

يستخدم التطبيق متغيرات البيئة التالية:

- `PORT` - منفذ الخادم (افتراضي: 3000)

- `NODE_TLS_REJECT_UNAUTHORIZED` - إعداد التحقق من SSL (مضبوط على "0" للشبكات الداخلية)

## اعتبارات التصميم الرئيسية

### الأداء

- **بيئة تشغيل Bun**: يستفيد من تنفيذ JavaScript عالي الأداء في Bun

- **تبعيات قليلة**: مجموعة إطار عمل خفيفة للبدء السريع

- **تجميع فعال**: عملية بناء محسنة مع بناء Docker متعدد المراحل

### الموثوقية

- **استراتيجية إعادة المحاولة**: محاولات متعددة مع تأخير ذكي

- **استرداد الأخطاء**: معالجة شاملة للأخطاء مع رسائل سهلة الفهم للمستخدم

- **مراقبة الصحة**: نقاط نهاية صحة مدمجة لمراقبة النظام

### قابلية التوسع

- **تصميم بلا حالة**: لا توجد إدارة جلسة من جانب الخادم

- **جاهز للحاويات**: تكوين Docker للتوسع السهل

- **متوافق مع الحافة**: إطار عمل Hono مصمم للنشر على الحافة

### الأمان

- **التحقق من صحة الإدخال**: التحقق من جانب الخادم لجميع مدخلات المستخدم

- **تكوين CORS**: معالجة صحيحة للأصل لاستدعاءات API الخارجية

- **تطهير الأخطاء**: عرض رسائل خطأ آمنة بدون معلومات حساسة

### إمكانية الوصول

- **دعم RTL**: اتجاه النص العربي الأصلي من اليمين إلى اليسار

- **HTML دلالي**: هيكل HTML صحيح لقارئات الشاشة

- **التنقل بلوحة المفاتيح**: دعم كامل لإمكانية الوصول بلوحة المفاتيح

- **تباين الألوان**: تصميم عالي التباين للوصول البصري

## تكامل API

يتكامل التطبيق مع واجهة برمجة التطبيقات الرسمية لنتائج امتحانات الأزهر:

- **نقطة النهاية**: `https://natiga.azhar.eg/WebService1.asmx/GetResult`

- **الطريقة**: POST مع حمولة JSON

- **المصادقة**: يستخدم رؤوس مناسبة وسلاسل وكيل المستخدم

- **تحديد المعدل**: ينفذ أنماط إعادة محاولة محترمة

## المساهمة

يتبع هذا المشروع ممارسات التطوير القياسية لـ TypeScript و React. عند المساهمة:

- حافظ على دعم اللغة العربية

- تأكد من توافق التصميم المتجاوب

- أضف معالجة أخطاء مناسبة للميزات الجديدة

- اتبع أسلوب الكود والهيكل الموجود