System Requirements Document for earthy-api

1. Introduction

earthy-api هو الاسم التقني للمشروع، ويُقدَّم للمستخدم النهائي باسم «دليل اليمن للخدمات». المنتج هو تطبيق احترافي متكامل مخصص لليمن، يعمل كدليل خدمات وطني حقيقي وقابل للتوسع — وليس نموذجًا تجريبيًا أو واجهات وهمية.

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

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

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

2. System Overview

earthy-api / دليل اليمن للخدمات تطبيق ويب عربي RTL متجاوب مع الهاتف، مبني على واجهة أمامية وخلفية حقيقية وقاعدة بيانات حقيقية وواجهات API حقيقية. لا تُبنى أي شاشة على بيانات تجريبية فقط؛ كل عرض وكل إجراء يُربط فعليًا بقاعدة البيانات والـBackend.

الأدوار الفاعلة (مغلقة):

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

السلوك المقبول الحالي: التسجيل وإنشاء الحساب وتسجيل الدخول؛ دليل خدمات في جميع محافظات ومديريات اليمن؛ تصنيفات خدمات؛ بحث متقدم بالاسم والتصنيف والمحافظة والمديرية؛ صفحة تفصيلية لكل مقدم خدمة؛ إضافة الخدمات وتعديلها؛ التقييمات والمراجعات؛ المفضلة؛ التواصل مع مقدم الخدمة؛ إرسال طلب خدمة؛ نظام عروض على الطلبات؛ الإشعارات؛ رفع الصور؛ لوحة إدارة؛ إحصائيات؛ معالجة انقطاع الاتصال؛ حماية الحسابات والصلاحيات والتحقق من البيانات.

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

2a. Product Interpretation and Delivery Boundary

ملكية التسليم والوصول: التطبيق يملك هوية حسابه الخاصة (app-owned identity) وواجهة مخصصة (custom UI). المستخدم العادي ومقدم الخدمة ينشئان حسابيهما ذاتيًا عبر Sign Up، ويعودان عبر Login. حساب مدير النظام يُهيَّأ عبر مسار provisioning إداري عند الحاجة، ولا يُنشأ ذاتيًا من واجهة عامة. الوصول إلى الأعمال المحمية (الطلبات، العروض، الرسائل، المفضلة، التقييمات، الإشعارات، الملف الشخصي، خدماتي، لوحة مقدم الخدمة، لوحة الإدارة) يتطلب تسجيل الدخول، وبعضها مقيّد بالدور.

الحدود الحالية والمستقبلية: كل ما ورد في قائمة الوظائف الأساسية (1–18) وقائمة الواجهات وقاعدة البيانات والـBackend هو نطاق حالي. لا توجد في المصدر أي متطلبات مؤجلة إلى أفق مستقبلي؛ لذلك لا تُدرج أي ميزات مستقبلية في الصفحات أو معايير القبول الحالية.

حدود التكامل: قاعدة البيانات والـBackend/API حقيقيان. لا تُخزَّن المفاتيح السرية في التطبيق. تُطبَّق مصادقة وتفويض على كل عملية محمية.

2b. Source Content Inventory

لا يوجد في توجيهات المراجع أي content_source صريح؛ لذلك لا يُدرج هذا القسم.

2c. Page Content and Component Coverage

الصفحة الرئيسية

• المعلومات والحالة: شريط masthead بعرض كامل بلون terracotta #B23A1F يحمل wordmark «دليل اليمن للخدمات» بخط Noto Kufi Arabic 800، محاذى إلى اليمين (RTL flush-right)، مع خط شعري كريمي أسفله وعدّاد tabular «٢٢ محافظة · ٣٣٣ مديرية» في الزاوية. أسفله على الأرضية الورقية الدافئة شريط بحث أبيض بعرض كامل بحدّ حبري 4px على الحافة الأمامية RTL، وثلاثة محدّدات inline (التصنيف / المحافظة / المديرية) مفصولة بخطوط رأسية 1px. أسفله شريط تصنيفات أفقي (route chips) بخطوط لونية 4px.
• الإجراءات الأساسية: البحث بالاسم/التصنيف/المحافظة/المديرية؛ الانتقال إلى التصنيفات؛ الانتقال إلى المحافظات والمديريات؛ فتح تفاصيل خدمة.
• الإجراءات المساندة: تسجيل الدخول / إنشاء حساب؛ الانتقال إلى المفضلة أو الطلبات أو الإشعارات إن كان مسجّلًا.
• الكيانات: التصنيف، المحافظة، المديرية، مقدم الخدمة، الخدمة.
• مسؤوليات المكوّنات: Masthead (wordmark + عدّاد)؛ SearchBar (ثلاثة محدّدات + حقل الاسم)؛ CategoryRouteStrip (chips بخطوط لونية، تمرير أفقي مع snap)؛ RuledBands (٠١ التصنيفات، ٠٢ المحافظات، ٠٣ قريب منك) بخطوط فاصلة بعرض المحتوى.
• الحالات: تحميل (skeleton لأشرطة التصنيفات والمحافظات)؛ فراغ (لا توجد تصنيفات/محافظات بعد — رسالة عربية موجزة)؛ نجاح (عرض الأشرطة والنتائج)؛ خطأ (تعذّر تحميل البيانات — إعادة المحاولة)؛ استرداد (إعادة جلب عند عودة الاتصال).

المحافظات والمديريات

• المعلومات والحالة: قائمة محافظات اليمن كمسارات مرقّمة (صنعاء ٠١، عدن ٠٢، تعز ٠٣ …) في جدول بعمودين بأرقام tabular، مع عدد المديريات محاذى إلى اليمين، وخطوط فاصلة شعرية. عند اختيار محافظة تُعرض مديرياتها.
• الإجراءات الأساسية: اختيار محافظة؛ اختيار مديرية؛ الانتقال إلى نتائج البحث أو التصنيفات مقيّدة بالمنطقة.
• الإجراءات المساندة: العودة إلى الرئيسية؛ مسح التحديد.
• الكيانات: المحافظة، المديرية، مقدم الخدمة، الخدمة.
• مسؤوليات المكوّنات: GovernorateRouteTable (أرقام tabular + عدد المديريات)؛ DistrictList؛ Breadcrumb RTL.
• الحالات: تحميل؛ فراغ (لا مديريات مسجّلة بعد)؛ نجاح؛ خطأ مع إعادة محاولة؛ استرداد عند عودة الاتصال.

