القبول

يمتد تدفّق القبول من جانب المسؤول من مراجعة الطلب وحتى تأكيد التسجيل. تأكيد التسجيل يُشغّل معاملة ذرّية واحدة تفوِّض إلى نواة provisionStudent() المشتركة، فتُنشئ Student وGuardians وFeeAssignments وUserInvoices معاً — إمّا أن تكتمل كلّها أو لا يُنشأ شيء.

التقديم مجاني دائماً. يجمع معالج الطلب المعلومات فحسب — لا تُحصَّل أي مدفوعات في مرحلة التقديم. تُستحق المدفوعات في مرحلتين لاحقتين: رسوم التسجيل عند قبول المتقدّم للعرض، وفواتير الرسوم الدراسية بعد تأكيد التسجيل.

إضافة الطلاب — أربع قنوات وخطّ أنابيب واحد

لا يصل الطالب عبر التقديم العلني فحسب؛ هناك أربع طرق لإضافته، وكلّها تمرّ منذ توحيد الإدخال عبر خطوة "provision" المشتركة نفسها، فيخرج الطالب متطابقاً أيّاً كانت قناته: حساب دخول، فواتير رسوم، أولياء أمور، صف وفصل، وسجل قبول حقيقي مُوسوم بالقناة.

القنوات غير PORTAL تُنشئ طلب "قبول مباشر" بحالة ADMITTED على حملة نظامية خفية لكل مدرسة، فلا تُغرق قائمة المراجعة — تبويبا الطلبات والتسجيل يعرضان قناة PORTAL افتراضياً مع مرشّح يكشف البقية.

الطالب الذي يسجّل نفسه ليس قناة خامسة — بل يتقدّم بطلب. مساران التسجيل الذاتي (internal-onboarding وnewcomers) مخصّصان للبالغين الذين ينضمّون إلى المدرسة — المعلمون والموظفون والمسؤولون وأولياء الأمور — وقد أُزيل خيار "طالب" منهما، ويُوجَّه الطالب إلى /{lang}/application ليدخل مسار PORTAL كأي متقدّم آخر. وإذا لم تكن هناك حملة قبول مفتوحة، تعرض الصفحة نموذج الاستفسار فيظهر اسم الأسرة في تبويب العملاء المحتملين لدعوتها عند فتح باب القبول.

كل قناة قابلة للتتبّع

أياً كان الباب الذي دخل منه الطالب، تجد المدرسة طلبه وتتابعه:

• تبويب الطلبات يعرض كل القنوات افتراضياً. عمود قناة الالتحاق ومرشّح متعدد الاختيار (?channel=PORTAL,BULK_IMPORT — قابل للمشاركة كرابط، ويعمل على الخادم) يعيدان القائمة إلى طابور المراجعة عند الحاجة. حتى 2026-08-15 كان التبويب مثبتاً على PORTAL، فكان للطالب المضاف مباشرة أو المستورد رقم طلب حقيقي لا تستطيع أي شاشة الوصول إليه.
• من ملف الطالب إلى الطلب. الشريط الجانبي في الملف الموحّد يعرض رقم الطلب ويربط بصفحة التفاصيل (للمسؤول والموظف فقط — الصفحة محمية بالصلاحيات فلا يُعرض الرابط لمن لا يستطيع فتحها). الطلاب القدامى بلا طلب (قبل التوحيد وقبل تشغيل الاستدراك) لا يظهر لهم صف.
• من الطلب إلى الطالب. صفحة التفاصيل تعرض شارة القناة، وبمجرد وجود سجل طالب رابط عرض ملف الطالب — فتنغلق الحلقة من الجهتين.
• الإضافة المباشرة نهائية. الحالة ADMITTED بلا انتقالات، وconfirmEnrollment يرفض طلباً مقبولاً سلفاً على الخادم، فإظهار هذه الصفوف لا يمكن أن يُنشئ طالباً مرتين. صفحة تفاصيلها تُخفي صفوف العرض ورسوم التسجيل (ذلك الدفتر لا يعمل لها) وتقول إن الرسوم تُحتسب عبر المالية ← الرسوم كأي طالب مسجّل.
• تبويب التسجيل يبقى على PORTAL — الإضافة المباشرة لا تمرّ بالعرض ولا بتأكيد رسوم التسجيل.

توقّع ظهور الاستدراك. بمجرد تشغيل scripts/backfill-legacy-applications.ts يظهر لكل طالب سابق للتوحيد صف LEGACY_BACKFILL في العرض الافتراضي (نحو 970 في المدرسة النموذجية). المرشّح نقرة واحدة ويبقى في الرابط.

