الإعدادات

يُدار كل مشروع FORGE بملف إعدادات واحد — forge.yaml — يقع في جذر مشروعك. يُحدد هذا الملف اسم التطبيق، واختيارات التقنيات، وطريقة المصادقة، واللغات المدعومة، ومزودي الخدمات، وتوجيه النطاقات. يقرأ FORGE هذا الملف أثناء توليد الأكواد والترحيلات والنشر.

مرجع forge.yaml

إليك ملف forge.yaml كامل بجميع الحقول المتاحة:

# =============================================================================
# FORGE Project Configuration
# =============================================================================

# Project identity
name: myapp                     # Application name (lowercase, no spaces)
version: 1.0.0                  # Your application version

# Technology stack
backend: rust                   # Backend framework: rust | laravel | fastapi | node
frontend: nextjs                # Frontend framework: nextjs | nuxtjs | angular | vanilla
template: base                  # Template: base | crm | helpdesk | invoicing

# Authentication
auth:
  method: email_password        # email_password | mobile_otp | mobile_password
  jwt:
    access_ttl: 15m             # Access token lifetime
    refresh_ttl: 7d             # Refresh token lifetime
  password:
    min_length: 8               # Minimum password length
    require_uppercase: true     # Require at least one uppercase letter
    require_number: true        # Require at least one digit

# Languages
languages:
  - code: en
    name: English
    direction: ltr
  - code: ar
    name: العربية
    direction: rtl
default_language: en            # Must match one of the language codes above

# Provider configuration
providers:
  sms:
    driver: twilio              # twilio | vonage | unifonic | mock
  email:
    driver: smtp                # smtp | mailgun | sendgrid | ses | mock
  storage:
    driver: local               # local | s3 | minio | gcs
  payments:
    driver: stripe              # stripe | paddle | moyasar | mock

# Domain routing
domains:
  web: myapp.test               # Public website domain
  admin: admin.myapp.test       # Admin dashboard domain
  api: api.myapp.test           # API server domain

أقسام الإعدادات

هوية المشروع

الحقل	النوع	مطلوب	الوصف
name	نص	نعم	اسم المشروع المُستخدم للمجلدات وأسماء قواعد البيانات وبادئات النطاقات. يجب أن يكون بأحرف صغيرة بدون مسافات.
version	نص	لا	إصدار تطبيقك. يتبع نظام الإصدارات الدلالي. القيمة الافتراضية 1.0.0.

تنبيه — حقل name لا يمكن تغييره بعد الإنشاء

تغيير اسم المشروع بعد الإنشاء لن يعيد تسمية قواعد البيانات أو المجلدات أو إدخالات النطاقات. اختر اسمك بعناية قبل تشغيل forge new.

حزمة التقنيات

الحقل	النوع	الافتراضي	الخيارات
backend	نص	rust	rust، laravel، fastapi، node
frontend	نص	nextjs	nextjs، nuxtjs، angular، vanilla
template	نص	base	base، crm، helpdesk، invoicing

يُحدد حقلا backend وfrontend مجلد القوالب الذي يستخدمه FORGE أثناء توليد الأكواد. يُحدد حقل template وحدات الميزات المضمّنة.

المصادقة

يتحكم حقل auth.method في تدفق المصادقة المُنشأ:

الطريقة	الوصف	يتطلب
email_password	تسجيل دخول تقليدي بالبريد الإلكتروني وكلمة المرور مع التحقق من البريد	مزود بريد إلكتروني
mobile_otp	تسجيل دخول برقم الجوال مع كلمة مرور لمرة واحدة عبر رسالة نصية	مزود رسائل نصية
mobile_password	تسجيل دخول برقم الجوال وكلمة المرور مع التحقق عبر رسالة نصية	مزود رسائل نصية

نصيحة — تغيير طريقة المصادقة بعد الإنشاء

يمكنك تغيير طريقة المصادقة بتحديث forge.yaml وتشغيل forge upgrade. سيعيد FORGE توليد معالجات المصادقة المتأثرة ونماذج الواجهة الأمامية وترحيلات قاعدة البيانات.

اللغات

تُحدد مصفوفة languages جميع اللغات المدعومة. يتطلب كل إدخال:

الحقل	النوع	الوصف
code	نص	رمز اللغة بمعيار ISO 639-1 (مثل en، ar، fr)
name	نص	اسم اللغة المقروء
direction	نص	اتجاه النص: ltr أو rtl

يجب أن يطابق حقل default_language أحد رموز اللغات المُعرّفة. يُحدد:

• اللغة الافتراضية للمستخدمين الجدد
• اللغة الاحتياطية عند فقدان ترجمة
• اللغة المُستخدمة أثناء بذر قاعدة البيانات

languages:
  - code: en
    name: English
    direction: ltr
  - code: ar
    name: العربية
    direction: rtl
  - code: fr
    name: Français
    direction: ltr
default_language: en

نصيحة — إضافة لغات بعد إنشاء المشروع

استخدم سطر الأوامر لإضافة لغات ديناميكياً:

forge lang:add fr --name="Français" --direction=ltr

هذا يُحدّث forge.yaml، ويُنشئ بذور الترجمة، ويضيف اللغة إلى مبدّل اللغات في الواجهة الأمامية.

مزودو الخدمات