التصنيفات

• المعلومات والحالة: شبكة/شريط تصنيفات، كل تصنيف بخط لوني ثابت 4px على الحافة الأمامية RTL وchip مستطيل بنصف قطر 6px بخلفية ملوّنة 8%، وأيقونة pictogram بخط 2px على شبكة 24px. التصنيفات تشمل: صيانة السيارات، الكهرباء، السباكة، المطاعم، المحلات، النقل، المقاولات، التقنية والبرمجة، الصحة، التعليم، الخدمات المنزلية، وغيرها.
• الإجراءات الأساسية: اختيار تصنيف؛ الانتقال إلى نتائج مقيّدة بالتصنيف.
• الإجراءات المساندة: الانتقال إلى البحث المتقدم؛ العودة.
• الكيانات: التصنيف، الخدمة، مقدم الخدمة.
• مسؤوليات المكوّنات: CategoryChip (خط لوني + أيقونة + اسم)؛ CategoryGrid/Wrap (يتحوّل إلى صفوف ملتفّة عند prefers-reduced-motion).
• الحالات: تحميل؛ فراغ؛ نجاح؛ خطأ مع إعادة محاولة.

البحث

• المعلومات والحالة: نموذج بحث متقدم بأربعة معايير: الاسم، التصنيف، المحافظة، المديرية. النتائج كبطاقات مقدم خدمة بخط تصنيف لوني 4px على الحافة الأمامية RTL، وحدّ 1px #E2D9C8، ونصف قطر 12px، وقاعدة حبرية 2px أسفل البطاقة.
• الإجراءات الأساسية: إدخال معايير البحث؛ تنفيذ البحث؛ فتح تفاصيل خدمة؛ حفظ في المفضلة (لمسجّل الدخول).
• الإجراءات المساندة: مسح المعايير؛ تغيير الترتيب؛ تحميل المزيد.
• الكيانات: مقدم الخدمة، الخدمة، التصنيف، المحافظة، المديرية، التقييم.
• مسؤوليات المكوّنات: AdvancedSearchForm؛ ResultCard (اسم، تصنيف، منطقة، تقييم، هاتف/واتساب مختصر)؛ EmptyState؛ Pagination/LoadMore.
• الحالات: تحميل؛ فراغ (لا نتائج مطابقة — اقتراح توسيع المعايير)؛ نجاح؛ خطأ مع إعادة محاولة؛ استرداد عند عودة الاتصال.

تفاصيل الخدمة

• المعلومات والحالة: صفحة تفصيلية لكل مقدم خدمة تحتوي على: الاسم، وصف الخدمة، الموقع، رقم الهاتف، واتساب، أوقات العمل، الصور، التقييمات. على سطح المكتب: تخطيط بعمودين — rail تواصل ثابت (sticky) على الجانب الأمامي RTL يضم الهاتف والواتساب وأوقات العمل وزر الطلب كأزواج label-value تحت تسميات عربية صغيرة، والمحتوى على الجانب التالي. على الهاتف: عمود واحد مع تثبيت rail التواصل كشريط سفلي.
• الإجراءات الأساسية: الاتصال بالهاتف؛ فتح واتساب؛ إرسال طلب خدمة؛ كتابة تقييم/مراجعة؛ إضافة إلى المفضلة؛ بدء محادثة.
• الإجراءات المساندة: عرض الصور؛ عرض التقييمات؛ مشاركة؛ الإبلاغ.
• الكيانات: مقدم الخدمة، الخدمة، الموقع، أوقات العمل، الصورة، التقييم، المراجعة، الطلب، المفضلة، الرسالة.
• مسؤوليات المكوّنات: ContactRail (sticky)؛ ProviderHeader (اسم + خط تصنيف لوني)؛ HoursTable؛ PhotoGallery (إطار 4:3 بحدّ حبري 1px بدون قناع دائري)؛ ReviewsList؛ RequestCTA؛ FavoriteToggle؛ ReportAction.
• الحالات: تحميل؛ فراغ (لا صور/لا تقييمات بعد)؛ نجاح؛ خطأ مع إعادة محاولة؛ استرداد عند عودة الاتصال.

الطلبات

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

العروض

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

الرسائل

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

المفضلة

• المعلومات والحالة: قائمة مقدمي الخدمات المحفوظين للمستخدم.
• الإجراءات الأساسية: إضافة/إزالة من المفضلة؛ فتح تفاصيل خدمة محفوظة.
• الإجراءات المساندة: البحث داخل المفضلة؛ الانتقال إلى الطلبات.
• الكيانات: المفضلة، مقدم الخدمة، الخدمة، المستخدم.
• مسؤوليات المكوّنات: FavoriteList؛ FavoriteToggle؛ EmptyState.
• الحالات: تحميل؛ فراغ (لا عناصر محفوظة)؛ نجاح؛ خطأ مع إعادة محاولة؛ استرداد عند عودة الاتصال.

التقييمات

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

الإشعارات

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

الملف الشخصي

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

خدماتي

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

لوحة مقدم الخدمة

• المعلومات والحالة: مركز مقدم الخدمة لمتابعة خدماته وطلباته وعروضه وتقييماته.
• الإجراءات الأساسية: استعراض الخدمات؛ استعراض الطلبات الواردة؛ تقديم عرض؛ متابعة التقييمات.
• الإجراءات المساندة: الانتقال إلى خدماتي؛ الانتقال إلى الرسائل؛ الانتقال إلى الإشعارات.
• الكيانات: مقدم الخدمة، الخدمة، الطلب، العرض، التقييم، الإشعار.
• مسؤوليات المكوّنات: ProviderDashboardBands؛ ServiceSummary؛ IncomingRequests؛ OffersSummary؛ ReviewsSummary.
• الحالات: تحميل؛ فراغ (لا خدمات/طلبات بعد)؛ نجاح؛ خطأ مع إعادة محاولة؛ استرداد عند عودة الاتصال.

لوحة الإدارة