إبلاغ الأسرة — مُرسِل واحد لكل القنوات

تعمل خطوة provisionStudent داخل معاملة يملكها المُستدعي، ولا تُرسل أي إشعار عمداً، فالإبلاغ يقع بعد الحفظ. كان هذا العمل مكتوباً داخل confirmEnrollment وحدها، ما يعني أن طلاب PORTAL فقط كانوا يُبلَّغون: أما الطالب المُضاف عبر المعالج أو استيراد CSV فكان يحصل على حساب ورسوم وفواتير في صمت، وكذلك وليّ أمره.

الوحدة src/lib/student-provisioning-notify.ts هي هذا الإرسال، مشتركاً بين القنوات الخمس: إشعار الحساب (مع رابط إنشاء كلمة مرور للحسابات الجديدة)، وإشعار رسوم يذكر جدول الأقساط، وإشعار لوليّ الأمر يُرسَل إلى بريده مباشرة لأن أولياء الأمور المُنشأين عبر createOrLinkGuardian سجلات تواصل بلا حساب دخول.

قاعدتان لا يجوز كسرهما:

• العناوين النائبة تفقد قناة البريد عند إنشاء السجل نفسه. الطالب بلا بريد يحصل على عنوان مُركَّب …@student.local؛ ولا يكفي تخطّي الإرسال الفوري، لأن مهمة البريد الدورية تتخطّى من لا عنوان له، والعنوان النائب عنوان.
• الاستيراد الجماعي يُدرِج في الطابور، والإضافة الفردية تُرسل فوراً. يمرّ الاستيراد دائماً بـdelivery: "queue" فتُصرّفه المهمة الدورية بخمسين رسالة في كل تشغيل. والإشعار في الاستيراد اختياري ومغلق افتراضياً.

لا أحد يسقط من المسار

الطالب بلا academicGradeId كان العطب الصامت في المسار كلّه: تتوقف ensureStudentFeeAssignments عند الصف الفارغ، فلا تُسنَد رسوم ولا تصدر فواتير ولا تلاحقه أي مهمة تذكير. تكفي خانة section غير مقروءة في ملف CSV لحدوث ذلك، ولم يكن شيء يُظهر النتيجة.

صار في قائمة الطلاب مرشّح بلا صف أو فصل، مع تنبيه أسبوعي للمسؤولين ضمن مهمة fee-due. وإسناد الصف من القائمة يُعيد احتساب الرسوم ويستدرك ما فات.

كما صارت الفواتير والإيصالات تُسلَّم لا أن تُنشأ فحسب: إشعار الرسوم يذكر جدول الأقساط ويُوسم UserInvoice.sentAt، والدفعة المُحصّلة تربط الدافع بإيصاله.

الرحلة كاملةً — مراجعة من البداية إلى النهاية (2026-08-15)

تُتبّع المسار كله — التقديم ← المراجعة ← القائمة المختصرة أو الرفض ← العرض ← ردّ الأسرة ← رسوم التسجيل ← التسجيل ← التوزيع على فصل ← فواتير الأقساط ← تذكيرات الدفع ← السداد ← الإيصال — عبر كتل القبول والإشعارات والمالية والفواتير. حركة المال في الجوهر سليمة؛ كل الأعطاب كانت على الأطراف. ما أُصلح في تلك الجولة:

ما زال مفتوحاً — مُعلَّم لا مُصلَح، ولكلٍّ سببه:

• تذكيرات الأقساط واكتشاف التأخر يقرآن FeeStructure.paymentSchedule فقط (مهمتا fee-due / fee-overdue)؛ الرسوم ذات القسط الواحد أو غير المجدولة لها UserInvoice.due_date صالح لا تقرأه أي مهمة — فلا تُذكِّر ولا تتأخر ولا تُغرَّم. الإصلاح في المهمتين (مسار يعتمد تاريخ استحقاق الفاتورة). كان الملفان قيد التعديل في جلسة أخرى يوم 2026-08-15.
• مواعيد الاستحقاق ونوافذ «اليوم» بتوقيت UTC — نفس صنف العطب الذي أُصلح في الرواتب؛ المساعدات في src/lib/timezone.ts.
• الطالب المؤرشف/المنسحب تستمر رسومه المفتوحة في التغريم والتذكير — مرشّح archivedAt: null كان قيد الإضافة في تعديلات الجلسة الأخرى.
• لا سبب للرفض — Application.reviewNotes موجود ولا شيء يكتبه، وإشعار الرفض بلا مضمون. يحتاج واجهة صغيرة — قرار منتج.
• لا مسار للاسترداد ولا إلغاء للفواتير عند الانسحاب — عمل ميزات.
• حساب ولي أمر واحد لطفلين — إعادة استخدام الطالب حسب userId والقيد @@unique([schoolId, campaignId, userId]) — قرار نموذج حسابات.
• حذف الطالب نهائياً يترك فواتير يتيمة (ON DELETE SET NULL) ويُبقي User.
• التوزيع الجماعي على الفصول موجود في القاموس فقط.
• groupLabels في إعدادات كل معالج لا تُعرض — FormFooter يستخدم المصفوفة لطولها فقط.

