لوحة تحكم وتطبيق جوال على API واحد: لماذا بنيناها هكذا في Escore
- نُشر
- القراءة
- قراءة في 8 دقائق
- الكاتب
- محمود حمديمهندس برمجيات متكامل (Full-Stack)
موضوعات المقال

في Escore يقرأ تطبيق Flutter ولوحة التحكم المبنية بـ Next.js من واجهة REST واحدة، وتعمل بجانبها طبقة WebSocket للأحداث المباشرة. هذا المقال يشرح لماذا بنينا لوحة تحكم وتطبيق جوال على API واحد، وما الذي كسبناه من ذلك، والثمن الذي يفرضه هذا الاختيار، ومتى أختار شكلًا آخر، مع مثالين من مشروعين آخرين بنيتهما: IAI وإحكام.
عملنا على Escore عامًا كاملًا لصالح شركة Rov Group السعودية. قاد محمد مجدي تطبيق الجوال، وبنيتُ أنا الخادم الخلفي ولوحة التحكم.
كيف تبدو البنية: ثلاثة مستهلكين وواجهة واحدة
الخادم عملية Node.js وExpress واحدة مقسّمة إلى 16 وحدة، وكلها خلف واجهة REST واحدة. يستهلك هذه الواجهة طرفان كتبناهما: تطبيق Flutter على iOS وAndroid، وتطبيق Next.js على الويب.
ولتطبيق Next.js نفسه وجهان. الأول صفحات عامة يهمّها محرك البحث، مثل مخططات البطولات وملفات اللاعبين والمقالات، تُعرض من الخادم أو تُولَّد مسبقًا لتُحمَّل بسرعة. والثاني لوحة التحكم، بتخطيطها المتداخل الذي يحتاجه المديرون والمحررون، مبنية على App Router. فالواجهة البرمجية الواحدة تخدم في الحقيقة ثلاثة مستهلكين: الجوال، والصفحات العامة، واللوحة.
من اللوحة ينشئ المحرر البطولة، ويولّد مخططها بنظام المجموعات أو الإقصاء الفردي أو المزدوج أو الدوري، ويتابع المباريات. وينشر منها الأخبار بالعربية والإنجليزية بروابط مهيّأة لمحركات البحث، ويتابع انتقالات اللاعبين. وكل ذلك يظهر في التطبيق من المصدر نفسه؛ الخبر الذي يُنشر من اللوحة هو ما يقرؤه المستخدم في تبويب الأخبار.
ما الذي كسبناه من لوحة تحكم وتطبيق جوال على API واحد
المكسب الأول أن لكل قاعدة عمل مكانًا واحدًا. توليد مخطط البطولة يحدث في وحدة البطولات على الخادم، وتحديث التصنيفات بعد كل نتيجة يحدث في وحدة التصنيفات. لا يحسب التطبيق ترتيبًا ولا تحسبه اللوحة، فكلاهما يعرض ما قرره الخادم. ولو كان للوحة منطق خاص بها، لكان ظهور ترتيب في اللوحة يخالف ما في الجوال مسألة وقت.
المكسب الثاني أنه لا توجد مهمة مزامنة. في أي نظام من هذا النوع، حين يعدّل المحرر سجلًا من اللوحة، لا يحتاج التعديل إلى من ينقله من قاعدة بيانات اللوحة إلى قاعدة بيانات التطبيق إن كانتا قاعدة واحدة. وهذا حال Escore: خلف الواجهة الواحدة قاعدة بيانات واحدة، فلا وجود لهذه المهمة أصلًا.
المكسب الثالث نظام دخول واحد. رموز JWT قصيرة العمر، ومعها رموز تجديد مشفّرة تُستبدل عند كل تجديد، تخدم التطبيق واللوحة معًا. وطبقة الصلاحيات نفسها تحرس مسارات الطرفين.
والمكسب الرابع أن البيانات الخارجية تدخل مرة واحدة. مهام مجدولة تسحب بيانات المباريات من PandaScore وGRID وAbios، وتوحّد شكلها، وتحفظها في MongoDB. ثم يقرأ الجميع من واجهة Escore، فيعمل المحرر على السجلات نفسها التي يراها الجمهور.
الثمن الذي يفرضه هذا الاختيار
الواجهة الواحدة ليست مجانية. الأثمان التالية عامة لهذا النمط، وأكتبها كما أراها، لا كسجل لحوادث وقعت في Escore.
الثمن الأول أن التطبيق المنشور لا يتحدّث فورًا. حين تغيّر شكل رد ليخدم اللوحة، تستطيع نشر اللوحة الجديدة في دقائق. أما تطبيق الجوال فيبقى بإصداره القديم على أجهزة كثيرة حتى يحدّثه أصحابها. لذلك يجب أن يبقى كل تغيير في الواجهة متوافقًا مع الإصدارات السابقة: تضيف حقولًا ولا تحذفها، أو تفتح إصدارًا جديدًا من المسار.
الثمن الثاني أن الطرفين يحتاجان إلى أشكال مختلفة من البيانات. اللوحة تريد السجل كاملًا بحقوله الداخلية وعوامل التصفية، والجوال يريد أخف ما يكفي الشاشة. وفي Escore رقم يبيّن وزن شكل الرد: حين أعاد محمد بناء طريقة تكامل التطبيق مع الواجهة وتحويل بيانات JSON، انخفض حجم البيانات المنقولة 65% وزمن الاستجابة 54%. لا أقول إن مشاركة اللوحة كانت سبب الحجم الأصلي، لكن الرقم يوضح أن ما يكفي اللوحة قد يكون عبئًا على جوال في شبكة بطيئة.
الثمن الثالث أن مسارات الإدارة موجودة على الخادم العام نفسه. المسار الذي يعدّل بطولة أو يحذف خبرًا موجود على العنوان الذي يتصل به كل تطبيق، وحمايته تعتمد على حارس الصلاحيات وحده. يكفي نسيان الحارس على مسار واحد لفتحه.
والثمن الرابع أن النشر واحد. خطأ في وحدة تخدم اللوحة قد يُسقط العملية التي تخدم الجمهور، لأنهما عملية واحدة. الفصل بين الوحدات يقلّل هذا الاحتمال ولا يلغيه.
صلاحيات المستخدمين في لوحة التحكم حين تشارك التطبيق واجهته
حين تكون الواجهة مشتركة، لا يمكن أن تكون الصلاحيات في الشاشة. الجوال واللوحة يرسلان طلبات إلى الخادم نفسه، ومن يملك رمز دخول يستطيع إرسال الطلب دون أي شاشة.
في Escore خمسة أدوار: مدير أعلى، ومدير، ومحرر، ومدير فريق، ومشاهد. وتفرض طبقة الصلاحيات حدود كل دور على مسارات الواجهة نفسها. ومن الأدوار ما يقف بين الجمهور والإدارة: مدير الفريق الموثّق يحرّر ملفات فريقه ولاعبيه، فلا هو محرر ولا مشاهد عادي.
والطريقة التي أنصح بها لتصميم الأدوار أن تبدأ من الأفعال لا من الشاشات. اكتب ما يمكن فعله في النظام، مثل إنشاء بطولة وتسجيل نتيجة ونشر خبر وتعديل ملف فريق، ثم حدّد لكل دور ما يحق له منها، واجعل الخادم يفحص الفعل مع كل طلب. بعد ذلك تُبنى الشاشات لتخفي ما لا يحق للمستخدم، وهذا تحسين للتجربة وليس حماية.
IAI: حين يكون الطرف الآخر روبوتًا لا تطبيقًا
IAI مساعد ذكاء اصطناعي يجيب عملاء متجر سعودي للطباعة ثلاثية الأبعاد على منصة سلة، بالعربية، عبر نافذة محادثة في المتجر وروبوت على Telegram. وصاحب المتجر لا يكتب كودًا، فبنيت له لوحة Next.js يرى فيها سجل المحادثات وتوزيع نوايا الأسئلة ودقة الإجابات. ومنها يعدّل قوالب الردود وحدود الثقة التي يُحوَّل عندها السؤال إلى موظف.
هنا لم يكن الشكل واجهة واحدة يستهلكها طرفان. خدمة الروبوت عملية تستمع إلى Telegram وتقرأ بيانات المتجر من واجهة سلة، واللوحة تطبيق مستقل. فجاءت المشاركة في الكود بدل الواجهة: مستودع واحد بـ Turborepo فيه ثلاث حزم، هي خدمة الروبوت واللوحة وحزمة مشتركة. تحمل الحزمة المشتركة أنواع TypeScript وأدوات الاتصال بواجهة سلة ومخططات التحقق، ويستخدمها الطرفان.
والغاية واحدة رغم اختلاف الأداة. حين يستخدم الطرفان الأنواع ومخططات التحقق نفسها، يصعب أن تحفظ اللوحة إعدادًا بشكل لا تتوقعه خدمة الروبوت.
إحكام: منصة ويب بلا واجهة عامة
إحكام منصة ويب عربية لحفّاظ القرآن الكريم، تعمل على ihkamquran.com منذ سبتمبر 2026، وبنيتها كاملة. ليس لها تطبيق جوال أصلي؛ يثبّتها المستخدم على هاتفه كتطبيق ويب. لذلك لم تكن هناك حاجة إلى واجهة REST عامة يستهلكها طرف آخر. تكلّم الصفحات قاعدة البيانات عبر server actions في Next.js، والبيانات في PostgreSQL على Neon عبر Drizzle.
وفي المنصة أدوات إدارة لمراجعة المجموعات المتشابهة ومتابعة بلاغات الأخطاء، وهي ضرورية لمحتوى بهذه الحساسية: 1,090 موضعًا متشابهًا منشورًا، كل منها موثّق من كتب المتشابهات. وحتى دون واجهة عامة، بقيت قاعدة الخادم صارمة: الإجابة الصحيحة لا تصل إلى المتصفح قبل أن يرسل المستخدم إجابته.
متى أختار API واحدًا ومتى أختار شكلًا آخر
الخلاصة من المشاريع الثلاثة أن السؤال ليس عدد الواجهات، بل أين تُنفَّذ قواعد العمل. هذه الطريقة التي أقرر بها اليوم:
- تطبيق جوال أصلي ولوحة تديران البيانات نفسها: واجهة واحدة كما في Escore، مع التزام صارم بالتوافق مع الإصدارات القديمة من التطبيق.
- خدمة تعمل في الخلفية، كروبوت أو مهام مجدولة، ولوحة تضبطها: مستودع واحد وحزمة مشتركة للأنواع والمخططات كما في IAI.
- منصة ويب بلا تطبيق أصلي: لا حاجة إلى واجهة عامة في البداية؛ server actions داخل التطبيق كما في إحكام، وتُضاف الواجهة العامة يوم يأتي تطبيق جوال.
- لوحة تحتاج إلى تقارير ثقيلة: الواجهة نفسها للكتابة، مع مسارات قراءة خاصة بالتقارير حتى لا تُبطئ الاستعلامات الثقيلة ما يراه الجمهور.
إن كان لديك تطبيق قائم بلا لوحة تحكم
أول ما أسأل عنه حين يطلب أحد لوحة تحكم لتطبيق موجود: هل للتطبيق واجهة برمجية، وهل هي موثّقة؟ إن وُجدت، فاللوحة تُبنى فوقها، وأي مسار تحتاجه اللوحة يدخل في الواجهة ذاتها بالصلاحيات ذاتها. تفاصيل هذا المسار ومدته في صفحة تصميم وبرمجة لوحة تحكم، وتفاصيل المشروع كاملة في دراسة حالة Escore.
إن كان لديك تطبيق وتحتاج إلى لوحة تحكم له، أرسل لنا وصفًا قصيرًا من هنا.
مشاركة
مقالات في الموضوع نفسه
| رقم | التاريخ | المقال | المواضيع | القراءة |
|---|---|---|---|---|
| 07 | باك إند تطبيق نتائج مباشرة بـ WebSocket: كيف بنينا Escore | قراءة في 8 دقائق | ||
| 06 | دعم العربية RTL في Flutter: ما تعلّمته من تطبيق Escore ثنائي اللغة | قراءة في 8 دقائق |