• المعلومات والحالة: إدارة المستخدمين والخدمات والتصنيفات والمحافظات والمديريات والتقييمات والبلاغات، مع شريط إحصائيات كـ ruled instrument band: خمسة أزواج label-value مفصولة بخطوط رأسية 1px بأرقام tabular تعدّ تصاعديًا مرة واحدة عند أول عرض (400ms). التنقل عبر left-hand numbered nav rail بكثافة 13px وخطوط فاصلة شعرية.
• الإجراءات الأساسية: إدارة المستخدمين؛ إدارة الخدمات؛ إدارة التصنيفات؛ إدارة المحافظات والمديريات؛ إدارة التقييمات؛ إدارة البلاغات؛ الاطلاع على الإحصائيات.
• الإجراءات المساندة: البحث داخل الجداول؛ تصفية؛ الانتقال إلى الملف الشخصي.
• الكيانات: المستخدم، الدور، الخدمة، التصنيف، المحافظة، المديرية، التقييم، البلاغ، الإحصائية.
• مسؤوليات المكوّنات: AdminNavRail؛ StatisticsBand؛ UsersTable؛ ServicesTable؛ CategoriesTable؛ RegionsTable؛ ReviewsTable؛ ReportsTable.
• الحالات: تحميل؛ فراغ (لا عناصر في جدول ما)؛ نجاح؛ خطأ مع إعادة محاولة؛ استرداد عند عودة الاتصال.

Sign Up

• المعلومات والحالة: إنشاء حساب مستقل للمستخدم العادي أو مقدم الخدمة، مع مسار provisioning للمدير عند الحاجة. الوصول: عام (none).
• الإجراءات الأساسية: إدخال بيانات الحساب؛ اختيار نوع الحساب (مستخدم عادي / مقدم خدمة)؛ إنشاء الحساب.
• الإجراءات المساندة: الانتقال إلى Login؛ عرض شروط الاستخدام.
• الكيانات: المستخدم، الدور، بيانات الاعتماد.
• مسؤوليات المكوّنات: SignUpForm؛ RoleSelector؛ ValidationMessages.
• الحالات: تحميل؛ فراغ (نموذج فارغ)؛ نجاح (إنشاء الحساب والانتقال إلى Login أو الدخول)؛ خطأ (بيانات غير صحيحة/بريد مستخدم — رسالة عربية واضحة)؛ استرداد عند عودة الاتصال.

Login

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

3. Functional Requirements

المصادقة وإدارة الحساب

FR-01 — إنشاء حساب [explicit]

• As a مستخدم عادي أو مقدم خدمة I should إنشاء حساب جديد في التطبيق so that أتمكن من الوصول إلى الأعمال المحمية.
• المُشغِّل/المدخل: فتح Sign Up وإدخال بيانات الحساب واختيار نوع الحساب.
• النتيجة المرصودة: إنشاء الحساب في قاعدة البيانات الحقيقية، وإمكانية تسجيل الدخول.
• الوصول: عام (none).
• الفشل/الاسترداد: بيانات غير صحيحة أو حساب موجود مسبقًا → رسالة عربية واضحة وإعادة المحاولة.
• الاستمرار: الانتقال إلى Login أو الدخول مباشرة.

FR-02 — تسجيل الدخول والتحقق من الهوية عند العودة [required_inference]

• As a مستخدم عادي أو مقدم خدمة أو مدير نظام I should تسجيل الدخول والتحقق من هويتي عند العودة so that أصل إلى أعمالي المحمية.
• المُشغِّل/المدخل: فتح Login وإدخال بيانات الاعتماد.
• النتيجة المرصودة: إنشاء جلسة صحيحة وربطها بالدور.
• الوصول: عام (none).
• الفشل/الاسترداد: بيانات اعتماد غير صحيحة → رسالة عربية واضحة وإعادة المحاولة.
• الاستمرار: الانتقال إلى الأعمال المحمية المناسبة للدور.

FR-03 — تهيئة حساب مدير النظام [required_inference]

• As a مدير النظام I should أن يكون حسابي مُهيَّأ قبل أول استخدام محمي so that أتمكن من إدارة الدليل.
• المُشغِّل/المدخل: مسار provisioning إداري (لا يُنشأ ذاتيًا من واجهة عامة).
• النتيجة المرصودة: حساب مدير صالح للدخول.
• الوصول: provisioning.
• الفشل/الاسترداد: فشل التهيئة → إعادة التنفيذ.
• الاستمرار: تسجيل الدخول إلى لوحة الإدارة.

FR-04 — تفويض الأدوار [required_inference]

• As a مدير النظام I should أن تُطبَّق صلاحيات الأدوار (مستخدم عادي، مقدم خدمة، مدير النظام) على العمليات so that لا يصل أي دور إلى أعمال ليست له.
• المُشغِّل/المدخل: كل عملية محمية.
• النتيجة المرصودة: رفض العمليات غير المصرّح بها.
• الوصول: حسب الدور.
• الفشل/الاسترداد: رفض الوصول → رسالة عربية واضحة.
• الاستمرار: العودة إلى العمل المصرّح به.

الدليل والتصنيفات والمناطق

FR-05 — دليل الخدمات في جميع محافظات ومديريات اليمن [explicit]

• As a مستخدم عادي I should تصفح دليل الخدمات في جميع محافظات ومديريات اليمن so that أجد مقدم خدمة في منطقتي.
• المُشغِّل/المدخل: فتح المحافظات والمديريات أو التصنيفات.
• النتيجة المرصودة: عرض المحافظات والمديريات والخدمات المرتبطة بها من قاعدة البيانات الحقيقية.
• الوصول: عام (none).
• الفشل/الاسترداد: تعذّر التحميل → إعادة المحاولة.
• الاستمرار: الانتقال إلى تفاصيل الخدمة.

FR-06 — تصنيفات الخدمات [explicit]

• As a مستخدم عادي I should استعراض تصنيفات الخدمات المتاحة so that أصل إلى نوع الخدمة الذي أحتاجه.
• المُشغِّل/المدخل: فتح التصنيفات.
• النتيجة المرصودة: عرض التصنيفات: صيانة السيارات، الكهرباء، السباكة، المطاعم، المحلات، النقل، المقاولات، التقنية والبرمجة، الصحة، التعليم، الخدمات المنزلية، وغيرها.
• الوصول: عام (none).
• الفشل/الاسترداد: تعذّر التحميل → إعادة المحاولة.
• الاستمرار: الانتقال إلى نتائج مقيّدة بالتصنيف.

