OkazX — E-Commerce REST API

OkazX — واجهة برمجية للتجارة الإلكترونية (Java/Spring Boot)

نظام خلفي (Backend) للتجارة الإلكترونية بمستوى إنتاجي يغطي رحلة العميل بالكامل — من المصادقة، إلى كتالوج المنتجات، إلى سلة التسوق، إلى معالجة الطلبات — مبني كتطبيق Monolith واحد منظم بعناية، مع أمان قوي ونمذجة بيانات نظيفة.

آلية العمل

يوفّر OkazX 22 نقطة نهاية REST موزعة على خمسة مجالات رئيسية: مصادقة المستخدمين، وكتالوج المنتجات (مع البحث والتصفح المُقسّم)، وسلة التسوق، ومعالجة الطلبات، وإدارة المستخدمين. يوجد دوران للصلاحيات — CUSTOMER وADMIN — يحكمان الوصول عبر النظام بالكامل، من إنشاء المنتجات إلى إدارة الطلبات.

الأمان

تعتمد المصادقة على JWT عديم الحالة (Stateless) وموقّع بخوارزمية HS256، مع فلتر مخصص يتحقق من توقيع الرمز وصلاحيته وهويته قبل السماح بالوصول. يتم فرض الصلاحيات على مستويين: قواعد على مستوى الروابط (URL Patterns) في إعدادات الأمان، وفحوصات على مستوى الدوال باستخدام @PreAuthorize — على سبيل المثال، يمكن للعميل تعديل ملفه الشخصي فقط، بينما يمكن للمسؤول (Admin) تعديل أي حساب. يتم تشفير كلمات المرور باستخدام BCrypt، والنظام عديم الحالة بالكامل (بدون جلسات، مع تعطيل CSRF المناسب لواجهات REST).

نمذجة البيانات

مخطط بيانات مُطبّع (Normalized) من 6 كيانات (المستخدمون، العناوين، المنتجات، عناصر السلة، الطلبات، عناصر الطلب) مبني باستخدام JPA/Hibernate، يغطي علاقات (1:1) و(1:M) بالإضافة إلى الحذف المتسلسل (Cascade). يتم التعامل مع تحويل DTO عبر MapStruct وقت الترجمة (Compile-time)، مما يفصل عقود الطلب/الاستجابة عن الكيانات دون أي تكلفة أداء وقت التشغيل.

تصميم الـ API

تشترك نقاط عرض القوائم (المنتجات، الطلبات، المستخدمون) في نمط تصفح موحّد (Pagination) عبر غلاف مخصص PageResponse<T>، يدعم تحديد حجم الصفحة، والفرز متعدد الحقول، والتحقق من صحة معاملات الطلب. الـ API موثّق بالكامل عبر SpringDoc OpenAPI ويمكن استكشافه من خلال Swagger UI، بما في ذلك آلية مصادقة JWT المدمجة في التوثيق.

المراقبة والتشغيل

يوفّر Spring Boot Actuator نقاط فحص للصحة والمعلومات والمقاييس والبيئة والسجلات — مع إتاحة فحص الصحة للجميع وتقييد الباقي للمسؤولين فقط. كما توجد آلية تلقائية عند إقلاع التطبيق لإنشاء أول حساب مسؤول من إعدادات البيئة.

OkazX — E-Commerce REST API (Java/Spring Boot)

A production-style e-commerce backend covering the full customer journey — authentication, product catalog, cart, and order processing — built as a single, well-structured Spring Boot monolith with strong security and clean data modeling.

What it does

OkazX exposes 22 REST endpoints across five domains: user authentication, product catalog (with search and pagination), shopping cart, order processing, and user management. Two roles — CUSTOMER and ADMIN — govern access across the entire system, from creating products to managing orders.

Security

Authentication is stateless JWT (HS256-signed), with a custom filter that validates the token signature, expiration, and subject before granting access. Authorization is enforced at two levels: URL-pattern rules in the security config, and method-level @PreAuthorize checks on individual endpoints — for example, a customer can only update their own profile, while admins can update anyone's. Passwords are hashed with BCrypt, and the API is fully stateless (no sessions, CSRF disabled for REST).

Data modeling

A normalized 6-entity schema (users, addresses, products, cart items, orders, order items) built with JPA/Hibernate, covering one-to-one, one-to-many, and cascade relationships. DTO mapping is handled by MapStruct at compile time, keeping request/response contracts decoupled from entities with no runtime mapping overhead.

API design

List endpoints (products, orders, users) share a consistent pagination pattern through a custom PageResponse<T> wrapper, supporting page size, multi-field sorting, and validated query parameters. The full API is documented with SpringDoc OpenAPI and explorable via Swagger UI, including JWT bearer-token auth built into the docs.

Observability & ops

Spring Boot Actuator exposes health, info, metrics, environment, and logger endpoints — with health public and the rest restricted to admins. An application-startup seeder automatically creates the first admin account from environment configuration.