System Requirements Document for hollow-flutter

1. Introduction

hollow-flutter هو تطبيق متكامل يُبنى من الصفر لإدارة «مركز السنة للعلوم الشرعية وتأهيل الدعاة» في عتق – شبوة. يهدف التطبيق إلى تنظيم العمل التعليمي في المركز عبر إدارة المعلمين والطلاب والدروس اليومية والمتون والأوراد القرآنية والتقارير، مع فصل واضح للصلاحيات بين المدير والمعلم والمشرف.

الجمهور المستهدف: المدير المسؤول عن إدارة المركز وحساباته، والمعلمون الذين يديرون الطلاب ويسجّلون الدروس والحضور، والمشرفون من المعلمين الذين يتابعون سجلات المتون والأوراد ويسجّلون الأعمال نيابة عن المعلمين.

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

2. System Overview

التطبيق مبني بـ Flutter وDart، ويعمل على Android وFlutter Web. يستخدم Firebase Authentication لتسجيل الدخول، وCloud Firestore لتخزين البيانات، وProvider لإدارة الحالة، وSharedPreferences للإعدادات المحلية، وfl_chart للرسوم البيانية.

الأدوار الحالية:

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

المسارات التعليمية الخمسة: مفاتيح الطلب، معارج التحصيل – المستوى الأول، معارج التحصيل – المستوى الثاني، معارج التحصيل – المستوى الثالث، القرآن الكريم.

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

2a. Product Interpretation and Delivery Boundary

التطبيق مملوك بالكامل للمركز، ويُبنى من الصفر دون الاعتماد على أي شيفرة سابقة. الهوية مملوكة للتطبيق عبر Firebase Authentication، حيث يسجّل المدير والمعلم والمشرف الدخول بحسابات أنشأها المدير مسبقًا. لا يوجد تسجيل ذاتي عام؛ فالحسابات تُنشأ أو تُدعى من قبل المدير قبل أول استخدام.

حدود التسليم الحالية: تشمل جميع الوظائف المذكورة في هذا المستند: إدارة الحسابات، إدارة الطلاب، تسجيل الدروس والحضور، تسجيل المتون والأوراد، التقارير والرسوم البيانية، المسارات التعليمية الخمسة، وقواعد Firestore المحدودة الصلاحيات.

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

نقطة إعداد Firebase: إذا تعذّر إعداد Firebase دون بيانات تخص المالك، يُنشأ نقطة إعداد واضحة تشرح بدقة القيم المطلوبة (مثل apiKey, projectId, appId)، ولا يُدَّعى أن الاتصال يعمل قبل اختباره.

2b. Source Content Inventory

لا ينطبق — لم يُقدَّم أي توجيه مرجعي من نوع content_source.

2c. Page Content and Component Coverage

Landing

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

Login

• المعلومات والحالة: سطح موحد لتسجيل الدخول واستعادة الجلسة والتحقق العائد للمدير والمعلم والمشرف.
• الإجراءات الأساسية: إدخال البريد الإلكتروني وكلمة المرور، زر «تسجيل الدخول».
• الإجراءات المساندة: «نسيت كلمة المرور» (يوجّه المستخدم للتواصل مع المدير)، تبديل الوضع الفاتح/الداكن.
• الكيانات: بيانات اعتماد المستخدم، جلسة المستخدم.
• مسؤوليات المكونات: نموذج إدخال، تحقق من صحة المدخلات، عرض أخطاء المصادقة بوضوح.
• الحالات: تحميل (عند التحقق من الجلسة)، فارغ (لا ينطبق)، خطأ (بيانات اعتماد خاطئة، حساب معطّل، خطأ شبكة)، انقطاع إنترنت (رسالة واضحة مع إمكانية إعادة المحاولة).
• التوجيه بعد الدخول: المدير → Overview، المعلم → My Students، المشرف → Delegated Work.

Overview

• المعلومات والحالة: ملخص إداري لاستعراض المعلمين والطلاب والمستويات والسجلات. يعرض عدد المعلمين، عدد الطلاب، عدد الدروس اليوم، نسبة الحضور.
• الإجراءات الأساسية: الانتقال إلى Teacher Accounts، Assignments، Password Resets، Reports، Paths، Analytics.
• الإجراءات المساندة: تصفية سريعة حسب التاريخ.
• الكيانات: المعلمون، الطلاب، المستويات، السجلات.
• مسؤوليات المكونات: صفوف بيانات محكومة بخطوط فاصلة، أرقام جدولية، شريط تنقل جانبي RTL.
• الحالات: تحميل، فارغ (رسالة إذا لم توجد بيانات)، خطأ، انقطاع إنترنت.

Teacher Accounts

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

Assignments

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

Password Resets

• المعلومات والحالة: إدارة طلبات إعادة تعيين كلمات مرور المعلمين بأمان.
• الإجراءات الأساسية: إرسال رابط إعادة تعيين كلمة المرور، عرض حالة الطلب.
• الإجراءات المساندة: عرض سجل الطلبات السابقة.
• الكيانات: المعلم، طلب إعادة التعيين.
• مسؤوليات المكونات: جدول محكوم، زر إرسال، عرض نتيجة العملية.
• الحالات: تحميل، فارغ (رسالة إذا لم توجد طلبات)، خطأ، انقطاع إنترنت.

Reports

• المعلومات والحالة: تقارير إدارية قابلة للتصفية حسب المعلم والطالب والمستوى والتاريخ.
• الإجراءات الأساسية: تطبيق التصفية، عرض التقرير، تصدير (إن أمكن).
• الإجراءات المساندة: حفظ التصفية المفضلة.
• الكيانات: المعلم، الطالب، المستوى، التاريخ، السجلات.
• مسؤوليات المكونات: صفوف تصفية، جدول محكوم، رسم بياني واحد (fl_chart).
• الحالات: تحميل، فارغ (رسالة إذا لم توجد بيانات مطابقة)، خطأ، انقطاع إنترنت.

My Students

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

Student Details

• المعلومات والحالة: إنشاء ملف الطالب وتعديله ونقله بين المستويات مع حفظ السجل.
• الإجراءات الأساسية: تعديل بيانات الطالب، نقل الطالب بين المستويات، عرض سجل الطالب (الدروس، الحضور، الأوراد).
• الإجراءات المساندة: حذف الطالب (مع تأكيد).
• الكيانات: الطالب، المستوى، السجل.
• مسؤوليات المكونات: نموذج إدخال، جدول محكوم للسجل، حوار تأكيد الحذف.
• الحالات: تحميل، فارغ (رسالة إذا لم يوجد سجل)، خطأ، انقطاع إنترنت.

Lessons

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

Attendance

• المعلومات والحالة: تسجيل الحضور والغياب ومراجعة السجل المرتبط بالطالب.
• الإجراءات الأساسية: تسجيل حضور/غياب، تعديل سجل، عرض سجل الطالب.
• الإجراءات المساندة: تصفية حسب التاريخ والطالب.
• الكيانات: سجل الحضور (الطالب، التاريخ، الحالة).
• مسؤوليات المكونات: جدول محكوم، نموذج إدخال، عرض النتيجة.
• الحالات: تحميل، فارغ (رسالة إذا لم يوجد سجل)، خطأ، انقطاع إنترنت.

Memorization

• المعلومات والحالة: تسجيل إنجاز المتون والأوراد للمستخدمين المخوّلين.
• الإجراءات الأساسية: تسجيل متن جديد، تسجيل ورد قرآني (بعدد الصفحات)، تعديل سجل، حذف سجل (مع تأكيد).
• الإجراءات المساندة: تصفية حسب الطالب والتاريخ.
• الكيانات: المتن، الورد القرآني (عدد الصفحات).
• مسؤوليات المكونات: نموذج إدخال، جدول محكوم، حوار تأكيد الحذف.
• الحالات: تحميل، فارغ (رسالة إذا لم يوجد سجل)، خطأ، انقطاع إنترنت.

Delegated Work

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

Paths