FR-07 — البحث المتقدم [explicit]

• As a مستخدم عادي I should البحث عن الخدمات بالاسم والتصنيف والمحافظة والمديرية so that أضيّق النتائج إلى ما أحتاجه.
• المُشغِّل/المدخل: إدخال معايير البحث في صفحة البحث.
• النتيجة المرصودة: عرض النتائج المطابقة من قاعدة البيانات الحقيقية.
• الوصول: عام (none).
• الفشل/الاسترداد: لا نتائج → اقتراح توسيع المعايير؛ تعذّر التحميل → إعادة المحاولة.
• الاستمرار: فتح تفاصيل الخدمة.

FR-08 — صفحة تفصيلية لكل مقدم خدمة [explicit]

• As a مستخدم عادي I should استعراض صفحة تفصيلية لكل مقدم خدمة تحتوي على الاسم، وصف الخدمة، الموقع، رقم الهاتف، واتساب، أوقات العمل، الصور، التقييمات so that أتخذ قرار التواصل.
• المُشغِّل/المدخل: فتح تفاصيل الخدمة.
• النتيجة المرصودة: عرض كل الحقول المذكورة من قاعدة البيانات الحقيقية.
• الوصول: عام (none).
• الفشل/الاسترداد: تعذّر التحميل → إعادة المحاولة.
• الاستمرار: التواصل أو إرسال طلب أو تقييم أو حفظ في المفضلة.

خدمات مقدم الخدمة

FR-09 — إضافة مقدم الخدمة لخدماته وتعديلها [explicit]

• As a مقدم خدمة I should إضافة خدماتي وتعديلها so that تظهر للمستخدمين في الدليل.
• المُشغِّل/المدخل: فتح خدماتي وإنشاء/تعديل خدمة.
• النتيجة المرصودة: حفظ الخدمة في قاعدة البيانات وظهورها في الدليل.
• الوصول: role_restricted (مقدم خدمة).
• الفشل/الاسترداد: بيانات غير صحيحة → رسالة عربية واضحة وإعادة المحاولة.
• الاستمرار: متابعة الخدمة في لوحة مقدم الخدمة.

FR-10 — رفع الصور [explicit]

• As a مقدم خدمة I should رفع صور لخدماتي so that يرى المستخدمون الخدمة كما هي.
• المُشغِّل/المدخل: رفع صورة من خدماتي.
• النتيجة المرصودة: تخزين الصورة وربطها بالخدمة.
• الوصول: role_restricted (مقدم خدمة).
• الفشل/الاسترداد: فشل الرفع → إعادة المحاولة.
• الاستمرار: ظهور الصورة في تفاصيل الخدمة.

التقييمات والمفضلة والتواصل

FR-11 — نظام تقييم ومراجعات [explicit]

• As a مستخدم عادي I should تقييم مقدمي الخدمات وكتابة مراجعات so that أساعد الآخرين وأعبّر عن تجربتي.
• المُشغِّل/المدخل: كتابة تقييم/مراجعة من تفاصيل الخدمة أو صفحة التقييمات.
• النتيجة المرصودة: حفظ التقييم وظهوره في تفاصيل مقدم الخدمة.
• الوصول: role_restricted (مستخدم عادي).
• الفشل/الاسترداد: فشل الحفظ → إعادة المحاولة.
• الاستمرار: تعديل/حذف التقييم.

FR-12 — المفضلة [explicit]

• As a مستخدم عادي I should حفظ مقدمي الخدمات في المفضلة so that أعود إليهم لاحقًا.
• المُشغِّل/المدخل: إضافة/إزالة من المفضلة.
• النتيجة المرصودة: حفظ/إزالة العنصر في قاعدة البيانات.
• الوصول: role_restricted (مستخدم عادي).
• الفشل/الاسترداد: فشل الحفظ → إعادة المحاولة.
• الاستمرار: فتح تفاصيل الخدمة المحفوظة.

FR-13 — التواصل مع مقدم الخدمة [explicit]

• As a مستخدم عادي I should التواصل مع مقدم الخدمة so that أستفسر أو أتفق على الخدمة.
• المُشغِّل/المدخل: فتح واتساب أو بدء محادثة من تفاصيل الخدمة.
• النتيجة المرصودة: بدء محادثة أو فتح واتساب.
• الوصول: role_restricted (مستخدم عادي).
• الفشل/الاسترداد: تعذّر الاتصال → إعادة المحاولة.
• الاستمرار: متابعة المحادثة في الرسائل.

الطلبات والعروض

FR-14 — إرسال طلب خدمة [explicit]

• As a مستخدم عادي I should إرسال طلب خدمة so that يتلقى مقدم الخدمة طلبي ويقدّم عرضًا.
• المُشغِّل/المدخل: إنشاء طلب من تفاصيل الخدمة أو صفحة الطلبات.
• النتيجة المرصودة: إنشاء الطلب في قاعدة البيانات وظهوره لمقدم الخدمة.
• الوصول: role_restricted (مستخدم عادي).
• الفشل/الاسترداد: فشل الإنشاء → إعادة المحاولة.
• الاستمرار: متابعة الطلب واستقبال العروض.

FR-15 — نظام عروض من مقدمي الخدمات على الطلبات [explicit]

• As a مقدم خدمة I should تقديم عروض على الطلبات so that أفوز بالطلب.
• As a مستخدم عادي I should مراجعة العروض الواردة وقبول أحدها so that أختار الأفضل.
• المُشغِّل/المدخل: تقديم عرض من لوحة مقدم الخدمة أو صفحة العروض؛ مراجعة العروض من صفحة العروض.
• النتيجة المرصودة: حفظ العرض وظهوره للمستخدم؛ تحديث حالة الطلب عند القبول.
• الوصول: role_restricted (مقدم خدمة / مستخدم عادي).
• الفشل/الاسترداد: فشل التقديم/القبول → إعادة المحاولة.
• الاستمرار: متابعة الطلب أو المحادثة.

FR-16 — إشعارات للمستخدم ومقدم الخدمة [explicit]

