كيف تبني لوحة إدارة SaaS مع مساعد ذكاء اصطناعي في Next.js

في نهاية هذا الدليل ستملك لوحة إدارة داخلية مع مساعد ذكاء اصطناعي تعمل على حاسوبك وجاهزة للانتقال إلى خادم. هي لوحة تحكم مبنية بـ Next.js ومعها واجهة API خاصة بها، وتبنيها انطلاقاً من قالب Admin Dashboard Template 2 من Aniq UI بدلاً من البدء بمجلد فارغ.

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

قبل أن تبدأ: قرارات عليك اتخاذها

معظم متاعب الأدوات الداخلية تأتي من قرارات تُتخذ متأخرة. احسم هذه الستة قبل أن تفتح الطرفية، وسيمضي بقية الدليل أسرع.

• من يسجّل الدخول، وماذا يحق لكل شخص أن يفعل؟ اكتب قائمة الأدوار على الورق أولاً. يأتي القالب بخمسة أدوار (Super Admin وAdmin وManager وEditor وViewer) ويمكنك تعديلها، لكن التعديل أسهل إذا كانت لديك خطة.
• ما هي سجلاتك؟ يضم القالب مستخدمين ومشاريع ومهام وإعدادات للتطبيق. إذا كان عملك يدور حول شيء آخر مثل الطلبات أو التذاكر، فقرّر الآن هل ستعيد تسمية الموجود أم تضيف وحدة جديدة إلى الـ API.
• أي لغات؟ الإنجليزية والعربية متوفرتان. لغة ثالثة ممكنة لكنها تتطلب عملاً أكثر، فاعرف قبل أن تبدأ إن كنت تحتاجها.
• من يدفع ثمن الذكاء الاصطناعي؟ إما أن تحتفظ الشركة بمفتاح مزوّد واحد على الخادم، وإما أن يحضر كل شخص مفتاحه. هذا الاختيار يغيّر فاتورتك وسياسة الخصوصية لديك، والخطوة 8 تشرح الحالتين.
• أين سيعمل؟ على خادم صغير باستخدام Docker، أو على Vercel للوحة التحكم مع الـ API على مضيف Docker. اختر الشكل مبكراً لتضبط العناوين الصحيحة مرة واحدة.
• أي قاعدة بيانات؟ SQLite هي الافتراضية ولا تحتاج إلى إعداد. أما MySQL ففيها تغيير في الإعدادات. والسبب المعتاد لاختيار MySQL هو أن المضيف لا يوفّر قرصاً دائماً.

المطلوب

Larkspur Software وكالة صغيرة تبني تطبيقات ويب لشركات أخرى. يحتاج المكتب إلى مكان واحد يدير فيه عمله. وهذا ما يطلبه الفريق:

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

كيف يغطي القالب هذا المطلوب

الحاجة	أين توجد	ما الذي تستخدمه
موظفون بصلاحيات مختلفة	لوحة التحكم وAPI	شاشتا Admin Management وAdmin Roles؛ وصلاحيات بأسماء مثل projects.edit
متابعة مشاريع العملاء	لوحة التحكم وAPI	شاشة Projects مع الحالة والبيئة والنسخة واسم بالإنجليزية والعربية
حسابات العملاء	لوحة التحكم وAPI	شاشتا Users وDeleted users، والمرشحات، وإجراءا التحقق والاستعادة
أسئلة بلغة عادية	لوحة التحكم وAPI	شاشة AI Assistant، مع مفتاح مزوّد تضعه أنت
الإنجليزية والعربية	لوحة التحكم	العنوانان /en و/ar، وملفات الرسائل تحت messages/
حاسوب محمول ثم خادم	Docker والإعدادات	Docker Compose، وملفات .env، وخادم ويب في الواجهة
التحكم في المساعد	API	صلاحية ai_chat.use على دور ما

قالب جاهز أم البناء من الصفر أم منشئ مستضاف

هناك ثلاث طرق صادقة للحصول على لوحة إدارة مع مساعد ذكاء اصطناعي، ولكل طريقة فريق يناسبها.

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

منشئ مستضاف. تمنحك خدمة low-code أو أدوات داخلية شاشة تعمل بسرعة وتتولى الاستضافة عنك. في المقابل تعمل داخل مجموعة مكوّناتها ونموذج أسعارها، والانتقال بعيداً عنها لاحقاً يعني عادةً إعادة البناء. تحقق مما يتقاضاه عن كل مستخدم، وما الذي يمكنك تصديره، وهل تدعم التخطيط من اليمين إلى اليسار قبل أن تلتزم.

