1) Backend API Documentation
1.1 نظرة عامة
الـ Backend هو القلب الرئيسي للنظام، ومسؤول عن:

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

إدارة المتاجر

إدارة الكوبونات والعروض

إدارة الكاش باك

إدارة المفضلة

إدارة البنرات

إدارة الإشعارات

إدارة الدول واللغات

توفير REST APIs للويب والموبايل والداشبورد

1.2 التقنية المقترحة
Laravel 12

PHP 8.3+

MySQL

Laravel Sanctum أو JWT

Laravel Resource / API Resource

Queue + Jobs

Firebase Cloud Messaging للإشعارات

Storage للصور والشعارات

1.3 أنواع المستخدمين
Admin
إدارة النظام كامل

إضافة وتعديل وحذف

الاطلاع على الإحصائيات

إرسال إشعارات

التحكم في الإعدادات

User
التسجيل / تسجيل الدخول

تصفح المتاجر والكوبونات

نسخ الكوبونات

إضافة للمفضلة

تفعيل الكاش باك

إدارة الحساب

1.4 الوحدات الرئيسية
Auth

Users

Countries

Languages

Categories

Stores

Coupons

Cashback

Favorites

Banners

Notifications

Pages

Referrals

Settings

1.5 قاعدة البيانات
users
id

name

email

phone

password

country_id

language_id

referral_code

referred_by

wallet_balance

status

created_at

updated_at

admins
id

name

email

password

role

status

created_at

updated_at

countries
id

name_ar

name_en

code

currency

status

languages
id

name

code

direction

categories
id

name_ar

name_en

icon

image

sort_order

status

stores
id

category_id

name_ar

name_en

slug

logo

cover_image

description_ar

description_en

website_url

affiliate_url

cashback_enabled

cashback_rate

is_featured

status

sort_order

coupons
id

store_id

title_ar

title_en

description_ar

description_en

code

type (code / deal)

discount_type (percentage / fixed / text)

discount_value

start_date

end_date

usage_count

is_featured

status

cashback_offers
id

store_id

title_ar

title_en

rate

description_ar

description_en

terms_ar

terms_en

status

cashback_transactions
id

user_id

store_id

click_id

order_reference

amount

status (pending / approved / rejected / paid)

confirmed_at

paid_at

banners
id

title_ar

title_en

image

type (store / coupon / external / cashback)

reference_id

url

start_date

end_date

sort_order

status

favorites
id

user_id

type (store / coupon)

reference_id

notifications
id

title_ar

title_en

body_ar

body_en

type

reference_id

sent_to

status

pages
id

key

title_ar

title_en

content_ar

content_en

status

referrals
id

user_id

invited_user_id

reward_amount

status

settings
id

key

value

coupon_clicks
id

user_id

coupon_id

store_id

clicked_at

ip_address

device

1.6 العلاقات
كل Store ينتمي إلى Category

كل Coupon ينتمي إلى Store

كل Cashback Offer ينتمي إلى Store

كل Favorite يرتبط بمستخدم وعنصر

كل Banner يوجّه إلى Store أو Coupon أو رابط خارجي

كل Cashback Transaction ترتبط بمستخدم ومتجر

1.7 الـ API Structure
Base URL:

/api/v1
Authentication APIs
POST /auth/register
تسجيل مستخدم جديد

POST /auth/login
تسجيل الدخول

POST /auth/logout
تسجيل الخروج

GET /auth/me
بيانات المستخدم الحالي

POST /auth/forgot-password
استعادة كلمة المرور

Countries & Languages
GET /countries
GET /languages
Home APIs
GET /home
يرجع:

banners

featured_stores

featured_coupons

cashback_stores

categories

Categories APIs
GET /categories
GET /categories/{id}/stores
Stores APIs
GET /stores
فلاتر مقترحة:

category_id

featured

search

sort

GET /stores/{id}
GET /stores/{id}/coupons
GET /stores/{id}/cashback
Coupons APIs
GET /coupons
فلاتر:

search

store_id

category_id

featured

sort

GET /coupons/{id}
POST /coupons/{id}/copy
يسجل عملية نسخ الكوبون

POST /coupons/{id}/click
يسجل الضغط على العرض أو التوجيه للمتجر

Cashback APIs
GET /cashback/stores
GET /cashback/offers
POST /cashback/activate/{store_id}
GET /cashback/history
Favorites APIs
GET /favorites
POST /favorites/toggle
Body example:

{
  "type": "store",
  "reference_id": 5
}
Notifications APIs
GET /notifications
POST /notifications/read/{id}
Pages APIs
GET /pages/faq
GET /pages/terms
GET /pages/privacy
GET /pages/contact
Account APIs
GET /profile
PUT /profile
PUT /profile/language
PUT /profile/country
1.8 Admin APIs
Admin Auth
POST /admin/login

POST /admin/logout

Dashboard
GET /admin/dashboard/stats

Users
GET /admin/users

GET /admin/users/{id}

PUT /admin/users/{id}

DELETE /admin/users/{id}

Categories
GET /admin/categories

POST /admin/categories

PUT /admin/categories/{id}

DELETE /admin/categories/{id}

Stores
GET /admin/stores

POST /admin/stores

PUT /admin/stores/{id}

DELETE /admin/stores/{id}

Coupons
GET /admin/coupons

POST /admin/coupons

PUT /admin/coupons/{id}

DELETE /admin/coupons/{id}

Cashback
GET /admin/cashback/offers

POST /admin/cashback/offers

PUT /admin/cashback/offers/{id}

DELETE /admin/cashback/offers/{id}

Banners
GET /admin/banners

POST /admin/banners

PUT /admin/banners/{id}

DELETE /admin/banners/{id}

Notifications
GET /admin/notifications

POST /admin/notifications/send

Pages
GET /admin/pages

PUT /admin/pages/{id}

Settings
GET /admin/settings

PUT /admin/settings

1.9 صلاحيات الأدمن
super_admin

content_manager

marketing_manager

support_agent

1.10 Business Logic مهم
عند نسخ الكوبون يتم تسجيل usage_count

عند الضغط على تسوق الآن يتم تسجيل click tracking

عند تفعيل الكاش باك يتم إنشاء session أو tracking log

المفضلة تكون للمستخدم المسجل فقط

البنرات مرتبطة بتاريخ بداية ونهاية

الكوبونات يمكن إخفاؤها تلقائيًا عند الانتهاء

1.11 Validation Rules
اسم المتجر مطلوب بالعربي أو الإنجليزي

اللوجو مطلوب عند إنشاء متجر

الكوبون type لازم يكون code أو deal

end_date لازم تكون أكبر من start_date

discount_value غير سالب

country و language يجب أن يكونا صالحين

1.12 Non Functional Requirements
API response time سريع

pagination لكل القوائم

filtering و sorting

secure authentication

log activities

image upload management

multilingual support

scalable architecture