المشروع ج: نظام الحجز

الوصف

تطوير API RESTful لنظام حجز (فنادق، مطاعم، قاعات مؤتمرات، أو فعاليات) يسمح للمستخدمين بالبحث والحجز وإدارة حجوزاتهم.

الميزات المطلوبة

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

POST   /api/auth/register     - تسجيل
POST   /api/auth/login        - تسجيل الدخول (يعيد JWT)
GET    /api/users/me          - ملف المستخدم
PUT    /api/users/me          - تعديل الملف

كيان المستخدم:

id، email، password، firstName، lastName، phone
role (CUSTOMER، OWNER، ADMIN)
createdAt

2. إدارة الموارد

GET    /api/resources             - قائمة الموارد (التصفح، الفلاتر)
GET    /api/resources/{id}        - تفاصيل المورد
GET    /api/resources/search      - بحث متقدم
POST   /api/resources             - إنشاء مورد (OWNER/ADMIN)
PUT    /api/resources/{id}        - تعديل مورد
DELETE /api/resources/{id}        - حذف مورد
GET    /api/owner/resources       - مواردي (OWNER)

كيان المورد:

id، name، description، type
location (address، city، country)
capacity، pricePerHour/pricePerNight
amenities (List)، images
owner (User)، active
createdAt

3. التوافر

GET    /api/resources/{id}/availability     - التوافر
POST   /api/resources/{id}/availability     - تحديد التوافر (OWNER)
PUT    /api/availability/{id}               - تعديل
DELETE /api/availability/{id}               - حذف
GET    /api/resources/{id}/calendar         - تقويم الشهر

كيان التوافر:

id، resource، dayOfWeek أو specificDate
startTime، endTime
available (boolean)

4. الحجوزات

POST   /api/reservations              - إنشاء حجز
GET    /api/reservations              - حجوزاتي
GET    /api/reservations/{id}         - تفاصيل الحجز
PUT    /api/reservations/{id}/cancel  - إلغاء الحجز
GET    /api/owner/reservations        - حجوزات مواردي (OWNER)
PUT    /api/reservations/{id}/confirm - تأكيد (OWNER)
PUT    /api/reservations/{id}/reject  - رفض (OWNER)

كيان الحجز:

id، resource، user
startDateTime، endDateTime
status (PENDING، CONFIRMED، CANCELLED، COMPLETED)
totalPrice، notes
createdAt

5. المراجعات والتقييمات

POST   /api/reservations/{id}/review  - ترك مراجعة
GET    /api/resources/{id}/reviews    - مراجعات المورد
GET    /api/reviews/my-reviews        - مراجعاتي

كيان المراجعة:

id، reservation، user، resource
rating (1-5)، comment
createdAt

مخطط قاعدة البيانات

users
├── id (PK)
├── email (UNIQUE)
├── password
├── first_name
├── last_name
├── phone
├── role
└── created_at

resources
├── id (PK)
├── name
├── description
├── type
├── address
├── city
├── country
├── capacity
├── price_per_unit
├── price_unit (HOUR، NIGHT، EVENT)
├── owner_id (FK)
├── active
└── created_at

resource_amenities
├── resource_id (FK)
└── amenity (STRING)

resource_images
├── id (PK)
├── resource_id (FK)
└── image_url

availability
├── id (PK)
├── resource_id (FK)
├── day_of_week (0-6)
├── specific_date (nullable)
├── start_time
├── end_time
└── available

reservations
├── id (PK)
├── resource_id (FK)
├── user_id (FK)
├── start_datetime
├── end_datetime
├── status
├── total_price
├── notes
└── created_at

reviews
├── id (PK)
├── reservation_id (FK)
├── user_id (FK)
├── resource_id (FK)
├── rating
├── comment
└── created_at

قواعد العمل

التوافر

التحقق من التوافر قبل الحجز
لا يوجد تداخل في الحجوزات المؤكدة
المالك يحدد الفترات المتاحة

الحجوزات

حساب تلقائي للسعر الإجمالي
بريد إلكتروني للتأكيد (محاكاة)
الإلغاء ممكن حتى X ساعات قبل

حالات الحجز

PENDING -> CONFIRMED -> COMPLETED
       |-> REJECTED
       |-> CANCELLED (من العميل)
CONFIRMED -> CANCELLED (من المالك مع تبرير)

المراجعات

مراجعة واحدة لكل حجز
المراجعة ممكنة فقط بعد COMPLETED
يتم حساب متوسط التقييم لكل مورد