قالب مع الشيفرة المصدرية. تبدأ بشاشات جاهزة وواجهة API تعمل ومساعد، وتملك الشيفرة. تدفع ثمن القالب مرة واحدة، وتستضيفه بنفسك، وتغيّر ما تشاء. الثمن أن تكون مرتاحاً مع Next.js، ثم مع NestJS إذا وسّعت الـ API. لا تسمح الرخصة بنشر الشيفرة المصدرية أو إعادة بيعها، لكنها تغطي عدداً غير محدود من المشاريع، بما فيها مشاريع العملاء.

لدى Larkspur مطورون في فريقها وتريد إبقاء بيانات عملائها على خادمها الخاص، لذلك تختار القالب. وإذا لم يكن في فريقك من يكتب الشيفرة، فالمنشئ المستضاف هو الخيار الأقرب إلى الواقع.

مثال على خطة إطلاق أسبوعاً بأسبوع

هذا جدول نموذجي لـ Larkspur وليس معياراً. وتيرتك أنت ستكون مختلفة.

• الأسبوع 1، تشغيله. نزّل ملف ZIP، وشغّله بـ Docker، وتجوّل في كل شاشة، وجرّب الحسابين التجريبيين. واحسم الأسئلة الستة أعلاه.
• الأسبوع 2، جعله ملكهم. ضع هويتك التجارية، وأعد بناء الأدوار، وأنشئ حسابات الموظفين الحقيقية، واحذف المسؤولين التجريبيين.
• الأسبوع 3، إدخال العمل. أدخل المشاريع وحسابات العملاء الحقيقية، وأضف مفاتيح المزوّدين، ودع شخصين أو ثلاثة يستخدمون المساعد بأسئلة حقيقية.
• الأسبوع 4، التحصين والإطلاق. اضبط قيم بيئة الإنتاج، وانشر على الخادم، وافحص عنوان الصحة، وراجع قائمة التحقق قبل الإطلاق قرب نهاية هذا المقال.

خطوة بخطوة

1. اختر الحزمة

يأتي القالب في ثلاث حزم. حزمة Full Stack تضم لوحة التحكم وواجهة NestJS API. وحزمة Admin Dashboard هي لوحة التحكم وحدها، وتعمل مع خادم تجريبي صغير مدمج فيها وتحفظ السجلات التجريبية في متصفحك. وحزمة Backend API هي الـ API وحدها.

تريد Larkspur بيانات حقيقية ومساعداً حقيقياً، فتأخذ Full Stack. إذا أردت تصميم الشاشات أولاً فقط، فحزمة Admin Dashboard تكفي، ويمكنك ربطها بواجهة API لاحقاً. وإذا كانت لديك واجهة أمامية بالفعل وتحتاج إلى الخادم فقط، فحزمة Backend API تعطيك المسارات ومنطق الأدوار وأدوات المساعد.

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

2. شغّله محلياً بـ Docker

ثبّت Docker Desktop (أو Docker Engine على Linux) ولا شيء غيره. ثم اتبع هذه الخطوات الفرعية.

2a. التنزيل. افتح My templates في حسابك على Aniq UI ونزّل ملف ZIP الخاص بحزمة Full Stack.

انظر أي حزمة محددة في صفحة التنزيل، لأن أسماء المجلدات في الخطوات اللاحقة تعتمد عليها.

2b. فك الضغط وافتح المجلد. فك ضغط الأرشيف وافتح طرفية داخل مجلد dashboard-2-full-stack (على Windows، فك الضغط أولاً بمستكشف الملفات).

انظر إلى محتويات المجلد: يجب أن ترى back-end وfront-end وdocker-compose.yml جنباً إلى جنب.

2c. شغّل التطبيقين.

docker compose up --build

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

انظر إلى الطرفية: تعرض تقدم البناء أولاً، وتنتظر لوحة التحكم حتى تعلن الـ API أنها سليمة.

2d. افتحه. انتقل إلى localhost:3030 واستخدم الحساب admin@example.com وكلمة المرور Admin@123. العربية على /ar. وتستجيب الـ API على localhost:8000/api/health متى أصبحت قاعدة بياناتها جاهزة.

