# مستند تسليم مشروع "وصل-لي" (Wassili) للمطورين

هذا المستند يحتوي على كافة التفاصيل التقنية، المعمارية، والبرمجية لمشروع **"وصل-لي"** ليكون مرجعاً شاملاً لأي مبرمج جديد ينضم للعمل على المشروع.

---

## 1. نظرة عامة على المشروع (Overview)
تطبيق "وصل-لي" هو منصة متكاملة للطلبات والتوصيل، تربط بين أربعة أطراف رئيسية:
1. **العميل (Client):** يطلب منتجات من المتاجر أو يطلب توصيل طرد من مكان لآخر.
2. **الكابتن/المندوب (Captain):** يستقبل الطلبات، يقدم عروض توصيل، ويوصل الطلبات.
3. **التاجر (Merchant):** يدير متجره، يرفع منتجاته، ويستقبل طلبات الشراء.
4. **الإدارة (Admin):** تتحكم في المنصة بالكامل (المستخدمين، الطلبات، المناطق، المالية، المتاجر).

---

## 2. التقنيات المستخدمة (Tech Stack)
- **الخلفية (Backend):** Node.js مع إطار عمل Express.js.
- **قاعدة البيانات (Database):** MongoDB باستخدام مكتبة Mongoose.
- **الواجهة الأمامية (Frontend):** HTML5, CSS3, Vanilla JavaScript (بدون إطار عمل معقد لتسهيل التعديل).
- **تطبيق الموبايل (Mobile App):** تم تغليف الواجهة الأمامية باستخدام **Ionic Capacitor** لتوليد تطبيق Android (ويمكن iOS لاحقاً).
- **الوقت الفعلي (Real-time):** مكتبة Socket.io للتعامل مع الطلبات المباشرة، التتبع، الإشعارات الحية.
- **الخرائط والمواقع (Maps):** Google Maps API للويب، و Capacitor Google Maps (Native) للموبايل.
- **الإشعارات (Push Notifications):** Firebase Cloud Messaging (FCM).

---

## 3. هيكل المشروع (Project Structure)
المشروع مقسم إلى مجلدات واضحة كالتالي:

```text
wassili_V2/
├── index.js                 # نقطة الدخول الأساسية للسيرفر (Entry Point) وتهيئة Socket.io
├── .env                     # متغيرات البيئة (مفاتيح قواعد البيانات، JWT، Firebase)
├── capacitor.config.json    # إعدادات Capacitor لتطبيق الموبايل
├── package.json             # مكاتب وأوامر Node.js
│
├── models/                  # (قاعدة البيانات Mongoose Schemas)
│   ├── User.js              # المستخدمين (بكل أدوارهم)
│   ├── Order.js             # الطلبات بكل أنواعها
│   ├── Place.js             # المتاجر والأماكن
│   ├── Category.js          # تصنيفات المتاجر
│   ├── Settings.js          # الإعدادات العامة للأسعار ونطاق التوصيل الجغرافي (Polygon)
│   ├── DebtAdjustment.js    # تعديلات الديون والأرصدة
│   ├── PaymentRequest.js    # طلبات السحب والإيداع
│   ├── Complaint.js         # الشكاوى
│   ├── MerchantRequest.js   # طلبات انضمام التجار
│   └── Config.js            # الإعدادات العامة (العمولات، الخ)
│
├── routes/                  # (مسارات الـ API)
│   ├── auth.js              # التسجيل وتسجيل الدخول
│   ├── orders.js            # إدارة وإنشاء الطلبات
│   ├── places.js            # المتاجر
│   ├── admin.js             # وظائف لوحة تحكم الإدارة الشاملة (الإعدادات، نطاقات التوصيل، المالية، الإحصائيات)
│   ├── upload.js            # رفع الملفات والصور
│   ├── complaints.js        # الشكاوى
│   ├── merchantRequests.js  # واجهات طلبات التجار
│   └── emergency.js         # الطوارئ
│
├── public_html/             # (الواجهة الأمامية ولوحات التحكم - App & Dashboard)
│   ├── index.html           # شاشة البداية والتطبيق الأساسي
│   ├── admin*.html          # جميع شاشات لوحة تحكم الإدارة (admin-places, admin-finance, الخ)
│   ├── merchant*.html       # لوحة تحكم التاجر
│   ├── css/                 # ملفات التصميم
│   ├── js/                  # ملفات الجافاسكربت (أهمها config.js و app-core.js و admin-dashboard.js)
│   └── assets/              # الصور والأيقونات
│
├── android/                 # مشروع الـ Android Studio (مُولد من Capacitor)
└── uploads/                 # المجلد الذي تُحفظ فيه الصور المرفوعة (لوكال)
```

---

## 4. الأنظمة الأساسية وتفاصيلها (Core Systems)

### أ. نظام المستخدمين والأدوار (Users & Roles)
يحتوي النموذج `User.js` على حقل `role` والذي يحدد صلاحيات المستخدم:
- `user`: مستخدم عادي.
- `captain`: مندوب توصيل (يحتوي على حقول إضافية مثل المركبة، التقييم، الرصيد، رخصة القيادة).
- `merchant`: تاجر (مرتبط بـ `placeId`).
- `admin` / `sub-admin`: مشرفون لإدارة النظام.
- يتم التوثيق عبر **JWT (JSON Web Tokens)**.

