القالب الأساسي

القالب الأساسي (base) هو نقطة البداية الافتراضية لجميع مشاريع FORGE. يوفر البنية التحتية الأساسية للتطبيقات الحديثة.

نظرة عامة

┌─────────────────────────────────────────────────────────────────┐
│                        القالب الأساسي                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  المصادقة   │  │  الصلاحيات  │  │ المستخدمون  │             │
│  │ JWT + OAuth │  │    RBAC     │  │ والأدوار    │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   لوحة     │  │  تطبيق     │  │  توثيق     │             │
│  │  التحكم    │  │   الويب    │  │    API     │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   إدارة    │  │  الوسائط   │  │  سجل       │             │
│  │  المحتوى   │  │  المتعددة  │  │  التدقيق   │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

الميزات المضمنة

1. المصادقة (Authentication)

الميزة	الوصف
JWT	مصادقة بالرموز مع تجديد تلقائي
OAuth 2.0	تسجيل الدخول عبر Google, Apple, GitHub
Magic Link	تسجيل الدخول بدون كلمة مرور
2FA	المصادقة الثنائية (TOTP)
تحقق البريد	تأكيد البريد الإلكتروني
إعادة تعيين كلمة المرور	استعادة الحساب

2. الصلاحيات (Authorization)

┌─────────────────────────────────────────────────────────────────┐
│                      نظام RBAC                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  المستخدم ──────▶ الأدوار ──────▶ الصلاحيات                    │
│     │              │                │                           │
│     │         ┌────┴────┐      ┌────┴────┐                     │
│     │         │  admin  │      │ users.* │                     │
│     │         │  editor │      │ posts.* │                     │
│     │         │  viewer │      │ read    │                     │
│     │         └─────────┘      └─────────┘                     │
│     │                                                           │
│     └──────▶ صلاحيات مباشرة (اختياري)                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

الصلاحيات الافتراضية:

permissions:
  # Users
  - users.list
  - users.view
  - users.create
  - users.update
  - users.delete

  # Roles
  - roles.list
  - roles.view
  - roles.create
  - roles.update
  - roles.delete

  # Settings
  - settings.view
  - settings.update

  # Audit log
  - audit.list
  - audit.view

3. إدارة المستخدمين

حقول المستخدم:

الحقل	النوع	الوصف
id	UUID	المعرف الفريد
email	String	البريد الإلكتروني (فريد)
password_hash	String	كلمة المرور المشفرة
first_name	String	الاسم الأول
last_name	String	الاسم الأخير
phone	String?	رقم الهاتف
avatar_url	String?	صورة الملف الشخصي
email_verified_at	DateTime?	تاريخ تأكيد البريد
is_active	Boolean	الحالة النشطة
last_login_at	DateTime?	آخر تسجيل دخول
created_at	DateTime	تاريخ الإنشاء
updated_at	DateTime	تاريخ التحديث

4. نظام إدارة المحتوى (CMS)

┌─────────────────────────────────────────────────────────────────┐
│                        نظام CMS                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                     الصفحات                               │  │
│  │  - عنوان متعدد اللغات                                    │  │
│  │  - محتوى HTML/Markdown                                   │  │
│  │  - SEO metadata                                          │  │
│  │  - حالة النشر                                            │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                     القوائم                               │  │
│  │  - قوائم متداخلة                                         │  │
│  │  - روابط داخلية/خارجية                                   │  │
│  │  - ترتيب قابل للسحب                                      │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    الوسائط                               │  │
│  │  - رفع الصور والملفات                                    │  │
│  │  - تحويل الأحجام التلقائي                                │  │
│  │  - تخزين S3/Local                                        │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5. سجل التدقيق (Audit Log)

يسجل جميع العمليات الحساسة:

// Audit log example
AuditLog {
    id: Uuid,
    user_id: Option<Uuid>,        // Executing user
    action: String,               // "users.create", "roles.update"
    entity_type: String,          // "User", "Role"
    entity_id: Option<Uuid>,      // Entity ID
    old_values: Option<Json>,     // Previous values
    new_values: Option<Json>,     // New values
    ip_address: Option<String>,   // IP address
    user_agent: Option<String>,   // Browser
    created_at: DateTime,
}

ترحيلات قاعدة البيانات

القالب الأساسي يتضمن 17 ترحيل لقاعدة البيانات:

migrations/
├── 001_create_users.sql
├── 002_create_roles.sql
├── 003_create_permissions.sql
├── 004_create_role_permissions.sql
├── 005_create_user_roles.sql
├── 006_create_user_permissions.sql
├── 007_create_sessions.sql
├── 008_create_password_resets.sql
├── 009_create_email_verifications.sql
├── 010_create_oauth_providers.sql
├── 011_create_two_factor_auth.sql
├── 012_create_audit_logs.sql
├── 013_create_settings.sql
├── 014_create_pages.sql
├── 015_create_menus.sql
├── 016_create_menu_items.sql
└── 017_create_media.sql

نقاط النهاية للـ API

المصادقة

الطريقة	المسار	الوصف
POST	/api/auth/register	تسجيل مستخدم جديد
POST	/api/auth/login	تسجيل الدخول
POST	/api/auth/logout	تسجيل الخروج
POST	/api/auth/refresh	تجديد الرمز
POST	/api/auth/forgot-password	طلب إعادة تعيين كلمة المرور
POST	/api/auth/reset-password	إعادة تعيين كلمة المرور
POST	/api/auth/verify-email	تأكيد البريد الإلكتروني
GET	/api/auth/me	الحصول على المستخدم الحالي

OAuth

الطريقة	المسار	الوصف
GET	/api/auth/oauth/{provider}	بدء تدفق OAuth
GET	/api/auth/oauth/{provider}/callback	استقبال الرد

