دليل المسؤول لمنصة الحضور

خمسة أشياء تُعرَّف مرة واحدة، ثم يدور حولها كل شهر:

القاعدة الأهم: صف الروستر هو الذي يقول أين يكون الطالب في يوم بعينه. يُختم كل صف بالمستشفى والقسم والدفعة والمؤسسة لحظة رفعه، فلو نُقل الطالب لاحقًا إلى مستشفى أخرى بقيت شهوره السابقة كما كانت. صفحة الأعضاء تعرض «مستشفى اليوم»؛ الروستر يعرض التاريخ.

كود العضو يتكوّن من السنة + كود المؤسسة + رقم تسلسلي (مثل 2026050001) ويُستخدم في ملفات الروستر والحضور وفي البحث.

أنواع الحسابات الجاهزة في صفحة المشرفين اختصارات لمجموعات صلاحيات: مدير (كل الصفحات بلا إدارة المشرفين)، مشرف (يدير اليوم: لوحة التحكم، الروستر ومراجعته، الموجودون الآن، البحث وفحص الوجه، QR، ويقرأ الأعضاء بلا تعديل)، مراجع (يطّلع ويصدّر فقط)، أو مخصص تحدّده صفحةً صفحة.

عند أول تشغيل يُنشئ النظام حساب المدير العام الأول من إعدادات الخادم. بعده، الترتيب المنطقي:

1. الإعدادات ← المؤسسة: اسم المؤسسة وشعارها (يظهران في التطبيق وأعلى كل تقرير) وفئة المستخدمين («طلاب امتياز» تُسمّي الأشياء مستشفيات ودفعات).
2. المجموعات: أضف المؤسسة (الكلية) وكودها، ثم دفعاتها.
3. الفروع: أضف كل مستشفى بموقعها على الخريطة ونطاقها وطريقة الحضور فيها.
4. الأقسام: أقسام كل مستشفى.
5. الشيفتات: عرّف الشيفتات وأكوادها ونوافذها.
6. الأعضاء: استورد الطلاب من ملف Excel (أو أضفهم يدويًا).
7. الروستر الشهري: ارفع روستر الشهر لكل مستشفى.
8. المشرفون: أضف المشرفين وامنحهم صفحاتهم وتخصيصاتهم.
9. الأتمتة: شغّل بوت تيليجرام (الرمز، الـ webhook، مجموعة الإدارة) — انظر بوت تيليجرام.
10. النسخ الاحتياطي: نزّل نسخة من حسابات المدير العام واحفظها بعيدًا عن الخادم.

الصورة العامة للشهر (أو ليوم بعينه): نسبة الحضور، وعدد الحاضرين والمتأخرين والغائبين ومن لم يحن موعدهم، وتوزيعات حسب المستشفى والدفعة والشيفت، والمعدل اليومي.

• الفلاتر في الأعلى: الشهر والسنة، اليوم (أو الشهر كله)، المنشأة، المستشفى، الدفعة، الشيفت، القسم. كل ما تحتها يتبعها.
• نسبة الحضور تُحسب من الشيفتات التي انتهت فعلًا («من N شيفت خلصوا»)؛ الشيفتات الجارية لا تُحتسب غيابًا بعد.
• الرسوم البيانية: اختر الشكل (دائري، مؤشر، توزيع الحالات، المعدل اليومي أعمدة/خط، خريطة حرارية، الفروع حسب الحالة، رادار، قطبي، فقاعي، مبعثر).
• تصدير من أيقونة التنزيل في الشريط العلوي: ملف Excel أو PDF بنفس الفلاتر، يحمل الرسوم والأرقام.

• المنشآت: الاسم (كلية / معهد) والكود الرقمي الذي يدخل في كود كل عضو. لا تغيّر كود مؤسسة لها أعضاء إلا لضرورة — أكوادهم لا تتغير بأثر رجعي.
• الدفعة: الاسم والعام والمؤسسة التي تتبعها، وتاريخا البداية والنهاية (اختياريان)، وخيار «الانصراف في أي وقت» لأعضائها.
• الحذف مرفوض ما دامت الدفعة مرتبطة بأعضاء أو روستر؛ الرسالة تسمّي ما هي مرتبطة به.

لكل مستشفى: الاسم والعنوان، والموقع إمّا دائرة (نقطة + نصف قطر بالمتر) أو مضلّع ترسمه على الخريطة بثلاث نقاط فأكثر — أنسب للمستشفيات الكبيرة أو غير المنتظمة. الخريطة بطبقات شوارع / قمر صناعي / تضاريس، وزر «موقعي الحالي».

سياسة الحضور لكل مستشفى

• طريقة الحضور: الموقع أو QR، الموقع فقط، QR فقط، أو معطَّل. الفرع يزيد الصرامة على الإعداد العام ولا يخفّفها.
• إيقاف الحضور للفرع كله مؤقتًا.
• إلزام QR (الموقع وحده لا يكفي) — يفعّل «السماح بـ QR» تلقائيًا.
• تخطّي فحص الموقع / الوجه لأعضاء هذا الفرع، والانصراف في أي وقت.

الأقسام تتبع المستشفى (الباطنة، الجراحة، الطوارئ…). تُعرَّف هنا مرة واحدة، ثم يُعيَّن قسم كل عضو شهرًا بشهر: من صفحة الروستر (عند رفع ملف الشهر أو من نافذة «روستر هذا الشهر») — فالطالب يدور بين الأقسام، والتقارير تُفلتر بالقسم.