### ب. نظام الطلبات (Orders Flow)
- **أنواع الطلبات (`orderType`):** 
  - توصيل عادي (من نقطة أ إلى ب).
  - طلب من متجر (مربوط بـ `Place`).
- **حالات الطلب (`status`):**
  1. `pending`: بانتظار قبول المندوب.
  2. `assigned` / `accepted`: تم تعيين المندوب.
  3. `on_the_way`: المندوب في الطريق للعميل.
  4. `delivered`: تم التوصيل بنجاح.
  5. `cancelled`: تم الإلغاء.
- يتم استخدام **Socket.io** لإرسال الطلبات الجديدة للمناديب المتواجدين في نفس المنطقة وبث التحديثات الحية لمسار المندوب.

### ج. نظام الخرائط ومناطق التوصيل (Delivery Zone & Pricing)
- الإدارة تمتلك صفحة `admin-zone-builder.html` لرسم مضلع التوصيل (Polygon) على الخريطة.
- يتم حفظ إحداثيات النطاق الجغرافي والأسعار الأساسية وقيمة الكيلومتر الإضافي داخل نموذج `Settings.js` (ولا يوجد نموذج Zone منفصل).
- جميع هذه التعديلات تدار من خلال المسار `/api/admin/settings` داخل ملف `admin.js`.
- يعتمد النظام على التحقق مما إذا كان موقع المستخدم داخل نطاق `deliveryZone` المحفوظ لضمان إمكانية التوصيل.

### د. نظام التجار والانضمام (Merchant System)
- يوجد صفحة `merchant-join.html` للعملاء لتقديم طلب الانضمام كتاجر.
- تُحفظ الطلبات في `MerchantRequest`.
- تقوم الإدارة بمراجعة الطلبات من `admin-merchant-requests.html`. عند الموافقة (Approve):
  - يتم تغيير دور المستخدم إلى `merchant`.
  - يتم إنشاء متجر (`Place`) جديد بناءً على البيانات.

### هـ. النظام المالي (Finance System)
- كل مستخدم لديه `walletBalance` في قاعدة البيانات.
- يتم اقتطاع **عمولة التطبيق** تلقائياً من الطلبات المكتملة وإضافتها لحساب المنصة.
- المناديب والتجار يمكنهم طلب سحب أرباح أو شحن أرصدة عبر نموذج `PaymentRequest.js`.
- تقوم الإدارة بتسوية الديون وإضافة أو خصم الأرصدة للمناديب والتجار، ويتم حفظ العمليات في نموذج `DebtAdjustment.js`.
- لا يوجد ملف `finance.js` منفصل، بل تندرج هذه العمليات تحت واجهات الإدارة في `admin.js` وواجهات الكباتن في `captain.js`.

---

## 5. إعدادات بيئة العمل (Environment Setup)
لأي مطور جديد، للبدء في المشروع:
1. تأكد من تثبيت `Node.js` و `MongoDB` (إذا كنت تعمل محلياً).
2. قم بتشغيل `npm install` في المسار الرئيسي لتثبيت مكتبات الباك إند.
3. اصنع ملف `.env` يحتوي على التالي:
   ```env
   PORT=5000
   MONGODB_URI=mongodb://localhost:27017/wassili (أو رابط الأطلس)
   JWT_SECRET=your_secret_key
   FIREBASE_SERVICE_ACCOUNT_PATH=./path/to/firebase.json
   ```
4. تشغيل السيرفر للتطوير: `node index.js` أو `nodemon index.js`.

---

## 6. التعامل مع الواجهة الأمامية و Capacitor (Frontend & Mobile)
- **رابط الـ API:** في ملف `public_html/js/config.js` ستجد:
  ```javascript
  const API_CONFIG = {
      production: 'https://wassili.site',
      development: 'http://localhost:5000',
      get baseURL() { return this.production; } // للموبايل والإنتاج اجعلها production
  };
  ```
- **تحديث التطبيق (Mobile Sync):**
  أي تغيير تقوم به في مجلد `public_html` **لن يظهر في الأندرويد** حتى تقوم بتشغيل الأمر التالي في سطر الأوامر (Terminal):
  ```bash
  npx cap sync android
  ```
  بعدها يمكنك فتح `Android Studio` لعمل Build (APK / AAB) أو من سطر الأوامر.

- **تفادي الكاش (Cache Busting):**
  ملفات الجافاسكربت مربوطة بسكريبت `admin-cache-buster.js` لضمان تحديث الملفات وعدم احتفاظ المتصفح بنسخ قديمة عند التحديثات.

---

## 7. أمن وحماية النظام (Security Notes)
- مسارات الإدارة في الـ Backend محمية عبر `middleware/auth.js` للتحقق من أن المُرسل يمتلك `role: admin`.
- تم إضافة نظام Rate Limiting في بعض المسارات (مثل تسجيل الدخول والطوارئ) لمنع هجمات الـ Spam.
- رفع الصور يتم في مجلد `/uploads` ويجب التأكد من توافر صلاحيات الكتابة لهذا المجلد في سيرفر الإنتاج.

---

**تم إعداد هذا المستند في 1 يونيو 2026 لضمان سلاسة التسليم للمطورين الجدد.**