ما الذي تتحقق منه: يجب أن يستجيب عنوان الصحة، وأن تعرض لوحة التحكم بيانات في شاشتها الأولى. ما يخطئ فيه الناس عادةً: منفذ مستخدم بالفعل. إذا كان برنامج آخر يشغل 3030 أو 8000، فأنشئ ملفاً اسمه .env بجانب docker-compose.yml واضبط DASHBOARD_PORT=3040 (أو API_PORT للـ API)، ثم شغّل الأمر نفسه مرة أخرى. والتشغيل الذي يبدو عالقاً غالباً ما يكون لا يزال يملأ البيانات التجريبية.

لإيقاف التطبيقين اضغط Ctrl+C. تبقى بياناتك في وحدة تخزين Docker. احذر من docker compose down -v: الخيار -v يحذف وحدة التخزين، ويأتي التشغيل التالي ببيانات تجريبية جديدة.

3. تعرّف على الطرق الأخرى للتشغيل

لن تستخدمها كلها، لكن كل واحدة تحل حالة حقيقية.

لوحة التحكم وحدها. مع حزمة Admin Dashboard تبني صورة واحدة وتشغّل حاوية واحدة. وإذا لم تحدد عنوان API فإنها تعمل على خادمها التجريبي ولا تحتاج إلى خادم خلفي.

انظر إلى اسم المجلد في الطرفية: تُفك هذه الحزمة في مجلد مختلف عن مجلد Full Stack.

انظر إلى مخرجات البناء: يحدث تثبيت الاعتمادات والبناء داخل الصورة، لذلك يحتاج أول بناء إلى اتصال بالإنترنت.

الـ API وحدها. مع حزمة Backend API تبني صورة وتشغّلها مع وحدة تخزين تحمل ملف قاعدة البيانات. يملأ التشغيل الأول تلك القاعدة بالسجلات والحسابات التجريبية. جميع المسارات تحت /api، وتتحقق منها بعنوان الصحة.

انظر إلى الملفات في المجلد، ومنها Dockerfile وpackage.json و.env.example.

انظر إلى الصورة وهي تُبنى: صورة الـ API منفصلة عن صورة لوحة التحكم.

انظر إلى فحص الصحة في النهاية: الـ API التي تعمل تجيب بحالة ok.

من دون Docker. ثبّت Node.js بالإصدار 22.9 أو أحدث وشغّل corepack enable مرة واحدة. شغّل الـ API أولاً، لأن لوحة التحكم تقرأ كل بياناتها منها. في back-end انسخ ملف الإعدادات النموذجي، وأنشئ قاعدة البيانات بـ yarn seed، ثم شغّل yarn dev. وفي front-end انسخ ملف الإعدادات النموذجي وشغّله بالطريقة نفسها.

انظر إلى الطرفية الأولى التي تشغّل الـ API.

انظر إلى الطرفية الثانية التي تشغّل لوحة التحكم على الـ API الموجودة في الأولى.

الأسلوب نفسه يصلح للحزم ذات التطبيق الواحد.

انظر إلى قلة ما يلزم هنا: بلا ملف .env يجيب الخادم التجريبي.

انظر إلى طرفية الـ API وهي تبقى مفتوحة أثناء استخدامك لها.

ما يخطئ فيه الناس عادةً: إصدار Node.js أقدم من 22.9، فيفشل yarn dev عند قراءة .env؛ وYarn يجيب بالإصدار 1.22 لأن Corepack معطّل؛ ولوحة تحكم تعرض بيانات تجريبية مع أنك أردت استخدام الـ API الخاصة بك، لأن عنوان الـ API كان مفقوداً وقت البناء.

4. استكشف البيانات التجريبية قبل أن تغيّر أي شيء

تحمّل البيانات الأولية ما يكفي لشركة صغيرة: نحو اثني عشر مسؤولاً، وخمسة أدوار تحمل 25 صلاحية، و15 مستخدماً، و15 مشروعاً، و10 مهام، و13 إعداداً للتطبيق، إضافة إلى بعض المستخدمين والمشاريع المحذوفة للتدرب على الاستعادة. تنقّل في الشريط الجانبي من الأعلى إلى الأسفل، وانتهِ بالصفحة التي تعرض كل مكوّنات الواجهة.

