zerp/LOGIN_WORKFLOW_GUIDE.md

# 🔐 Z.CRM Login & User Access Workflow

## Overview
Complete login workflow with role-based routing for all user types in Z.CRM.

---

## 🚪 Login Flow for All Users

### **Step 1: Access the Login Page**

**URL**: `http://localhost:3001/login`

All users start here regardless of their role.

---

### **Step 2: Enter Credentials**

The system has 3 pre-configured user types:

#### **1. System Administrator (المدير العام)**
```
Email: gm@atmata.com
Password: Admin@123
Role: General Manager
Access: FULL SYSTEM ACCESS
```

#### **2. Sales Manager (مدير المبيعات)**
```
Email: sales.manager@atmata.com
Password: Admin@123
Role: Sales Manager
Access: Contacts, CRM, Limited Inventory, Projects view
```

#### **3. Sales Representative (مندوب مبيعات)**
```
Email: sales.rep@atmata.com
Password: Admin@123
Role: Sales Representative
Access: Contacts, CRM (limited permissions)
```

---

## 🎯 After Login - Role-Based Routing

### **Automatic Redirect to Dashboard**

Upon successful login, **ALL users** are automatically redirected to:
```
http://localhost:3001/dashboard
```

The dashboard **adapts** based on the user's role and permissions:

---

## 📊 Dashboard Experience by Role

### **1. System Administrator / General Manager**

**What They See:**

✅ **Full Dashboard Access**
- Welcome message with their name
- All 6 module cards visible:
  - إدارة جهات الاتصال (Contacts)
  - إدارة علاقات العملاء (CRM)
  - المخزون والأصول (Inventory)
  - المهام والمشاريع (Projects)
  - الموارد البشرية (HR)
  - التسويق (Marketing)

✅ **Admin Panel Access**
- Red Shield icon (🛡️) visible in header
- Click to access `/admin` panel
- Full system administration capabilities

✅ **Statistics Cards**
- All available modules: 6
- Active tasks: 12
- Notifications: 5
- Total contacts: 248

**Example:**
```
مرحباً، admin! 👋
المدير العام - 6 وحدة متاحة
```

---

### **2. Sales Manager (مدير المبيعات)**

**What They See:**

✅ **Limited Dashboard Access**
- Welcome message with their name
- Only authorized module cards:
  - ✅ إدارة جهات الاتصال (Contacts)
  - ✅ إدارة علاقات العملاء (CRM)
  - ✅ المستودعات والأصول (View only)
  - ✅ المهام والمشاريع (View only)
  - ❌ الموارد البشرية (Hidden)
  - ❌ التسويق (Hidden)

❌ **No Admin Panel Access**
- Shield icon NOT visible
- Cannot access `/admin` routes

**Permissions:**
- **Contacts**: View, Create, Edit, Export
- **CRM**: View, Create, Edit, Export, Approve
- **Inventory**: View only
- **Projects**: View only

**Example:**
```
مرحباً، salesmanager! 👋
مدير المبيعات - 4 وحدة متاحة
```

---

### **3. Sales Representative (مندوب مبيعات)**

**What They See:**

✅ **Basic Dashboard Access**
- Welcome message with their name
- Only authorized module cards:
  - ✅ إدارة جهات الاتصال (Contacts)
  - ✅ إدارة علاقات العملاء (CRM)
  - ✅ المستودعات والأصول (View only)
  - ✅ المهام والمشاريع (View only)
  - ❌ All other modules hidden

❌ **No Admin Panel Access**

**Permissions:**
- **Contacts**: View, Create, Edit
- **CRM**: View, Create, Edit
- **Inventory**: View only
- **Projects**: View only

**Example:**
```
مرحباً، salesrep! 👋
مندوب مبيعات - 4 وحدة متاحة
```

---

## 🔒 Permission System

### How Permissions Work

The system uses **Role-Based Access Control (RBAC)** with:

1. **Module Level**: Which modules can be accessed
2. **Permission Level**: What actions can be performed

### Permission Types

| Permission | Arabic | Description |
|------------|--------|-------------|
| `canView` | عرض | Can view records |
| `canCreate` | إنشاء | Can create new records |
| `canEdit` | تعديل | Can edit existing records |
| `canDelete` | حذف | Can delete records |
| `canExport` | تصدير | Can export data |
| `canApprove` | اعتماد | Can approve requests |

---

## 📱 Complete User Journey

### **Journey 1: System Administrator**

```
1. Visit http://localhost:3001
2. Click "تسجيل الدخول" button
3. Enter: gm@atmata.com / Admin@123
4. Click "تسجيل الدخول"
   ↓
5. Redirected to /dashboard
6. See all 6 modules available
7. Notice red Shield icon in header
8. Click Shield icon
   ↓
9. Access /admin panel
10. Manage users, roles, backups, settings
```

### **Journey 2: Sales Manager**