• المعلومات والحالة: استعراض المسارات التعليمية الخمسة وطلابها وسجلاتها وتقاريرها.
• الإجراءات الأساسية: الانتقال إلى تفاصيل مسار، عرض طلاب المسار، عرض سجلات المسار، عرض تقارير المسار.
• الإجراءات المساندة: تصفية حسب المستوى.
• الكيانات: المسار (مفاتيح الطلب، معارج التحصيل ١/٢/٣، القرآن الكريم)، الطلاب، السجلات.
• مسؤوليات المكونات: شريط لوني بعرض كامل يحمل اسم المسار ورمزه (م ط / ع١ / ع٢ / ع٣ / ق)، جدول محكوم.
• الحالات: تحميل، فارغ (رسالة إذا لم يوجد طلاب)، خطأ، انقطاع إنترنت.

Analytics

• المعلومات والحالة: ملخصات إحصائية ورسوم بيانية للتقدم والتقارير.
• الإجراءات الأساسية: عرض الرسوم البيانية، تصفية حسب التاريخ والمعلم والمستوى.
• الإجراءات المساندة: تبديل نوع الرسم البياني.
• الكيانات: الإحصائيات، الرسوم البيانية.
• مسؤوليات المكونات: رسوم fl_chart، صفوف تصفية، جدول محكوم.
• الحالات: تحميل، فارغ (رسالة إذا لم توجد بيانات)، خطأ، انقطاع إنترنت.

Quran Progress

• المعلومات والحالة: عرض تقدم الورد القرآني المحسوب من مجموع الصفحات المسجلة فعليًا.
• الإجراءات الأساسية: عرض مجموع الصفحات، عرض مؤشر التقدم الدائري، عرض سجل الأوراد.
• الإجراءات المساندة: تصفية حسب الطالب والتاريخ.
• الكيانات: الورد القرآني، مجموع الصفحات، مؤشر التقدم.
• مسؤوليات المكونات: رقم كبير بأرقام جدولية (40px موبايل → 88px ديسكتوب)، مؤشر دائري ذهبي على أخضر (120px)، جدول محكوم.
• الحالات: تحميل، فارغ (رسالة إذا لم توجد أوراد)، خطأ، انقطاع إنترنت.

Confirmations

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

System States

• المعلومات والحالة: عرض حالات التحميل والفراغ والأخطاء وانقطاع الإنترنت.
• الإجراءات الأساسية: إعادة المحاولة عند الخطأ أو انقطاع الإنترنت.
• الإجراءات المساندة: عرض تفاصيل الخطأ (إن أمكن).
• الكيانات: حالة النظام، رسالة الخطأ.
• مسؤوليات المكونات: مؤشر تحميل، إطار محكوم مركزي برسالة عربية واحدة للحالة الفارغة، رسالة خطأ واضحة، رسالة انقطاع إنترنت.
• الحالات: تحميل، فارغ، خطأ، انقطاع إنترنت.

3. Functional Requirements

FR-01: إنشاء التطبيق من الصفر

As a مدير المركز I should أن يكون لدي تطبيق متكامل مبني من الصفر لإدارة المركز so that أتمكن من إدارة المعلمين والطلاب والدروس والمتون والأوراد القرآنية والتقارير.

• Provenance: explicit
• Lifecycle: initiator = المدير (كممثل للمركز)، trigger = الحاجة لإدارة المركز، result = تطبيق قابل للتشغيل والتطوير، failure = تعذّر البناء، recovery = مراجعة الإعدادات وإعادة البناء، continuation = استخدام التطبيق في الإدارة اليومية.
• Acceptance: التطبيق يُبنى بنجاح على Android وFlutter Web، ويشمل جميع الوظائف المذكورة.

FR-02: البناء من الصفر دون شيفرة سابقة

As a مطوّر I should أن أبني المشروع من الصفر دون فحص مستودع موجود أو الاعتماد على شيفرة سابقة so that يكون الكود نظيفًا ومملوكًا بالكامل للمركز.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = بدء المشروع، result = ملفات المشروع وبنيته وكوده منشأة، failure = الاعتماد على شيفرة سابقة، recovery = إعادة الإنشاء من الصفر، continuation = تطوير التطبيق.
• Acceptance: لا يوجد أي اعتماد على مستودع أو شيفرة سابقة.

FR-03: التقنيات المحددة

As a مطوّر I should أن أستخدم Flutter وDart وFirebase Authentication وCloud Firestore وProvider وSharedPreferences وfl_chart so that يلبي التطبيق المتطلبات التقنية.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = إعداد المشروع، result = تقنيات مثبّتة ومهيّأة، failure = تعارض إصدارات، recovery = استخدام أحدث إصدارات مستقرة متوافقة، continuation = البناء والتشغيل.
• Acceptance: جميع التقنيات المذكورة مستخدمة، ودعم Android وFlutter Web يعمل.

FR-04: الواجهة العربية RTL

As a مستخدم I should أن أرى واجهة عربية بالكامل باتجاه RTL so that تكون تجربة الاستخدام طبيعية بالعربية.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = فتح التطبيق، result = واجهة RTL بالعربية، failure = ظهور عناصر LTR، recovery = تصحيح إعدادات الاتجاه، continuation = الاستخدام.
• Acceptance: جميع الشاشات تعرض النصوص العربية باتجاه RTL.

FR-05: التصميم المتجاوب والوضعان

As a مستخدم I should أن أرى تصميمًا متجاوبًا للهاتف والويب مع دعم الوضعين الفاتح والداكن so that أستخدم التطبيق على أي جهاز وبأي إضاءة.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = تغيير حجم الشاشة أو الوضع، result = تصميم متجاوب ووضع مطبّق، failure = كسر التخطيط، recovery = تصحيح التخطيط، continuation = الاستخدام.
• Acceptance: التطبيق يعمل على 375px و768px و1280px، والوضعان الفاتح والداكن يعملان.

FR-06: الهوية البصرية

As a مستخدم I should أن أرى هوية بصرية هادئة (أخضر داكن ولمسات ذهبية) وخط عربي واضح مثل IBM Plex Sans Arabic so that تناسب الواجهة مركزًا شرعيًا.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = فتح التطبيق، result = هوية بصرية مطبّقة، failure = عدم تطبيق الهوية، recovery = تصحيح الثيم، continuation = الاستخدام.
• Acceptance: الألوان والخطوط مطبّقة في جميع الشاشات.

FR-07: تصميم الشاشات الأساسية

As a مستخدم I should أن أرى شاشة دخول ولوحات رئيسية وقوائم ونماذج إدخال وتقارير so that أتمكن من إنجاز مهامي.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = التنقل، result = شاشات مصمّمة، failure = شاشة مفقودة، recovery = إضافة الشاشة، continuation = الاستخدام.
• Acceptance: جميع الشاشات المذكورة موجودة وقابلة للاستخدام.

FR-08: حالات التحميل والفراغ والأخطاء وانقطاع الإنترنت

As a مستخدم I should أن أرى حالات التحميل والبيانات الفارغة والأخطاء وانقطاع الإنترنت برسائل واضحة so that أفهم ما يحدث وأتخذ الإجراء المناسب.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = حدوث الحالة، result = رسالة واضحة، failure = رسالة غير واضحة، recovery = تحسين الرسالة، continuation = إعادة المحاولة أو المتابعة.
• Acceptance: جميع الحالات الأربع معروضة برسائل عربية واضحة.

FR-09: الشعار المؤقت

As a مستخدم I should أن أرى شعارًا مؤقتًا بسيطًا قابلًا للاستبدال so that لا نستخدم صورًا محمية أو غير مرخصة.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = فتح التطبيق، result = شعار مؤقت معروض، failure = شعار مفقود، recovery = إضافة الشعار، continuation = الاستخدام.
• Acceptance: الشعار مبني بالكود وقابل للاستبدال في ملف واحد، ولا توجد صور محمية.

FR-10: أسماء المستخدمين الديناميكية

As a مستخدم I should أن أرى أسماء المستخدمين ديناميكية من بيانات Firestore so that لا تُثبَّت أسماء أشخاص في الواجهة.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = عرض البيانات، result = أسماء ديناميكية، failure = أسماء ثابتة، recovery = تصحيح المصدر، continuation = الاستخدام.
• Acceptance: جميع الأسماء والأدوار والأرقام تأتي من بيانات Firestore.

