المشروع E: نموذج الاتصال

وضعية

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

ما يجب عليك إنشاؤه

واجهة برمجة تطبيقات REST باستخدام Spring Boot مع:

نموذج اتصال عام - يمكن لأي شخص تقديم معلومات الاتصال الخاصة به
لوحة إدارة محمية - لعرض وإدارة جهات الاتصال المستلمة
نظام البريد الإلكتروني - إشعارات تلقائية

التدفق

نظرة عامة على النموذج (الواجهة الأمامية)

إليك كيف يجب أن يبدو النموذج على صفحة الويب:

┌─────────────────────────────────────────────────────────┐
│                    اتصل بنا                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  الاسم الكامل *                   الشركة                 │
│  ┌─────────────────────────┐    ┌─────────────────────┐│
│  │ Your name               │    │ Your company name   ││
│  └─────────────────────────┘    └─────────────────────┘│
│                                                         │
│  البريد الإلكتروني *              الهاتف                 │
│  ┌─────────────────────────┐    ┌─────────────────────┐│
│  │ your@company.com        │    │ Your phone number   ││
│  └─────────────────────────┘    └─────────────────────┘│
│                                                         │
│  نوع الطلب *                                           │
│  ┌─────────────────────────────────────────────────┬──┐│
│  │ اختر نوع الطلب                                  │ v││
│  ├─────────────────────────────────────────────────┴──┤│
│  │ > اختر نوع الطلب                                   ││
│  │   طلب معلومات                                      ││
│  │   طلب عرض سعر                                      ││
│  │   دعم فني                                          ││
│  │   شراكة                                            ││
│  │   أخرى                                             ││
│  └────────────────────────────────────────────────────┘│
│                                                         │
│  الرسالة *                                             │
│  ┌────────────────────────────────────────────────────┐│
│  │ صف طلبك، ميزانيتك،                                ││
│  │ ومواعيدك...                                       ││
│  │                                                    ││
│  │                                                    ││
│  └────────────────────────────────────────────────────┘│
│                                                         │
│            ┌─────────────────────┐                      │
│            │      إرسال           │                      │
│            └─────────────────────┘                      │
│                                                         │
│  * الحقول المطلوبة                                      │
└─────────────────────────────────────────────────────────┘

حقول النموذج:

الحقل	نوع HTML	التحقق
الاسم الكامل	`<input type="text">`	مطلوب
الشركة	`<input type="text">`	اختياري
البريد الإلكتروني	`<input type="email">`	مطلوب، تنسيق البريد الإلكتروني
الهاتف	`<input type="tel">`	اختياري
نوع الطلب	`<select>`	مطلوب
الرسالة	`<textarea>`	مطلوب، 10 أحرف كحد أدنى

خيارات حقل "نوع الطلب":

القيمة	العرض
`INFO`	طلب معلومات
`QUOTE`	طلب عرض سعر
`SUPPORT`	دعم فني
`PARTNERSHIP`	شراكة
`OTHER`	أخرى

نقاط النهاية التي يجب إنشاؤها

نقطة نهاية عامة (بدون مصادقة)

الطريقة	URL	الوصف
POST	`/api/contact`	إرسال النموذج

بيانات النموذج:

fullName (مطلوب)
company (اختياري)
email (مطلوب)
phone (اختياري)
requestType (مطلوب) - قائمة اختيار
message (مطلوب)

نقاط نهاية الإدارة (مع JWT)

الطريقة	URL	الوصف
GET	`/api/admin/leads`	قائمة جهات الاتصال
GET	`/api/admin/leads/\{id\}`	تفاصيل جهة اتصال
PUT	`/api/admin/leads/\{id\}/status`	تغيير الحالة
DELETE	`/api/admin/leads/\{id\}`	حذف

مخطط الفئات

إليك اقتراح للهيكل. يمكنك التعديل أو الإضافة أو التبسيط حسب الحاجة.

حرية التصميم

هذا المخطط هو اقتراح. أنت حر في:

إضافة فئات (مثل: LeadNote للملاحظات الداخلية)
إضافة حقول (مثل: company, source)
تعديل العلاقات
التبسيط إذا وجدت أنه معقد جدًا

المهم أن يكون حلك يعمل و منظم بشكل جيد.

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

قم بإنشاء هذه الجداول في PostgreSQL:

جدول leads

id (المفتاح الأساسي)
full_name
company
email (فريد)
phone
request_type (INFO, QUOTE, SUPPORT, PARTNERSHIP, OTHER)
message
status (NEW, CONTACTED, CONVERTED, LOST)
created_at

جدول users (للإدارة)

id
email
password
role

رسائل البريد الإلكتروني التي يجب إرسالها

عندما يقوم شخص ما بإرسال النموذج:
- بريد إلكتروني للإدارة: "تم استلام جهة اتصال جديدة"
- بريد إلكتروني للزائر: "شكرًا، لقد استلمنا رسالتك"
استخدام @Async لعدم حجب الطلب

التكوين

# application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/contactdb
    username: postgres
    password: postgres
  
  mail:
    host: localhost
    port: 1025  # MailHog للاختبارات

لاختبار رسائل البريد الإلكتروني محليًا:

docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

عرض رسائل البريد الإلكتروني على http://localhost:8025

الاختبارات التي يجب كتابتها

POST /api/contact مع بيانات صالحة → يعيد 200
POST /api/contact مع بريد إلكتروني غير صالح → يعيد 400
GET /api/admin/leads بدون رمز → يعيد 401
GET /api/admin/leads مع رمز → يعيد القائمة

التقييم

المعيار	النقاط
نقطة النهاية POST /api/contact تعمل	20
البيانات محفوظة في PostgreSQL	20
رسائل البريد الإلكتروني مرسلة	15
نقاط نهاية الإدارة محمية بواسطة JWT	20
الاختبارات	15
كود نظيف	10
المجموع	100

للبدء

إنشاء المشروع على start.spring.io مع:
- Spring Web
- Spring Data JPA
- Spring Security
- Spring Mail
- Validation
- PostgreSQL Driver
- Lombok
إنشاء الكيان Lead
إنشاء LeadRepository
إنشاء ContactController مع POST /api/contact
اختبار باستخدام curl أو Postman

التسليمات

الكود على GitHub
README مع التعليمات
مجموعة Postman للاختبار

العودة إلى المشروع النهائي

وضعية​

ما يجب عليك إنشاؤه​

التدفق​

نظرة عامة على النموذج (الواجهة الأمامية)​

نقاط النهاية التي يجب إنشاؤها​

نقطة نهاية عامة (بدون مصادقة)​

نقاط نهاية الإدارة (مع JWT)​

مخطط الفئات​

قاعدة البيانات​

رسائل البريد الإلكتروني التي يجب إرسالها​

التكوين​

الاختبارات التي يجب كتابتها​

التقييم​

للبدء​

التسليمات​