دليل الاستخدام والاختبار

1 الإعداد الأولي

خطوات لازم تتعمل مرة واحدة بعد تفعيل البلجن. كل خطوة بتفتح اللي بعدها.

1. فعّل البلجن من Plugins → Taalam → Activate
   • أول page load بيشغّل migrations 2.0.0 → 2.0.17 ويبني 25+ جدول + 80+ index.
   • الـ cron tasks بتتسجّل تلقائياً (daily 04:00، weekly Sunday 03:00، broadcast كل 5 دقايق، monthly day-1 03:00).
2. سجّل دخول كـ WP administrator على /login
   • هيتم redirect تلقائي على /admin/dashboard (لوحة السوبر-أدمن).
3. (اختياري) شغّل الـ demo seeder من /admin/dashboard → "Reset Demo"
   • بيولّد 3 سناتر + 3 مديرين + 6 موظفين + 6 مدرسين + ~30 طالب + 90 يوم past attendance + dues + payments.
   • الكريدنشيالز تظهر في flash message: demo_manager_1 / Demo@123 وهكذا.
   • يضمن جلسة واحدة على الأقل اليوم لكل سنتر (للاختبار الفوري).
4. أضف سنتر من السناتر (مثلاً "سنتر النور").
5. أضف مدير من المديرين
   • الاسم + الإيميل + كلمة مرور 8+ حرف.
   • اربطه بسنتر أو أكتر (multi-tenant).
6. اضبط Wapilot وقوالب الواتساب من الإعدادات العامة
   • API key + sender phone للـ Wapilot.
   • قوالب الـ 7 رسائل (حضور، غياب، دفعة، تذكير، متأخرات، ترحيب، غياب متكرر) — لو سبتها فاضية، النظام بيستخدم قوالب عربية افتراضية.
7. سجّل خروج ودخل بحساب المدير على /login → redirect على /center/dashboard.
8. المدير يكمّل إعداد السنتر بالترتيب ده:
   • المواد (فيزياء، رياضة…)
   • القاعات (قاعة 1، قاعة 2…)
   • المدرسين + عقود التعويض
   • الموظفين + صلاحياتهم (8 خانات)
   • المجموعات + الجدول الأسبوعي
   • الطلاب + اشتراكاتهم
   • الإجازات (أيام رسمية)
9. توليد الحصص من الجدول → اضغط "توليد الحصص" (للأسبوعين الجايين). الـ daily cron بعد كده بيكمّل تلقائياً.
10. فعّل التذكيرات التلقائية من إعدادات السنتر → toggles: تذكير الدفع، المتأخرات، الترحيب، الغياب المتكرر.

لوحة front-end كاملة بنفس التصميم. wp-admin مش محتاج (بيظهر notice فيه redirect).

الصفحات (10)

سيناريوهات الاختبار

1. سجّل دخول بحساب WP administrator على /login → redirect على /admin/dashboard ✓
2. /admin/centers → "إضافة سنتر" → "اختبار-1" → ظهر بحالة "نشط"
3. اضغط "تعطيل" → بيظهر "معطل" + الزر بقى "تفعيل"
4. تأكد من عدم وجود زرار "حذف" ⚠️ (قرار التصميم)
5. /admin/managers → ضيف مدير + اختار 2 سناتر → الـ user اتعمل وقدر يدير الاتنين
6. /admin/security → كل محاولة login (سواء عبر /login أو wp-login.php) بتـ-سجّل ✓
7. /admin/activity → كل create/update/delete مع user + IP + timestamp ✓
8. /admin/settings → "نسخة احتياطية الآن" → بيتولّد ملف .zip أو .sql.gz في uploads/sca-backups/
9. /admin/whatsapp → فلترة على status=failed → اضغط "إعادة محاولة" على رسالة فاشلة

بعد login المدير بيتـ redirect هنا تلقائياً. عنده 21 صفحة + center switcher لو مدير لأكتر من سنتر + جرس إشعارات + بحث شامل.

الصفحات (21)

أ. إعداد البيانات الأولية

