شركة شحن
تفاصيل العمل
> تطبيق ويب مبني على **Next.js (App Router)** لإدارة السفن/الشحنات وعرض بيانات حساسات (Sensor Data) مع نظام صلاحيات (Admin/Auditor/Viewer) ومصادقة عبر كُوكي (auth_token) وبث بيانات لحظي عبر Socket.
---
## 1) نظرة عامة على التطبيق
يتكوّن AtlasLogix من جزئين رئيسيين:
1. **جزء المصادقة (Auth)**
- تسجيل (Register)
- تسجيل دخول (Login)
- تسجيل خروج (Logout)
- جلب معلومات المستخدم الحالي (Me)
2. **جزء لوحة التحكم (Dashboard)**
- صفحة الحسابات (/accounts) لإدارة المستخدمين (للـ Admin)
- صفحة الشحنات (/shipments) مع فلترة وعرض قائمة الشحنات
- صفحة إنشاء شحنة (/shipments/create)
- صفحة تفاصيل شحنة (/shipments/[shipmentId])
- صفحة إضافة قراءة حساسات لشحنة معينة (/shipments/[shipmentId]/add-reading)
- عرض إحصاءات الشحنة/بيانات الحسّاسات
بالإضافة إلى ذلك:
- يوجد **حماية مسارات** (ProtectedRoute / AuthGuard) للتحقق من الصلاحيات.
- يوجد **بث لحظي** لقراءات الحسّاسات عبر Socket.
- يوجد **تنبيهات** (Alert service) كآلية لإظهار حالات/تنبيهات في الواجهة.
---
## 2) هيكل المجلدات (Structure)
- `app/`
- صفحات Next.js (Routes) باستخدام App Router
- أمثلة:
- `app/(auth)/...` صفحات تسجيل/…
- `app/(dashboard)/...` صفحات لوحة التحكم
- `app/api/...` Endpoints
- `features/`
- طبقات المجال (Domain) والمنطق الخاص بكل ميزة
- مثال:
- `features/auth/` (models/services/slices/types)
- `features/shipments/`
- `features/sensor-data/`
- `components/`
- مكوّنات واجهة المستخدم
- مثل: layout (Sidebar/Navbar/FloatingDock)، وعناصر dashboard، وUI components.
- `lib/`
- خدمات عامة مثل الاتصال بـ MongoDB و Socket و utils
- مثال:
- `lib/mongodb.ts`
- `lib/socket.ts`
- `lib/auth/`
- `lib/api/`
---
## 3) المتطلبات وتشغيل المشروع محلياً
> يوجد ملف `package.json` يحدد سكربتات التشغيل.
### 3.1 التثبيت
```bash
npm install
```
### 3.2 التشغيل في وضع التطوير
```bash
npm run dev
```
ثم افتح:
### 3.3 إنشاء Build وتشغيل الإنتاج
```bash
npm run build
npm run start
```
---
## 4) إعدادات البيئة (Environment)
يوجد ملف `.env` ضمن المشروع (ظاهر في الهيكل). يجب التأكد من القيم المطلوبة مثل:
- إعدادات الاتصال بقاعدة البيانات (MongoDB)
- مفاتيح/Secrets الخاصة بالـ JWT
- إعدادات Socket/أي provider خارجي (إن وجدت)
> **ملاحظة:** لا يمكنني تأكيد أسماء المتغيرات الدقيقة بدون قراءة ملف `.env` (غير ظاهر كمحتوى هنا). راجع `lib/mongodb.ts` و `lib/auth/` و `lib/socket.ts` لاستخراج أسماء المتغيرات المطلوبة.
---
## 5) المصادقة والصلاحيات (Auth & Authorization)
### 5.1 المصادقة
- يتم الاعتماد على **cookie** باسم غالباً `auth_token`.
- يوجد endpoints:
- `/api/auth/login`
- `/api/auth/register`
- `/api/auth/logout`
- `/api/auth/me`
### 5.2 الصلاحيات
- الأدوار المتوقعة: **Admin / Auditor / Viewer**.
- يتم تحويل/تطبيع أسماء الأدوار لضمان التوافق مع المنطق داخل:
- `app/config/routes.ts`
- مكوّنات الحماية مثل `ProtectedRoute`.
### 5.3 حماية المسارات
- يتم حماية صفحات لوحة التحكم عبر:
- `components/auth/ProtectedRoute.tsx`
- `components/auth/AuthGuard.tsx`
---
## 6) تدفق الشحنات (Shipments Workflow)
### 6.1 قائمة الشحنات
- الصفحة: `app/(dashboard)/shipments/page.tsx`
- تقوم باستدعاء البيانات (غالباً عبر hooks/services من `features/shipments/`).
### 6.2 إنشاء شحنة
- الصفحة: `app/(dashboard)/shipments/create/page.tsx`
- تعتمد على services داخل `features/shipments/services/shipment.service.ts`
### 6.3 تفاصيل شحنة
- الصفحة: `app/(dashboard)/shipments/[shipmentId]/page.tsx`
- تعرض معلومات الشحنة بالإضافة إلى بيانات حساسات مرتبطة بها.
### 6.4 إضافة قراءة حساسات
- الصفحة: `app/(dashboard)/shipments/[shipmentId]/add-reading/page.tsx`
- ترسل قراءة جديدة إلى API خاص بالحساسات.
---
## 7) بيانات الحسّاسات (Sensor Data)
يوجد Modules:
- `features/sensor-data/`
وأجزاء مهمة:
- موديل القراءة: `features/sensor-data/models/sensor-reading.model.ts`
- خدمة البيانات: `features/sensor-data/services/sensor-data.service.ts`
- Redux slice: `features/sensor-data/slices/sensorData.slice.ts`
### 7.1 API الخاصة بالـ Sensor Data
أمثلة endpoints:
- `app/api/v1/shipments/[shipmentId]/sensor-data/route.ts`
- `app/api/v1/stream/sensor-data/route.ts` (لبث لحظي)
---
## 8) بث Socket في التطبيق
- يوجد Context: `app/context/SocketContext.tsx`
- يوجد ملف اتصال/Client: `lib/socket.ts`
الفكرة العامة:
- يتم فتح اتصال Socket
- يتم استلام أحداث/رسائل خاصة بقراءات حساسات
- يتم تحديث الحالة داخل الـ store/Redux أو داخل components حسب تصميم التطبيق
---
## 9) الأداء (Performance)
يوجد إعدادات مرتبطة بالأداء مثل:
- `app/config/performance.ts`
كما يوجد `instrumentation.ts` لميزات/Tracking حسب إعداد المشروع.
---
## 10) اختبارات (Testing)
يوجد `vitest.config.ts` بالإضافة إلى deps الخاصة بالـ Vitest.
راجع:
- `vitest.config.ts`
- أي ملفات test داخل المشروع (إن وجدت)
---
## 11) كيف أضيف Feature جديدة؟ (إرشادات عملية)
1. ضع منطق المجال داخل `features/<feature-name>/`
2. إذا كانت هناك صفحة جديدة:
- أضف Route داخل `app/(dashboard)/...` أو `app/(auth)/...`
3. استخدم services/models/types لتوحيد عقود البيانات.
4. إذا كانت هناك API جديدة:
- أضف Endpoint داخل `app/api/...`
5. حدّث `app/config/routes.ts` لإضافة قواعد الصلاحيات للمسار الجديد.
---
## مراجع ملفات مهمة في المشروع
- `app/config/routes.ts` — تعريف صلاحيات المسارات
- `components/auth/ProtectedRoute.tsx` — حماية المسارات
- `app/api/auth/*` — Endpoints المصادقة
- `app/api/v1/shipments/*` — Endpoints الشحنات
- `app/api/v1/stream/sensor-data/*` — بث حساسات لحظياً
- `features/*/services/*` — طبقات الخدمات
- `lib/mongodb.ts` — الاتصال ب MongoDB