المستخدمون

الطريقة	المسار	الوصف
GET	/api/admin/users	قائمة المستخدمين
GET	/api/admin/users/{id}	تفاصيل المستخدم
POST	/api/admin/users	إنشاء مستخدم
PUT	/api/admin/users/{id}	تحديث مستخدم
DELETE	/api/admin/users/{id}	حذف مستخدم

الأدوار

الطريقة	المسار	الوصف
GET	/api/admin/roles	قائمة الأدوار
GET	/api/admin/roles/{id}	تفاصيل الدور
POST	/api/admin/roles	إنشاء دور
PUT	/api/admin/roles/{id}	تحديث دور
DELETE	/api/admin/roles/{id}	حذف دور

الصفحات

الطريقة	المسار	الوصف
GET	/api/admin/pages	قائمة الصفحات
GET	/api/admin/pages/{id}	تفاصيل الصفحة
POST	/api/admin/pages	إنشاء صفحة
PUT	/api/admin/pages/{id}	تحديث صفحة
DELETE	/api/admin/pages/{id}	حذف صفحة
GET	/api/pages/{slug}	الصفحة العامة

الوسائط

الطريقة	المسار	الوصف
GET	/api/admin/media	قائمة الوسائط
POST	/api/admin/media	رفع ملف
DELETE	/api/admin/media/{id}	حذف ملف

صفحات لوحة التحكم

admin/
├── dashboard/              # لوحة المعلومات الرئيسية
├── users/
│   ├── page.tsx           # قائمة المستخدمين
│   ├── [id]/
│   │   └── page.tsx       # تفاصيل المستخدم
│   └── new/
│       └── page.tsx       # إنشاء مستخدم
├── roles/
│   ├── page.tsx           # قائمة الأدوار
│   ├── [id]/
│   │   └── page.tsx       # تفاصيل الدور
│   └── new/
│       └── page.tsx       # إنشاء دور
├── pages/
│   ├── page.tsx           # قائمة الصفحات
│   ├── [id]/
│   │   └── page.tsx       # تحرير الصفحة
│   └── new/
│       └── page.tsx       # إنشاء صفحة
├── menus/
│   ├── page.tsx           # قائمة القوائم
│   └── [id]/
│       └── page.tsx       # تحرير القائمة
├── media/
│   └── page.tsx           # مكتبة الوسائط
├── settings/
│   └── page.tsx           # إعدادات النظام
└── audit/
    └── page.tsx           # سجل التدقيق

صفحات تطبيق الويب

web/
├── page.tsx               # الصفحة الرئيسية
├── login/
│   └── page.tsx          # تسجيل الدخول
├── register/
│   └── page.tsx          # التسجيل
├── forgot-password/
│   └── page.tsx          # نسيت كلمة المرور
├── reset-password/
│   └── page.tsx          # إعادة تعيين كلمة المرور
├── verify-email/
│   └── page.tsx          # تأكيد البريد
├── profile/
│   └── page.tsx          # الملف الشخصي
└── [slug]/
    └── page.tsx          # الصفحات الديناميكية

البيانات الأولية (Seeders)

المستخدم الإداري الافتراضي

-- seeders/001_admin_user.sql
INSERT INTO users (email, password_hash, first_name, last_name, email_verified_at)
VALUES (
    'admin@example.com',
    '$argon2id$v=19$m=65536,t=3,p=4$...',  -- password: 'password'
    'Admin',
    'User',
    NOW()
);

الأدوار الافتراضية

-- seeders/002_default_roles.sql
INSERT INTO roles (name, slug, description) VALUES
    ('Administrator', 'admin', 'Full system access'),
    ('Editor', 'editor', 'Content management access'),
    ('Viewer', 'viewer', 'Read-only access');

الصلاحيات الافتراضية

-- seeders/003_default_permissions.sql
INSERT INTO permissions (name, slug, group_name) VALUES
    ('List Users', 'users.list', 'Users'),
    ('View User', 'users.view', 'Users'),
    ('Create User', 'users.create', 'Users'),
    ('Update User', 'users.update', 'Users'),
    ('Delete User', 'users.delete', 'Users'),
    -- ... المزيد من الصلاحيات

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

# .env

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/app

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRATION=3600
JWT_REFRESH_EXPIRATION=604800

# OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
APPLE_CLIENT_ID=
APPLE_CLIENT_SECRET=

# Email
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
MAIL_FROM=noreply@example.com

# Storage
STORAGE_DRIVER=local  # or s3
S3_BUCKET=
S3_REGION=
S3_ACCESS_KEY=
S3_SECRET_KEY=

# Application
APP_URL=http://localhost:3000
APP_NAME="My App"

التخصيص

إضافة حقول للمستخدم

# contracts/models/user.yaml
model: User
extends: base.User  # يرث من القالب الأساسي
fields:
  - name: company
    type: string
    nullable: true
  - name: job_title
    type: string
    nullable: true

إضافة صلاحيات

# contracts/permissions.yaml
permissions:
  - name: reports.view
    description: View reports
  - name: reports.export
    description: Export reports

تخصيص الصفحات

# contracts/pages.yaml
pages:
  admin:
    - path: /reports
      component: ReportsPage
      permissions: [reports.view]

الأوامر

# Create project with base template
forge new my-project

# Run migrations
forge db migrate

# Run seeders
forge db seed

# Generate JWT secret
forge generate jwt-secret

# Create admin user
forge admin create admin@example.com

المزيد من المعلومات

• نظام القوالب - كيف تعمل القوالب
• القوالب المتوفرة - قوالب إضافية
• إنشاء قوالب مخصصة - بناء قالبك الخاص