FR-11: إدارة حسابات المعلمين

As a مدير I should أن أنشئ حسابات المعلمين وأعدّلها وأعطّلها وأحذفها so that أدير المعلمين في المركز.

• Provenance: explicit
• Lifecycle: initiator = المدير، trigger = الحاجة لإدارة معلم، result = حساب منشأ/معدّل/معطّل/محذوف، failure = فشل العملية، recovery = رسالة خطأ وإعادة المحاولة، continuation = عرض النتيجة.
• Acceptance: جميع العمليات الأربع تعمل، مع تأكيد قبل الحذف أو التعطيل.

FR-12: تعيين مسؤول المتون والأوراد

As a مدير I should أن أعيّن معلمًا مسؤولًا عن المتون والأوراد القرآنية so that يكون هناك مشرف مسؤول.

• Provenance: explicit
• Lifecycle: initiator = المدير، trigger = الحاجة لمشرف، result = معلم معيّن مشرفًا، failure = فشل التعيين، recovery = إعادة المحاولة، continuation = ظهور واجهة المشرف للمعلم.
• Acceptance: التعيين يعمل، وتظهر واجهة المشرف للمعلم المعيّن.

FR-13: إعادة تعيين كلمات المرور

As a مدير I should أن أعيد تعيين كلمات مرور المعلمين بأمان so that يستعيد المعلمون وصولهم.

• Provenance: explicit
• Lifecycle: initiator = المدير، trigger = طلب معلم، result = رابط إعادة تعيين مرسل، failure = فشل الإرسال، recovery = إعادة المحاولة، continuation = إشعار المعلم.
• Acceptance: العملية تعمل بأمان دون تخزين كلمات المرور كنص صريح.

FR-14: استعراض المعلمين والطلاب والمستويات والسجلات

As a مدير I should أن أستعرض المعلمين والطلاب والمستويات والسجلات so that أتابع حالة المركز.

• Provenance: explicit
• Lifecycle: initiator = المدير، trigger = الحاجة للمتابعة، result = بيانات معروضة، failure = فشل الجلب، recovery = إعادة المحاولة، continuation = اتخاذ قرار.
• Acceptance: جميع القوائم معروضة وقابلة للتصفية.

FR-15: تقارير شاملة للمدير

As a مدير I should أن أعرض تقارير شاملة حسب المعلم والطالب والمستوى والتاريخ so that أحلّل أداء المركز.

• Provenance: explicit
• Lifecycle: initiator = المدير، trigger = الحاجة للتحليل، result = تقرير معروض، failure = فشل التوليد، recovery = إعادة المحاولة، continuation = اتخاذ قرار.
• Acceptance: التقارير قابلة للتصفية بالأربعة معايير.

FR-16: إدارة الطلاب التابعين للمعلم

As a معلم I should أن أدير الطلاب التابعين لي so that أنظّم تعليمهم.

• Provenance: explicit
• Lifecycle: initiator = المعلم، trigger = الحاجة لإدارة طالب، result = طالب مضاف/معدّل، failure = فشل العملية، recovery = إعادة المحاولة، continuation = عرض النتيجة.
• Acceptance: المعلم يرى طلابه فقط.

FR-17: تسجيل الدروس اليومية

As a معلم I should أن أسجّل الدروس اليومية وأربطها بالطلاب والمستوى والتاريخ so that يكون هناك سجل دقيق.

• Provenance: explicit
• Lifecycle: initiator = المعلم، trigger = انتهاء درس، result = درس مسجّل، failure = فشل الحفظ، recovery = إعادة المحاولة، continuation = عرض السجل.
• Acceptance: الدرس مرتبط بالطالب والمعلم والمستوى والتاريخ.

FR-18: تسجيل الحضور والغياب

As a معلم I should أن أسجّل الحضور والغياب so that أتابع انتظام الطلاب.

• Provenance: explicit
• Lifecycle: initiator = المعلم، trigger = بداية الحصة، result = سجل حضور، failure = فشل الحفظ، recovery = إعادة المحاولة، continuation = عرض السجل.
• Acceptance: الحضور والغياب مسجّلان لكل طالب.

FR-19: استعراض سجل الدروس والتقارير للمعلم

As a معلم I should أن أستعرض سجل الدروس والتقارير الخاصة بطلابي so that أتابع تقدمهم.

• Provenance: explicit
• Lifecycle: initiator = المعلم، trigger = الحاجة للمتابعة، result = سجل وتقارير معروضة، failure = فشل الجلب، recovery = إعادة المحاولة، continuation = اتخاذ قرار.
• Acceptance: السجل والتقارير خاصة بطلاب المعلم فقط.

FR-20: تسجيل المتون والأوراد للمعلم المخوّل

As a معلم مخوّل I should أن أسجّل المتون والأوراد so that أوثّق إنجاز الطلاب.

• Provenance: explicit
• Lifecycle: initiator = المعلم المخوّل، trigger = إنجاز طالب، result = سجل متن/ورد، failure = فشل الحفظ، recovery = إعادة المحاولة، continuation = عرض السجل.
• Acceptance: التسجيل متاح فقط للمعلم المخوّل.

FR-21: واجهة المشرف

As a مشرف I should أن أرى واجهة للوصول إلى قائمة المعلمين والطلاب so that أتابع السجلات.

• Provenance: explicit
• Lifecycle: initiator = المشرف، trigger = تسجيل الدخول، result = واجهة معروضة، failure = فشل العرض، recovery = إعادة المحاولة، continuation = المتابعة.
• Acceptance: الواجهة تعرض قوائم المعلمين والطلاب.

FR-22: متابعة سجلات المعلمين والطلاب

As a مشرف I should أن أتابع سجلات المعلمين والطلاب ضمن الصلاحيات المحددة لي so that أراقب الجودة.

• Provenance: explicit
• Lifecycle: initiator = المشرف، trigger = الحاجة للمتابعة، result = سجلات معروضة، failure = فشل الجلب، recovery = إعادة المحاولة، continuation = اتخاذ قرار.
• Acceptance: المتابعة ضمن الصلاحيات المحددة فقط.

FR-23: تسجيل العمل نيابة عن معلم

As a مشرف I should أن أسجّل عملًا نيابة عن معلم مع حفظ اسم المعلم المقصود وإظهار ذلك بوضوح so that يكون السجل دقيقًا.

• Provenance: explicit
• Lifecycle: initiator = المشرف، trigger = حاجة المعلم، result = سجل باسم المعلم المقصود مع وسم «نيابةً عن»، failure = فشل الحفظ، recovery = إعادة المحاولة، continuation = عرض السجل.
• Acceptance: السجل محفوظ باسم المعلم المقصود، والوسم ظاهر بوضوح.

FR-24: المسارات التعليمية الخمسة

As a مستخدم I should أن أرى المسارات الخمسة (مفاتيح الطلب، معارج التحصيل ١/٢/٣، القرآن الكريم) so that أتنقل بينها.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = الحاجة للتنقل، result = مسارات معروضة، failure = فشل العرض، recovery = إعادة المحاولة، continuation = الانتقال لمسار.
• Acceptance: المسارات الخمسة موجودة بأسمائها الدقيقة.

FR-25: عرض طلاب وسجلات وتقارير كل مسار

As a مستخدم I should أن أرى لكل مسار طلابه وسجلاته وتقاريره مع إمكانية الانتقال إلى تفاصيله so that أتابع كل مسار.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = اختيار مسار، result = تفاصيل معروضة، failure = فشل العرض، recovery = إعادة المحاولة، continuation = المتابعة.
• Acceptance: كل مسار يعرض طلابه وسجلاته وتقاريره.

FR-26: تسجيل دخول آمن واستعادة جلسة

As a مستخدم I should أن أسجّل الدخول بأمان وأن تُستعاد جلستي so that لا أحتاج لتسجيل الدخول في كل مرة.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = فتح التطبيق، result = جلسة مستعادة أو شاشة دخول، failure = فشل المصادقة، recovery = إعادة المحاولة، continuation = الاستخدام.
• Acceptance: الجلسة تُستعاد تلقائيًا عند وجودها.