انظر كيف يجمع الشريط الجانبي الشاشات، لأنك ستعيد تسمية هذه القائمة وتقلّمها لاحقاً.

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

ثم سجّل الخروج وادخل بالحساب john.smith@admin.com وكلمة المرور admin123. لهذا الحساب دور Viewer. يستطيع قراءة كل القوائم لكنه لا يستطيع إنشاء أو تعديل أو حذف أي شيء، ولا يستطيع فتح المساعد. ومعرفة هذا الفرق مبكراً تخبرك كيف يعمل نظام الصلاحيات، وهو ما يهمك في الخطوة 6.

ما الذي تتحقق منه: تستطيع أن تشرح بجملة لكل منهما ما يفعله Super Admin وViewer. ما يخطئ فيه الناس عادةً: يعدّلون السجلات التجريبية أولاً ثم ينسون أيها البيانات الحقيقية. اترك البيانات التجريبية كما هي حتى تصبح مستعداً لاستبدالها دفعة واحدة.

5. ضع اسم الوكالة عليه

كل عناصر الهوية موجودة في مجلد لوحة التحكم (front-end في حزمة Full Stack). شغّل yarn dev هناك أثناء التعديل وسيُعاد تحميل الصفحة مع كل حفظ. أربعة أماكن هي الأهم:

• يضم src/config/brand.config.ts الكائن BRAND_CONFIG: الاسم والشركة وبيانات الصفحة الوصفية وتفاصيل التطبيق المثبّت، بالإنجليزية والعربية.
• الملفان public/assets/images/logo-for-lightmode.png وlogo-for-darkmode.png هما الشعاران. استبدل الملفين وأبقِ الاسمين.
• يعرّف src/styles/theme-variables.css كل لون مرة للوضع الفاتح ومرة للوضع الداكن. ولون الهوية هو --primaryColor.
• يحتوي messages/<namespace>/en.json وar.json على كل كلمة تظهر على الشاشة. عدّل اللغتين معاً.

تغيّر Larkspur الاسم، وتبدّل الشعارين، وتختار لوناً أساسياً جديداً. هذا يكفي لتبدو لوحة التحكم لها. تقرأ المكوّنات الألوان عبر متغيرات مثل bg-[var(--surface)]، لذلك أي مكوّن تضيفه لاحقاً يحافظ على الوضعين إذا فعل الأمر نفسه.

انظر إلى صفحة المكوّنات: هي أسرع طريقة لرؤية لونك الجديد على كل أنواع عناصر التحكم دفعة واحدة.

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

6. أعدّ الموظفين والأدوار

تأتي البيانات الأولية بخمسة أدوار: Super Admin وAdmin وManager وEditor وViewer. يمكن أن يحمل الشخص الواحد أكثر من دور، وتجتمع له صلاحياتها كلها. تُسمّى الصلاحيات بصيغة module.action، مثل users.view أو projects.edit أو settings.edit، وعددها 25 موزعة على المسؤولين والأدوار والمستخدمين والمشاريع والإعدادات والمساعد.

توزّع Larkspur فريقها هكذا: يبقى المالك Super Admin، ويصبح قائدا المشاريع Manager، ويصبح المطورون Editor، ويصبح المتعاونون الخارجيون Viewer. نفّذ ذلك في ثلاث جولات:

1. افتح Admin Roles واقرأ ما يمنحه كل دور. أعد التسمية أو قلّم حتى تطابق الأدوار الخطة المكتوبة على الورق.
2. افتح Admin Management وأنشئ كل شخص حقيقي، ثم عيّن له أدواره.
3. سجّل الدخول بشخص واحد لكل دور وجرّب الإجراءات التي يجب أن يملكها ذلك الدور والتي لا يجب.

إذا غيّرت دوراً بينما شخص ما مسجّل الدخول، فإن قوائمه وأزراره تتحدث دون إعادة تحميل، لأن الـ API تخبر لوحة التحكم الخاصة به عبر WebSocket.

انظر إلى شارات الأدوار على كل حساب: تظهر بنظرة واحدة من يحمل أي دور.

انظر كيف تُجمّع الصلاحيات حسب الوحدة، مما يسهّل منح «العرض» دون «التعديل».

