البداية السريعة

يأخذك هذا الدليل من الصفر إلى تطبيق متكامل يعمل في أقل من خمس دقائق. في النهاية، سيكون لديك واجهة برمجية بلغة Rust، وموقع ويب عام بـ Next.js، ولوحة إدارة بـ Next.js — كلها تعمل محلياً عبر HTTPS مع قاعدة بيانات مُهيّأة وحساب مدير افتراضي.

إنشاء تطبيق جديد

شغّل أمر forge new لإنشاء مشروعك:

forge new --name=myapp

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

forge new \
  --name=myapp \
  --backend=rust \
  --frontend=nextjs \
  --template=base \
  --auth=email_password \
  --default-lang=en \
  --languages=en,ar

نصيحة — الوضع التفاعلي

تفضّل إعداداً موجّهاً؟ استخدم forge new --interactive للمرور عبر كل خيار مع أوصاف وقيم افتراضية.

ما الذي يتم إنشاؤه

بعد اكتمال الأمر، سيحتوي مجلد مشروعك على:

myapp/
├── apps/
│   ├── api/              # Rust (Axum) backend API
│   ├── web/              # Next.js public website
│   └── admin/            # Next.js admin dashboard
├── infra/
│   ├── docker/           # Docker Compose and Dockerfiles
│   ├── caddy/            # Caddyfile reverse proxy config
│   └── certs/            # SSL certificates (auto-generated)
├── database/
│   ├── migrations/       # Versioned SQL migrations
│   └── seeders/          # Default data (admin user, roles, permissions)
└── forge.yaml            # Project configuration

يقوم FORGE أيضاً بتنفيذ خطوات الإعداد هذه تلقائياً:

1. توليد شهادات SSL باستخدام mkcert لنطاقاتك المحلية
2. إضافة إدخالات المضيف إلى /etc/hosts لـ myapp.test وadmin.myapp.test وapi.myapp.test
3. تثبيت الاعتماديات — يشغّل cargo build وnpm install
4. تشغيل ترحيلات قاعدة البيانات — ينشئ جميع الجداول في PostgreSQL
5. بذر قاعدة البيانات — يدرج مستخدم مدير افتراضي وأدوار وصلاحيات وترجمات

تنبيه — تعديل ملف المضيفين يتطلب صلاحيات مرتفعة

سيطلب FORGE كلمة مرورك (عبر sudo) لإضافة إدخالات إلى /etc/hosts. إذا كنت تفضّل إدارة المضيفين يدوياً، استخدم علامة --no-hosts وأضف الإدخالات بنفسك:

127.0.0.1   myapp.test
127.0.0.1   admin.myapp.test
127.0.0.1   api.myapp.test

تشغيل خادم التطوير

انتقل إلى مشروعك وشغّل جميع الخدمات:

cd myapp
forge serve

هذا الأمر الواحد يشغّل:

الخدمة	الرابط	الوصف
تطبيق الويب	https://myapp.test	موقع Next.js العام
لوحة الإدارة	https://admin.myapp.test	لوحة الإدارة (Next.js)
خادم الواجهة البرمجية	https://api.myapp.test	واجهة Rust البرمجية الخلفية
توثيق الواجهة البرمجية	https://api.myapp.test/docs	توثيق Swagger UI
PostgreSQL	localhost:5432	قاعدة البيانات (عبر Docker)
Redis	localhost:6379	مخزن التخزين المؤقت (عبر Docker)

نصيحة — ما الذي يفعله forge serve خلف الكواليس

يشغّل حاويات Docker لـ PostgreSQL وRedis وCaddy، ثم يطلق خادم Rust للواجهة البرمجية وكلا خادمي تطوير Next.js بالتوازي. يتولى Caddy التوجيه العكسي وإنهاء SSL لجميع النطاقات الثلاثة.

تسجيل الدخول إلى لوحة الإدارة

افتح متصفحك وانتقل إلى:

https://admin.myapp.test

سجّل الدخول ببيانات المدير الافتراضية:

الحقل	القيمة
البريد الإلكتروني	admin@myapp.test
كلمة المرور	admin123

تحذير — غيّر كلمة المرور الافتراضية فوراً

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

بعد تسجيل الدخول، سترى لوحة الإدارة مع:

• لوحة المعلومات — إحصائيات عامة وإجراءات سريعة
• المستخدمون — إنشاء وتعديل وإدارة حسابات المستخدمين
• الأدوار — تعريف الأدوار وتعيين الصلاحيات
• المحتوى — إنشاء وإدارة صفحات المحتوى القابلة للترجمة
• القوائم — بناء قوائم التنقل الديناميكية لتطبيق الويب
• الوسائط — رفع وإدارة الملفات والصور
• الإعدادات — إعدادات التطبيق الشاملة
• سجل التدقيق — تتبع جميع الإجراءات الإدارية

استكشاف تطبيق الويب

افتح الموقع العام على:

https://myapp.test

يتضمن تطبيق الويب:

• الصفحة الرئيسية بمحتوى ديناميكي مسحوب من نظام إدارة المحتوى
• تسجيل المستخدمين وتسجيل الدخول
• إدارة الملف الشخصي للمستخدم (مسار محمي)
• مبدّل اللغات مع دعم RTL (إذا تم إعداد لغات متعددة)
• تنقل ديناميكي مدفوع بالقوائم المُنشأة في لوحة الإدارة
• صفحات المحتوى يمكن الوصول إليها بالمسار (مثلاً https://myapp.test/about)

استكشاف الواجهة البرمجية

يوفر خادم الواجهة البرمجية واجهة REST كاملة. افتح التوثيق التفاعلي على:

https://api.myapp.test/docs

يمكنك أيضاً اختبار نقاط النهاية مباشرة:

Login

curl -X POST https://api.myapp.test/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@myapp.test",
    "password": "admin123"
  }'

List Users (authenticated)

# Use the token from the login response
curl https://api.myapp.test/api/v1/admin/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Public Content

curl https://api.myapp.test/api/v1/contents/home

صيغة استجابة الواجهة البرمجية موحدة عبر جميع نقاط النهاية:

{
  "success": true,
  "message": "Users retrieved successfully",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "per_page": 15,
      "total": 42,
      "total_pages": 3
    }
  }
}

أوامر المشروع

إليك الأوامر الأكثر استخداماً أثناء التطوير:

# Start all services
forge serve

# Run database migrations
forge migrate

# Reset database and re-run all migrations + seeders
forge migrate:fresh

# Seed the database
forge seed:run

# Generate a new model with migration, handler, and service
forge make:model Post

# Add a new language
forge lang:add fr

# View container logs
forge docker:logs

# Stop all services
forge docker:down

ماذا بعد؟

الآن بعد أن أصبح تطبيقك يعمل، استكشف الأدلة المتعمقة:

• الإعدادات — خصّص ملف forge.yaml حسب احتياجات مشروعك
• بنية المجلدات — افهم كيف يُنظّم الكود المُنشأ
• التصميم بالعقود أولاً — تعرّف على كيفية تمكين معمارية FORGE من التوسع
• نظرة عامة على الخلفية — تعمّق في طبقة واجهة Rust البرمجية
• نظرة عامة على الواجهة الأمامية — استكشف تطبيقات Next.js
• إدارة المحتوى — أنشئ وأدِر صفحات نظام إدارة المحتوى