FR-27: التوجيه حسب الدور

As a مستخدم I should أن أوجَّه بعد تسجيل الدخول إلى الواجهة المناسبة لدوري so that أصل بسرعة لما يخصني.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = تسجيل الدخول، result = توجيه للواجهة المناسبة، failure = توجيه خاطئ، recovery = تصحيح المنطق، continuation = الاستخدام.
• Acceptance: المدير → Overview، المعلم → My Students، المشرف → Delegated Work.

FR-28: إدارة ملفات المعلمين والطلاب

As a مدير أو معلم I should أن أدير ملفات المعلمين والطلاب so that تكون البيانات محدّثة.

• Provenance: explicit
• Lifecycle: initiator = المدير/المعلم، trigger = الحاجة للتحديث، result = ملف محدّث، failure = فشل الحفظ، recovery = إعادة المحاولة، continuation = عرض النتيجة.
• Acceptance: الملفات قابلة للإضافة والتعديل.

FR-29: إضافة طالب وتعديله ونقله بين المستويات

As a معلم I should أن أضيف طالبًا وأعدّله وأنقله بين المستويات مع المحافظة على سجله so that يتابع الطالب مساره دون فقدان تاريخه.

• Provenance: explicit
• Lifecycle: initiator = المعلم، trigger = الحاجة للنقل، result = طالب منقول مع سجل محفوظ، failure = فقدان السجل، recovery = استعادة السجل، continuation = المتابعة.
• Acceptance: السجل محفوظ بعد النقل.

FR-30: متابعة الحضور والغياب وسجل كل طالب

As a معلم I should أن أتابع الحضور والغياب وسجل كل طالب so that أعرف انتظامه.

• Provenance: explicit
• Lifecycle: initiator = المعلم، trigger = الحاجة للمتابعة، result = سجل معروض، failure = فشل الجلب، recovery = إعادة المحاولة، continuation = اتخاذ قرار.
• Acceptance: السجل معروض لكل طالب.

FR-31: تقارير قابلة للتصفية

As a مستخدم I should أن أصفّي التقارير حسب التاريخ والمعلم والطالب والمستوى so that أحصل على ما أحتاجه.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = الحاجة للتصفية، result = تقرير مصفّى، failure = فشل التصفية، recovery = إعادة المحاولة، continuation = التحليل.
• Acceptance: التصفية تعمل بالأربعة معايير.

FR-32: ملخصات إحصائية ورسوم بيانية

As a مستخدم I should أن أرى ملخصات إحصائية ورسومًا بيانية مفهومة so that أفهم البيانات بسرعة.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = فتح التحليلات، result = ملخصات ورسوم معروضة، failure = فشل العرض، recovery = إعادة المحاولة، continuation = التحليل.
• Acceptance: الرسوم البيانية معروضة بوضوح.

FR-33: تأكيد الإجراءات الحساسة

As a مستخدم I should أن أرى تأكيدًا قبل الحذف أو أي إجراء حساس مع إظهار نتيجة العملية so that أتجنب الأخطاء.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = إجراء حساس، result = تأكيد ثم نتيجة، failure = فشل الإجراء، recovery = إعادة المحاولة، continuation = المتابعة.
• Acceptance: التأكيد يظهر قبل الحذف، والنتيجة تُعرض بوضوح.

FR-34: قاعدة تسجيل القرآن

As a مستخدم I should أن يعتمد تسجيل الورد ومؤشر تقدم الطالب على عدد الصفحات المسجلة فقط so that يكون المقياس دقيقًا.

• Provenance: explicit
• Lifecycle: initiator = المستخدم، trigger = تسجيل ورد، result = مجموع صفحات محدّث، failure = حساب خاطئ، recovery = تصحيح الحساب، continuation = عرض المؤشر.
• Acceptance: مجموع الصفحات المسجلة فعليًا هو المصدر الوحيد، ولا يُحسب التقدم من الأيام أو الجلسات أو مدة الاستخدام.

FR-35: نماذج بيانات واضحة

As a مطوّر I should أن أنشئ نماذج بيانات واضحة للمستخدم والمعلم والطالب والدرس والمتن والورد القرآني والتقارير so that يكون الكود منظمًا.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = بدء التطوير، result = نماذج منشأة، failure = نماذج ناقصة، recovery = إكمالها، continuation = التطوير.
• Acceptance: جميع النماذج المذكورة موجودة.

FR-36: فصل الواجهات عن الخدمات

As a مطوّر I should أن أفصل الواجهات عن الخدمات وأضع عمليات Firebase في طبقة خدمات مستقلة so that يكون الكود قابلًا للصيانة.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = بدء التطوير، result = فصل واضح، failure = تداخل، recovery = إعادة الهيكلة، continuation = التطوير.
• Acceptance: عمليات Firebase في طبقة خدمات مستقلة.

FR-37: قواعد Firestore محدودة الصلاحيات

As a مدير I should أن تكون قواعد Firestore محدودة الصلاحيات so that تكون البيانات آمنة.

• Provenance: explicit
• Lifecycle: initiator = المدير، trigger = إعداد القواعد، result = قواعد مطبّقة، failure = قواعد خاطئة، recovery = تصحيحها، continuation = الاستخدام.
• Acceptance: المدير فقط يدير الحسابات والإعدادات العامة، المعلم يصل لبياناته وطلابه وسجلاته المصرّح بها، المشرف يحصل على الصلاحيات الإضافية الممنوحة له فقط.

FR-38: عدم الاعتماد على إخفاء الأزرار

As a مطوّر I should أن أتحقق من الصلاحية على قاعدة البيانات وليس بإخفاء الأزرار فقط so that تكون الحماية حقيقية.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = إعداد الصلاحيات، result = تحقق على القاعدة، failure = اعتماد على الواجهة، recovery = إضافة التحقق، continuation = الاستخدام.
• Acceptance: قواعد Firestore تتحقق من الصلاحية.

FR-39: عدم تخزين كلمات المرور كنص صريح

As a مطوّر I should أن لا أخزّن كلمات المرور كنص صريح ولا أضع مفاتيح أو أسرار Firebase في الشيفرة المنشورة so that تكون البيانات آمنة.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = إعداد المصادقة، result = كلمات مرور مشفّرة، failure = تخزين صريح، recovery = تصحيح، continuation = الاستخدام.
• Acceptance: لا توجد كلمات مرور أو مفاتيح في الشيفرة.

FR-40: بيانات تجريبية اختيارية

As a مطوّر I should أن أضيف بيانات تجريبية اختيارية للتطوير فقط مع فصلها بوضوح عن بيانات الإنتاج so that أختبر التطبيق دون تلويث الإنتاج.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = الحاجة للاختبار، result = بيانات تجريبية مفصولة، failure = خلط البيانات، recovery = فصلها، continuation = التطوير.
• Acceptance: البيانات التجريبية مفصولة بوضوح.

FR-41: بنية المشروع

As a مطوّر I should أن أنشئ بنية مشروع واضحة تشمل core وmodels وservices وscreens وwidgets وtest so that يكون الكود منظمًا.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = بدء التطوير، result = بنية منشأة، failure = بنية ناقصة، recovery = إكمالها، continuation = التطوير.
• Acceptance: جميع المجلدات المذكورة موجودة.

FR-42: كود كامل قابل للبناء

As a مطوّر I should أن أكتب كودًا كاملًا قابلًا للبناء لا تصاميم أو شرح فقط so that يكون التطبيق قابلًا للتشغيل.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = التسليم، result = كود قابل للبناء، failure = كود ناقص، recovery = إكماله، continuation = البناء.
• Acceptance: الكود يُبنى بنجاح.

FR-43: ملف README

As a مطوّر I should أن أضيف ملف README يشرح المتطلبات وتشغيل التطبيق وإعداد Firebase so that يفهم المطوّرون كيفية التشغيل.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = التسليم، result = README منشأ، failure = README ناقص، recovery = إكماله، continuation = الاستخدام.
• Acceptance: README يشرح المتطلبات والتشغيل وإعداد Firebase.