قبل أي شيء آخر، غيّر كلمات مرور المسؤولين التجريبيين من Settings ثم Security، أو احذف تلك الحسابات. تنشئها البيانات الأولية بكلمات مرور مطبوعة في الوثائق العامة، وأدلة القالب تحذّر من ذلك أكثر من مرة وبحق.

ما يخطئ فيه الناس عادةً: حذف Super Admin قبل أن يتمكن مسؤول آخر من إدارة الأدوار، أو منح دور Admin للجميع لأنه أسهل. ابدأ بتشدد ثم خفّف عندما يطلب أحدهم.

7. أدخل المشاريع وحسابات العملاء

افتح Projects واستبدل الصفوف التجريبية بعمل Larkspur الحقيقي. يحمل المشروع اسماً ووصفاً بالإنجليزية والعربية، وحالة (in-progress أو ready أو blocked)، وبيئة، ونسخة، وصورة اختيارية. والحذف حذف ناعم: تنتقل المشاريع المحذوفة إلى شاشتها الخاصة ويمكن استعادتها.

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

انظر إلى العدادات فوق الجدول وإلى شارات الحالة في كل صف.

إذا كان لمنتجك سجلات أخرى، فالـ API من نوع REST بسيط تحت /api، لذلك يمكنك إضافة وحدات بجانب الموجودة. سجّل الدخول عبر POST /api/auth/login لتحصل على الرمز الذي يحتاجه كل طلب آخر، وأرسله بوصفه bearer token. تقبل القوائم page وpage_count، بحد أقصى 100 في الصفحة.

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

8. فعّل مساعد الذكاء الاصطناعي

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

يعمل مع Google Gemini أو OpenAI أو DeepSeek، تُختار من قائمة النماذج. تُحفظ المحادثات لكل مسؤول في شريط جانبي للسجل. وأمامك طريقتان لتوفير المفتاح:

• ضع مفتاح المزوّد في back-end/.env وأعد تشغيل الـ API (مع Docker Compose شغّل docker compose up مرة أخرى). عندها يستخدم كل من لديه وصول مفتاحك.
• اترك الخادم بلا مفتاح. عندها يطلب المساعد من كل شخص مفتاحه الخاص، ويبقى في متصفحه.

تبدأ Larkspur بالخيار الثاني، حتى لا يقع استخدام أحد على فاتورة الوكالة عن طريق الخطأ. تذكر الوثائق أن Gemini يعمل بمفاتيح مجانية، بينما يتطلب OpenAI تفعيل الفوترة على المفتاح. قد ينفد حد المفتاح المجاني، ويخبرك المساعد بذلك؛ اختر نموذجاً آخر أو انتظر.

تحكّم في الوصول عبر صلاحية ai_chat.use. ولأن المساعد يستطيع الكتابة، امنحها فقط للأدوار التي تثق بها في تلك التعديلات. أما المتعاونون الخارجيون بدور Viewer فلا يحصلون على شيء منها.

انظر كيف يمزج الرد بين ملخص مكتوب ورسم بياني مبني من أرقام لوحة التحكم نفسها.

هناك إضافتان اختياريتان. حاوية Cloudflare R2 تتيح رفع صور الملفات الشخصية ومرفقات الصور؛ وبدونها ترد عمليات الرفع بأنها غير مُعدّة ويعمل كل شيء آخر. ومفتاح MCP تختاره أنت يفعّل نقطة نهاية MCP في الـ API؛ وبدونه ترفض تلك النقطة كل الطلبات.

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

9. افحص العربية وبقية تفاصيل اللغة

افتح /ar. تضبط الصفحة lang="ar" وdir="rtl" قبل أن ترسم نفسها، فينتقل الشريط الجانبي إلى اليمين وتُقرأ الجداول والقوائم من اليمين إلى اليسار. وتجيب الـ API بالعربية أيضاً عندما يرسل الطلب Accept-Language: ar، وتحمل المشاريع والإعدادات والدول اللغتين في قاعدة البيانات.

يجب أن يستخدم كل ما تضيفه أصناف Tailwind المنطقية مثل ms-2 وpe-4 وstart-0 وtext-start بدلاً من ml-* وpr-* وleft-* أو text-left، وإلا ظهرت الصفحة العربية بشكل خاطئ. وإذا احتجت يوماً إلى لغة ثالثة فأضف رمزها في ثلاث قوائم للغات، وانسخ كل ملف en.json تحت الرمز الجديد، وأضفها إلى قائمة اللغات. وتستمر الـ API في الرد بالإنجليزية على اللغة الجديدة إلى أن تضيف ترجماتها في back-end/src/i18n/.

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