1. أضف 3 مواد: فيزيا (لون أحمر) + رياضة (لون أزرق) + كيميا (لون أخضر)
2. أضف 2 قاعات: قاعة 1 (سعة 30) + قاعة 2 (سعة 20)
3. أضف مدرس "أ.محمد" بـ password 8+ حرف، عقد 50% commission
4. (اختياري) من صفحة المدرس → "التوفر" → الجمعة "غير متاح" → الـ generator هيـ-skip الجمعة لـ أ.محمد
5. أضف موظف "حسن" بصلاحيات: record_attendance + collect_payments + view_dues
6. أضف مجموعة "3 ث - فيزيا - السبت 10ص" (المادة فيزيا، أ.محمد، قاعة 1، السبت 10:00-12:00، 200/شهر)
7. أضف 3 طلاب → افتح صفحة المجموعة (تعديل) → استخدم قسم "إضافة طالب" فيها (الجديد) لإضافة الـ 3 (بدل ما تروح صفحة كل طالب)
8. روح الجدول → "توليد الحصص" → السبت الجاي session بيظهر
9. أضف إجازة "عيد الفطر" بتاريخ معيّن → الـ generator هيـ-skip اليوم ده

ب. اختبار الـ flow المالي الكامل

1. روح المستحقات → اختر شهر الحالي → "توليد الشهر" → 3 dues بـ 200 ج.م
2. افتح تقرير الأعمار → الـ buckets ظاهرة (0-30 يوم لو الشهر ده)
3. روح المدفوعات → "تحصيل دفعة" → اختار طالب 1 → اختار الـ due المعلق → سدد 200 → الـ due يتحول مدفوع
4. طبع الإيصال (Receipt#: YYYY-MM-NNN auto-generated) → حقول كاملة + رقم القيد
5. روح أرباح المدرسين → اختر الشهر → "احسب الشهر" → أ.محمد له 100 ج.م (50% × 200)
6. اضغط اسم المدرس → drill-down: كل الجلسات + كل الدفعات
7. اضغط "دفع" على صف أ.محمد → سدد 100 → الحالة "مدفوع"
8. أضف مصروف: إيجار 1000 ج.م
9. روح التقارير → P&L: 200 إيراد − (100 + 1000) = −900
10. اضغط "تنزيل CSV" → ملف بـ UTF-8 BOM (Excel-friendly)

ج. اختبار Multi-center

1. السوبر-أدمن أضاف سنتر تاني وربط نفس المدير
2. المدير يـ logout/login → في الـ topbar بيظهر center switcher (dropdown بالسنترين)
3. بدّل للسنتر التاني → كل الـ data تتغير (طلاب، مدفوعات، إلخ)
4. تأكد إن طلاب السنتر A ما بيظهروش في السنتر B ✓

بعد login الموظف بيتـ redirect على /center/attendance. الـ navigation محدودة بـ 5 صفحات حسب صلاحياته.

الصلاحيات الـ Granular (8)

سيناريوهات الاختبار

1. المدير يعمل موظف "حسن" بصلاحية record_attendance + view_students فقط
2. اعمل logout بحساب المدير، ادخل بحساب حسن
3. روح /center/attendance → الترتيب الجديد: حصص اليوم فوق (للـ roster الكامل) + التسجيل السريع تحت (للـ door scan)
4. اضغط "تسجيل الحضور" بجوار session → افتح roster كل الطلاب → سجّل دفعة واحدة
5. أو: استخدم الـ scan/code form للحالات الفردية (طالب واحد بكوده)
6. جرّب تروح /center/payments → 403 (مفيش collect_payments) ✓
7. المدير يضيف صلاحية collect_payments لحسن
8. حسن يـ refresh → دلوقتي يقدر يحصّل
9. حسن يحصّل دفعة → بتسجل بـ received_by_user_id = حسن
10. روح /center/payments → في الـ stats بيظهر "في صندوقي اليوم" (الإجمالي اللي حسن استلمه فقط)

المدرس بيشوف بياناته فقط: العقود، الأرباح المحسوبة، الدفعات المستلمة. مفيش صلاحية تعديل، مفيش center switcher (كل السناتر بتظهر مع بعض).

سيناريوهات الاختبار

1. تأكد إن المدير عمل عقد لـ أ.محمد + ضيفه لمجموعة فعّالة
2. يكون فيه تحصيل + توليد أرباح + دفعة لـ أ.محمد
3. اعمل logout، ادخل بحساب أ.محمد
4. هتلاقي اللوحة فيها card لكل سنتر هو شغال فيه:
   • اسم السنتر + نوع العقد ("نسبة 50% من إيراد طلابك")
   • إجمالي الأرباح + المعلق
   • جدول آخر 12 شهر (حصص، إيراد، صافي، حالة)
   • جدول آخر الدفعات المستلمة
5. جرّب تروح /center/dashboard → redirect لـ /teacher/dashboard ✓
6. جرّب تروح /center/students → redirect ✓

Multi-center للمدرس

لو أ.محمد بيدرّس في 2 سناتر (عنده عقدين):

• هيشوف 2 cards منفصلين، كل واحد فيه أرباحه من السنتر ده
• الإجماليات لكل سنتر مستقلة (مفيش data leakage بين السناتر)
• الـ center switcher dropdown مخفي للمدرس (مش محتاجه — كل السناتر ظاهرة في الصفحة)

صفحة عامة بدون login — الرابط فيه token مميز لكل طالب. ولي الأمر بيشوف بيانات ابنه فقط، read-only.

المحتوى

• 4 KPI cards: حضور / تأخير / غياب (آخر 60 يوم) / إجمالي المتأخرات
• سجل الحضور آخر 60 يوم (التاريخ، المجموعة، المادة، الحالة)
• سجل المدفوعات آخر 12 شهر (المبلغ، النوع، الفترة)
• المتأخرات غير المسددة (لو فيه)
• Layout مخصص responsive — مفيش sidebar أو session UI

سيناريوهات الاختبار

1. المدير يفتح /center/students → بروفايل طالب → عند "رابط ولي الأمر" يضغط زرار "نسخ" (الجديد)
2. افتح الـ URL في tab خاص (no session) → بيرسم صفحة الطالب كاملة ✓
3. جرّب token غلط: /parent/INVALID → 404 themed (مفيش data leakage) ✓
4. المدير يضغط "تجديد" على الـ token → الرابط القديم بيبطل، الجديد يشتغل ✓

7 التواصل والإشعارات

قنوات التواصل مع الأهالي (واتساب) والإشعارات الداخلية للمستخدمين.

أ. التذكيرات التلقائية (cron) — Phase 19

الـ daily cron بيـ-fire كل يوم 04:00 ويبعت 4 أنواع تذكيرات بشروط محددة:

الـ flow:

1. السوبر-أدمن في /admin/settings يضبط Wapilot + (اختياري) قوالب مخصصة. لو سابهم فاضيين → يستخدم الـ قوالب العربية الافتراضية المضمنة.
2. المدير في /center/settings يفعّل toggles: تذكير الدفع، المتأخرات، الترحيب، الغياب المتكرر
3. كل توكن متاح في القوالب: {student_name} {center_name} {amount} {period} {days} {streak} {group_name} {date} {time}
4. اختبر بـ trigger يدوي: WP-Cron page → run sca_daily_tick
5. راجع /center/whatsapp → بتلاقي الرسائل المرسلة بـ status=sent (أو skipped لو الـ phone فاضي)

ب. الإعلانات الجماعية (Broadcast) — Phase 20

• المدير من /center/broadcast يضغط "إعلان جديد"
• scope: السنتر كله (كل الأهالي) أو مجموعة محددة
• الـ message بيتقسّم لـ queue في sca_broadcast_queue
• الـ sca_broadcast_tick cron (كل 5 دقايق) بيرسل 50 رسالة في الـ batch — pacing آمن لـ Wapilot
• صفحة الـ broadcast بتعرض progress: sent / total، meta-refresh كل 10 ثواني وقت ما الـ status=running
• 2000 طالب يخلصوا في ~3.5 ساعة

ج. سجل الواتساب (WhatsApp Logs) — Phase 21

• السوبر-أدمن: /admin/whatsapp — كل الرسائل عبر السناتر
• المدير: /center/whatsapp — رسائل سنتره فقط
• Filters: status (sent/failed/skipped) + event_type + date range + اسم الطالب
• زرار "إعادة محاولة" لرسالة فاشلة → بيـ-create insert جديد (مش mutate القديم — preserves history)
• Stats cards: 24-hour window (sent / failed / skipped)

د. الإشعارات الداخلية (Notifications Inbox) — Phase 22

• Bell icon في الـ topbar (لكل الأدوار) مع red dot + count لو فيه unread
• Dropdown بآخر 10 إشعارات + click على واحد بيـ-mark as read + يفتح اللينك
• صفحة كاملة على /notifications مع pagination + "علّم الكل"
• JS بيـ-poll كل 30 ثانية لتحديث الـ badge
• Trigger points: session.cancel، payment.create لو > 1000، broadcast.done، backup.create، student.create

8 الكالندر والبحث

أ. عرض الكالندر للجدول — Phase 23

• /center/schedule فيه 3 views: قائمة (default) / أسبوع / شهر
• الأسبوعي: شبكة 7 أعمدة × ساعات 8:00-22:00، الحصص ملوّنة بـ subject_color
• الشهري: 7×5 grid مع dots للأيام المزدحمة
• الاختيار محفوظ في cookie sca_schedule_view
• click على حصة يفتح صفحة الـ session

ب. البحث الشامل (Global Search) — Phase 24

• شريط بحث في الـ topbar — debounce 300ms
• AJAX endpoint: sca_global_search بيرجّع JSON بـ 4 categories: students / teachers / groups / payments
• كل category top 5 results — scoped على الـ active center
• السوبر-أدمن: بحث عبر كل السناتر
• الـ keyboard navigation (Arrow + Enter)
• Receipt number search مدعوم (مثلاً 2026-04-001)

9 الامتحانات والواجبات والمواد

أ. الامتحانات (/center/exams)

• إنشاء امتحان: عنوان، مادة، مجموعة، تاريخ، درجة كاملة
• تسجيل درجة لكل طالب (مع notes)
• إحصائيات: متوسط، أعلى، أقل

ب. الواجبات (/center/homework)

• تكليف للمجموعة كاملة مع موعد تسليم
• تتبع التسليمات per طالب (submitted / late / not submitted)
• درجات اختيارية

ج. المواد التعليمية (/center/materials)

• ملفات / روابط YouTube / PDFs
• ربط بمجموعة أو متاحة لكل المجموعات
• الطالب يقدر يشوفها من بوابة ولي الأمر (لاحقاً)

د. تقارير الطلاب (/center/students/{id}/progress)

• تقرير شهري printable: نسبة الحضور + درجات الامتحانات + الواجبات + المتأخرات
• قابل للطباعة بـ note شخصية من المدرس

10 الإدارة المتقدمة

أ. الإجازات وتوفر المدرسين — Phase 25

• /center/holidays: إضافة إجازة (تاريخ + اسم + recurring اختياري)
• is_recurring=1 = نفس اليوم كل سنة (الأعياد الرسمية)
• الـ session_generator بيشيك قبل ما يخلق جلسة → لو يوم إجازة → skip
• صفحة المدرس → "التوفر" → 7 checkboxes (الأحد-السبت) + reason field — الـ generator بيـ-skip أيام عدم التوفر

ب. النسخ الاحتياطية

• الـ weekly cron (Sunday 03:00) بيعمل backup تلقائي للـ sca_* tables فقط
• 3 fallback paths: mysqldump shell → PHP fallback → uncompressed SQL
• نتيجة: .zip (لو ZipArchive متاح) أو .sql.gz أو .sql
• تخزين في wp-content/uploads/sca-backups/ + .htaccess deny + index.html
• Cleanup تلقائي: backups أقدم من 30 يوم بتنحذف
• السوبر-أدمن من /admin/settings يقدر يعمل backup يدوي + يحمّل أي ملف
• الـ download endpoint محمي بـ role check + path traversal protection

ج. Activity Log (/admin/activity)

• كل create / update / delete / archive / restore بيتـ-log
• الحقول: action + entity_type + entity_id + user + IP + occurred_at + before/after JSON
• Filters: action / entity / center / تاريخ
• الـ super-admin بيشوف الكل، المدير بيشوف سنتره فقط (/center/activity)

د. Security Log (/admin/security)

• كل محاولة تسجيل دخول بتتـ-log (نجاح / فشل / محظور)
• الحقول: user_id / identifier / IP / user_agent / status / attempted_at
• Rate limiting: 5+ محاولات فاشلة من نفس IP في 15 دقيقة → block 30 دقيقة
• بيلتقط محاولات الـ wp-login.php كمان (مش بس /login المخصص)

هـ. Health Check (/admin/health)

• سناتر معطّلة، مديرين بدون سنتر، مدرسين بدون عقد
• حصص ملغاة في آخر 30 يوم
• dues معلقة + aging
• backup الأخير + size + age

و. Forgot Password

• الـ flow القياسي: /wp-login.php?action=lostpassword
• الـ link في صفحة /login بيوجّه ليه
• الإيميل من WordPress core — يشتغل من غير setup إضافي لو SMTP مظبوط

11 اختبار النظام (E2E)

السيناريوهات دي بتختبر سلوك السلامة (security + multi-tenancy + edge cases). اتعمل عليهم E2E شامل لكل الـ 5 لوحات.

أ. Multi-tenancy isolation Track A

1. سنتر A ومدير A، سنتر B ومدير B (منفصلين)
2. مدير A يضيف طالب → معرف الطالب = X
3. مدير B يفتح URL: /center/students/edit?id=X → redirect مع flash "الطالب غير موجود في سنترك" ✓
4. مدير B يحاول POST لـ /center/students/save بـ id=X → يرفض ✓

ب. Permission gates للموظفين Track D

1. موظف بصلاحية view_students فقط
2. /center/students → ✓ يشوف القائمة
3. POST /center/students/save → 403
4. /center/payments → 403 (مفيش view_dues)
5. /center/dues → 403

ج. Payment over-application validation Track B

1. طالب عليه dues إجمالي 500 ج.م
2. افتح /center/payments/new?student_id=X
3. اختار dues مجموعها 500، أدخل المبلغ 200
4. اضغط تأكيد → يرفض برسالة "قيمة المستحقات (500) أكبر من مبلغ الدفعة (200)" ✓
5. اختار due واحد بقيمة 200 → ✓ ينجح

د. Session cancel block (بعد الحضور) Decision 2

1. session مولّد + حضّر طالب فيه
2. روح الجدول → اضغط "إلغاء" → يرفض "لا يمكن إلغاء حصة تم تسجيل حضور فيها" ✓
3. session تاني بدون حضور → اضغط "إلغاء" → ✓ ينجح

هـ. Teacher contract block (لو فيه مجموعات شغالة) Decision 3

1. مدرس له عقد + مجموعة فعّالة
2. روح /center/teachers → اضغط "إيقاف" → يرفض "فيه N مجموعة شغالة، حوّلها لمدرس آخر أو عطّلها أولاً" ✓
3. عطّل المجموعة → اضغط "إيقاف العقد" تاني → ✓ ينجح

و. Soft-delete student cascade Track E

1. طالب مسجل في 3 مجموعات
2. أرشف الطالب → الـ 3 enrollments بتتعطّل (end_date = اليوم)
3. روح المستحقات → "توليد الشهر القادم" → الطالب ما يطلعش ✓
4. اضغط "استعادة" على الطالب → الـ 3 enrollments بترجع نشطة (end_date = NULL) ✓

ز. Room conflict detection Phase 3

1. مجموعة A: قاعة 1، السبت 10-12
2. مجموعة B: قاعة 1، السبت 11-13 (متداخلة)
3. روح الجدول → "توليد الحصص" → الـ output: "تم إنشاء X حصة، 1+ تعارض في القاعات" ✓

ح. Holiday + teacher availability Phase 25

1. أضف إجازة "عيد الفطر" بتاريخ معيّن (recurring=1)
2. مدرس "أ.محمد" → التوفر → الجمعة "غير متاح"
3. الـ daily cron يـ-generate sessions → اليوم ده + الجمعة لـ أ.محمد اتـ-skip ✓

ط. Idempotent reminders Phase 19

1. طالب عنده monthly_due غير مدفوع، اليوم = آخر الشهر
2. شغّل الـ daily cron يدوياً
3. راجع sca_whatsapp_logs → 1 رسالة payment_reminder ✓
4. شغّل الـ cron تاني في نفس اليوم → مفيش رسالة جديدة (already_sent_today) ✓
5. غيّر تاريخ النظام → اليوم التالي → الـ cron → رسالة جديدة (لو لسه في window) ✓

ي. Default templates fallback Phase 19+

1. السوبر-أدمن في /admin/settings سايب القوالب فاضية
2. المدير فعّل toggle تذكير الدفع
3. الـ cron يـ-fire → الرسالة بتطلع بـ القالب العربي الافتراضي ✓
4. السوبر-أدمن يكتب قالب مخصص → الرسائل الجديدة تستخدم القالب المخصص ✓

ك. Login rate limit + audit Security

1. 5 محاولات failed login من نفس IP في 15 دقيقة
2. المحاولة السادسة → blocked برسالة "تم حظر المحاولات مؤقتاً" ✓
3. راجع /admin/security → كل محاولة بـ status (failed / blocked) + IP ✓
4. محاولات السوبر-أدمن عبر wp-login.php بتتسجّل كمان ✓

ل. CSV export integrity

1. /center/reports → "تنزيل CSV"
2. الملف بيبتدي بـ UTF-8 BOM (EF BB BF) → الحروف العربية تظهر صح في Excel ✓
3. أي قيمة بتبدأ بـ = + - @ بتتـ-prefix بـ apostrophe → CSV-injection protection ✓