FR-44: قواعد Firestore وخطوات نشرها

As a مطوّر I should أن أضيف قواعد Firestore وخطوات نشرها so that يمكن نشر القواعد.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = التسليم، result = قواعد وخطوات منشأة، failure = قواعد ناقصة، recovery = إكمالها، continuation = النشر.
• Acceptance: القواعد وخطوات النشر موجودة.

FR-45: اختبارات الوظائف والصلاحيات

As a مطوّر I should أن أضيف اختبارات للوظائف الأساسية والصلاحيات ثم أشغّل التحليل والبناء so that يكون الكود موثوقًا.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = التسليم، result = اختبارات ناجحة، failure = اختبارات فاشلة، recovery = إصلاح الكود، continuation = البناء.
• Acceptance: الاختبارات تعمل، والتحليل والبناء ينجحان.

FR-46: نقطة إعداد Firebase

As a مطوّر I should أن أنشئ نقطة إعداد واضحة عند تعذّر إعداد Firebase دون بيانات المالك مع شرح القيم المطلوبة so that يعرف المالك ما يجب إضافته.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = تعذّر الإعداد، result = نقطة إعداد موثّقة، failure = إعداد خاطئ، recovery = تصحيحه، continuation = الإعداد.
• Acceptance: النقطة واضحة، ولا يُدَّعى أن الاتصال يعمل قبل اختباره.

FR-47: عدم النشر الفعلي

As a مطوّر I should أن لا أنفّذ نشرًا فعليًا ولا أرفع المشروع إلى مستودع بعيد دون إذن صريح so that لا تحدث تغييرات غير مصرّح بها.

• Provenance: explicit
• Lifecycle: initiator = المطوّر، trigger = التسليم، result = لا نشر، failure = نشر غير مصرّح، recovery = إيقافه، continuation = التسليم.
• Acceptance: لا يوجد نشر فعلي أو رفع بعيد.

FR-48: إنشاء حسابات المعلمين قبل أول استخدام

As a مدير I should أن أنشئ حسابات المعلمين أو أدعوهم قبل أول استخدام so that يتمكنوا من الدخول.

• Provenance: required_inference
• Lifecycle: initiator = المدير، trigger = إضافة معلم، result = حساب منشأ، failure = فشل الإنشاء، recovery = إعادة المحاولة، continuation = إشعار المعلم.
• Acceptance: الحساب منشأ وقابل للدخول.

FR-49: تسجيل الدخول والتحقق من الجلسة

As a مستخدم I should أن أسجّل الدخول ويتم التحقق من جلستي قبل الوصول إلى البيانات المحمية so that تكون البيانات آمنة.

• Provenance: required_inference
• Lifecycle: initiator = المستخدم، trigger = فتح التطبيق، result = جلسة محقّقة، failure = فشل التحقق، recovery = إعادة الدخول، continuation = الاستخدام.
• Acceptance: البيانات المحمية غير متاحة بدون جلسة محقّقة.

FR-50: تطبيق قواعد Firestore للتحقق من الدور

As a مطوّر I should أن أطبّق قواعد Firestore للتحقق من الدور ونطاق الوصول so that لا يُكتفى بإخفاء عناصر الواجهة.

• Provenance: required_inference
• Lifecycle: initiator = المطوّر، trigger = إعداد القواعد، result = تحقق مطبّق، failure = تحقق ناقص، recovery = تصحيحه، continuation = الاستخدام.
• Acceptance: القواعد تتحقق من الدور ونطاق الوصول.

FR-51: تعيين المشرف قبل منحه الصلاحيات

As a مدير I should أن أعيّن المشرف قبل منحه صلاحيات المتون والأوراد أو التسجيل نيابة عن معلم so that تكون الصلاحيات صحيحة.

• Provenance: required_inference
• Lifecycle: initiator = المدير، trigger = تعيين مشرف، result = صلاحيات ممنوحة، failure = صلاحيات خاطئة، recovery = تصحيحها، continuation = الاستخدام.
• Acceptance: المشرف لا يحصل على الصلاحيات قبل التعيين.

FR-52: حفظ المعلم المقصود عند النيابة

As a مشرف I should أن يُحفظ المعلم المقصود عند تسجيل العمل بالنيابة ويظهر في السجل so that يكون السجل دقيقًا.

• Provenance: required_inference
• Lifecycle: initiator = المشرف، trigger = تسجيل نيابة، result = سجل باسم المعلم المقصود، failure = حفظ باسم المشرف، recovery = تصحيح السجل، continuation = عرض السجل.
• Acceptance: السجل محفوظ باسم المعلم المقصود ومعروض بوضوح.

FR-53: حساب تقدم الورد من مجموع الصفحات

As a مستخدم I should أن يُحسب تقدم الورد القرآني من مجموع الصفحات المسجلة فعليًا فقط so that يكون المقياس دقيقًا.

• Provenance: required_inference
• Lifecycle: initiator = المستخدم، trigger = تسجيل ورد، result = مجموع محدّث، failure = حساب خاطئ، recovery = تصحيح الحساب، continuation = عرض المؤشر.
• Acceptance: المجموع محسوب من الصفحات فقط، ولا يُحسب من الأيام أو الجلسات أو مدة الاستخدام.

4. User Personas

المدير

سياق المنتج: المدير هو المسؤول الأعلى عن المركز، ويدير جميع الجوانب الإدارية والتعليمية. يستخدم التطبيق لإنشاء حسابات المعلمين، وتعيين المشرف، وإعادة تعيين كلمات المرور، واستعراض البيانات، وعرض التقارير الشاملة.

الهدف الأساسي: أن يكون لديه رؤية كاملة عن المركز وأن يدير المعلمين والطلاب والمستويات والسجلات بكفاءة.

المسؤوليات المقبولة:

• إنشاء حسابات المعلمين وتعديلها وتعطيلها وحذفها.
• تعيين معلم مسؤول عن المتون والأوراد القرآنية.
• إعادة تعيين كلمات المرور بأمان.
• استعراض المعلمين والطلاب والمستويات والسجلات.
• عرض تقارير شاملة حسب المعلم والطالب والمستوى والتاريخ.
• إدارة الإعدادات العامة.

المدخلات والقرارات: بيانات المعلمين الجدد، قرارات التعيين، طلبات إعادة تعيين كلمات المرور، معايير التصفية في التقارير.

التفاعلات: يتفاعل مع المعلمين (بإنشاء حساباتهم وتعيينهم)، ومع المشرف (بتعيينه)، ومع البيانات (بالاستعراض والتحليل).

النجاح الملحوظ: جميع الحسابات منشأة وصحيحة، والمشرف معيّن، والتقارير معروضة بدقة.

ما يميّز هذا الدور: المدير هو الوحيد الذي يملك صلاحية إدارة الحسابات والإعدادات العامة، وهو الوحيد الذي يرى تقارير شاملة عن جميع المعلمين والطلاب.

المعلم

سياق المنتج: المعلم هو المسؤول المباشر عن تعليم الطلاب التابعين له. يستخدم التطبيق لإدارة طلابه، وتسجيل الدروس اليومية، وتسجيل الحضور والغياب، واستعراض السجلات والتقارير، وتسجيل المتون والأوراد إذا كان مخوّلًا.

الهدف الأساسي: أن يدير تعليم طلابه بكفاءة وأن يوثّق تقدمهم بدقة.

المسؤوليات المقبولة:

• إدارة الطلاب التابعين له.
• تسجيل الدروس اليومية وربطها بالطلاب والمستوى والتاريخ.
• تسجيل الحضور والغياب.
• استعراض سجل الدروس والتقارير الخاصة بطلابه.
• تسجيل المتون والأوراد إذا كان مخوّلًا بذلك.

المدخلات والقرارات: بيانات الطلاب، تفاصيل الدروس، حالات الحضور، إنجازات الطلاب في المتون والأوراد.

التفاعلات: يتفاعل مع طلابه (بإدارتهم وتسجيل تقدمهم)، ومع المدير (بتلقي التعيينات)، ومع المشرف (عند تسجيل المشرف نيابة عنه).