خط الأنابيب

Applicant submits (free) → SUBMITTED
Review application       → UNDER_REVIEW
Score & rank             → Merit list
Select applicant         → SELECTED (admissionOffered=true)
  Applicant accepts offer → pays registration fee
Confirm enrollment       → ADMITTED
                           → Student (ACTIVE)
                           → User (role=STUDENT)
                           → Guardians + StudentGuardian
                           → StudentYearLevel + AcademicGrade
                           → FeeAssignments + UserInvoices (tuition)
                           → StudentDocuments
Place in section         → Classroom roster
Edit in wizard           → Update details

المسارات

تدفّق الحالات

معاملة التسجيل

confirmEnrollment() يتحقّق من أن الطلب SELECTED وأن عرضه غير منقضٍ، ثم يُشغّل db.$transaction واحدة تفوِّض إنشاء الطالب إلى النواة المشتركة provisionStudent() (src/lib/student-provisioning.ts) — الخطوة نفسها التي تستخدمها قنوات الإدخال الأربع:

1. ضبط حالة الطلب ADMITTED مع رقم تسجيل ENR-{timestamp}-{random}.
2. إنشاء User (دور STUDENT) إذا كان المتقدّم زائراً؛ ترقية USER → STUDENT خلاف ذلك (البحث عن الحساب مُنطَّق بـ schoolId).
3. إنشاء Student ببيانات الطلب مُعبَّأة مسبقاً؛ مطابقة applyingForClass → YearLevel؛ إنشاء StudentYearLevel وضبط academicGradeId.
4. تخصيص FeeStructures النشطة تلقائياً عبر ensureStudentFeeAssignments(tx) → صفوف FeeAssignment (PENDING) وفواتير UserInvoice المقابلة.
5. إنشاء Guardian وStudentGuardian وGuardianPhoneNumber من بيانات الأب / الأم (مع منع تكرار وليّ الأمر بالبريد أو الهاتف)؛ نسخ وثائق الطلب إلى StudentDocument.

ما بعد المعاملة (best-effort): إخطار الطالب وأولياء الأمور (داخل التطبيق + بريد)، رابط تعيين كلمة مرور للمستخدم الجديد، إرسال إشعارات fee_due، إعادة studentId. يُنشأ الطالب بـ wizardStep: null وstatus: ACTIVE.

نقل البيانات من Application إلى Student

إنشاء Guardian تلقائياً

لكل والد (الأب، الأم):

1. تقسيم الاسم إلى firstName + lastName (آخر فراغ).
2. Upsert لـ GuardianType (father, mother).
3. إنشاء Guardian (أو إيجاده بالبريد).
4. إنشاء صف ربط StudentGuardian مع المهنة وisPrimary.
5. إنشاء GuardianPhoneNumber إذا كان الهاتف متوفّراً.

الأب هو الأساسي؛ إذا لم يوجد أب، تصبح الأم هي الأساسية.

توزيع الفصل

بعد التسجيل، يُوزَّع الطالب على فصل:

• استجابة التسجيل تشمل suggestedSectionId إذا كان هناك فصل واحد فقط بسعة كافية لصف الطالب.
• يسرد الفصول التي بها سعة متاحة لذلك الصف.
• placeStudentInSection() يُسند ويُسجِّل تلقائياً في فصول الصف عبر enrollStudentInGradeClasses().

التحرير عبر Wizard

يمكن تحرير الطلاب المُسجَّلين عبر معالج الطالب (جدول الطلاب → Actions → Edit). كل بيانات الطلب مُعبَّأة مسبقاً.

updateStudentWizardStep يُحدّث wizardStep فقط للطلاب المسوَّدين (wizardStep غير فارغ) — يمنع التراجع العرضي للطلاب المُسجَّلين. الزر النهائي يقرأ "Save" وليس "Create".

قائمة الجدارة

يُدخل المسؤولون درجات امتحان القبول والمقابلة مباشرةً في جدول الجدارة (0–100 لكل درجة). تحسب generateMeritList() meritScore مرجّحاً لكل طلب:

• امتحان القبول — 60%
• المقابلة — 40%

تُرتَّب الطلبات تنازلياً حسب meritScore؛ تظهر الطلبات غير المُقيَّمة في آخر القائمة. تُكتب الدرجات دفعةً عبر updateApplicationScores(). يشمل الجدول الطلبات المُدرَجة والمُختارة وتلك في قائمة الانتظار.

العرض → القبول → الدفع → التسجيل

بمجرد انتقال المتقدّم إلى حالة SELECTED:

1. يُنشأ عرض بانتهاء صلاحية قابل للتهيئة (offerExpiryDays، افتراضياً 14 يوماً).
2. يسجّل المتقدّم دخوله عبر رابط العرض المُضمَّن بالرمز (يحافظ تسجيل الدخول على مسار الاستدعاء الكامل).
3. يدفع المتقدّم رسوم التسجيل عبر بوّابة الدفع الخاصة بالمدرسة (Tap لدول الخليج، Stripe لسائر الدول). يعرض معالج الطلب معاينة إعلامية فقط — لا يُحصَّل أي مبلغ في مرحلة التقديم.
4. عند نجاح الدفع، يظهر للمسؤول لافتة تأكيد دفع رسوم التسجيل ويمكنه المتابعة.
5. ينقر المسؤول على "تأكيد التسجيل" ← تُشغَّل معاملة confirmEnrollment() (انظر معاملة التسجيل).
6. بعد التسجيل يستخدم المسؤول مربع حوار التوزيع في جدول التسجيل لاختيار فصل (تظهر أعداد المقاعد)؛ تُسجِّل placeStudentInSection() الطالب في جميع فصول الصف.

إعادة محاولة إتمام الدفع المُهجَّر متاحة — يمكن للمتقدّمين الذين غادروا الصفحة العودة وإكمال الدفع.

تبويب العملاء المحتملون

يعرض تبويب العملاء المحتملون (/{lang}/admission/leads):

• الاستفسارات — طلبات التواصل مع الاسم والبريد والهاتف والصف المطلوب والمصدر وحالة المتابعة.
• حجوزات الجولات — الزيارات المجدولة مع عدد الحضور والحالة (PENDING / CONFIRMED / CANCELLED) وإجراءات إعادة الجدولة والإلغاء.

يملك دورا ADMIN وSTAFF صلاحية الإجراءات الكاملة؛ يملك ACCOUNTANT صلاحية القراءة فقط. تُرسَل إشعارات داخل التطبيق إلى ADMIN وSTAFF عند كل استفسار أو حجز جديد. تحمي حجوزات الجولات من التجاوز في البيع (آمنة من TOCTOU) وتحترم علامة enableTourBooking للحملة؛ يُخصَّم عدد الحضور بشكل صحيح عند الإلغاء أو إعادة الجدولة.

معالجة وثائق الذكاء الاصطناعي

تُعالَج وثائق المتقدّمين المُرفوعة (بطاقات الهوية، كشوف الدرجات) عبر قائمة انتظار استخراج. يعمل الـ cron /api/cron/process-document-jobs كل 10 دقائق ويُفرغ الوظائف المعلّقة. classifyDocument() وgetDocumentProcessingStatus() محمية بنظام RBAC. يُفحص حصة استخدام الذكاء الاصطناعي (canUseAI) قبل كل استدعاء؛ مخطط Zod لإيصال البنك اختياري حتى لا تُفشل الاستخراجات الجزئية الوظيفة بأكملها.

الإعدادات

Copy{
  allowMultipleApplications: false,
  requireDocuments: true,
  // applicationFee محذوف — التقديم مجاني دائماً
  offerExpiryDays: 14,           // 1-90
  autoEmailNotifications: true,
  enableOnlinePayment: false,
  paymentMethods: ["stripe", "cash"],
  bankDetails: { bankName, accountName, accountNumber, iban, swiftCode },
  cashPaymentInstructions: "",
  entranceWeight: 60,            // أوزان الجدارة (مجموعها 100)
  interviewWeight: 40,
}

Server actions (مسؤول، auth + صلاحية)

أمان متعدّد المستأجرين

كل الاستعلامات مُنطقَة بـ schoolId. يحلّ تدفّق التقديم المدرسة من النطاق الفرعي عبر getSchoolBySubdomain()؛ ويُتحقَّق من أن الجلسة تنتمي لتلك المدرسة.

ملفات أساسية

انظر أيضاً

• Application — تدفّق جانب المتقدّم
• تعدد المستأجرين — نطقة schoolId
• Invoice — التوليد التلقائي من التسجيل
• Fees — دورة حياة تخصيص الرسوم