• As a مستخدم عادي أو مقدم خدمة I should تلقّي إشعارات عن التفاعلات والطلبات والعروض so that أتابع ما يخصني.
• المُشغِّل/المدخل: حدث مرتبط (طلب جديد، عرض جديد، رسالة، تقييم).
• النتيجة المرصودة: ظهور الإشعار في صفحة الإشعارات.
• الوصول: role_restricted.
• الفشل/الاسترداد: تعذّر التحميل → إعادة المحاولة.
• الاستمرار: الانتقال إلى الكيان المرتبط.

لوحة الإدارة

FR-17 — لوحة تحكم Admin [explicit]

• As a مدير النظام I should إدارة المستخدمين والخدمات والتصنيفات والمحافظات والتقييمات والبلاغات so that يبقى الدليل موثوقًا ومنظّمًا.
• المُشغِّل/المدخل: فتح لوحة الإدارة واختيار القسم.
• النتيجة المرصودة: تنفيذ الإجراءات على قاعدة البيانات الحقيقية.
• الوصول: role_restricted (مدير النظام).
• الفشل/الاسترداد: فشل الإجراء → رسالة عربية واضحة وإعادة المحاولة.
• الاستمرار: متابعة الإدارة.

FR-18 — إحصائيات لوحة الإدارة [explicit]

• As a مدير النظام I should الاطلاع على إحصائيات لوحة الإدارة so that أعرف حالة الدليل.
• المُشغِّل/المدخل: فتح لوحة الإدارة.
• النتيجة المرصودة: عرض شريط الإحصائيات بأرقام tabular.
• الوصول: role_restricted (مدير النظام).
• الفشل/الاسترداد: تعذّر التحميل → إعادة المحاولة.
• الاستمرار: اتخاذ إجراء إداري.

الاتصال والأمان

FR-19 — دعم العمل مع الإنترنت ومعالجة انقطاع الاتصال [explicit]

• As a مستخدم عادي أو مقدم خدمة I should أن يعمل التطبيق مع الإنترنت وأن تُعالَج حالات انقطاع الاتصال so that لا أفقد عملي.
• المُشغِّل/المدخل: انقطاع الاتصال أثناء عملية.
• النتيجة المرصودة: حفظ العملية أو إعادة محاولتها عند عودة الاتصال.
• الوصول: حسب العملية.
• الفشل/الاسترداد: إعادة المحاولة التلقائية أو اليدوية.
• الاستمرار: إكمال العملية.

FR-20 — حماية الحسابات والصلاحيات والتحقق من البيانات [explicit]

• As a مدير النظام I should أن تكون الحسابات والصلاحيات محمية والبيانات متحقَّقًا منها so that يبقى التطبيق آمنًا.
• المُشغِّل/المدخل: كل عملية إدخال أو وصول.
• النتيجة المرصودة: رفض المدخلات غير الصحيحة والوصول غير المصرّح به.
• الوصول: حسب العملية.
• الفشل/الاسترداد: رسالة عربية واضحة.
• الاستمرار: إعادة الإدخال الصحيح.

FR-21 — ربط الواجهات فعليًا بقاعدة البيانات والـBackend [explicit]

• As a مستخدم عادي أو مقدم خدمة أو مدير النظام I should أن تكون كل البيانات والإجراءات مربوطة فعليًا بقاعدة البيانات والـBackend so that لا أتعامل مع واجهات وهمية.
• المُشغِّل/المدخل: كل عرض وكل إجراء.
• النتيجة المرصودة: بيانات حقيقية من قاعدة البيانات.
• الوصول: حسب العملية.
• الفشل/الاسترداد: إعادة المحاولة.
• الاستمرار: إكمال العملية.

4. User Personas

مستخدم عادي

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

مقدم خدمة

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

مدير النظام

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

5. Core User Flows

CU-01 — إنشاء حساب جديد (مستخدم عادي / مقدم خدمة)

1. يفتح الزائر Sign Up (وصول عام).
2. يُدخل بيانات الحساب ويختار نوع الحساب: مستخدم عادي أو مقدم خدمة.
3. يُرسل النموذج؛ يتحقق النظام من البيانات.
4. النتيجة المرصودة: إنشاء الحساب في قاعدة البيانات الحقيقية.
5. الفشل/الاسترداد: بيانات غير صحيحة أو حساب موجود → رسالة عربية واضحة وإعادة المحاولة.
6. الاستمرار: الانتقال إلى Login أو الدخول مباشرة.

CU-02 — تسجيل الدخول والوصول إلى الأعمال المحمية

1. يفتح المستخدم Login (وصول عام).
2. يُدخل بيانات الاعتماد.
3. النتيجة المرصودة: إنشاء جلسة صحيحة وربطها بالدور.
4. الفشل/الاسترداد: بيانات اعتماد غير صحيحة → رسالة عربية واضحة وإعادة المحاولة.
5. الاستمرار: الانتقال إلى الأعمال المحمية المناسبة للدور (الطلبات، العروض، الرسائل، المفضلة، التقييمات، الإشعارات، الملف الشخصي، خدماتي، لوحة مقدم الخدمة، لوحة الإدارة).

CU-03 — تهيئة حساب مدير النظام والدخول إلى لوحة الإدارة

1. يُهيَّأ حساب مدير النظام عبر مسار provisioning إداري (لا يُنشأ ذاتيًا من واجهة عامة).
2. يسجّل المدير الدخول عبر Login.
3. النتيجة المرصودة: الوصول إلى لوحة الإدارة.
4. الفشل/الاسترداد: فشل التهيئة → إعادة التنفيذ.
5. الاستمرار: إدارة الدليل.

CU-04 — البحث عن خدمة وإتمام الطلب عبر العروض (مستخدم عادي)

1. يفتح المستخدم الصفحة الرئيسية ويستخدم شريط البحث أو ينتقل إلى البحث.
2. يُدخل معايير البحث: الاسم، التصنيف، المحافظة، المديرية.
3. النتيجة المرصودة: عرض النتائج المطابقة من قاعدة البيانات الحقيقية.
4. الفشل/الاسترداد: لا نتائج → توسيع المعايير؛ تعذّر التحميل → إعادة المحاولة.
5. يفتح تفاصيل الخدمة ويستعرض الاسم، الوصف، الموقع، الهاتف، واتساب، أوقات العمل، الصور، التقييمات.
6. يقرر التواصل: فتح واتساب أو بدء محادثة في الرسائل.
7. يُرسل طلب خدمة من تفاصيل الخدمة أو من الطلبات.
8. النتيجة المرصودة: إنشاء الطلب وظهوره لمقدم الخدمة.
9. يستقبل عروضًا من مقدمي الخدمات في العروض.
10. يراجع العروض ويقارنها ويقبل أحدها.
11. النتيجة المرصودة: تحديث حالة الطلب.
12. الاستمرار: متابعة الطلب في الطلبات واستقبال الإشعارات.