النجاح الملحوظ: جميع الدروس والحضور والأوراد مسجّلة بدقة، وسجلات الطلاب محدّثة.

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

المشرف

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

الهدف الأساسي: أن يتابع جودة تسجيل المتون والأوراد وأن يسجّل الأعمال نيابة عن المعلمين عند الحاجة.

المسؤوليات المقبولة:

• الوصول إلى قائمة المعلمين والطلاب.
• متابعة سجلات المعلمين والطلاب ضمن الصلاحيات المحددة له.
• تسجيل الأعمال نيابة عن معلم مع حفظ اسم المعلم المقصود وإظهار ذلك بوضوح.

المدخلات والقرارات: اختيار المعلم المقصود، تفاصيل العمل المسجّل نيابة عنه، معايير المتابعة.

التفاعلات: يتفاعل مع المدير (الذي عيّنه)، ومع المعلمين (الذين يسجّل نيابة عنهم)، ومع الطلاب (بمتابعة سجلاتهم).

النجاح الملحوظ: السجلات المسجّلة نيابة عن المعلمين محفوظة باسم المعلم المقصود ومعروضة بوضوح.

ما يميّز هذا الدور: المشرف هو معلم له صلاحيات إضافية محددة، وأهم ما يميّزه هو قدرته على تسجيل الأعمال نيابة عن المعلمين مع الحفاظ على دقة الإسناد.

5. Core User Flows

Flow 1: تسجيل الدخول والتوجيه حسب الدور

1. السياق: المستخدم (مدير/معلم/مشرف) يفتح التطبيق.
2. الإجراء: التطبيق يتحقق من وجود جلسة محفوظة.
3. النتيجة: إذا وُجدت جلسة صالحة، يوجَّه المستخدم مباشرة إلى واجهته المناسبة. إذا لم توجد، يظهر صفحة Login.
4. الإجراء: المستخدم يدخل البريد الإلكتروني وكلمة المرور.
5. النتيجة: Firebase Authentication يتحقق من البيانات.
6. التوجيه: المدير → Overview، المعلم → My Students، المشرف → Delegated Work.
7. الفشل: إذا كانت البيانات خاطئة، تظهر رسالة خطأ واضحة مع إمكانية إعادة المحاولة.
8. الاستمرار: المستخدم يبدأ العمل في واجهته.

Flow 2: إنشاء حساب معلم جديد (المدير)

1. السياق: المدير في صفحة Teacher Accounts.
2. الإجراء: المدير يضغط «إضافة معلم جديد».
3. الإجراء: يدخل بيانات المعلم (الاسم، البريد الإلكتروني).
4. النتيجة: Firebase Authentication ينشئ الحساب، وFirestore يحفظ بيانات المعلم.
5. النتيجة: يظهر المعلم في القائمة.
6. الفشل: إذا فشل الإنشاء، تظهر رسالة خطأ واضحة.
7. الاستمرار: المدير يمكنه تعديل الحساب أو تعطيله أو حذفه لاحقًا.

Flow 3: تعيين مشرف (المدير)

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

Flow 4: إعادة تعيين كلمة مرور معلم (المدير)

1. السياق: المدير في صفحة Password Resets.
2. الإجراء: المدير يختار معلمًا ويضغط «إرسال رابط إعادة التعيين».
3. النتيجة: Firebase Authentication يرسل رابطًا إلى بريد المعلم.
4. النتيجة: تظهر حالة الطلب في السجل.
5. الفشل: إذا فشل الإرسال، تظهر رسالة خطأ.
6. الاستمرار: المعلم يستخدم الرابط لتعيين كلمة مرور جديدة.

Flow 5: إضافة طالب جديد (المعلم)

1. السياق: المعلم في صفحة My Students.
2. الإجراء: المعلم يضغط «إضافة طالب».
3. الإجراء: يدخل بيانات الطالب (الاسم، المستوى).
4. النتيجة: Firestore يحفظ بيانات الطالب مرتبطًا بالمعلم.
5. النتيجة: يظهر الطالب في قائمة المعلم.
6. الفشل: إذا فشل الحفظ، تظهر رسالة خطأ.
7. الاستمرار: المعلم يمكنه تعديل الطالب أو نقله بين المستويات.

Flow 6: نقل طالب بين المستويات (المعلم)

1. السياق: المعلم في صفحة Student Details.
2. الإجراء: المعلم يختار المستوى الجديد.
3. الإجراء: يضغط «نقل».
4. النتيجة: يُحدَّث مستوى الطالب في Firestore مع الحفاظ على سجله.
5. النتيجة: يظهر الطالب في المستوى الجديد مع سجله الكامل.
6. الفشل: إذا فشل النقل، تظهر رسالة خطأ.
7. الاستمرار: المعلم يمكنه متابعة سجل الطالب.

Flow 7: تسجيل درس يومي (المعلم)

1. السياق: المعلم في صفحة Lessons.
2. الإجراء: المعلم يضغط «تسجيل درس اليوم».
3. الإجراء: يختار الطالب والمستوى ويدخل موضوع الدرس.
4. النتيجة: Firestore يحفظ الدرس مرتبطًا بالمعلم والطالب والمستوى والتاريخ.
5. النتيجة: يظهر الدرس في السجل.
6. الفشل: إذا فشل الحفظ، تظهر رسالة خطأ.
7. الاستمرار: المعلم يمكنه تسجيل دروس أخرى.

Flow 8: تسجيل الحضور والغياب (المعلم)

1. السياق: المعلم في صفحة Attendance.
2. الإجراء: المعلم يختار الطالب والتاريخ.
3. الإجراء: يحدد الحالة (حاضر/غائب).
4. النتيجة: Firestore يحفظ سجل الحضور.
5. النتيجة: يظهر السجل في صفحة الطالب.
6. الفشل: إذا فشل الحفظ، تظهر رسالة خطأ.
7. الاستمرار: المعلم يمكنه تسجيل حضور طلاب آخرين.

Flow 9: تسجيل ورد قرآني (المعلم المخوّل)

1. السياق: المعلم المخوّل في صفحة Memorization.
2. الإجراء: المعلم يختار الطالب ويدخل عدد الصفحات المسجّلة.
3. النتيجة: Firestore يحفظ الورد.
4. النتيجة: يُحدَّث مجموع الصفحات المسجّلة للطالب.
5. النتيجة: يظهر مؤشر التقدم في صفحة Quran Progress مع الرقم الجديد.
6. الفشل: إذا فشل الحفظ، تظهر رسالة خطأ.
7. الاستمرار: المعلم يمكنه تسجيل أوراد أخرى.

Flow 10: تسجيل عمل نيابة عن معلم (المشرف)

1. السياق: المشرف في صفحة Delegated Work.
2. الإجراء: المشرف يختار المعلم المقصود من القائمة.
3. الإجراء: يسجّل الدرس أو الورد نيابة عنه.
4. النتيجة: Firestore يحفظ السجل باسم المعلم المقصود (وليس باسم المشرف).
5. النتيجة: يظهر السجل مع وسم «نيابةً عن» وخط ذهبي تحت اسم المعلم.
6. الفشل: إذا فشل الحفظ، تظهر رسالة خطأ.
7. الاستمرار: المشرف يمكنه تسجيل أعمال أخرى.

Flow 11: متابعة سجلات المعلمين والطلاب (المشرف)

1. السياق: المشرف في صفحة Delegated Work أو My Students.
2. الإجراء: المشرف يختار معلمًا أو طالبًا.
3. النتيجة: تظهر سجلات المعلم أو الطالب ضمن الصلاحيات المحددة.
4. الفشل: إذا فشل الجلب، تظهر رسالة خطأ.
5. الاستمرار: المشرف يمكنه متابعة سجلات أخرى.

Flow 12: عرض تقارير شاملة (المدير)

