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 - نظام إدارة علاقات العملاء