CU-05 — حفظ مقدم خدمة في المفضلة (مستخدم عادي)

1. من تفاصيل الخدمة أو البحث، يضغط المستخدم على إضافة إلى المفضلة.
2. النتيجة المرصودة: حفظ العنصر في قاعدة البيانات وظهوره في المفضلة.
3. الفشل/الاسترداد: فشل الحفظ → إعادة المحاولة.
4. الاستمرار: فتح تفاصيل الخدمة المحفوظة لاحقًا.

CU-06 — تقييم مقدم خدمة وكتابة مراجعة (مستخدم عادي)

1. من تفاصيل الخدمة أو التقييمات، يكتب المستخدم تقييمًا ومراجعة.
2. النتيجة المرصودة: حفظ التقييم وظهوره في تفاصيل مقدم الخدمة.
3. الفشل/الاسترداد: فشل الحفظ → إعادة المحاولة.
4. الاستمرار: تعديل أو حذف التقييم.

CU-07 — إضافة خدمة وتعديلها ورفع صورها (مقدم خدمة)

1. يسجّل مقدم الخدمة الدخول ويفتح خدماتي.
2. يُنشئ خدمة جديدة أو يعدّل خدمة قائمة (الاسم، الوصف، الموقع، الهاتف، واتساب، أوقات العمل).
3. يرفع صور الخدمة.
4. النتيجة المرصودة: حفظ الخدمة والصور في قاعدة البيانات وظهورها في الدليل.
5. الفشل/الاسترداد: بيانات غير صحيحة أو فشل رفع → رسالة عربية واضحة وإعادة المحاولة.
6. الاستمرار: متابعة الخدمة في لوحة مقدم الخدمة.

CU-08 — استقبال طلب وتقديم عرض (مقدم خدمة)

1. يفتح مقدم الخدمة لوحة مقدم الخدمة أو الطلبات.
2. يستعرض الطلبات الواردة.
3. يقدّم عرضًا على الطلب من العروض.
4. النتيجة المرصودة: حفظ العرض وظهوره للمستخدم.
5. الفشل/الاسترداد: فشل التقديم → إعادة المحاولة.
6. الاستمرار: متابعة حالة العرض واستقبال الإشعارات، والتواصل عبر الرسائل.

CU-09 — التواصل بين المستخدم ومقدم الخدمة (الطرفان)

1. يبدأ المستخدم محادثة من تفاصيل الخدمة أو من طلب مرتبط.
2. النتيجة المرصودة: ظهور المحادثة في الرسائل لدى الطرفين.
3. يتبادل الطرفان الرسائل.
4. الفشل/الاسترداد: تعذّر الإرسال → إعادة المحاولة.
5. الاستمرار: الانتقال إلى الطلب أو العرض المرتبط.

CU-10 — متابعة الإشعارات (مستخدم عادي / مقدم خدمة)

1. يفتح المستخدم أو مقدم الخدمة الإشعارات.
2. النتيجة المرصودة: عرض الإشعارات المتعلقة بالتفاعلات والطلبات والعروض.
3. ينتقل إلى الكيان المرتبط (طلب/عرض/رسالة/تقييم).
4. الفشل/الاسترداد: تعذّر التحميل → إعادة المحاولة.
5. الاستمرار: إكمال الإجراء المرتبط.

CU-11 — إدارة الدليل والإحصائيات (مدير النظام)

1. يسجّل المدير الدخول ويفتح لوحة الإدارة.
2. يستعرض شريط الإحصائيات (خمسة أزواج label-value بأرقام tabular).
3. يدير المستخدمين أو الخدمات أو التصنيفات أو المحافظات والمديريات أو التقييمات أو البلاغات.
4. النتيجة المرصودة: تنفيذ الإجراءات على قاعدة البيانات الحقيقية.
5. الفشل/الاسترداد: فشل الإجراء → رسالة عربية واضحة وإعادة المحاولة.
6. الاستمرار: متابعة الإدارة.

CU-12 — معالجة انقطاع الاتصال (جميع الأدوار)

1. أثناء عملية (بحث، طلب، عرض، رسالة، تقييم، رفع صورة)، ينقطع الاتصال.
2. النتيجة المرصودة: حفظ العملية أو إعادة محاولتها عند عودة الاتصال.
3. الفشل/الاسترداد: إعادة المحاولة التلقائية أو اليدوية.
4. الاستمرار: إكمال العملية.

6. Visuals Colors and Theme

المصدر الإبداعي: Erik Spiekermann — typography-as-infrastructure. العنوان: Typographic infrastructure for a national service directory — wayfinding clarity, warm order, signal colours as service lines.

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

ألوان خطوط التصنيفات (خطوط 4px وchips فقط — لا تُستخدم كتعبئات كبيرة)

الخطوط

• العناوين: Noto Kufi Arabic، أوزان 700–800، tracking ضيّق على الأحجام الكبيرة، line-height 1.15، محاذاة flush-right (RTL)، حواف يسرى غير منتظمة، بلا توسيط وبلا justify.
• النص: IBM Plex Sans Arabic.
• التسميات الدقيقة (التصنيف، المحافظة، المديرية، التقييم): IBM Plex Sans Arabic 600، تباعد 0.08em، مع خط شعري أعلاها.
• الأرقام: IBM Plex Sans Arabic tabular، تُستخدم كزخرفة في العدّادات والتقييمات وأرقام مسارات المحافظات.

مقياس الأحجام (1.333 modular على قاعدة 4/8pt)

• الهاتف: 34 / 26 / 20 / 17 / 15 / 13
• سطح المكتب: 72 / 48 / 32 / 22 / 17 / 15
• Display headline: clamp(34px, 8vw, 72px)
• Section titles: clamp(24px, 4.5vw, 40px)
• Body: 17px desktop / 15px mobile
• Labels: 13px بتباعد 0.08em