1. السياق: المدير في صفحة Reports.
2. الإجراء: المدير يطبّق التصفية حسب المعلم والطالب والمستوى والتاريخ.
3. النتيجة: يظهر التقرير المصفّى.
4. النتيجة: يمكن للمدير عرض الرسوم البيانية في صفحة Analytics.
5. الفشل: إذا فشل التوليد، تظهر رسالة خطأ.
6. الاستمرار: المدير يمكنه تصدير التقرير أو تغيير التصفية.

Flow 13: عرض تقدم الورد القرآني

1. السياق: المستخدم في صفحة Quran Progress.
2. الإجراء: المستخدم يختار الطالب.
3. النتيجة: يظهر مجموع الصفحات المسجّلة فعليًا كرقم كبير بأرقام جدولية.
4. النتيجة: يظهر مؤشر التقدم الدائري الذهبي على الأخضر.
5. النتيجة: يظهر سجل الأوراد في جدول محكوم.
6. الفشل: إذا فشل الجلب، تظهر رسالة خطأ.
7. الاستمرار: المستخدم يمكنه اختيار طالب آخر.

Flow 14: استعراض المسارات التعليمية

1. السياق: المستخدم في صفحة Paths.
2. الإجراء: المستخدم يختار مسارًا من الخمسة.
3. النتيجة: يظهر شريط لوني بعرض كامل يحمل اسم المسار ورمزه (م ط / ع١ / ع٢ / ع٣ / ق).
4. النتيجة: يظهر جدول محكوم بطلاب المسار وسجلاته وتقاريره.
5. الفشل: إذا فشل الجلب، تظهر رسالة خطأ.
6. الاستمرار: المستخدم يمكنه الانتقال إلى تفاصيل طالب أو العودة.

Flow 15: تأكيد إجراء حساس

1. السياق: المستخدم يحاول حذف سجل أو تعطيل حساب.
2. الإجراء: يظهر حوار تأكيد.
3. الإجراء: المستخدم يؤكد أو يلغي.
4. النتيجة: إذا أكّد، يُنفَّذ الإجراء وتظهر النتيجة. إذا ألغى، لا يحدث شيء.
5. الفشل: إذا فشل الإجراء، تظهر رسالة خطأ واضحة.
6. الاستمرار: المستخدم يمكنه إعادة المحاولة أو المتابعة.

6. Visuals Colors and Theme

المصدر الإلهامي: Peter Saville — «قطعة مرمّزة واحدة، صمت لا ينتهي».

العنوان الرئيسي: سجل محكوم — الأخضر الداكن والذهبي كهوية المركز، والصمت كخلفية.

الألوان (الوضع الفاتح)

الألوان (الوضع الداكن)

التباين: #12211C على #F4F1E9 ≈ 14:1؛ #F4F1E9 على #0F3D2E ≈ 11:1؛ #B08A3E على #0F3D2E ≈ 4.8:1 (يُستخدم بأحجام عرض كبيرة فقط).

الخطوط

• العناوين: IBM Plex Sans Arabic — وزن 500 فقط (لا 700+)، تباعد +0.04em، محاذاة يمين، أرقام جدولية دائمًا (tnum).
• النص: IBM Plex Sans Arabic.
• الشيفرات والأرقام اللاتينية: IBM Plex Mono بتباعد 0.18em، أحرف كبيرة، صغيرة.
• لا مائل، لا تسطير.

مقياس الخطوط

مقياس معياري 1.25 على أساس 16px:

• Display: 40/28 (موبايل 40px → ديسكتوب 88px لرقم عدد الصفحات).
• H1: 28/22.
• H2: 22/18.
• Body: 16/15.
• Label: 12/11.
• ارتفاع السطر: 1.7 للنص العربي، 1.15 لأرقام العرض.

لغة الشكل

• زوايا مربعة تمامًا — 0px على البطاقات والمدخلات والأزرار والأوراق.
• المنحنى الوحيد في المنتج هو مؤشر التقدم الدائري للورد القرآني، ويُقرأ كقرص آلة لا كشكل ودود.
• خطوط شعرية 1px بلون #0F3D2E بشفافية 20% تفصل كل كتلة بيانات وصفية.
• لا ظلال: الارتفاع يُعبَّر عنه بخط 1px وتحوّل لوني من #F4F1E9 إلى #FFFFFF.
• الأزرار مستطيلات مسطحة بقاعدة سفلية 2px ذهبية عند التمرير/الضغط.

التخطيط

• شبكة 12 عمودًا صارمة مع شريط جانبي أيمن ثابت (RTL) يحمل شعار المركز المؤقت، ورمز المسار النشط، وشارة الدور.
• المحتوى يشغل الأعمدة 1–9 على الديسكتوب، وعرض كامل على الموبايل مع انطواء الشريط إلى قاعدة علوية.
• كل شاشة قائمة هي جدول محكوم: التسمية بلون باهت على اليمين، القيمة بالحبر على اليسار، مفصولة بخط شعري.
• صفحات تفاصيل المسار تفتح بشريط لوني بعرض كامل من الأخضر الداكن يحمل اسم المسار ورمزه، ثم الجسم المحكوم.
• التقارير صفوف تصفية فوق رسم بياني واحد، لا جدار بطاقات.

الصور

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

7. Signature Design Concept

المدخل العام (Landing): أرضية #F4F1E9 بعرض كامل، مع قاعدة خضراء داكنة 2px تمتد بعرض نافذة العرض أسفل الرأس مباشرة.

في الثلث العلوي، محاذاة يمين:

• سطر الدور بخط mono ذهبي 12px بأحرف كبيرة (المدير / المعلم / المشرف — من بيانات المستخدم المسجّل، لا مثبّت).
• اسم المركز بخط IBM Plex Sans Arabic وزن 500 بحجم 28px موبايل → 44px ديسكتوب، يلتف داخل نافذة العرض.

أسفل القاعدة، الرقم البطولي:

• تسمية «مجموع الصفحات المسجّلة» بلون باهت.
• الرقم نفسه بأرقام جدولية بحجم 40px موبايل → 88px ديسكتوب، بلون أخضر داكن، مع عدّ تصاعدي مرة واحدة عند التحميل — هذا أكبر عنصر على الشاشة وهو الحقيقة الجوهرية للمنتج.
• إلى يساره، قرص تقدم دائري ذهبي على أخضر بحجم 120px يعرض نفس الرقم مقابل هدف المسار، يُرسم مرة واحدة.

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

الإجراء الوحيد هو مستطيل أخضر داكن مسطح، بعرض كامل على الموبايل و240px على الديسكتوب، مكتوب عليه «تسجيل درس اليوم»، مثبّت أسفل الرقم بفجوة 24px.

لا شيء آخر ينافس: لا تدرج، لا شكل، لا لون ثانٍ، لا صورة بطولية.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction)

Motion Tempo: still

Hero Dimensionality: flat

Landing Hero Motion Brief

• الموضوع البؤري: الرقم البطولي «مجموع الصفحات المسجّلة» بأرقام جدولية، مع قرص التقدم الدائري الذهبي على الأخضر.
• أطروحة الإدخال → التحويل → النتيجة: عند تحميل الشاشة، يُرسم القرص مرة واحدة (600ms، ease-out) ويرتفع الرقم من صفر إلى قيمته الحقيقية — الإدخال هو بيانات Firestore، والتحويل هو العدّ التصاعدي، والنتيجة هي عرض الحقيقة الجوهرية للمنتج.
• مفردات الحركة: تلاشٍ دقيق 180ms بدون انزلاق، رسم القرص مرة واحدة، عدّ الرقم مرة واحدة، ظهور خط 1px عند التمرير، انزلاق تسطير ذهبي 120ms.
• الإطار الأول المركّب: أرضية #F4F1E9، قاعدة خضراء 2px، سطر الدور الذهبي، اسم المركز، الرقم البطولي، القرص الدائري، صف البيانات الوصفية الثلاثي، الزر الأخضر.
• حالة تقليل الحركة: عند prefers-reduced-motion، يُرسم القرص والرقم بقيمتهما النهائية فورًا دون عدّ أو رسم.

9. Non-Functional Requirements

NFR-01: الأداء