```
1. Visit http://localhost:3001
2. Click "تسجيل الدخول" button
3. Enter: sales.manager@atmata.com / Admin@123
4. Click "تسجيل الدخول"
   ↓
5. Redirected to /dashboard
6. See 4 modules (Contacts, CRM, Inventory-view, Projects-view)
7. No admin access (no Shield icon)
8. Click "إدارة علاقات العملاء" (CRM)
   ↓
9. Access CRM features
10. Can create, edit, approve deals
```

### **Journey 3: Sales Representative**

```
1. Visit http://localhost:3001
2. Click "تسجيل الدخول" button
3. Enter: sales.rep@atmata.com / Admin@123
4. Click "تسجيل الدخول"
   ↓
5. Redirected to /dashboard
6. See 4 modules (limited access)
7. No admin access
8. Click "إدارة جهات الاتصال" (Contacts)
   ↓
9. Access Contacts features
10. Can create and edit contacts only
```

---

## 🛡️ Security Features

### **Authentication**
- ✅ JWT-based authentication
- ✅ Secure token storage (localStorage)
- ✅ Auto-refresh on page reload
- ✅ Automatic logout on token expiry

### **Authorization**
- ✅ Role-based module visibility
- ✅ Permission-level action control
- ✅ Protected routes (ProtectedRoute component)
- ✅ Admin routes restricted to administrators only

### **Session Management**
- ✅ Token stored in localStorage
- ✅ Token sent with every API request
- ✅ Automatic redirect to login if unauthorized
- ✅ Session persistence across page refreshes

---

## 🎨 Visual Indicators

### **For All Users:**
- Profile badge with username
- Role name displayed
- Available modules count
- Last login timestamp

### **For Administrators Only:**
- Red Shield icon (🛡️) in header
- "لوحة الإدارة" tooltip on hover
- Admin panel sidebar access
- Red-themed admin interface

---

## 🔄 Logout Process

All users can logout via:

1. **From Dashboard**: Click "خروج" button (with LogOut icon)
2. **From Admin Panel**: Click "تسجيل الخروج" in sidebar

**What Happens:**
- JWT token removed from localStorage
- User redirected to landing page (`/`)
- All auth state cleared

---

## 🚫 Unauthorized Access Prevention

### **If Not Logged In:**
- Accessing `/dashboard` → Redirected to `/`
- Accessing `/admin` → Redirected to `/`
- Accessing module pages → Redirected to `/`

### **If Logged In (Non-Admin):**
- Accessing `/admin` → Still loads but should show access denied
  - **Note**: Currently relies on frontend check
  - Recommendation: Add backend API route protection

---

## 📊 Permission Matrix by Role

### **General Manager (المدير العام)**

| Module | View | Create | Edit | Delete | Export | Approve |
|--------|------|--------|------|--------|--------|---------|
| Contacts | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| CRM | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Inventory | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Projects | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| HR | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Marketing | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

### **Sales Manager (مدير المبيعات)**

| Module | View | Create | Edit | Delete | Export | Approve |
|--------|------|--------|------|--------|--------|---------|
| Contacts | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
| CRM | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
| Inventory | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Projects | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| HR | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Marketing | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |

### **Sales Representative (مندوب مبيعات)**

| Module | View | Create | Edit | Delete | Export | Approve |
|--------|------|--------|------|--------|--------|---------|
| Contacts | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| CRM | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| Inventory | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Projects | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| HR | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Marketing | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

---

## ✅ Testing Checklist

### **Test Each User Type:**

- [ ] Login with General Manager credentials
- [ ] Verify dashboard shows 6 modules
- [ ] Verify Shield icon is visible
- [ ] Access Admin Panel successfully
- [ ] Logout and verify redirect to landing

- [ ] Login with Sales Manager credentials
- [ ] Verify dashboard shows 4 modules
- [ ] Verify no Shield icon
- [ ] Cannot access /admin (redirected)
- [ ] Logout successfully

- [ ] Login with Sales Rep credentials
- [ ] Verify dashboard shows 4 modules
- [ ] Verify limited permissions
- [ ] Cannot access /admin
- [ ] Logout successfully

---

## 🎯 Summary

**Z.CRM Login Workflow:**

1. ✅ **Single Login Page** for all users
2. ✅ **JWT Authentication** with secure tokens
3. ✅ **Role-Based Dashboard** that adapts to user permissions
4. ✅ **Admin Panel Access** only for administrators
5. ✅ **Module Visibility** based on permissions
6. ✅ **Protected Routes** prevent unauthorized access
7. ✅ **Session Management** with auto-logout
8. ✅ **Clean Logout** with token cleanup

**All users → Login Page → Dashboard (role-based) → Features (permission-based)**

---

## 🔗 Quick Access Links

- **Landing Page**: http://localhost:3001
- **Login Page**: http://localhost:3001/login
- **Dashboard**: http://localhost:3001/dashboard (requires auth)
- **Admin Panel**: http://localhost:3001/admin (admin only)

---

© 2024 Z.CRM - نظام إدارة علاقات العملاء