لغة الشكل

• مسطّرة ومرقّمة: خطوط أفقية 2px و4px كأدوات wayfinding لا كزخرفة.
• البطاقات مستطيلات بنصف قطر 12px (لا pills ولا blobs)، بحدّ 1px #E2D9C8 وخط تصنيف لوني 4px على الحافة الأمامية RTL.
• chips التصنيفات مستطيلات بنصف قطر 6px بخط لوني 3px على اليسار وتعبئة ملوّنة 8%.
• الأزرار مستطيلات بنصف قطر 10px بتعبئة إشارية صلبة؛ الأزرار الثانوية بحدّ حبري 1.5px.
• لا ظلال ناعمة مُزاحة — الارتفاع يُعبَّر عنه بحدّ 1px وقاعدة حبرية صلبة 2px أسفل البطاقة.

التخطيط

• شبكة 12 عمودًا عند 1280px (24px gutters)، 8 أعمدة عند 768px، عمود واحد عند 375px بحشو جانبي 16px.
• الرئيسية سلسلة أشرطة مسطّرة بعناوين مرقّمة (٠١ التصنيفات، ٠٢ المحافظات، ٠٣ قريب منك) وخط شعري بعرض المحتوى.
• التصنيفات شريط route chips أفقي قابل للتمرير (overflow-x: auto, snap) يتحوّل إلى شبكة ملتفّة عند prefers-reduced-motion.
• المحافظات قائمة مسارات مرقّمة (صنعاء ٠١، عدن ٠٢، تعز ٠٣ …) في جدول بعمودين بأرقام tabular وعدد المديريات محاذى لليمين.
• تفاصيل الخدمة تخطيط بعمودين على سطح المكتب: rail تواصل ثابت على الجانب الأمامي RTL، والمحتوى على الجانب التالي؛ عمود واحد مكدّس على الهاتف مع تثبيت rail التواصل كشريط سفلي.
• لوحة الإدارة تستخدم نفس الشبكة بصفوف أكثف 13px وخطوط فاصلة شعرية وleft-hand numbered nav rail.

الصور