10. انشره على خادم

ملف docker-compose.yml نفسه الذي عمل على الحاسوب المحمول يعمل أيضاً على الخادم. امنح لوحة التحكم والـ API نطاقاً لكل منهما خلف Caddy أو Nginx، فهو يضيف HTTPS، ووجّه النطاق الأول إلى المنفذ 3030 (لوحة التحكم) والثاني إلى المنفذ 8000 (الـ API).

أنشئ .env بجانب docker-compose.yml واضبط DASHBOARD_URL وAPI_URL على العنوانين العامين. تدمج لوحة التحكم عنوان الـ API في شيفرتها المبنية، وتأخذ الـ API السطرين نفسيهما لـ CORS_ORIGIN وFRONTEND_URL. ضع مفاتيح الذكاء الاصطناعي وTRUST_PROXY=1 في back-end/.env. ثم شغّله في الخلفية:

docker compose up --build -d

في الإنتاج ترفض الـ API أن تبدأ مع قيمة JWT_SECRET النموذجية أو مع CORS_ORIGIN فارغ. ومع Docker تولّد لك سراً وتحفظه في وحدة تخزين البيانات، أو يمكنك صنع سرّك بنفسك:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

عندما يعمل كل شيء، افتح https://api.your-domain.com/api/health (بنطاقك أنت) وابحث عن "status":"ok". وإن فضّلت، يمكن نشر لوحة التحكم وحدها على Vercel من مستودع Git خاص: اضبط ENABLE_EXPERIMENTAL_COREPACK على 1، ثم NEXT_PUBLIC_API_BASE_URL وNEXT_PUBLIC_WEBSOCKET_BASE_URL وNEXT_PUBLIC_BASE_URL. أعد النشر بعد تغيير أي قيمة NEXT_PUBLIC_*، لأنها تُدمج وقت البناء. واترك NEXT_PUBLIC_DEMO_MODE معطلاً ما لم يكن الموقع عرضاً تجريبياً عاماً.

قاعدة البيانات الافتراضية هي SQLite، محفوظة في وحدة التخزين /data. أما MySQL ففيها تغيير في الإعدادات: أنشئ قاعدة بيانات فارغة، واضبط DB_TYPE والاتصال في back-end/.env، ثم املأها بالبيانات الأولية. اختر MySQL إذا لم يكن لدى مضيفك قرص دائم. وإذا شغّلت الـ API بدون Docker في الإنتاج، فإن yarn seed:prod ينشئ الجداول مرة واحدة؛ شغّله مرة واحدة فقط، لأن التشغيل الثاني يعيد إعدادات التطبيق وصلاحيات الأدوار المدمجة إلى قيمها التجريبية.

ما الذي تتحقق منه: سجّل الدخول من حاسوب آخر، وغيّر دوراً، وراقب جلسة ثانية مسجّلة وهي تتحدث. هذا يثبت أن عنوان WebSocket صحيح. ما يخطئ فيه الناس عادةً: صفحات فارغة مع سطر CORS في وحدة تحكم المتصفح. لا تجيب الـ API إلا المتصفحات القادمة من العناوين الموجودة في CORS_ORIGIN، فأضف عنوان لوحة التحكم الحقيقي هناك وفي FRONTEND_URL.

التشغيل اليومي

بعد أن تصبح Larkspur على الإنترنت، يتحول العمل إلى روتينات صغيرة متكررة.

• إضافة شخص جديد. أنشئ المسؤول في Admin Management، وعيّن له دوراً واحداً، وأرسل له العنوان. لا تشارك حساب Super Admin.
• إنهاء خدمة شخص. احذف حساب المسؤول في اليوم نفسه. ولأن الأدوار تتحدث مباشرة، يمكنك أيضاً سحب دور من شخص لا يزال مسجّل الدخول فتختفي أزراره دون إعادة تحميل.
• تغيير ما يستطيع دور ما فعله. عدّله في شاشة Admin Roles وأخبر الفريق. واختبره بحساب حقيقي لذلك الدور.
• استعادة الأخطاء. يُحذف المستخدمون والمشاريع حذفاً ناعماً. افتح شاشة Deleted المقابلة لإعادة أحدها.
• النسخ الاحتياطية. مع SQLite في Docker تعيش البيانات في وحدة تخزين واحدة. انسخ احتياطياً تلك الوحدة وفق جدول يناسب مدى تكرار تغيّر السجلات. ومع MySQL استخدم أداة النسخ الاحتياطي لدى مزوّد قاعدة البيانات.
• التحديث. بعد تغيير الشيفرة أعد بناء الصور، لأن الحاوية العاملة لقطة من الشيفرة وقت البناء.
• مراقبة المساعد. راجع من يملك ai_chat.use بين حين وآخر.