لكل شيفت اسم وكود من حرف أو حرفين (هو ما يُكتب في خلايا ملف الروستر)، ووقت البداية والنهاية، وخمس نوافذ تحكم التسجيل:

الشيفت الليلي الذي يعبر منتصف الليل (8 مساءً – 8 صباحًا): اضبط أوقات الانصراف في الصباح والنظام يفهمها. تطبيق النوافذ يخضع لإعداد «إلزام النافذة الزمنية للشيفت» في الإعدادات.

قائمة الطلاب مع البحث (بالاسم / بالرقم القومي / بالكود) والقوائم (المستشفى، القسم، المؤسسة، الدفعة)، مقسّمة صفحات. بقية المفاتيح خلف زر واحد تصفية يفتح نافذة تختار فيها كل ما تريد ثم تطبيق: الخصائص المفعّلة (تخطّي الوجه، تخطّي الموقع، تجميد الساعة) وأسئلة نعم/لا/الكل (بصمة الوجه، صورة، مربوط بتيليجرام، نشط). عدد المفاتيح المختارة يظهر على الزر، وملخصها بجواره مع زر لمسحها.

تيليجرام الطالب

تحت كل طالب شارة تقول أين هو من تيليجرام: مربوط (واسمه على تيليجرام)، متوقف مؤقتًا (أرسل /stop)، محظور (حظر البوت)، غير مربوط، أو تيليجرام موقوف (الخدمة كلها موقوفة له). اضغطها تفتح نافذة الطالب: إعادة الربط (رابط جديد) يعطيك رابطًا لمرة واحدة ترسله له فيضغط Start؛ أو تكتب معرّف محادثته بنفسك وتعدّل الاسم وتوقفه مؤقتًا؛ تحديث يقرأ اسمه وحالته من تيليجرام؛ فك الربط يحذف الربط. وزر مزامنة تيليجرام لكل الطلاب أعلى الصفحة يحدّث روابط كل طلاب نطاقك دفعةً بعد دفعة. كل ذلك لمن له «تعديل» على صفحة الأعضاء، وفي حدود مستشفياته ودفعاته.

إضافة واستيراد

• إضافة عضو: الجنسية، الرقم القومي (أو رقم الجواز للوافد — انظر غير المصريين)، الاسم، الهاتف، البريد، الدفعة، المستشفى. كلمة مرور الدخول الأولى = الرقم القومي (أو رقم الجواز).
• استيراد من ملف (CSV/Excel) بالأعمدة national_id, full_name, nationality, phone, email, group, branch, department, status — نزّل النموذج: الجنسية والدفعة والمستشفى والقسم والحالة قوائم منسدلة فيه، تُختار ولا تُكتب، وفيه صفّان مثالان: طالب مصري برقم قومي، وطالب وافد رقمه رقم جواز في العمود نفسه والجنسية تقول إنه أجنبي. يُفحص كل صف قبل الرفع: للمصري 14 رقمًا صحيحة، وللوافد أي رقم جواز — والخطأ يُقال باسمه. الرقم القومي هو المعرّف: الموجود يُحدَّث ولا يُكرَّر. قبل التنفيذ تُعرض معاينة: كم صفًا جديدًا وكم تحديثًا وكم صفًا غير صالح، مع اختيار سلوك التكرار (تحديث / تجاهل / إيقاف).
• توليد أرقام تجريبية (لمن مُنح هذه العملية): أعضاء وهميون بأرقام قومية صحيحة للاختبار.

تعديل عضو

• البيانات الشخصية، الدفعة، والمستشفى (اليوم). تغيير المستشفى هنا لا يمس روستر الشهور — لذلك يُغيَّر روستر الشهر من صفحة الروستر.
• إعادة تعيين كلمة المرور إلى الرقم القومي.
• إعادة تعيين البصمة: يحذف بصمة الوجه ليعيد الطالب التقاطها.
• استثناءات فردية: تخطّي الوجه، تخطّي الموقع، الانصراف في أي وقت.
• أدوات يُمنحها الطالب: يمكنه إنشاء رمز QR لزملائه (في فرعه فقط)، ويمكنه حذف بصمة الوجه لزملائه بالكود (في فرعه فقط).
• تجميد الساعة (للاختبار): يرى الطالب التطبيق كأن الوقت هو المحدّد.
• إيقاف الحساب (غير نشط) بدل حذفه؛ الحذف يزيل الحضور والروستر أيضًا.

تعديل جماعي

«تطبيق على كل النتائج» يعدّل كل الأعضاء الذين تطابقهم الفلاتر الحالية — لا الصفحة المعروضة فقط — لتغيير الدفعة أو المستشفى أو الحالة دفعة واحدة، أو حذف الصور (الصورة الشخصية لكل من له صورة في التصفية، بتأكيد يذكر عددهم)، أو حذفهم جميعًا (بتأكيد).

العمود الذي يحمل الرقم القومي يحمل رقم جواز السفر للوافد، وبجواره الجنسية — تُختار من قائمة الدول (بالعربية والإنجليزية، مصر أولًا) ولا تُكتب نصًا، فتتوحّد في التقارير والتصدير.