• Diagrammatic وdocumentary، لا stock. أيقونات التصنيفات pictograms بخط 2px على شبكة 24px بنهايات مربّعة (مفتاح ربط، قابس، أنبوب، طبق، حافلة، مالج، شاشة، سماعة طبية، كتاب، مكنسة).
• صور مقدمي الخدمة رفع حقيقي، مقصوصة إلى إطار 4:3 بحدّ حبري 1px وبلا قناع دائري.
• بطاقات المحافظات قد تحمل صورة documentary واحدة مُشبَعة إلى duotone دافئ (#1A1714 → #F4EFE6) مع خط تصنيف لوني مُركَّب.
• لا gradient blobs، لا 3D renders، لا شخصيات مرسومة.

7. Signature Design Concept

الفكرة: أول شاشة تُقرأ كـ masthead مطبوع لخريطة نقل وطنية، لا كـ hero لصفحة SaaS.

• الشريط العلوي: كتلة terracotta #B23A1F صلبة بعرض كامل من الحافة إلى الحافة، تحمل wordmark «دليل اليمن للخدمات» بخط Noto Kufi Arabic 800 بحجم clamp(34px, 8vw, 72px)، محاذى إلى اليمين، يشغل نحو 9 من 12 عمودًا، مع خط شعري كريمي أسفله وعدّاد tabular صغير «٢٢ محافظة · ٣٣٣ مديرية» بحجم 13px في الزاوية التالية.
• أسفله على الأرضية الورقية الدافئة: شريط بحث أبيض بعرض كامل بحدّ حبري 4px على الحافة الأمامية RTL، وثلاثة محدّدات inline (التصنيف / المحافظة / المديرية) مفصولة بخطوط رأسية 1px — بلا pill عائم وبلا ظل.
• أسفله: شريط أفقي واحد من category route chips، كل chip بخطه اللوني، ينجرف ببطء.
• العنصر المهيمن: كتلة wordmark العربية المفرطة الحجم؛ لا رسم توضيحي، لا gradient، واللون الوحيد على الشاشة الأولى هو masthead terracotta وخطوط التصنيفات.

الحركات المميزة: التصنيفات كنظام مسارات مرقّمة بألوان إشارية ثابتة؛ المحافظات كقائمة مسارات مرقّمة بأرقام tabular؛ تفاصيل الخدمة كجدول مواعيد بعمودين؛ إحصائيات الإدارة كشريط آلي مسطّر.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• الموضوع البؤري: كتلة wordmark «دليل اليمن للخدمات» على masthead terracotta، مع شريط البحث المسطّر وشريط category route chips أسفله.
• أطروحة المدخل → التحويل → النتيجة: عند تحميل الصفحة الرئيسية، تظهر أشرطة ruled bands بترتيبها المرقّم (٠١، ٠٢، ٠٣) بحركة reveal واحدة (8px rise + opacity fade، staggered 60ms)؛ ثم ينجرف شريط category route chips ببطء من اليمين إلى اليسار فقط عندما يتجاوز عرض الحاوية، ويتوقف عند hover/focus. النتيجة: أول شاشة تُقرأ كـ masthead مطبوع لخريطة نقل، مع إبراز البحث كإجراء أساسي.
• مفردات الحركة: 140–180ms ease-out على تغييرات الحالة واختيار chip وفتح accordion وتبديل tab؛ حلقة واحدة هادفة على شريط التصنيفات (marquee) تتوقف عند hover/focus؛ reveal-on-scroll واحد لكل ruled band؛ عدّ تصاعدي مرة واحدة على شريط إحصائيات الإدارة (400ms).
• الإطار الأول المُركَّب: masthead terracotta بعرض كامل مع wordmark flush-right وخط شعري كريمي وعدّاد tabular في الزاوية؛ أسفله شريط البحث الأبيض بحدّه الحبري 4px وثلاثة محدّدات inline؛ أسفله شريط category route chips بخطوطه اللونية.
• حالة prefers-reduced-motion: يتوقف الـ marquee وتلتفّ chips في صفوف؛ تُعرض قيم العدّادات النهائية فورًا؛ تصبح الـ reveals فورية.

9. Non-Functional Requirements

• NFR-01 — تصميم عربي RTL كامل ومتجاوب مع الهاتف وشاشات Android [explicit]: كل الشاشات عربية RTL، متجاوبة عند 375px و768px و1280px، والنصوص وعناصر التحكم تبقى كاملة داخل الإطار.
• NFR-02 — قاعدة بيانات حقيقية قابلة للتوسع [explicit]: قاعدة بيانات مناسبة (Firebase/Firestore أو SQL) مصمّمة باحترافية وقابلة للتوسع، مع العلاقات والفهارس اللازمة للبحث السريع.
• NFR-03 — Backend حقيقي وآمن [explicit]: REST API أو Firebase APIs حسب التقنية المختارة، مع تطبيق صلاحيات Authentication وAuthorization.
• NFR-04 — عدم وضع المفاتيح السرية داخل التطبيق [explicit]: تُحفظ المفاتيح خارج التطبيق.
• NFR-05 — ربط فعلي بالبيانات [explicit]: لا واجهات وهمية ولا بيانات تجريبية فقط؛ كل عرض وإجراء مربوط بقاعدة البيانات والـBackend.
• NFR-06 — معالجة انقطاع الاتصال [explicit]: حفظ العمليات أو إعادة محاولتها عند عودة الاتصال.
• NFR-07 — حماية الحسابات والصلاحيات والتحقق من البيانات [explicit]: تحقق من المدخلات وضبط صلاحيات الأدوار.
• NFR-08 — الحفاظ على الكود السابق [explicit]: فحص المشروع الحالي أولًا، وعدم إعادة بناء الأجزاء المكتملة، والحفاظ على أي كود سابق وتطويره بدل حذفه وإعادة كتابته.
• NFR-09 — تنفيذ المشروع على مراحل [explicit]: بنية المشروع، قاعدة البيانات، Backend/API، Authentication، الواجهات، ربط الواجهات بالبيانات الحقيقية، الصلاحيات والأمان، الاختبارات وإصلاح الأخطاء، تجهيز المشروع للإطلاق.
• NFR-10 — تقرير ختامي [explicit]: تقرير مختصر يوضح ما تم بناؤه، وما تبقى، وكيف يمكن تشغيل التطبيق.
• NFR-11 — قابلية القراءة والوصول البصري [direction]: النصوص وعناصر التحكم تبقى كاملة داخل الإطار عند 375px و768px و1280px؛ المحتوى المتحرك والتمريري قد يعبر الحافة بالتصميم بشرط أن يتحرك فعلًا وأن يصبح كل عنصر مقروءًا بالكامل أثناء مروره، وعند prefers-reduced-motion يتوقف ويلتفّ أو يصبح قابلًا للتمرير.

10. Tech Stack

• الواجهة الأمامية: React (تطبيق ويب عربي RTL متجاوب مع الهاتف وشاشات Android).
• الخلفية: Python / FastAPI مع REST API.
• قاعدة البيانات: قاعدة بيانات علائقية (SQL) مع العلاقات والفهارس اللازمة للبحث السريع — مع إمكانية Firebase/Firestore حسب ما يثبت أنه أفضل للبنية.
• الحاويات: Docker و docker-compose.
• Kubernetes: يُستخدم فقط إذا تطلّب النشر ذلك.
• الخطوط: Noto Kufi Arabic (العناوين) و IBM Plex Sans Arabic (النص والتسميات والأرقام tabular).

11. Assumptions and Constraints

• A-01 [assumption]: التطبيق يملك هويته الخاصة (app-owned identity) وواجهة مخصصة (custom UI)، والمستخدم العادي ومقدم الخدمة ينشئان حسابيهما ذاتيًا.
• A-02 [assumption]: حساب مدير النظام يُهيَّأ عبر مسار provisioning إداري، ولا يُنشأ ذاتيًا من واجهة عامة.
• A-03 [constraint]: لا تُبنى واجهات وهمية أو بيانات تجريبية فقط.
• A-04 [constraint]: لا تُوضع المفاتيح السرية داخل التطبيق.
• A-05 [constraint]: لا يُعاد بناء الأجزاء المكتملة إن كانت موجودة؛ يُفحص المشروع الحالي ويُكمل من آخر نقطة صحيحة.
• A-06 [constraint]: يُحافظ على أي كود سابق ويُطوَّر بدل حذفه وإعادة كتابته.
• A-07 [constraint]: تصميم عربي RTL بالكامل ومتجاوب مع الهاتف وشاشات Android.
• A-08 [constraint]: قاعدة البيانات مصمّمة باحترافية وقابلة للتوسع مع العلاقات والفهارس اللازمة للبحث السريع.
• A-09 [constraint]: تطبيق صلاحيات Authentication وAuthorization على كل عملية محمية.
• A-10 [assumption]: لا توجد متطلبات مؤجلة إلى أفق مستقبلي في المصدر؛ كل ما ورد هو نطاق حالي.

12. Glossary

• earthy-api: الاسم التقني للمشروع.
• دليل اليمن للخدمات: الاسم الذي يُقدَّم به المنتج للمستخدم النهائي.
• مستخدم عادي: دور يبحث ويتصفح ويتواصل ويطلب ويقيّم ويحفظ المفضلة.
• مقدم خدمة: دور ينشر خدماته ويستقبل الطلبات ويقدّم العروض.
• مدير النظام: دور يدير الدليل والإحصائيات والصلاحيات.
• الطلب: طلب خدمة يُرسله المستخدم العادي.
• العرض: عرض يقدّمه مقدم الخدمة على طلب.
• المحافظة: وحدة إدارية يمنية.
• المديرية: وحدة إدارية فرعية داخل المحافظة.
• التصنيف: فئة خدمة (صيانة السيارات، الكهرباء، السباكة، المطاعم، المحلات، النقل، المقاولات، التقنية والبرمجة، الصحة، التعليم، الخدمات المنزلية، وغيرها).
• RTL: اتجاه الكتابة من اليمين إلى اليسار.
• route chip: chip تصنيف بخط لوني ثابت.
• ruled band: شريط في الصفحة الرئيسية بعنوان مرقّم وخط فاصل.
• prefers-reduced-motion: تفضيل نظام لتقليل الحركة.