كم تكلّف التشغيل

القالب عملية شراء لمرة واحدة بدءاً من $99، والحزمة تفرق: حزمة Full Stack التي يستخدمها هذا الدليل تكلّف أكثر من سعر البداية، وصفحة المنتج تسرد كل حزمة. تغطي الرخصة عدداً غير محدود من المشاريع، بما فيها أعمال العملاء، ما دمت لا تشارك الشيفرة المصدرية علناً.

وراء ذلك تدفع مقابل ما تضيفه:

• استضافة لوحة التحكم والـ API. خادم يدعم Docker يشغّل الاثنين؛ ويمكن لـ Vercel استضافة لوحة التحكم وحدها.
• استخدام الذكاء الاصطناعي، إذا وضعت مفتاح مزوّد على الخادم. تحاسب Google وOpenAI وDeepSeek وفق صفحات أسعارها. وإذا أحضر كل شخص مفتاحه فالفاتورة عليه.
• حاوية Cloudflare R2، إذا أردت رفع الصور، ومفتاح WeatherAPI.com إذا أردت الطقس في عبارة الترحيب. وكلاهما اختياري.
• اسم نطاق، وخدمة بريد لرسائل التحقق إذا استخدمتها.

وما هو مجاني: التطوير المحلي على SQLite، والبيانات التجريبية، والـ API التجريبية المدمجة في حزمة لوحة التحكم، وكل ميزة اختيارية تتركها معطلة.

ما الذي تخصصه بعد ذلك

• أدوار تناسب شركتك. أعد تسمية الأدوار الخمسة وقلّم صلاحياتها حتى يمنح كل دور ما تتطلبه الوظيفة فقط.
• سجلاتك الخاصة. أضف وحدة إلى NestJS API لشيء تتابعه Larkspur وليس مشروعاً، مثل الفواتير أو تذاكر الدعم، وشاشة مناسبة له. لكل نطاق في الـ API وحدته الخاصة، فتجد الوحدة الجديدة مكانها بجانب الأخريات.
• أدوات جديدة للمساعد. يمر المساعد عبر سجل MCP مصمم ليتوسع، فيمكنك تعليمه أسئلة خاصة ببياناتك.
• لغة ثالثة. انسخ ملفات الرسائل، وأضف الرمز إلى قوائم اللغات الثلاث، وأضف ترجمات الـ API.
• شيفرة إنتاج أنظف. عندما تصبح الـ API الخاصة بك المصدر الدائم للبيانات، يحذف السكربت yarn remove:mock الخادم التجريبي المدمج، ويزيل yarn remove:demo مفتاح العرض التجريبي العام. نفّذ commit أولاً، لأن كليهما يعيد كتابة الملفات.

قائمة التحقق قبل الإطلاق

• حُذف المسؤولون التجريبيون أو غُيّرت كلمات مرورهم.
• ضُبط JWT_SECRET الخاص بك، أو تأكدت من السر الذي ولّده Docker في وحدة تخزين البيانات.
• يحمل CORS_ORIGIN وFRONTEND_URL عنوان لوحة التحكم الحقيقي.
• يشير NEXT_PUBLIC_API_BASE_URL إلى الـ API مع /api، وبُنيت لوحة التحكم بعد ضبطه.
• HTTPS أمام لوحة التحكم والـ API معاً.
• يجيب عنوان الصحة بـ "status":"ok".
• اختُبر كل دور بحساب حقيقي.
• مُنحت ai_chat.use فقط حيث يُراد، ووُضعت مفاتيح المزوّدين حيث قررت.
• فُحصت العربية في كل شاشة غيّرتها.
• جُدولت نسخة احتياطية لوحدة تخزين البيانات أو قاعدة البيانات.
• وضع العرض التجريبي معطّل.

