الحضور

تتبّع وحدة الحضور حضور الطلاب عبر طرق التقاط متعدّدة، مع وصول مبني على الأدوار، إشعارات للأهل، مستويات خطر وفق US DoE، تتبّع للتدخّلات، وتصدير CSV / Excel / PDF. المعلمون يرون فصولهم المسندة فقط؛ الطلاب وأولياء الأمور يرون سجلاتهم فقط.

متتبّع الإصدار: databayt/hogwarts#1 — متتبّع رئيسي موحّد للحضور والامتثال. راجع كذلك Aldar Epic 01.

الحالة

على الهاتف

تحت نقطة التحوّل md تتبع النظرة العامة وكل الصفحات الفرعية نمط الهاتف في لوحة المدرسة — المفردات نفسها في لوحة التحكم والمكتبة والبث المباشر على الهاتف: الأرقام في لوحة رمادية واحدة بعمودين، وبطاقات رمادية بلا حدود بأزرار بيضاوية، وأبواب الأقسام أيقونات تطبيقات، وصفوف تنزل تفاصيلها تحت العنوان بدل أن تضغطه. الأجهزة اللوحية وسطح المكتب دون تغيير، ويبقى التحضير اليدوي والكشك والجداول كما هي في كل المقاسات.

المسارات

صفحة الحضور الرئيسية حسب الدور: المعلم يصل إلى التحضير السريع (موجه للجوال والغياب — الجميع حاضر افتراضيًا، واللمسات تتنقل غائب ← متأخر ← حاضر، وحفظ واحد يرسل الكشف كاملًا ويُشعر أولياء أمور الغائبين)، والمشرف/الموظف إلى النظرة العامة، والطالب/ولي الأمر إلى سجله الذاتي. كلها تحت src/app/[lang]/s/[subdomain]/(school-dashboard)/attendance/. التبويبات: /, /manual, /qr-code, /records, /excuses, /early-warning, /interventions, /analytics, /reports, /settings. شبكة الوصول السريع في النظرة العامة تربط /recent, /bulk-upload, /barcode, /hall-pass, /interventions/tiers, /gamification, /ai (+ /kiosk, /letters للمشرفين). روابط مباشرة فقط: /geo, /intentions, /bulk. /analysis يعيد التوجيه نهائيًا إلى /analytics؛ /parent/attendance يعيد التوجيه إلى /attendance/records. راجع جدول طرق الالتقاط أدناه لغرض كل route؛ راجع RBAC للوصول حسب الدور.

RBAC

فصول المعلم هي: فصل الريادة، وكل فصل له معه حصة في الجدول، وكل فصل أُسنِدت إليه فيه مادة — getTeacherSectionIds() (actions/helpers.ts). ويطبّقها sectionScopeWhere() على القراءة: فلتر الفصل يُقاطَع معها ولا يوسّع النطاق أبدًا. وفلتر الصف يمرّ عبر الفصل (section.gradeId).

الحضور اليدوي

شريط أدوات مسطّح inline (PlatformToolbar): محدّد الفصل، منتقي التاريخ، أزرار حالة جماعية، Save. getCurrentPeriod() يختار تلقائياً الفصل المطابق لحصة الجدول الحالية؛ الأسماء تُترجَم عند الطلب عبر getText(). لوحة المفاتيح: P / A / L لحاضر / غائب / متأخر، Cmd/Ctrl+S للحفظ. أولياء الأمور للطلاب الغائبين يُخطَرون تلقائياً عند الحفظ؛ AbsenceIntention معتمَد يحوّل ABSENT → EXCUSED.

طرق الالتقاط

تصاريح الخروج (/hall-pass) تُصدَر على فصل الطالب نفسه، فلا يُطلب عند إصدارها إلا الطالب والوجهة.

إشراك الأهل

triggerAbsenceNotification() يُطلَق عند الغياب: داخل التطبيق (أولوية عالية)، SMS عبر Twilio (إن كان مهيّأً)، بريد. يستخدم preferredLanguage للمدرسة.

أسباب العذر: طبّي، طارئ عائلي، ديني، نشاط مدرسي، نقل، طقس، أخرى. معتمَد → EXCUSED؛ مرفوض → غير معذور. العذر المقدَّم — وكذلك نيّة الغياب إذا فُعِّل "إشعار المعلمين" — يصل إلى رائد الفصل والمعلمين المسنَدة إليهم مواده هذا الفصل الدراسي (sectionTeacherUserIds). وقائمة المراجعة لدى المعلم هي أعذار فصوله فقط.

عرض الطالب / ولي الأمر: نسبة + اتجاه، تقويم تاريخي، تفصيل الحالات، تقديم عذر للغيابات غير المعذورة.

الإنذار المبكّر

مستويات خطر US DoE:

تتبّع التدخّلات في /attendance/interventions — 14 نوع تدخّل (تواصل مع ولي الأمر، زيارة منزلية، إحالة لمرشد / أخصائي اجتماعي / إداري، عقد حضور، إحالة تغيّب، مورد مجتمعي، دعم أكاديمي، إرشاد، تحفيز، أخرى) مع حالات Scheduled → In Progress → Completed / Cancelled / Escalated. محرّك السياسات في actions/policy.ts يقيّم المُحفّزات ويدير الاستثناءات.

التحليلات والتقارير

تحليلات بـ7 تبويبات في /analytics: Summary، Calendar، Trends، Patterns، Methods، Classes (الفصول مرتّبة حسب النسبة)، At Risk. الفلاتر: نطاق التاريخ والفصل.

التقارير في /reports: فلترة بالفصل، الطالب، الحالة، نطاق التاريخ، الحصة. تصدير: CSV، Excel (5 أوراق — summary، detailed، by status، by section، by date)، PDF (بهوية المدرسة). ويتبع التصدير فلتر الفصل.

الرفع الجماعي في /bulk-upload لفصل واحد: كل طالب في الملف يجب أن يكون منه.

الامتثال: getComplianceDashboard(), getComplianceReport(), getScheduledReports().

Server actions

الـactions مقسّمة عبر وحدات حسب المعنى تحت src/components/.../attendance/actions/.

توقيعات نموذجية:

CopymarkAttendance(input: {
  sectionId: string
  date: string
  records: Array<{ studentId: string; status: 'present' | 'absent' | 'late' }>
})
 
markPeriodAttendance(input: {
  sectionId: string     // فصل المعلم نفسه؛ وكل طالب يجب أن يكون منه
  date: string
  periodId: string
  timetableId?: string  // يجب أن تكون حصة هذا الفصل
  records: Array<{ studentId: string; status: 'PRESENT' | 'ABSENT' | 'LATE'; notes?: string }>
})
 
getAttendanceList({ sectionId, date, lang? })  // lang يُطلق الترجمة
deleteAttendance(id: string)                  // حذف ناعم
restoreAttendance(id: string)

Schema

Copymodel Attendance {
  id           String           @id @default(cuid())
  schoolId     String
  studentId    String
  sectionId    String?          // الفصل الذي يُحفظ عليه الحضور
  date         DateTime         @db.Date
  status       AttendanceStatus
  method       AttendanceMethod @default(MANUAL)
  checkInTime  DateTime?
  checkOutTime DateTime?
  notes        String?
  markedBy     String?
  markedAt     DateTime         @default(now())
  deletedAt    DateTime?
 
  periodId    String?
  timetableId String?
  periodName  String?
 
  @@unique([schoolId, studentId, sectionId, date, periodId])
  @@index([schoolId, date, periodId])
}

دلالات الحذف الناعم. الحقل deletedAt علامة حذف (tombstone) وليس حذفًا نهائيًا. يُستبعَد السجل المحذوف من كل قراءات التحليلات ولوحة المعلومات والتصدير والامتثال التنظيمي، ومن عروض الطالب وولي الأمر على الجوال — مع الاحتفاظ بالصف للتدقيق وإمكانية استعادته من قِبل المسؤول (restoreAttendance). وبما أن قيد @@unique لا يزال يحجز مفتاح الصف المحذوف، فإن إعادة تسجيل الطالب لنفس اليوم/الحصة تُحيي السجل الأصلي (تمسح deletedAt) بدلًا من إنشاء نسخة مكررة — وينطبق ذلك على التسجيل اليدوي والحصص ورمز QR والباركود والسياج الجغرافي والكشك.

نماذج داعمة: AttendanceExcuse, AttendanceIntervention, QRCodeSession, StudentIdentifier, AbsenceIntention, PolicyTrigger, PolicyExemption, MasterAttendance, HallPass, KioskLog, AttendanceReward, StudentBadge, AttendanceStreak.

Seed

Copypnpm db:seed:single attendance

الامتثال للجهات التنظيمية (ADEK eSIS — الإمارات)

يمكن لمدارس الإمارات (School.country === "AE") تفعيل رفع يومي لملف CSV إلى بوابة ADEK eSIS على esis.adek.gov.ae بالإضافة إلى التواصل مع ولي الأمر خلال ساعتين من الغياب غير المُبلَّغ (متطلب ADEK). الإطار العام — إضافة جهة تنظيمية جديدة (هيئة التعليم السعودية، وزارة التعليم القطرية، وزارة التعليم السودانية) تتطلب فقط إضافة قيمة إلى enum ComplianceProvider ودليل تحت src/lib/compliance/providers/<authority>/.

أوضاع الموصّل — قابلة للضبط لكل مدرسة × مزوّد:

مهلة التواصل مع ولي الأمر — ساعتين

عند تفعيل SchoolComplianceConfig.enabled = true، فإن triggerAbsenceNotification يُرسل عبر قنوات in_app + email + whatsapp (بدلاً من in_app فقط) لكي تستهلك كرونات البريد و WhatsApp الصف. كل 30 دقيقة، يبحث كرون absence-followup عن صفوف ABSENT التي:

• markedAt < now() - parentContactSlaMinutes (افتراضي 120، محسوب بـ UTC)
• لا يوجد لها AttendanceExcuse
• لا يوجد لها AbsenceIntention معتمَد يغطّي اليوم
• لا يوجد لها AttendanceIntervention من نوع PARENT_PHONE_CALL / PARENT_EMAIL خلال آخر 24 ساعة

يُرسل إشعار absence_unreported_followup لكل ولي أمر، ثم يكتب صفّ AttendanceIntervention (PARENT_EMAIL, parentNotified=true, contactMethod=in_app+email+whatsapp). هذا الصفّ هو سجل التدقيق الموجّه للجهة التنظيمية — يستعلم getParentContactSlaReport() عنه لتقديم عدّ "تواصل ضمن المهلة" لتدقيقات ADEK.

النموذج البياني (جانب الامتثال)

خمسة كيانات جديدة في prisma/models/compliance.prisma — ليس أيٌّ منها خاصّاً بـ ADEK:

• ComplianceProvider enum (حالياً ADEK_ESIS، CUSTOM)
• ConnectorMode enum
• ComplianceSubmissionStatus enum + CircuitBreakerState enum
• SchoolComplianceConfig — صفّ واحد لكل مدرسة × مزوّد (تفعيل اختياري)
• SharedComplianceCredentialGroup — بيانات اعتماد مشتركة لمجموعة (نمط الدار)
• SchoolComplianceCredential — بيانات اعتماد لكل مدرسة (وضع OFFICIAL_API)
• ComplianceSubmission — صفّ لكل محاولة، مفهرس بـ (schoolId, provider, submissionDate, attemptNumber). تتسلسل المحاولات عبر supersededBy. يُحفظ CSV داخل csvArtifactContent ويُنزَّل عبر /api/compliance/artifact/[submissionId] (S3 URL موقّع قيد التخطيط).

تمّ توسيع AuditLog.userId ليقبل null في نفس الإصدار لكي يُسجَّل كرون / عامل / webhook كأحداث نظام — تمرير userId: null في المكالمات.

أُضيف نوع NotificationType.absence_unreported_followup لمسار المهلة.

التحضير دون اتصال

التحضير السريع (/attendance للمعلّمين) يعمل بلا اتصال. يُحفظ التحضير في صندوق الصادر على الجهاز (النوع attendance، عنصر واحد معلّق لكل شعبة ويوم) ويُعاد إرساله عبر POST /api/offline/sync ← actions/quick-core.ts، وهو الكود نفسه الذي يشغّله الإجراء المتّصل. التحضير الأحدث الموجود على الخادم يفوز ويُهمل المكرَّر. إشعارات أولياء الأمور بالغياب تُرسَل عند وصول الإعادة. راجع العمل دون اتصال.

انظر أيضاً

• تعدد المستأجرين — RBAC + نطاق المستأجر
• الإشعارات — إرسال الغياب
• الجدول — اكتشاف الحصة تلقائياً
• الامتثال — إطار الإرسال للجهات التنظيمية (ADEK + جهات مستقبلية)

التحضير بلا اتصال

التحضير السريع (/attendance للمعلّمين) يعمل من دون اتصال. تذهب العلامات إلى صندوق الصادر على الجهاز (النوع attendance، عنصر معلّق واحد لكل شعبة ويوم) وتُعاد عبر POST /api/offline/sync ← actions/quick-core.ts، الشيفرة نفسها التي يشغّلها الإجراء المتصل. التحضير الأحدث الموجود على الخادم يفوز وتُسقَط الإعادة كتكرار. تنطلق إشعارات الغياب لأولياء الأمور عند وصول الإعادة. انظر العمل دون اتصال.

جرّبه على هاتف: افتح الحضور ← التحضير السريع، فعّل وضع الطيران، علّم شعبة واحفظ — تؤكد اللوحة أن العلامات حُفظت على الجهاز ويعرض شريط المزامنة عنصرًا واحدًا معلّقًا. أعد الاتصال فيفرغ الشريط وتكون العلامات على الخادم خلال ثوانٍ. تعليم الشعبة نفسها مرة أخرى يُعاد كتكرار ويفوز التحضير الأحدث. تثبيت التطبيق أولًا (زر متابعة في ورقة الترحيب) ليس شرطًا للتحضير بلا اتصال، لكنه شرط على آيفون لإشعارات الدفع.