• إضافة أو تعديل عضو / مستخدم: اختر الجنسية أولًا. اختيار أي دولة غير مصر يقلب الحقل تلقائيًا إلى «رقم جواز السفر» ويفعّل مفتاح أجنبي — الدخول برقم جواز السفر؛ يبقى المفتاح بيدك لو احتجت عكسه.
• القاعدة التي يحكم بها الخادم: 14 رقمًا صحيحة = رقم قومي. حروف = جواز. أرقام فقط ليست رقمًا قوميًا صحيحًا (13 رقمًا مثلًا) تُرفض على أنها خطأ كتابة — إلا لو كان المفتاح مفعّلًا، فتُقبل جوازًا. هكذا لا يمرّ رقم قومي ناقص، ولا يُرفض جواز كله أرقام.
• كلمة المرور الأولى: للطالب هي رقمه (قوميًا أو جوازًا). للمشرف الوافد لا يوجد تاريخ ميلاد يُشتق منه، فيولّد النظام كلمة مرور ويعرضها لك مرة واحدة عند الإنشاء أو عند إعادة التعيين — انقلها له.
• ملف الاستيراد: صار فيه عمود nationality بقائمة منسدلة بالدول (يُقبل الاسم بالعربية أو الإنجليزية أو الكود). دولة غير مصر في الصف تجعل رقمه جوازًا، فيُستورد الجواز الرقمي من الملف أيضًا. اتركه فارغًا = مصري لعضو جديد، ولا يتغيّر لعضو موجود.
• الاستيراد بالصور (zip): اسم ملف الصورة قد يكون رقم الجواز كما هو رقم قومي: A1234567.jpg.

الجنسية تظهر للطالب في شاشته الرئيسية، ولك في صف العضو وفي تصدير الأعضاء (عمود «الجنسية»).

صفحة بطاقات الطلاب (صلاحية مستقلة) تعرض بطاقة كل طالب كما يراها على هاتفه — بحث وتصفية كصفحة الأعضاء (المستشفى، الدفعة، المنشأة، بصمة الوجه، نشط) — لطباعتها من المكتب.

• تصدير PDF: بطاقة في كل صفحة، وكل صفحة بمقاس البطاقة المطبوعة (86.7 × 54.3 مم). صدّر المحدد، أو الصفحة، أو كل النتائج. فوق 300 بطاقة دفعة واحدة يسأل: «عدد كبير — المتصفح قد يثقل» ثم متابعة على أي حال.
• كل بند على سطر واحد بصيغة «الاسم: أحمد …»، «الرقم القومي: …»، «الكود: …» ثم الدفعة والمستشفى والمؤسسة والفرقة: المسمّى بلون هادئ والقيمة بخط أثقل على السطر نفسه. القيمة الطويلة تصغُر لتتسع، وإن طالت فوق ذلك تُحذف آخر كلماتها — لا تنقسم على سطرين ولا تُقطع في منتصف كلمة.
• الخلفية بيضاء حتى الحواف بلا تدوير ولا إطار مرسوم، فتُطبع على الكارنيه دون زوايا داكنة أو إطار لا يطابق حافة البطاقة.
• التاريخان: في الشريط العلوي، إلى جوار اسم الكلية، العام الدراسي («2025/2026»)، وتحت الختم تاريخ الإصدار («09/2025» — شهر بداية الامتياز وسنته). كلاهما يُحسب من تاريخ بداية الدفعة: سنة البداية/السنة التالية أيًّا كان موعد النهاية. ولكل دفعة أن تكتب صيغتها هي في نموذج المجموعة («العام الدراسي على البطاقة» و«تاريخ الإصدار على البطاقة») — الخانة الفارغة تعني الحساب التلقائي.
• ظهر البطاقة: تصميم بلا أي بيانات — شعار الكلية واسمها، ورموز QR لروابط الكلية — حتى ثلاثة: البوابة الرقمية للكلية، وروابط الكلية، وموقعها الرسمي افتراضيًا؛ يغيّرها المدير العام من «بنود البطاقة» ← روابط ظهر البطاقة (اسم كل رابط كما يُطبع وعنوانه https، الصف الفارغ = لا رمز). بنفس المقاس. طباعته اختيارية: علامة طباعة ظهر البطاقة أيضًا فوق القائمة قبل التصدير، فيأتي في الملف خلف كل بطاقة. وظهوره للطلاب قرار واحد للجميع يتخذه المدير العام وحده من «بنود البطاقة» ← إظهار ظهر البطاقة للطلاب؛ ثم لكل طالب علامة إظهار الظهر تحت بطاقته (تُحفظ على جهازه) تكشف الظهر مع زرَي تحميل PNG وفتح في نافذة. وفي نافذة البطاقة هنا يظهر الظهر تحت الوجه مع الزرين نفسيهما.
• الصورة تُضبط حول الوجه عند رفعها (من الملف الشخصي أو من ملف ZIP): يُكتشف الوجه على الجهاز ويُرسم حوله مربع يحوي الرأس كاملة والرقبة وأعلى الكتفين أينما كان الوجه في الصورة. وإن كانت الصورة أضيق من ذلك تُصغَّر بدل أن تُقص — تمتد خلفية الصورة نفسها (مموّهة) لتملأ الحواف. في نافذة رفع الصور تعرض كل بطاقة الصورة كما ستُحفظ فعلًا، فراجعها قبل الرفع.
• إيقاف بطاقة (تعطيل على المحدد): لا تُطبع ولا يفتح رمزها. وإعادة تشغيلها بالمثل.
• بنود البطاقة (زر أعلى الصفحة، لمن يملك صلاحية التعديل): أيّ البنود الاختيارية تظهر (الدفعة، المستشفى، المؤسسة، الفرقة) ونص بند الفرقة، ثم مسمّيات البطاقة: الكلمة التي تسبق كل بند («الاسم»، «المؤسسة» ← «الكلية»، «كود العضو» ← «الكود» …) وعنوان سنة الإصدار وعبارة الـ QR. الخانة الفارغة تُكتب بلغة التطبيق؛ ما تكتبه أنت يظهر كما هو في العربية والإنجليزية، على بطاقات المكتب وعلى هاتف كل طالب.