الأذونات

الدور	الموارد	الحجوزات	المراجعات
ADMIN	CRUD all	عرض all	إدارة
OWNER	CRUD owns	إدارة owns	-
CUSTOMER	قراءة all	CRUD owns	إنشاء

نقاط النهاية المفصلة

البحث عن الموارد

GET /api/resources/search?city=Paris&date=2024-02-15&capacity=4&type=MEETING_ROOM
Authorization: Bearer <token>

Response 200:
{
  "content": [
    {
      "id": 1,
      "name": "Salle Eiffel",
      "description": "Salle de reunion moderne avec vue",
      "type": "MEETING_ROOM",
      "location": {
        "address": "123 Rue de Paris",
        "city": "Paris",
        "country": "France"
      },
      "capacity": 10,
      "pricePerHour": 50.00,
      "amenities": ["WIFI", "PROJECTOR", "WHITEBOARD"],
      "averageRating": 4.5,
      "reviewCount": 23,
      "availableSlots": [
        { "start": "09:00", "end": "12:00" },
        { "start": "14:00", "end": "18:00" }
      ]
    }
  ],
  "page": 0,
  "totalElements": 15
}

إنشاء حجز

POST /api/reservations
Authorization: Bearer <token>
Content-Type: application/json

{
  "resourceId": 1,
  "startDateTime": "2024-02-15T09:00:00",
  "endDateTime": "2024-02-15T12:00:00",
  "notes": "Reunion equipe marketing"
}

Response 201:
{
  "id": 1,
  "resource": {
    "id": 1,
    "name": "Salle Eiffel"
  },
  "user": {
    "id": 5,
    "firstName": "Marie",
    "lastName": "Dupont"
  },
  "startDateTime": "2024-02-15T09:00:00",
  "endDateTime": "2024-02-15T12:00:00",
  "status": "PENDING",
  "totalPrice": 150.00,
  "notes": "Reunion equipe marketing",
  "createdAt": "2024-01-20T10:30:00"
}

التقويم

GET /api/resources/1/calendar?month=2024-02
Authorization: Bearer <token>

Response 200:
{
  "resource": { "id": 1, "name": "Salle Eiffel" },
  "month": "2024-02",
  "days": [
    {
      "date": "2024-02-15",
      "slots": [
        { "start": "09:00", "end": "12:00", "status": "BOOKED" },
        { "start": "14:00", "end": "18:00", "status": "AVAILABLE" }
      ]
    },
    ...
  ]
}

ترك مراجعة

POST /api/reservations/1/review
Authorization: Bearer <token>
Content-Type: application/json

{
  "rating": 5,
  "comment": "Excellente salle, tres bien equipee. Je recommande!"
}

Response 201:
{
  "id": 1,
  "rating": 5,
  "comment": "Excellente salle, tres bien equipee. Je recommande!",
  "user": { "firstName": "Marie", "lastName": "D." },
  "createdAt": "2024-02-16T10:00:00"
}

الاختبارات المطلوبة

اختبارات الوحدة

ResourceService: البحث، التحقق من التوافر
ReservationService: الإنشاء، التحقق، الإلغاء
ReviewService: الإنشاء، حساب المتوسط

اختبارات التكامل

البحث مع الفلاتر
سير عمل الحجز
نقاط نهاية إدارة المالك

نقاط إضافية

الميزة	النقاط
إشعارات البريد الإلكتروني	+3
تذكيرات تلقائية (@Scheduled)	+3
تكامل التقويم (تصدير iCal)	+3
نظام الدفع (محاكاة)	+5
البحث الجغرافي	+3
لوحة تحكم المالك	+5

تقدير الوقت

المهمة	الساعات
إعداد المشروع وDB	2
الكيانات والمستودعات	5
خدمات العمل	8
وحدات تحكم REST	5
الأمان والأذونات	5
الاختبارات	6
التوثيق	2
إضافات	4-8
الإجمالي	33-41

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

الوصف​

الميزات المطلوبة​

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

2. إدارة الموارد​

3. التوافر​

4. الحجوزات​

5. المراجعات والتقييمات​

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

قواعد العمل​

التوافر​

الحجوزات​

حالات الحجز​

المراجعات​

الأذونات​

نقاط النهاية المفصلة​

البحث عن الموارد​

إنشاء حجز​

التقويم​

ترك مراجعة​

الاختبارات المطلوبة​

اختبارات الوحدة​

اختبارات التكامل​

نقاط إضافية​

تقدير الوقت​