• المتطلب: يجب أن يستجيب التطبيق بسرعة معقولة على Android وFlutter Web.
• Provenance: required_inference
• المبرر: ضروري لتجربة استخدام مقبولة.

NFR-02: الأمان

• المتطلب: يجب أن تكون قواعد Firestore محدودة الصلاحيات، ولا تُخزَّن كلمات المرور كنص صريح، ولا تُوضع مفاتيح أو أسرار Firebase في الشيفرة المنشورة.
• Provenance: explicit
• المبرر: حماية بيانات المركز.

NFR-03: التوافق

• المتطلب: يجب أن يعمل التطبيق على Android وFlutter Web بأحدث إصدارات مستقرة متوافقة.
• Provenance: explicit
• المبرر: دعم المنصات المطلوبة.

NFR-04: إمكانية الوصول

• المتطلب: يجب أن تكون النصوص والأزرار كاملة داخل نافذة العرض عند 375px و768px و1280px، مع تباين كافٍ.
• Provenance: required_inference
• المبرر: ضمان قابلية القراءة والاستخدام.

NFR-05: إمكانية الصيانة

• المتطلب: يجب أن يكون الكود منظمًا بفصل الواجهات عن الخدمات، مع بنية واضحة (core, models, services, screens, widgets, test).
• Provenance: explicit
• المبرر: تسهيل التطوير والصيانة.

NFR-06: قابلية الاختبار

• المتطلب: يجب أن تكون هناك اختبارات للوظائف الأساسية والصلاحيات والمنطق.
• Provenance: explicit
• المبرر: ضمان موثوقية الكود.

NFR-07: التوطين

• المتطلب: يجب أن تكون الواجهة عربية بالكامل باتجاه RTL.
• Provenance: explicit
• المبرر: الجمهور المستهدف عربي.

NFR-08: عدم النشر

• المتطلب: لا يُنفَّذ نشر فعلي ولا يُرفع المشروع إلى مستودع بعيد دون إذن صريح.
• Provenance: explicit
• المبرر: احترام صلاحيات المالك.

10. Tech Stack

• Flutter وDart: إطار العمل واللغة الأساسية.
• Firebase Authentication: لتسجيل الدخول وإدارة الجلسات.
• Cloud Firestore: لتخزين البيانات.
• Provider: لإدارة الحالة.
• SharedPreferences: للإعدادات المحلية.
• fl_chart: للرسوم البيانية.
• Android وFlutter Web: المنصات المدعومة.
• أحدث إصدارات مستقرة متوافقة: من Flutter والحزم.

بنية المشروع:

• core: الثوابت، الألوان، والثيمات.
• models: نماذج البيانات (المستخدم، المعلم، الطالب، الدرس، المتن، الورد القرآني، التقارير).
• services: المصادقة وFirestore والخدمات.
• screens: شاشات الدخول والإدارة والمعلم والتقارير.
• widgets: مكونات واجهة مشتركة.
• test: اختبارات أساسية للنماذج والصلاحيات والمنطق.

11. Assumptions and Constraints

الافتراضات

• A-01: المدير هو المسؤول الوحيد عن إنشاء حسابات المعلمين وإدارتها. [Assumption — required_inference]
• A-02: المشرف هو معلم عيّنه المدير، ولا يحصل على صلاحياته قبل التعيين. [Assumption — required_inference]
• A-03: تقدم الورد القرآني يُحسب من مجموع الصفحات المسجّلة فعليًا فقط. [Assumption — explicit]
• A-04: البيانات التجريبية اختيارية ومفصولة بوضوح عن بيانات الإنتاج. [Assumption — explicit]
• A-05: لا يوجد تسجيل ذاتي عام؛ الحسابات تُنشأ من قبل المدير. [Assumption — required_inference]

القيود

• C-01: لا تفحص مستودعًا موجودًا ولا تعتمد على شيفرة سابقة. [Constraint — explicit]
• C-02: واجهة عربية بالكامل باتجاه RTL. [Constraint — explicit]
• C-03: دعم Android وFlutter Web. [Constraint — explicit]
• C-04: استخدم أحدث إصدارات مستقرة متوافقة من Flutter والحزم. [Constraint — explicit]
• C-05: استخدم شعارًا مؤقتًا بسيطًا قابلًا للاستبدال، ولا تستخدم صورًا محمية أو تدرج صورًا خارجية غير مرخصة. [Constraint — explicit]
• C-06: اجعل أسماء المستخدمين ديناميكية، ولا تثبّت أسماء أشخاص في الواجهة. [Constraint — explicit]
• C-07: يعتمد تسجيل الورد ومؤشر تقدم الطالب على عدد الصفحات المسجلة فقط؛ لا تحسب التقدم من عدد الأيام أو الجلسات أو مدة استخدام التطبيق. [Constraint — explicit]
• C-08: المدير فقط يدير الحسابات والإعدادات العامة. [Constraint — explicit]
• C-09: المعلم يصل إلى بياناته وطلابه وسجلاته المصرح بها. [Constraint — explicit]
• C-10: المشرف يحصل على الصلاحيات الإضافية الممنوحة له فقط. [Constraint — explicit]
• C-11: لا تعتمد على إخفاء الأزرار في الواجهة بدل التحقق من الصلاحية على قاعدة البيانات. [Constraint — explicit]
• C-12: لا تخزن كلمات المرور كنص صريح، ولا تضع مفاتيح أو أسرار Firebase في الشيفرة المنشورة. [Constraint — explicit]
• C-13: أضف بيانات تجريبية اختيارية للتطوير فقط، مع فصلها بوضوح عن بيانات الإنتاج. [Constraint — explicit]
• C-14: لا تستخدم بيانات اعتماد حقيقية أو مفاتيح سرية. [Constraint — explicit]
• C-15: إذا تعذر إعداد Firebase دون بيانات تخص المالك، أنشئ نقطة إعداد واضحة واشرح بدقة القيم التي يجب إضافتها، ولا تدّعِ أن الاتصال يعمل قبل اختباره. [Constraint — explicit]
• C-16: لا تنفّذ نشرًا فعليًا ولا ترفع المشروع إلى مستودع بعيد دون إذن صريح. [Constraint — explicit]
• C-17: اكتب كودًا كاملًا قابلًا للبناء، لا تكتفِ بالتصاميم أو الشرح. [Constraint — explicit]
• C-18: أضف ملف README يشرح المتطلبات وتشغيل التطبيق وإعداد Firebase. [Constraint — explicit]
• C-19: أضف قواعد Firestore وخطوات نشرها. [Constraint — explicit]
• C-20: أضف اختبارات للوظائف الأساسية والصلاحيات، ثم شغّل التحليل والبناء للمنصات المطلوبة. [Constraint — explicit]

12. Glossary

• المركز: «مركز السنة للعلوم الشرعية وتأهيل الدعاة» في عتق – شبوة.
• المدير: المستخدم الأعلى صلاحية، يدير الحسابات والإعدادات العامة والتقارير الشاملة.
• المعلم: المستخدم الذي يدير الطلاب التابعين له ويسجّل الدروس والحضور.
• المشرف: معلم يعيّنه المدير مسؤولًا عن المتون والأوراد، وله صلاحيات إضافية محددة.
• المسار: أحد المسارات التعليمية الخمسة (مفاتيح الطلب، معارج التحصيل ١/٢/٣، القرآن الكريم).
• المستوى: مستوى تعليمي داخل المسار.
• المتن: نص علمي يُحفظ.
• الورد القرآني: مقدار الحفظ القرآني المسجّل بعدد الصفحات.
• مجموع الصفحات المسجّلة: مجموع الصفحات التي سُجّلت فعليًا، وهو المصدر الوحيد لحساب تقدم الورد.
• النيابة: تسجيل المشرف عملًا نيابة عن معلم، مع حفظ اسم المعلم المقصود.
• RTL: اتجاه الكتابة من اليمين إلى اليسار.
• Firestore: قاعدة بيانات Cloud Firestore من Firebase.
• Provider: مكتبة إدارة الحالة في Flutter.
• SharedPreferences: مكتبة التخزين المحلي في Flutter.
• fl_chart: مكتبة الرسوم البيانية في Flutter.