انتقل إلى المحتوى الرئيسي

الفصل 1: البدء مع GitHub Codespaces

الأهداف​

  • إعداد بيئة تطوير سحابية باستخدام GitHub Codespaces
  • تشغيل مشروع e-contact-backend
  • فهم هيكل المشروع
  • إجراء الاختبارات الأولى لـ API

🌐 ما هو GitHub Codespaces؟​

GitHub Codespaces هو بيئة تطوير سحابية تتيح لك:

  • التطوير مباشرة من المتصفح
  • الحصول على بيئة مُعدة مسبقًا
  • تجنب مشاكل التثبيت المحلي
  • التعاون بسهولة
الميزة الرئيسية

لا حاجة لتثبيت Java أو Maven أو PostgreSQL أو أي أداة أخرى على جهازك!

المتطلبات الأساسية​

  • حساب GitHub (مجاني)
  • متصفح ويب حديث

خطوات الإعداد​

الخطوة 1: الوصول إلى المستودع​

  1. افتح المستودع الرئيسي:
المستودع

URL: https://github.com/hrhouma1/inskillflow-docs-formation-spring-boot-projet-e-contact-backend

الخطوة 2: إنشاء Codespace​

  1. انقر على الزر الأخضر Code
  2. اختر علامة التبويب Codespaces
  3. انقر على Create codespace on main
┌─────────────────────────────────────────┐
│  Code ▼                                 │
├─────────────────────────────────────────┤
│  Local    │  Codespaces               │
│           │                            │
│           │  ┌──────────────────────┐  │
│           │  │ + Create codespace   │  │
│           │  │   on main            │  │
│           │  └──────────────────────┘  │
└─────────────────────────────────────────┘

الخطوة 3: انتظار التهيئة​

سيقوم Codespace بـ:

  1. إنشاء آلة افتراضية
  2. استنساخ المستودع
  3. تثبيت التبعيات
  4. فتح VS Code في المتصفح

⏱️ الوقت المقدر: 2-3 دقائق

الخطوة 4: التحقق من البيئة​

بمجرد أن يكون Codespace جاهزًا، افتح الطرفية وتحقق:

# التحقق من Java
java -version
# المتوقع: openjdk 17.x.x أو أعلى

# التحقق من Maven
./mvnw -version
# المتوقع: Apache Maven 3.x.x

🏃 تشغيل التطبيق​

أمر التشغيل​

في طرفية Codespace:

./mvnw spring-boot:run

المخرجات المتوقعة​

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.2.x)

...
Started EContactApplication in X.XXX seconds

الوصول إلى التطبيق​

عند بدء التطبيق، يعرض Codespaces إشعارًا:

┌──────────────────────────────────────────────────┐
│  Your application running on port 8080 is       │
│  available.                                      │
│                                                  │
│  [Open in Browser]  [Make Public]               │
└──────────────────────────────────────────────────┘

انقر على Open in Browser للوصول إلى الـ API.

🔍 استكشاف هيكل المشروع​

inskillflow-docs-formation-spring-boot-projet-e-contact-backend/
│
├── 📁 src/main/java/com/example/econtact/
│   │
│   ├── 📄 EContactApplication.java      # نقطة الدخول
│   │
│   ├── 📁 config/
│   │   ├── SecurityConfig.java          # تكوين الأمان
│   │   └── CorsConfig.java              # تكوين CORS
│   │
│   ├── 📁 controller/
│   │   ├── ContactController.java       # نقطة النهاية العامة /api/contact
│   │   ├── AuthController.java          # نقاط نهاية المصادقة
│   │   └── AdminController.java         # نقاط نهاية الإدارة المحمية
│   │
│   ├── 📁 model/
│   │   ├── Lead.java                    # كيان الاتصال/العميل المحتمل
│   │   ├── User.java                    # كيان المستخدم
│   │   └── enums/                       # RequestType, LeadStatus, Role
│   │
│   ├── 📁 dto/
│   │   ├── ContactRequest.java          # DTO نموذج الاتصال
│   │   ├── LoginRequest.java            # DTO المصادقة
│   │   └── LeadResponse.java            # DTO استجابة العميل المحتمل
│   │
│   ├── 📁 repository/
│   │   ├── LeadRepository.java
│   │   └── UserRepository.java
│   │
│   ├── 📁 service/
│   │   ├── LeadService.java
│   │   ├── UserService.java
│   │   └── EmailService.java
│   │
│   └── 📁 security/
│       ├── JwtService.java              # توليد/تحقق JWT
│       ├── JwtAuthenticationFilter.java # فلتر المصادقة
│       └── UserDetailsServiceImpl.java
│
├── 📁 src/main/resources/
│   └── application.yml                   # التكوين
│
├── 📁 frontend/                          # واجهة اختبار
│
├── 📁 troubleshooting/                   # أدلة استكشاف الأخطاء
│
└── 📁 cours/                             # الوثائق والدروس

الاختبارات الأولى لـ API​

الاختبار 1: التحقق من أن الـ API متاح​

curl http://localhost:8080/api/health

الاستجابة المتوقعة:

{"status": "UP"}

الاختبار 2: إرسال اتصال (نقطة نهاية عامة)​

curl -X POST http://localhost:8080/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jean Dupont",
    "email": "jean.dupont@example.com",
    "company": "Ma Société",
    "phone": "514-555-1234",
    "requestType": "INFO",
    "message": "Je voudrais plus d'\''informations sur vos services."
  }'

الاستجابة المتوقعة:

{
  "id": 1,
  "fullName": "Jean Dupont",
  "email": "jean.dupont@example.com",
  "status": "NEW",
  "createdAt": "2025-02-02T12:00:00"
}

الاختبار 3: الوصول إلى نقطة نهاية محمية (بدون رمز)​

curl http://localhost:8080/api/admin/leads

الاستجابة المتوقعة:

{
  "status": 401,
  "error": "Unauthorized"
}

⚠️ المشاكل الشائعة​

المنفذ 8080 مستخدم بالفعل​

# تحديد العملية
lsof -i :8080

# أو استخدام منفذ آخر
./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

خطأ في قاعدة البيانات​

تحقق من أن تكوين H2 نشط للتطوير في application.yml.

انقطاع الاتصال بـ Codespace​

الـ Codespaces المجانية لها حد زمني. أعد التشغيل إذا لزم الأمر.

موارد استكشاف الأخطاء​

لمزيد من التفاصيل حول خطوات التنفيذ واستكشاف الأخطاء:

أدلة مفصلة

📖 دليل استكشاف الأخطاء الكامل

قائمة التحقق من التحقق​

قبل الانتقال إلى الفصل التالي، تحقق من أنك قد:

  • أنشأت Codespace بنجاح
  • شغلت تطبيق Spring Boot
  • اختبرت نقطة النهاية /api/contact
  • فهمت هيكل المشروع

⏭️ الخطوة التالية​

الفصل 2: استكشاف الأخطاء →

العودة إلى فهرس الوحدة