الشبكة: صف لكل عضو وعمود لكل يوم، والخلية تحمل كود الشيفت. الفلاتر في الأعلى (الشهر/السنة، المستشفى، الدفعة، المؤسسة، القسم، اليوم أو الشهر كله، نوع الروستر) والبحث.

رفع الروستر من ملف

1. اختر المنشأة ثم المستشفى (وقسمًا اختياريًا لتعيين المرفوعين عليه).
2. نزّل نموذج الروستر: العمود الأول code (كود العضو) ثم أعمدة الأيام 1..31، وكل خلية = كود الشيفت.
3. املأه وارفعه. الأكواد تُطابَق داخل المنشأة المختارة فقط؛ صف بكود غير موجود يُتجاهل ويُذكر عددها، وأكواد الشيفتات غير المعرّفة تُذكر أيضًا.

رفع الحضور والانصراف من ملف

لمن مُنح عملية «رفع الحضور»: نزّل ملف الحضور (كل الورديات المجدولة جاهزة فيه)، املأ وقتَي الدخول والخروج بصيغة HH:mm بتوقيت القاهرة، وارفعه. كل صف يجب أن يقابل وردية مجدولة لنفس العضو في نفس اليوم؛ اترك الدخول فارغًا لمن غاب. أو ضع الشيت نفسه باسم attendance داخل ملف الروستر فيُسجَّل معه.

التعديل من الشاشة

• اضغط خلية لتعيين شيفت أو تغييره أو إزالته. إزالة شيفت عليه حضور مسجّل تحذف الحضور أيضًا (بتأكيد).
• شيفت جماعي (أيقونة الشريط العلوي): إضافة أو استبدال أو إزالة شيفت على نطاق أيام لكل الأعضاء المفلترين في المستشفى المحدد.
• اضغط اسم العضو لفتح «روستر هذا الشهر»: المستشفى والقسم والدفعة والمؤسسة لروستر هذا الشهر فقط — صفحة الأعضاء والشهور الأخرى لا تتأثر. وزر «روستر هذا الشهر للأعضاء المعروضين» يطبّق الشيء نفسه على كل من تطابقهم الفلاتر.
• تصدير الشبكة كما هي (Excel/PDF) من أيقونة التنزيل.

لبناء ملف روستر من الصفر بدل كتابته في Excel: اختر المستشفى والشهر، ثم شيفتًا، واضغط الخلايا (أو طبّق على نطاق أيام)، واستخدم الممحاة للحذف. المسودة تُحفظ على جهازك تلقائيًا. عند الانتهاء نزّل ملف الروستر وارفعه من صفحة الروستر. الطالب له نسخة مبسّطة من الأداة نفسها لدفعته.

الشبكة نفسها، لكن كل خلية تحمل حكم اليوم بلونه: حاضر، متأخر، انصراف مبكر، ترك العمل، غائب، لم يحضر بعد. فوقها ملخص الأعداد، ويمكنك النقر على أي رقم لتصفية الشبكة به.

• اضغط خلية لترى تفاصيل التسجيل: وقت الحضور والانصراف، المسافة عن المستشفى، دقة GPS، نسبة مطابقة الوجه، هل الموقع وهمي، أي تخطّيات طُبّقت ومصدرها (إعداد / نافذة مؤقتة / رمز QR)، «مسجَّل دون اتصال» ووقت وصوله للخادم، وصورة التحقق وموقع التسجيل على الخريطة لو كان التخزين مفعّلًا.
• من النافذة نفسها سجّل أو عدّل الحضور يدويًا (الحالة، الأوقات، الشيفت) لمن مُنح عملية التعديل — كل تعديل يدوي يُسجَّل في التدقيق.
• تصدير الشهر أو اليوم (Excel/PDF) بالفلاتر الحالية وبالألوان نفسها والمفتاح أسفل الجدول.

من على الشيفت الآن (سجّل حضورًا ولم ينصرف) حسب الفلاتر. ومنها تأكيد حضور مفاجئ:

1. اضبط الفلاتر (مستشفى، قسم، دفعة، شيفت) واختر المهلة بالدقائق ثم إرسال الطلب.
2. يظهر لكل مستهدف على هاتفه «أكّد وجودك» ويضغط «أنا موجود» (وقد يُطلب وجهه).
3. تتابع في «طلبات التأكيد النشطة» من أكّد ومن ينتظر، ويمكنك تأكيد شخص يدويًا.
4. عند انتهاء المهلة اضغط حسم: إمّا تركهم كما هم أو وسم من لم يؤكّد بـ «ترك العمل».

