هذا المشروع هو عبارة عن واجهة برمجية (RESTful API) متكاملة لإدارة المهام والتعليقات، تم تطويرها باستخدام إطار عمل Laravel. يركز المشروع على تطبيق المعايير الهندسية المتقدمة لضمان الأمان، الأداء، والموثوقية.
هذا المشروع يتجاوز مفهوم CRUD البسيط، حيث يشتمل على الميزات التقنية التالية:
| الميزة | الوصف | الفائدة الهندسية |
|---|---|---|
| Laravel Sanctum | نظام مصادقة آمن يعتمد على الـ Tokens لتأمين جميع الـ Endpoints المحمية. | مصادقة فعالة وآمنة للـ Single Page Applications (SPA). |
| Middleware للتحكم بالملكية | تم تطوير Middleware مخصص لفرض ضوابط Authorization، لضمان أن المستخدم لا يمكنه تعديل أو حذف إلا المهام التي يمتلكها. | أمان دقيق على مستوى المورد (Resource Level Security). |
| Caching | تفعيل آلية التخزين المؤقت (Cache) لنتائج الـ /api/tasks لمدة 60 ثانية. |
تحسين ملحوظ في الأداء وتقليل الضغط على قاعدة البيانات. |
| Observer (Log) | استخدام Observer لتسجيل Log تلقائي في ملف النظام عند إنشاء مهمة جديدة. | سهولة المراقبة (Observability) وتتبع أنشطة النظام. |
| Eager Loading | استخدام with() في جميع الاستعلامات الضرورية (Tasks -> User/Comments) |
حل مشكلة N+1 وتقليل زمن استجابة الاستعلامات. |
| API Resources | تنظيم وتنسيق استجابات JSON لضمان هيكل بيانات موحد ومتسق. | فصل طبقة العرض عن طبقة الكود وزيادة نظافة الكود. |
تم بناء المشروع حول ثلاثة جداول أساسية:
| الجدول | الوصف | العلاقات |
|---|---|---|
users |
معلومات المستخدم الأساسية. | hasMany Tasks, hasMany Comments |
tasks |
جدول المهام (العنوان، الوصف، الحالة). | belongsTo User, hasMany Comments |
comments |
تعليقات المستخدمين على المهام. | belongsTo User, belongsTo Task |
تم تنظيم الكود باستخدام الـ Controllers المخصصة لكل وظيفة:
ApiController: التعامل مع المصادقة (Register, Login, Logout).TasksController: تنفيذ عمليات CRUD والبحث والفلترة على المهام.CommentsController: إضافة وعرض التعليقات على المهام.
اتبع الخطوات التالية لتشغيل المشروع على جهازك المحلي:
-
استنساخ المشروع:
git clone https://github.com/bmask2020/tasks-app cd advanced_task_api -
تثبيت التبعيات:
composer install
-
إعداد ملف البيئة:
cp .env.example .env php artisan key:generate
(قم بتعديل بيانات قاعدة البيانات في ملف
.env، وتأكد من تفعيل DB_CONNECTION=mysql أو sqlite) -
ترحيل قاعدة البيانات:
php artisan migrate
-
تشغيل الخادم:
php artisan serve
الـ API ستكون متاحة على
http://127.0.0.1:8000/api/
هذه قائمة بالمسارات الرئيسية المتاحة للوصول إلى الموارد:
| الفئة | المسار (Endpoint) | الطريقة (Method) | الوصف | الأمان |
|---|---|---|---|---|
| Auth | /api/register |
POST |
تسجيل مستخدم جديد (يُرجع Token) | لا يوجد |
| Auth | /api/login |
POST |
تسجيل الدخول (يُرجع Token) | لا يوجد |
| Auth | /api/logout |
POST |
تسجيل الخروج وحذف Token الحالي | auth:sanctum |
| Tasks | /api/tasks |
GET |
عرض جميع المهام (يُطبق عليه Caching) | auth:sanctum |
| Tasks | /api/tasks |
POST |
إنشاء مهمة جديدة | auth:sanctum |
| Tasks | /api/tasks/{id} |
PUT |
تحديث مهمة | auth:sanctum + Middleware Ownership |
| Tasks | /api/tasks/{id} |
DELETE |
حذف مهمة | auth:sanctum + Middleware Ownership |
| Tasks | /api/tasks/status/{status} |
GET |
فلترة المهام حسب الحالة (e.g., pending) | auth:sanctum |
| Comments | /api/tasks/{id_task}/comments |
POST |
إضافة تعليق على مهمة محددة | auth:sanctum |
| Comments | /api/tasks/{id_task}/comments |
GET |
عرض جميع التعليقات على مهمة محددة | لا يوجد |
للتأكد من عمل الـ API بشكل سليم، تم توفير ملف Postman Collection شامل:
- استيراد الملف: قم باستيراد ملف
Advanced Task API.postman_collection.jsonالمرفق في المشروع إلى برنامج Postman. - البيئة (Environment): يجب إنشاء Environment جديد وتعيين المتغير
{{base_url}}إلىhttp://127.0.0.1:8000/api. - Tests Scripts: جميع الـ Requests في الـ Collection تحتوي على اختبارات مدمجة (Tests Scripts) للتحقق من:
- Status Code (200, 403, 422).
- صيغة الاستجابة (JSON).
- عمل آليات الأمان (فشل تحديث مهمة لا يملكها المستخدم).