# Artal CRM — خطة التطوير الاحترافية
### نظام إدارة علاقات العملاء لمندوبي المبيعات الميدانيين

---

## 📍 أين وصلنا — آخر تحديث: 2026-05-17

```
المرحلة 1 — الأساس        ████████████ 100% ✅
المرحلة 2 — العملاء        ████████████ 100% ✅ (يحتاج اختبار)
المرحلة 3 — الصفقات       ████████████ 100% ✅ (يحتاج اختبار)
المرحلة 4 — التقارير       ████████████ 100% ✅ (يحتاج اختبار)

الحالة الكلية: الكود مكتوب — قيد الاختبار والإصلاح 🔧
```

### ✅ مكتمل ومرفوع على GitHub
- [x] هيكل المشروع (مستودع منفصل، تاريخ git نظيف)
- [x] `database/db.js` — schema كامل (clients, client_activities, tasks, admin_users, audit_log, settings)
- [x] `server.js` — منظّف، بدون /apply
- [x] `routes/admin.js` — Login/Logout/Dashboard/Settings/Audit/Ping
- [x] `routes/clients.js` — CRUD + أنشطة + تصدير Excel
- [x] `routes/pipeline.js` — Kanban API + drag & drop move
- [x] `routes/tasks.js` — قائمة/إضافة/إنجاز/حذف
- [x] `routes/reports.js` — Pipeline + أداء + مصادر
- [x] `routes/users.js` — إدارة المستخدمين
- [x] `views/login.ejs` — تصميم احترافي
- [x] `views/dashboard.ejs` — Pipeline cards + تنبيهات + Chart.js
- [x] `views/clients.ejs` — جدول + فلاتر + pagination
- [x] `views/client-detail.ejs` — بطاقة + timeline + modal
- [x] `views/client-form.ejs` — نموذج إضافة/تعديل
- [x] `views/pipeline.ejs` — Kanban drag & drop
- [x] `views/tasks.ejs` — مهام بتبويبات
- [x] `views/reports.ejs` — تقارير بـ Chart.js
- [x] `views/audit.ejs` — سجل التدقيق
- [x] `views/settings.ejs` — الإعدادات
- [x] `views/users.ejs` — إدارة المستخدمين
- [x] `views/partials/sidebar.ejs` — sidebar RTL احترافي
- [x] نظام الصلاحيات (مدير/موظف)
- [x] إصلاح مشكلة تسجيل الدخول (session.save + sameSite: lax)

### 🔧 قيد الاختبار والإصلاح (الخطوة التالية)
- [ ] التأكد من عمل تسجيل الدخول على السيرفر
- [ ] اختبار إضافة عميل جديد
- [ ] اختبار بطاقة العميل وإضافة أنشطة
- [ ] اختبار Pipeline Kanban
- [ ] اختبار صفحة المهام
- [ ] اختبار التقارير والرسوم البيانية
- [ ] اختبار تصدير Excel
- [ ] إصلاح أي أخطاء تظهر أثناء الاختبار

### 🔜 ما لم يُنفَّذ بعد (مرحلة قادمة)
- [ ] Bulk actions (تغيير مرحلة/مندوب لمجموعة دفعة واحدة)
- [ ] إشعارات real-time للمهام المتأخرة
- [ ] تصدير تقارير PDF

---

## نظرة عامة

نظام CRM مخصص لمندوبي المبيعات في شركات التسويق، يتيح متابعة العملاء
ميدانياً وعبر جميع قنوات التواصل، مع pipeline مرئي للصفقات وتقارير أداء
تفصيلية لكل مندوب.

**المكدس التقني:** Node.js · Express · MySQL · EJS · Tailwind CDN
**المستودع:** https://github.com/mohammedALrabeai/artal-crm (private)
**بيانات الدخول الافتراضية:** admin@company.com / Admin@2025

---

## أولاً: هيكل قاعدة البيانات ✅

### 1. جدول العملاء `clients`
```sql
id, full_name, company, phone, email, city, region, address,
source (field|referral|cold_call|ad|social|exhibition|other),
stage  (lead|contacted|visited|proposal|negotiation|closed_won|closed_lost),
priority (1|2|3), deal_value, rating (0-5),
next_visit_date, last_contact_at, assigned_to,
tags, activity_count, visit_count, created_at, updated_at
```