عندما يفشل موقع الطالب داخل مستشفى بلا تغطية، يعرض له المشرف رمزًا يمسحه فيتجاوز فحص الموقع لدقائق محدودة ويكمل بالوجه. الرمز موقَّع ومربوط بـ: المستشفى، الدفعة والمؤسسة، اليوم، و(اختياريًا) عضو واحد.

1. اختر المستشفى ثم الدفعة (أو عضوًا بعينه فتُؤخذ دفعته).
2. توليد QR. يتجدّد الرمز تلقائيًا قبل انتهاء ثوانيه، فلا تنفع لقطة شاشة قديمة. إيقاف حين تنتهي.

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

• بحث عن عضو: بالكود كاملًا أو الرقم القومي — بطاقته وهل سجّل وجهه. البحث عن عضو خارج تكليفاتك يُرفض ويُسجَّل.
• فحص الوجه: صوّر أو ارفع صورة وقارنها ببصمة عضو — المقارنة والعتبة نفسهما اللتان تجريان عند الحضور، ولا يُحفظ شيء. مفيد عند شكوى «الوجه لا يطابق».
• الصور المحفوظة: صور الحضور/الانصراف لأيام معينة أو بصمة وجه كل عضو (حين يكون تخزينها مفعّلًا)، مع تصدير المعروض أو حذفه أو تفريغ المخزن. الروابط خاصة وتنتهي خلال دقيقتين.

كل رفض وكل إجراء ذي صلاحية كما سجّله الخادم، بالتاريخ والفاعل: تسجيلات الدخول، تغيير كلمات المرور، تسجيل البصمات، الحضور والانصراف، والأحداث الأمنية (موقع وهمي، خارج النطاق، دقة ضعيفة، عدم تطابق الوجه، فشل إثبات الحياة، خارج نافذة الوردية، دخول بكلمة المرور الرئيسية، حذف حساب إداري، بحث خارج النطاق، النسخ الاحتياطي والاسترجاع، استيراد الحضور…).

• فلترة بالتاريخ من/إلى ونوع الحدث، وخيار «الأحداث الأمنية فقط» لإخفاء حركة الحضور العادية.
• تصدير النطاق المعروض كاملًا.
• السجل ملفات يومية على الخادم لا جدول في قاعدة البيانات — لا يُعدَّل من التطبيق.

إعدادات على مستوى التطبيق كله. المستشفى تستطيع أن تزيد الصرامة على بعضها لا أن تخفّفها.

صفحة الأتمتة (صلاحية مستقلة) تشغّل بوت تيليجرام الذي يراسل الطلاب والإدارة. البوت يرسل للطالب الذي ربط حسابه: تأكيد كل حضور وانصراف، تذكيرًا قبل فتح التسجيل، وتنبيهًا بالغياب — وللإدارة ملخصًا يوميًا بأعداد المجدولين والحاضرين والمتأخرين والغائبين لكل مستشفى.

التشغيل مرة واحدة

1. رمز البوت (Token): من @BotFather في تيليجرام. الصق الرمز واحفظ؛ يتحقق النظام منه مع تيليجرام ويقرأ اسم البوت. لا يُعرض الرمز بعدها إلا بآخر حروفه.
2. سجّل الـ webhook بزر تسجيل الـ webhook — به يصل ما يكتبه الطلاب للبوت إلى الخادم (يلزم HTTPS). اضغط تحقق مع تيليجرام لترى أن كل شيء يرد.
3. معرّف محادثة الإدارة: أنشئ مجموعة على تيليجرام للمنسقين، أضف البوت إليها، وأرسل فيها /chatid؛ يردّ البوت بالرقم (يبدأ بـ -100 للمجموعات). الصقه هنا. إليها يذهب الملخص اليومي ورسالة الاختبار.
4. محادثتك على تيليجرام (يراها المدير العام الأول وحده): معرّف محادثتك الخاصة مع البوت (أرسل له /chatid). بمجرد حفظه يُربط حسابك به تلقائيًا دون ضغط Start، ويُعاد ربطه عند كل تشغيل للخادم وعند كل مزامنة. يمكن وضعه أيضًا في TELEGRAM_ROOT_CHAT_ID في ملف .env.
5. رابط الطلاب: ما يفتحه زر «بوت تيليجرام» في صفحة الطالب — اتركه فارغًا لصفحة البوت نفسها.
6. تسجيل الحضور بموقع مشارَك في المحادثة: خيار الكلية، مغلق افتراضيًا. مفعّلًا، يشارك الطالب موقعه مع البوت فيُسجَّل حضوره أو انصرافه فورًا بنفس بوابات التطبيق: نطاق المستشفى، نافذة الشيفت، والتحقق بالوجه كما هو — الطالب الذي يحتاج التحقق بالوجه لا يستطيع من المحادثة ويُرسَل إلى التطبيق؛ فتسجيل بلا وجه لا يحدث إلا لمن له تجاوز الوجه (على العضو أو المستشفى أو الدفعة). اختر «الموقع المباشر فقط»: هو موقع الهاتف الحقيقي، أما الموقع العادي فقد يكون نقطة مختارة على الخريطة والبوت لا يفرّق بينهما. السجل يحمل علامة via: telegram في المراجعة وسجل التدقيق، والتذكير يذكر الطريقة عندما تكون مفعّلة.
7. رابط التطبيق داخل تيليجرام: حيث يفتح التطبيق داخل تيليجرام (Mini App) من زر 📲 سجّل حضورك تحت تذكيرات الطلاب. اتركه فارغًا ليُشتق من عنوان الـ webhook (نفس العنوان + /tg). الطالب يدخل بحسابه المربوط من غير كلمة مرور — تيليجرام يوقّع هوية من فتح التطبيق والخادم يتحقق من التوقيع — ويسجّل بالوجه والحيوية والموقع والـ QR كما في التطبيق؛ في سجل التدقيق يظهر الدخول بعلامة via: telegram.
8. المواقيت: موعد الملخص اليومي (بتوقيت القاهرة) وكم دقيقة قبل فتح الشيفت يخرج التذكير.