مزودو الخدمات هم عمليات تكامل قابلة للتوصيل. لكل نوع مزود حقل driver يُحدد التنفيذ:

providers:
  sms:
    driver: twilio
  email:
    driver: smtp
  storage:
    driver: local
  payments:
    driver: stripe

المشغّلات المتاحة لكل نوع مزود:

المزود	المشغّلات	الافتراضي
الرسائل النصية	twilio، vonage، unifonic، mock	mock
البريد الإلكتروني	smtp، mailgun، sendgrid، ses، mock	mock
التخزين	local، s3، minio، gcs	local
المدفوعات	stripe، paddle، moyasar، mock	mock

معلومة — بيانات اعتماد المزودين تُخزّن في متغيرات البيئة

يُحدد ملف forge.yaml فقط المشغّل المُستخدم. مفاتيح الواجهة البرمجية والأسرار وتفاصيل الاتصال تُخزّن في ملفات .env. انظر قسم متغيرات البيئة أدناه.

توجيه النطاقات

يربط قسم domains كل تطبيق بنطاق التطوير المحلي الخاص به:

domains:
  web: myapp.test               # → apps/web (Next.js)
  admin: admin.myapp.test       # → apps/admin (Next.js)
  api: api.myapp.test           # → apps/api (Rust)

يستخدم Caddy هذه النطاقات لتوجيه طلبات HTTPS الواردة إلى خادم التطبيق الصحيح. يُهيّئ FORGE تلقائياً ملف Caddyfile وإدخالات /etc/hosts أثناء إنشاء المشروع.

متغيرات البيئة

يحترم FORGE عدة متغيرات بيئة تتحكم في سلوك أداة سطر الأوامر وإعدادات المشروع.

متغيرات بيئة أداة سطر الأوامر

المتغير	الافتراضي	الوصف
FORGE_PATH	~/.forge	المجلد الذي يخزن فيه FORGE الإعدادات العامة والقوالب
FORGE_TEMPLATES_PATH	~/.forge/templates	تجاوز مسار البحث الافتراضي عن القوالب
FORGE_NO_COLOR	false	تعطيل الألوان في مخرجات الطرفية
FORGE_VERBOSE	false	تفعيل التسجيل المفصّل لأغراض التصحيح
FORGE_ENCRYPTION_KEY	—	المفتاح المُستخدم لتشفير القيم الحساسة في forge.yaml

متغيرات بيئة التطبيق

يتضمن كل تطبيق مُنشأ ملفي .env و.env.example. المتغيرات الرئيسية تشمل:

API (.env)

# Database
DATABASE_URL=postgresql://forge:forge@localhost:5432/myapp
DATABASE_MAX_CONNECTIONS=10

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your-secret-key-here
JWT_ACCESS_TTL=900          # 15 minutes in seconds
JWT_REFRESH_TTL=604800      # 7 days in seconds

# Storage
STORAGE_DRIVER=local
STORAGE_PATH=./uploads
# S3_BUCKET=my-bucket
# S3_REGION=us-east-1
# S3_ACCESS_KEY=...
# S3_SECRET_KEY=...

# SMS (if using SMS auth)
# SMS_DRIVER=twilio
# TWILIO_ACCOUNT_SID=...
# TWILIO_AUTH_TOKEN=...
# TWILIO_FROM_NUMBER=...

# Email
# EMAIL_DRIVER=smtp
# SMTP_HOST=smtp.mailtrap.io
# SMTP_PORT=587
# SMTP_USERNAME=...
# SMTP_PASSWORD=...
# EMAIL_FROM=noreply@myapp.test

# Encryption
ENCRYPTION_KEY=your-encryption-key

Web & Admin (.env.local)

# API connection
NEXT_PUBLIC_API_URL=https://api.myapp.test
NEXT_PUBLIC_APP_NAME=MyApp
NEXT_PUBLIC_DEFAULT_LOCALE=en

# Internal API URL (server-side, bypasses Caddy)
API_INTERNAL_URL=http://localhost:3000

تحذير — لا ترفع ملفات .env إلى نظام التحكم بالإصدارات أبداً

تحتوي ملفات .env على أسرار (مفاتيح JWT، ورموز واجهات برمجية، وبيانات اعتماد قاعدة البيانات). يُنشئ FORGE ملف .gitignore يستثني هذه الملفات. استخدم دائماً .env.example كمرجع يُرفع إلى المستودع.

متغير FORGE_ENCRYPTION_KEY

يمكن لـ FORGE تشفير بيانات اعتماد المزودين الحساسة المخزّنة في forge.yaml. عند تعيينه، يتم فك تشفير القيم المميزة بالبادئة encrypted: أثناء التشغيل:

providers:
  sms:
    driver: twilio
    account_sid: "encrypted:abc123..."   # يُفك تشفيره باستخدام FORGE_ENCRYPTION_KEY

توليد مفتاح تشفير جديد:

forge secrets:generate-key

تشفير قيمة:

forge secrets:encrypt "my-secret-value"

فك تشفير قيمة:

forge secrets:decrypt "enc:v1:abc123..."

الخطوات التالية

• بنية المجلدات — افهم تخطيط المشروع المُنشأ
• البداية السريعة — أنشئ وشغّل أول تطبيق
• نمط مزودي الخدمات — تعرّف على كيفية إعداد وتبديل مزودي الخدمات