### 2. جدول الأنشطة `client_activities`
```sql
id, client_id, type (call|visit|whatsapp|email|note|stage_change|meeting),
content, outcome (positive|neutral|negative), next_action,
scheduled_at, user_id, user_name, created_at
```

### 3. جدول المهام `tasks`
```sql
id, client_id, title, description, due_date,
priority, status (pending|done|cancelled),
assigned_to, created_by, created_at
```

### 4. جداول موروثة
- `admin_users` · `audit_log` · `settings`

---

## ثانياً: صفحات النظام ✅

| الصفحة | المسار | الحالة |
|--------|--------|--------|
| تسجيل الدخول | `/admin/login` | ✅ مكتمل |
| لوحة التحكم | `/admin/dashboard` | ✅ مكتمل |
| قائمة العملاء | `/admin/clients` | ✅ مكتمل |
| بطاقة العميل | `/admin/clients/:id` | ✅ مكتمل |
| إضافة/تعديل | `/admin/clients/new` | ✅ مكتمل |
| Pipeline Kanban | `/admin/pipeline` | ✅ مكتمل |
| المهام | `/admin/tasks` | ✅ مكتمل |
| التقارير | `/admin/reports` | ✅ مكتمل |
| المستخدمون | `/admin/users` | ✅ مكتمل |
| سجل التدقيق | `/admin/audit` | ✅ مكتمل |
| الإعدادات | `/admin/settings` | ✅ مكتمل |
| تشخيص | `/admin/ping` | ✅ مؤقت |

---

## ثالثاً: مراحل الصفقة ✅

| الرمز | المرحلة | اللون |
|-------|---------|-------|
| `lead` | عميل محتمل | رمادي |
| `contacted` | تم التواصل | أزرق |
| `visited` | تمت الزيارة | بنفسجي |
| `proposal` | عرض سعر | برتقالي |
| `negotiation` | تفاوض | أصفر |
| `closed_won` | مكتسب ✅ | أخضر |
| `closed_lost` | خسارة ❌ | أحمر |

---

## رابعاً: نظام الصلاحيات ✅

| الصلاحية | مدير | موظف/مندوب |
|----------|:----:|:----------:|
| رؤية جميع العملاء | ✅ | ❌ عملاؤه فقط |
| إضافة عميل | ✅ | ✅ |
| تعديل/حذف عميل | ✅ | عملاؤه فقط |
| تعيين مندوب | ✅ | ❌ |
| تقارير الفريق | ✅ | تقاريره فقط |
| إدارة المستخدمين | ✅ | ❌ |
| سجل التدقيق | ✅ | ❌ |
| الإعدادات | ✅ | ❌ |

---

## خامساً: التصميم ✅

- **اللون الرئيسي:** `#1a3c6e`
- **النجاح:** `#10b981` · **الخطر:** `#ef4444` · **التحذير:** `#f59e0b`
- **RTL كامل** · **Mobile-first** · **Tailwind CDN** · **Material Icons**
- مؤشر الركود: 🟢 أقل من 3 أيام · 🟡 3-7 أيام · 🔴 أكثر من 7 أيام

---

## سادساً: هيكل الملفات الحالي

```
artal-crm/
├── server.js              ✅
├── database/db.js         ✅
├── middleware/
│   ├── auth.js            ✅
│   └── requireManager.js  ✅
├── routes/
│   ├── admin.js           ✅
│   ├── clients.js         ✅
│   ├── pipeline.js        ✅
│   ├── tasks.js           ✅
│   ├── reports.js         ✅
│   └── users.js           ✅
└── views/
    ├── login.ejs          ✅
    ├── dashboard.ejs      ✅
    ├── clients.ejs        ✅
    ├── client-detail.ejs  ✅
    ├── client-form.ejs    ✅
    ├── pipeline.ejs       ✅
    ├── tasks.ejs          ✅
    ├── reports.ejs        ✅
    ├── audit.ejs          ✅
    ├── settings.ejs       ✅
    ├── users.ejs          ✅
    └── partials/
        └── sidebar.ejs    ✅
```

---

## سابعاً: الـ Commits

| Commit | الوصف |
|--------|-------|
| `b7d345e` | Initial commit — Artal CRM |
| `2682256` | feat: complete CRM system implementation |
| `b529fe5` | fix: login session race condition |

---

*آخر تحديث: 2026-05-17*