الإدارة على القناة

قائمة «الإدارة على القناة» تعرض كل حساب مدير عام ومشرف صفًّا: الاسم في المنصة ونوع الحساب ونطاقه (كل المستشفيات، أو مستشفياته ودفعاته)، وإن كان مربوطًا فاسمه على تيليجرام ومعرّف محادثته ومنذ متى، وشارة الحالة (مربوط، متوقف مؤقتًا، محظور، غير مربوط). على يسار الصف أزرار: تحديث (يقرأ الاسم والحالة من تيليجرام)، تعديل/ربط، فك الربط — لمن يملك عملية «ربط حسابات المشرفين»؛ و«مزامنة الكل» أعلى القائمة تحدّث الجميع. صف المدير العام الأول (الجذر) لا يراه إلا هو، وزره يربطه من مفتاح «محادثة الجذر» مباشرة.

• ربط على صف غير مربوط يفتح نافذة بطريقتين: بالرابط — يُنشئ رابطًا لمرة واحدة ترسله للمشرف على أي وسيلة، يفتح البوت ويضغط Start فيُربط حسابه هو؛ أو يدويًا — تكتب معرّف محادثته (يرسل /chatid للبوت ويعطيك الرقم) واسمه، وما يصله من رسائل.
• تعديل على صف مربوط: إعادة توجيه المعرّف، الاسم، إيقاف الرسائل مؤقتًا أو إعادتها، وأنواع الرسائل. فك الربط يحذف الربط نهائيًا.
• تحديث على كل صف مربوط يسأل تيليجرام عن المحادثة: يقرأ الاسم كما هو اليوم ويتأكد أن الرسائل تصل (من حظر البوت يُعلَّم «حاظر»، ومن عاد يُعلَّم «مربوط»). زر مزامنة الكل أعلى القائمة يفعل ذلك للجميع دفعة واحدة.
• صف المدير العام الأول يراه هو وحده (بشارة «أنت»)، وعليه زر اربطني الآن إن لم يكن مربوطًا: يربطه بالمحادثة المحفوظة في المفاتيح أعلاه، وإن لم تكن محفوظة يفتح نافذة الربط العادية.
• الحدود كما في صفحة المشرفين: المشرف الممنوح الصلاحية يصل إلى حسابات المشرفين فقط، والمدير العام إلى الجميع عدا المدير العام الأول، وربط المدير العام الأول لنفسه فقط. يبقى بإمكان أي مدير عام أو مشرف أن يربط حسابه بنفسه من ملفه الشخصي ← التنبيهات ← ربط.

عمود «النطاق» في القائمة يقول ما يسمعه كل حساب: كل المستشفيات للمدير العام وللمشرف غير المخصص، وأسماء المستشفيات (والدفعات) للمشرف المخصص. كل ما يرسله البوت للإدارة وكل ما يجيب به مقصوص على هذا النطاق — المشرف المخصص لمستشفيين لا يصله ولا يستطيع أن يسأل عن غيرهما.

ما يصل الإدارة

• الملخص اليومي في موعده: سطر لكل مستشفى في النطاق (مجدول / حاضر / متأخر / غائب) — إلى مجموعة الإدارة كاملًا، وإلى كل مربوط بقدر نطاقه.
• تقرير كل شيفت عند إغلاق تسجيله: حاضر / متأخر / غائب في ذلك المستشفى — وأسماء الغائبين لمن يملك صفحة «مراجعة الحضور» أو «لوحة التحكم»؛ من لا يملكها يصله العدد فقط.
• ملخص الأسبوع كل سبت صباحًا: أرقام الأيام السبعة الماضية لكل مستشفى في النطاق ونسبة الحضور.
• تنبيه «لا حضور»: مستشفى فيه 3 مجدولين فأكثر ولم يسجّل أحد بعد 30 دقيقة من فتح الشيفت — عطل محتمل في التطبيق أو الموقع، أو دفعة ليست هناك. يصل لمن يغطي المستشفى.
• الأكثر غيابًا هذا الأسبوع (مغلق افتراضيًا): أسماء أكثر 10 طلاب غيابًا إلى محادثة الإدارة ولمن يملك صفحة المراجعة. أسماء طلاب في مجموعة قرارٌ للكلية، فشغّله من «الميزات» إن أردته.

