analysis/04-functional-spec/users-management-module.md
Users Management
Users Management Module – Functional Specification
1. Purpose
The Users Management Module handles the administration of all user accounts across the MASARUK platform.
This module covers:
- Viewing all registered users (B2C customers)
- Managing user account status (active/blocked)
- Viewing user booking history
- Admin user management (Admin Panel only)
- Provider staff management (handled in providers-module)
4. User Entity Fields
| Field | Type | Label | Notes |
|---|---|---|---|
| id | PK | — | Auto-generated |
| full_name | String | Full Name | Required |
| String | Email Address | Unique, required | |
| phone | String | Phone Number | Unique, required |
| password_hash | String | — | Encrypted |
| role | Enum | Role | user, admin, super_admin, provider_admin, provider_staff |
| status | Enum | Status | ACTIVE, BLOCKED |
| avatar_url | String | Profile Picture | Optional |
| provider_id | FK (nullable) | — | Only for provider users |
| created_at | Timestamp | Registration Date | Auto |
| updated_at | Timestamp | — | Auto |
5. User Roles
| Role | Arabic | Description |
|---|---|---|
| user | مستخدم (User) | B2C customer |
| admin | مشرف (Admin) | Platform administrator |
| super_admin | مشرف أعلى (Super Admin) | Full system access |
| provider_admin | مدير الشركة (Provider Admin) | Provider company admin |
| provider_staff | موظف الشركة (Provider Staff) | Provider staff member |
6. User Statuses
Activeblocked
| Label | Enum | Meaning |
|---|---|---|
| Active | ACTIVE | User can login and use platform |
| Blocked | BLOCKED | User cannot login |
7. Business Rules
BR-1. Only admins can manage users
CUSTOMER role cannot access this module.
BR-2. Cannot delete users
Users are never deleted; only blocked. This preserves booking history integrity.
BR-3. Blocking a user
When user.status = BLOCKED: User cannot login, existing bookings remain intact, user appears with 'Blocked' badge.
BR-4. Admin cannot block themselves
Prevent self-blocking to avoid admin lockout.
BR-5. Super Admin is protected
Cannot block a super_admin account.
BR-6. Provider users managed separately
Provider staff are managed via providers-and-companies-module.md
BR-7. View user booking history
Admin can view all bookings associated with a user.
8. Actions & Behaviors
A-1. View Users List
Users Management → Users Table → Columns: Name, Email, Phone, Role, Status, Registration Date → Filter by Role / Status → Search by Name or Email
A-2. View User Details
Users List
→ Select User
→ Eye Icon
→ View Details:
- Personal Data
- Bookings List
- Account StatusA-3. Block User
User Details → "Block User" Button → Confirmation Modal: "Are you sure you want to block this user?" → Confirm → Status changes to "Blocked"
A-4. Unblock User
User Details (Blocked) → "Unblock" Button → Confirmation Modal → Confirm → Status changes to "Active"
9. UI Structure
Users List Screen
┌─────────────────────────────────────────────────────────┐ │ Sidebar │ Users Management │ │ │ ┌─────────────────────────────────────────┐│ │ │ │ Search: [____________] Filter: [▼] ││ │ │ └─────────────────────────────────────────┘│ │ │ ┌─────────────────────────────────────────┐│ │ │ │ Name │ Email │ Phone │ Role │ Status│Actions││ │ │ │──────────────────────────────────────────│ │ │ │ John │ j@x.com│ 05... │ User │ Active│ 👁️ ││ │ │ │ Ahmed│ a@x.com│ 05... │ User │ Blocked│ 👁️ ││ │ │ └─────────────────────────────────────────┘│ │ │ [Pagination: < 1 2 3 ... >] │ └─────────────────────────────────────────────────────────┘
10. Error Cases
| Case | Message |
|---|---|
| No users found | No users match the search criteria |
| Attempt to block self | You cannot block your own account |
| Attempt to block super_admin | Cannot block Super Admin |
| User has active bookings | Warning: This user has active bookings |
| Network error | Error loading data. Please try again. |
12. Access Permissions (RBAC)
| Role | View Users | View Details | Block/Unblock |
|---|---|---|---|
| SUPER_ADMIN | ✅ | ✅ | ✅ |
| ADMIN | ✅ | ✅ | ✅ (not super_admin) |
| FINANCE_ADMIN | ❌ | ❌ | ❌ |
| PROVIDER_ADMIN | ❌ | ❌ | ❌ |
| PROVIDER_STAFF | ❌ | ❌ | ❌ |
| CUSTOMER | ❌ | ❌ | ❌ |
13. Saved Travelers Directory (Slice 4)
SSOT: analysis/04-functional-spec/users-management-module.md §15
Users can save frequently-used traveler information in their profile for faster booking.
Official Decisions
- • DEC-S4-01: Travelers Directory in Profile → المسافرين
- • DEC-S4-02: Relationship field: CHILD, PARENT, SIBLING, FRIEND, OTHER
- • DEC-S4-03: Birth date optional for domestic trips
SavedTraveler Entity Fields
| Field | Type | Required |
|---|---|---|
| full_name_ar | String | ✅ Domestic |
| full_name_en | String | ✅ International |
| gender | Enum | ✅ (MALE|FEMALE) |
| document_type | Enum | ✅ Domestic |
| document_number | String | ✅ |
| birth_date | Date | ⚠️ Optional (domestic) |
| passport_number | String | ✅ International |
| passport_expiry | Date | ✅ International |
| nationality | String | ✅ International |
| relationship_type | Enum | ⚠️ Optional |
| phone | Phone | ⚠️ Optional (DEC-S3-01) |
Business Rules
- • ST-BR-1: Maximum 20 saved travelers per account
- • ST-BR-2: Cannot save duplicate document_number
- • ST-BR-3: Deleting does not affect existing bookings