أخطاء شائعة

الإطلاق مع المسؤولين التجريبيين

تنشئ كل بيانات أولية مسؤولين بكلمات مرور منشورة. غيّرها أو احذفهم قبل أن يتمكن أي شخص آخر من الوصول إلى اللوحة، واضبط JWT_SECRET الخاص بك.

تعديل قيمة NEXT_PUBLIC وانتظار تغيير

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

مسح البيانات بأمر إيقاف خاطئ

الأمر docker compose down يُبقي بياناتك. وإضافة -v تحذف وحدة التخزين، ويذهب معها كل ما أنشأته.

الصفحات تبقى فارغة وتذكر وحدة التحكم CORS

لا تجيب الـ API إلا المتصفحات القادمة من العناوين الموجودة في CORS_ORIGIN. إذا كانت لوحة التحكم تعمل على نطاق أو منفذ جديد، فأضفه هناك وفي FRONTEND_URL.

إعطاء المساعد للجميع

يستطيع المساعد تغيير المستخدمين والإعدادات. امنح ai_chat.use للأدوار التي يجب أن تملك هذه القدرة ولا أحد غيرها.

تمرير ملف البيئة النموذجي إلى Docker

تعمل صورة الـ API في وضع الإنتاج. إذا شغّلتها بنسخة من ملف البيئة النموذجي فإن هذا الملف يضبط وضع التطوير فوق قيمة الصورة نفسها. مرّر كل قيمة تحتاجها عبر -e بدلاً من ذلك.

الأسئلة الشائعة

كيف أبني لوحة إدارة مع مساعد ذكاء اصطناعي في Next.js؟

ابدأ من لوحة تحكم فيها الأدوار والقوائم وشاشة المحادثة بالفعل، ثم اربط بياناتك ومزوّد نماذج. في هذا القالب يقرأ المساعد من الـ API نفسها التي تقرأ منها بقية اللوحة، فتضيف مفتاحاً وسجلاتك بدلاً من كتابة بنية المحادثة.

هل أحتاج إلى خادم خلفي؟

فقط للبيانات الحقيقية. تعمل حزمة Admin Dashboard على خادم تجريبي داخل المتصفح، وهذا يكفي لأعمال التصميم. أما للوحة حية فتحتاج إلى API، وحزمة Full Stack تتضمن واحدة بـ NestJS.

ما مزوّدو الذكاء الاصطناعي الذين يدعمهم المساعد؟

Google Gemini وOpenAI وDeepSeek، تُختار من قائمة نماذج. يستطيع كل شخص لصق مفتاحه، أو يمكنك ضبط مفتاح واحد على الخادم.

هل يدعم العربية وRTL؟

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

هل أستطيع استخدامه للعملاء؟

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

هل أستطيع تغيير ما يُسمح للمساعد بفعله؟

أنت تقرر من يستخدمه عبر صلاحية ai_chat.use، ولا يتصرف المساعد إلا ضمن صلاحيات ذلك الشخص نفسه. وتُضاف الأدوات الجديدة عبر سجل MCP الخاص به في الـ API.

هل أستطيع تجربته دون تثبيت أي شيء؟

نعم. العرض التجريبي المباشر يشغّل لوحة التحكم نفسها. وعلى جهازك، تعمل حزمة Admin Dashboard على بياناتها التجريبية المدمجة دون أي API أو مفتاح ذكاء اصطناعي.

هل أستطيع إزالة البيانات التجريبية والخادم التجريبي؟

نعم. سكربتان هما yarn remove:mock وyarn remove:demo يزيلان الخادم التجريبي ومفتاح العرض العام من الشيفرة. نفّذ commit أولاً، لأنهما يعيدان كتابة الملفات.

جرّبه بنفسك

افتح العرض التجريبي المباشر لتتجول في لوحة التحكم والمساعد. تسرد صفحة منتج Admin Dashboard Template 2 الحزم، وتغطي الوثائق كل خطوة أعلاه بالتفصيل. وتجد خيارات أخرى في فئة قوالب لوحات تحكم الإدارة، ويساعدك دليل قوالب لوحات تحكم الإدارة حسب المجال إذا كانت حالتك تختلف عن هذه.

هذا القالب أيضاً واحد من عشرة قوالب في Next.js Templates Bundle، إذا كنت تتوقع بناء أكثر من نوع من المنتجات.