لكل مشرف مفاتيحه الشخصية في الملف الشخصي ← التنبيهات (أو /notify على البوت)؛ وللكلية مفاتيحها العامة في «الميزات» أدناه. وتحت الملخص والتقارير زر 📲 افتح التطبيق يفتح لوحة الإدارة داخل تيليجرام مسجَّل الدخول — نفس الدخول التلقائي الذي يعمل للطلاب — وزر القائمة في البوت (☰ التطبيق) يفعل ذلك في أي وقت.

أوامر الإدارة على البوت

كل أمر يجيب عن نطاق السائل فقط، وكل أمر يقابل صفحة على المنصة: من لا يملك الصفحة يقال له ذلك ولا يُعطى بياناتها. حين يكون في النطاق أكثر من مستشفى يعرض البوت أزرارًا بأسمائها (وزر «الكل») — أزرار نطاقه وحده.

• /digest — أرقام اليوم لكل مستشفى في النطاق، لحظتها. (لا يحتاج صفحة.)
• /absent — الغائبون اليوم بالأسماء، و/late — المتأخرون. (صفحة مراجعة الحضور أو لوحة التحكم.)
• /now — الموجودون الآن: سجّلوا حضورًا ولم ينصرفوا. (صفحة الموجودون الآن.)
• /find اسم أو رقم قومي — بحث عن طالب في النطاق مع حالته اليوم. (صفحة بحث عن عضو أو الأعضاء.)
• /stats — أرقام الشهر حتى اليوم، و/week — آخر سبعة أيام، بنسبة الحضور. (لوحة التحكم.)
• /roster — روستر اليوم: لكل مستشفى في النطاق شيفتاته بالأعداد (مجدول / حاضر / متأخر / غائب / لم يحن)، ولمستشفى واحد بالأسماء وحالة كلٍّ منهم. (صفحة الروستر أو لوحة التحكم.)
• /hospitals — نطاق السائل. /notify — ما يصله. /help — الأوامر التي يملكها هو.

الميزات — تشغيل وإيقاف لكل نطاق

أسفل الصفحة قائمة «الميزات»: كل ما يفعله البوت، لكل واحدة مفتاح عام للكلية وتحته استثناءات — مؤسسة، مستشفى، دفعة، قسم (تخصيص هذا الشهر)، أو طالب بعينه — كل استثناء تشغيل أو إيقاف. الأخص يغلب: استثناء الطالب يغلب قسمه، والقسم يغلب الدفعة، والدفعة تغلب المستشفى، والمستشفى تغلب المؤسسة، والمؤسسة تغلب المفتاح العام. فتستطيع مثلًا إيقاف التذكيرات لمستشفى بعينه، أو تشغيل التسجيل بالموقع لدفعة واحدة، أو إيقاف زر التطبيق لطالب واحد.

• ما يصل الطلاب: تأكيد الحضور والانصراف · التذكير · تنبيه الغياب · شيفتات الأسبوع · زر «سجّل حضورك» · التسجيل بموقع مشارَك (مغلق افتراضيًا؛ يعمل مع الوضع المحدد في مفاتيح القناة).
• ما يصل الإدارة وما تسأله: الملخص اليومي · تقرير كل شيفت · تنبيه «لا حضور» · ملخص الأسبوع · الأكثر غيابًا (مغلق افتراضيًا) · أوامر الإدارة على البوت (مفتاح عام واحد). ما يخص الإدارة يُستثنى بالمستشفى: إيقاف الملخص لمستشفى يحذف سطره من كل ملخص.
• زر استثناء بجوار الميزة يفتح نموذجًا صغيرًا: النطاق، ثم الجهة (الطالب يُبحث عنه بالاسم أو الرقم القومي)، ثم تشغيل أو إيقاف. الاستثناءات تظهر شارات تحت الميزة، وعلامة ✕ تزيلها فيعود النطاق لما فوقه.

الأرقام والصادر

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

ملف تعريف البوت (الاسم، الوصف، الأوامر، رابط سياسة الخصوصية) يُضبط من @BotFather؛ سياسة الخصوصية جاهزة على /privacy/telegram.html في عنوان المنصة.

1. إضافة مستخدم: الجنسية، الرقم القومي (أو رقم الجواز)، الاسم، الهاتف. كلمة المرور الأولى = تاريخ الميلاد بصيغة ddmmyyyy المشتق من الرقم القومي؛ لصاحب الجواز يولّدها النظام ويعرضها مرة واحدة (انظر غير المصريين). يغيّرها المشرف من ملفه الشخصي.
2. اختر نوع الحساب (مدير / مشرف / مراجع / مخصص) ثم عدّل الصفحات والعمليات صفحةً صفحة: فعّل الصفحة، ثم اختر ما يُسمح به داخلها (إضافة، تعديل، حذف، تصدير، رفع الروستر، رفع الحضور، رفع الصور، توليد أرقام تجريبية — وفي صفحة الأتمتة: ربط حسابات المشرفين، التي تفتح ربط حسابات المشرفين على تيليجرام وتعديلها وتحديثها وفكّها).
3. التخصيص: المستشفيات والدفعات التي يديرها؛ عدم تحديد شيء = نطاق كامل.
4. من صف المشرف: تعديل، التخصيص، إعادة تعيين كلمة المرور، حذف. والمدير العام الأول وحده يرقّي/يخفّض المديرين العامّين ويمنح الصفحات الخاصة (المشرفون، النسخ الاحتياطي) وإعدادات المؤسسة.

