المشروع أ: منصة التجارة الإلكترونية

الوصف

تطوير API RESTful كامل لمنصة تجارة إلكترونية تتيح إدارة المنتجات، المستخدمين، السلة والطلبات.

---

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

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

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

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

• id، البريد الإلكتروني، كلمة المرور، الاسم الأول، الاسم الأخير
• الدور (CUSTOMER، ADMIN)
• createdAt، updatedAt

2. كتالوج المنتجات

GET    /api/products              - قائمة المنتجات (التقسيم إلى صفحات)
GET    /api/products/{id}         - تفاصيل المنتج
GET    /api/products/search       - البحث بالاسم/الفئة
POST   /api/products              - إنشاء منتج (ADMIN)
PUT    /api/products/{id}         - تعديل المنتج (ADMIN)
DELETE /api/products/{id}         - حذف المنتج (ADMIN)

كيان المنتج:

• id، الاسم، الوصف، السعر، المخزون
• الفئة (علاقة ManyToOne)
• imageUrl، نشط

كيان الفئة:

• id، الاسم، الوصف

3. السلة

GET    /api/cart                  - عرض السلة
POST   /api/cart/items            - إضافة منتج
PUT    /api/cart/items/{id}       - تعديل الكمية
DELETE /api/cart/items/{id}       - حذف من السلة
DELETE /api/cart                  - إفراغ السلة

كيان عنصر السلة:

• id، السلة، المنتج، الكمية، السعر

4. الطلبات

POST   /api/orders                - إنشاء طلب (من السلة)
GET    /api/orders                - قائمة الطلبات (المستخدم)
GET    /api/orders/{id}           - تفاصيل الطلب
PUT    /api/orders/{id}/status    - تعديل الحالة (ADMIN)
GET    /api/admin/orders          - جميع الطلبات (ADMIN)

كيان الطلب:

• id، المستخدم، العناصر، المبلغ الإجمالي
• الحالة (PENDING، CONFIRMED، SHIPPED، DELIVERED، CANCELLED)
• عنوان الشحن، createdAt

---

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

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

categories
├── id (PK)
├── name
└── description

products
├── id (PK)
├── name
├── description
├── price
├── stock
├── category_id (FK)
├── image_url
└── active

carts
├── id (PK)
└── user_id (FK, UNIQUE)

cart_items
├── id (PK)
├── cart_id (FK)
├── product_id (FK)
├── quantity
└── price

orders
├── id (PK)
├── user_id (FK)
├── total_amount
├── status
├── shipping_address
└── created_at

order_items
├── id (PK)
├── order_id (FK)
├── product_id (FK)
├── quantity
├── price
└── product_name

---

قواعد العمل

المخزون

• التحقق من التوفر قبل الإضافة إلى السلة
• تقليل المخزون عند الطلب
• استعادة المخزون إذا تم إلغاء الطلب

السعر

• السعر في السلة يجب أن يكون سعر اللحظة
• السعر في الطلب ثابت

السلة

• للمستخدم سلة واحدة فقط
• يتم إنشاء السلة تلقائيًا
• السلة فارغة بعد الطلب

الطلبات

• يمكن للمستخدم فقط رؤية طلباته
• يمكن للمسؤول رؤية جميع الطلبات
• انتقالات الحالة الصالحة:
  • PENDING -> CONFIRMED -> SHIPPED -> DELIVERED
  • PENDING -> CANCELLED
  • CONFIRMED -> CANCELLED

---

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

المصادقة

POST /api/auth/register
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "Password123!",
  "firstName": "John",
  "lastName": "Doe"
}

Response 201:
{
  "id": 1,
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "CUSTOMER"
}

POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "Password123!"
}

Response 200:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "type": "Bearer",
  "expiresIn": 86400
}

المنتجات

GET /api/products?page=0&size=10&category=electronics
Authorization: Bearer <token>

Response 200:
{
  "content": [
    {
      "id": 1,
      "name": "Laptop Pro",
      "description": "High-performance laptop",
      "price": 999.99,
      "stock": 50,
      "category": {
        "id": 1,
        "name": "Electronics"
      },
      "imageUrl": "https://..."
    }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 100,
  "totalPages": 10
}

السلة

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

{
  "productId": 1,
  "quantity": 2
}

Response 200:
{
  "items": [
    {
      "id": 1,
      "product": { "id": 1, "name": "Laptop Pro", ... },
      "quantity": 2,
      "price": 999.99,
      "subtotal": 1999.98
    }
  ],
  "totalItems": 2,
  "totalAmount": 1999.98
}

الطلبات

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

{
  "shippingAddress": "123 Main St, City, 12345"
}

Response 201:
{
  "id": 1,
  "status": "PENDING",
  "items": [...],
  "totalAmount": 1999.98,
  "shippingAddress": "123 Main St, City, 12345",
  "createdAt": "2024-01-15T10:30:00"
}

---

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

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

• ProductService: عمليات CRUD
• CartService: إضافة، تحديث، إزالة العناصر
• OrderService: إنشاء الطلب، التحقق من المخزون

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

• ProductController: جميع نقاط النهاية
• CartController: عمليات السلة
• OrderController: سير عمل الطلب

---

نقاط إضافية

الميزة	النقاط
Cache Redis على المنتجات	+5
إشعار البريد الإلكتروني (محاكاة)	+3
البحث النصي الكامل	+3
تصدير الطلبات بصيغة CSV	+2
Docker Compose كامل	+5
توثيق Swagger	+5

---

تقدير الوقت

المهمة	الساعات
إعداد المشروع وقاعدة البيانات	2
الكيانات والمستودعات	4
خدمات العمل	6
وحدات التحكم REST	4
أمان JWT	4
الاختبارات	6
التوثيق	2
النقاط الإضافية	4-8
الإجمالي	28-36

---

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