• تنزيل النسخة الاحتياطية: ملف بحسابات المدير العام بكلمات مرورها المعمّاة. سرّ — احفظه بعيدًا عن الخادم.
• استرجاع: ارفع الملف لإعادة الحسابات المفقودة؛ الموجودة تُترك كما هي إلا إن اخترت «استبدال» (حسابك أنت لا يُستبدل أبدًا).

لو ضاع الدخول كله

ثلاثة أبواب: إعادة تشغيل الخادم تُعيد إنشاء المدير العام الأول إن لم يوجد؛ صفحة النسخ الاحتياطي؛ وسكربتات سطر الأوامر على الخادم. كلها تُسجَّل في التدقيق.

كل صورة يحفظها النظام — بصمة التسجيل، لقطة الحضور، الصورة الشخصية — ملف على قرص الخادم داخل مجلد STORAGE_DIR، مرتّب ليقرأه إنسان من مدير الملفات بلا أن يسأل قاعدة البيانات. الخادم وحده يسمّي الملفات؛ التطبيق لا يرسل مسارًا أبدًا:

• لا شيء يتغيّر يُسمّى به مجلد شخص: ملفات الطالب لا تعيش تحت مستشفاه ولا دفعته ولا كوده — كلها تتغيّر بنقله، والكود يُعاد توليده مع الدفعة. ما يسمّي مجلده هو سنة إنشاء حسابه ورقمه القومي فقط. أما مجلد المستشفى في لقطات الحضور فهو المستشفى الذي سُجّل فيه الحضور ذلك اليوم — واقعة تاريخية لا تُراجَع.
• الأسماء العربية تبقى عربية في أسماء المجلدات (branch-مستشفى-كفر-الشيخ-الجامعي).
• الشجرة تتبع البيانات: طالب انتقل إلى دفعة أخرى، مستشفى أُعيدت تسميته، نسخة احتياطية قديمة استُرجعت — تُنقل ملفاته إلى مكانها الصحيح تلقائيًا عند كل تشغيل للخادم ومرة يوميًا وبعد كل استرجاع، وتُحذف المجلدات الفارغة. الملف الذي لا يُعرف صاحبه لا يُحذف أبدًا، ويظهر عدده في سجل الخادم.
• لكل شخص بصمة واحدة وصورة شخصية واحدة: الجديدة تحلّ محل القديمة ولا تُترك بجوارها.
• لقطات الحضور تُحذف بعد مدة الاحتفاظ (PROBE_RETENTION_DAYS، 90 يومًا افتراضيًا) لأنها صور بيومترية؛ البصمات والصور الشخصية لا تُحذف.

كل يوم

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

كل شهر

• قبل بداية الشهر: ارفع الروستر لكل مستشفى (أو ابنه بمنشئ الروستر)، وراجع الأقسام.
• خلال الشهر: نقل طالب لمستشفى أخرى = «روستر هذا الشهر» من الروستر، لا تعديل مستشفاه من الأعضاء.
• نهاية الشهر: تصدير مراجعة الحضور ولوحة التحكم (Excel/PDF) للجهة المعنية.

كل فصل

• دفعة جديدة: أضفها ثم استورد طلابها. دفعة انتهت: اجعل أعضاءها غير نشطين بدل حذفهم لتبقى تقاريرهم.
• راجع المشرفين وصلاحياتهم، ونزّل نسخة احتياطية.

الطالب مسجّل الحضور لكنه لا يظهر في المراجعة

الحضور يُسجَّل على صف روستر. تأكد أن للطالب شيفتًا في ذلك اليوم في المستشفى نفسها، وأن الفلاتر (المستشفى/القسم/الدفعة) لا تخفيه.

غيّرت مستشفى الطالب فتغيّر روستره

لن يحدث: تغيير المستشفى من صفحة الأعضاء يمس «مستشفى اليوم» فقط؛ روستر كل شهر يحمل مستشفاه. لتغيير روستر الشهر استخدم «روستر هذا الشهر» من صفحة الروستر.

الحذف مرفوض: «لا يمكن الحذف لأنه مرتبط بـ…»

الرسالة تسمّي الجدول المرتبط (سجلات الحضور، الروستر، الأعضاء…). فكّ الارتباط أولًا أو اجعل العنصر غير نشط.

رمز QR لا يقبله الطالب

الرمز لدفعة ومستشفى ويوم بعينها؛ راجع أنك اخترت دفعته ومستشفاه. «استُخدم من قبل» تعني أن الرموز لمرة واحدة — ولّد آخر.

الخريطة لا تظهر أو تظهر فارغة

تحتاج اتصالًا بالإنترنت لتحميل الطبقات. لو استمرت، بدّل الطبقة (شوارع / قمر صناعي) من زر الطبقات.

الطلاب يرون نسخة قديمة بعد تحديث الموقع

بعد النشر أعد تشغيل خدمة الخادم، واطلب منهم إغلاق التطبيق وفتحه؛ التحديث تلقائي. ولو ظهر «حدث خطأ في هذه الشاشة» لأحدهم: «مسح بيانات التطبيق وإعادة التحميل» ثم الدخول من جديد.

نسيت كلمة مرور المدير العام

مدير عام آخر يعيد تعيينها من صفحة المشرفين، أو تُسترجع الحسابات من النسخة الاحتياطية، أو تُستخدم سكربتات الخادم (انظر النسخ الاحتياطي).