# Fleet Management System - Role Manual

> **26 roles** defined in database. The first 7 below are the primary consolidated roles; the rest are legacy roles that remain in the system for backward compatibility with workflow/approval stages.

---

## Primary Roles

### 1. Superadmin (ID 31)

**Description:** Full system access. No restrictions. Can perform any operation, manage users, assign permissions, and access all modules.

**Permissions:** All 126 permissions in the system.

**Menu Access:**
| Section | Pages |
|---------|-------|
| Dashboard | Dashboard |
| Fleet | Vehicles, Drivers, Driver Off-Duty, Insurance, Incidents, GPS Tracking, Vehicle Inspection |
| Fuel | Fuel Vouchers, Fuel Cards, Fuel Cash Wallet, Station Consumption Analysis |
| Maintenance | Maintenance, Service Schedules, Workshop, Parts, Tyres |
| Logistics | Trips, Vehicle Requisition, Approvals, Expenses, Compliance |
| Intelligence | AI Insights |
| Settings | All 29 settings pages (Compliance Setup, States, LGAs, Branches, Users, Permissions, etc.) |
| Reports | All 16 report pages |
| Profile | My Profile |
| Auth | Logout |

---

### 2. Admin (ID 1)

**Description:** Full system access (bypasses permission checks via `isAdmin()`). Can manage all modules, users, settings, and reports.

**Permissions (92 assigned):** All core permissions — vehicles, drivers, fuel, maintenance, trips, insurance, incidents, expenses, parts, tyres, settings, users, reports. Missing 34 permissions that are delete/audit_retention/gps_track/power-user permissions not explicitly assigned to role 1.

> **Note:** Despite the database showing 92 explicitly assigned permissions, the `isAdmin()` function in code gives Admin full access regardless. The role operates identically to Superadmin in practice.

**Menu Access:** Same as Superadmin — full access.

---

### 3. Fuel Officer (ID 23)

**Description:** Manages fuel operations — vouchers, cards, wallet payments, and fuel reporting.

| Area | Permission | Action |
|------|-----------|--------|
| **Dashboard** | `dashboard.view` | View dashboard |
| **Fuel** | `fuel.view` | View fuel vouchers & all fuel reports |
| **Fuel** | `fuel.create` | Create fuel vouchers |
| **Fuel** | `fuel.approve` | Approve fuel requests |
| **Fuel Cards** | `fuel_card.view` | View fuel cards |
| **Fuel Cards** | `fuel_card.create` | Create/edit fuel cards |
| **Vehicles** | `vehicle.view` | View vehicle list |
| **Vehicles** | `vehicle.create` | Add vehicles |
| **Vehicles** | `vehicle.edit` | Edit vehicles |
| **Vehicles** | `vehicle.assign` | Assign vehicles to drivers |
| **Reports** | `report.view` | View reports overview & TCO report |
| **Data** | `data.export` | Export data to CSV |
| **Data** | `data.import` | Import data from CSV |

**Menu Access:**
- Dashboard
- Fleet: Vehicles only
- Fuel: Fuel Vouchers, Fuel Cards, Fuel Cash Wallet, Station Consumption Analysis
- Settings: Fuel Setup
- Reports: Overview, Vehicle Reports, Fuel Request Report, Fueling Report, Fuel Consumption Analysis, Fuel Weekly Summary, Fuel Voucher Balance, Fuel Summary Report, TCO Report, Data Import/Export
- Profile, Logout

---

### 4. Inspector (ID 25)

**Description:** Conducts vehicle inspections and manages parts/tyres inventory.

| Area | Permission | Action |
|------|-----------|--------|
| **Dashboard** | `dashboard.view` | View dashboard |
| **Vehicle Inspection** | `vehicle_inspection.view` | View inspections |
| **Vehicle Inspection** | `vehicle_inspection.create` | Create inspections |
| **Vehicle Inspection** | `vehicle_inspection.edit` | Edit inspections |
| **Parts** | `part.view` | View parts inventory |
| **Parts** | `part.create` | Add parts |
| **Parts** | `part.edit` | Edit parts |
| **Tyres** | `tyre.view` | View tyres |
| **Tyres** | `tyre.create` | Add tyres |
| **Tyres** | `tyre.edit` | Edit tyres |
| **Vehicles** | `vehicle.view` | View vehicle list |
| **Vehicles** | `vehicle.create` | Add vehicles |
| **Vehicles** | `vehicle.edit` | Edit vehicles |
| **Vehicles** | `vehicle.assign` | Assign vehicles |
| **Reports** | `report.view` | View reports overview & TCO report |
| **Data** | `data.export` / `data.import` | Import/export data |

**Menu Access:**
- Dashboard
- Fleet: Vehicles, Vehicle Inspection
- Maintenance: Parts, Tyres
- Settings: Vehicle Types, Vehicle Models, Part Catalog Setup, Bin Location Setup, Tyre Brand Setup, Tyre Model Setup
- Reports: Overview, Vehicle Reports, Workshop Reports, TCO Report, Data Import/Export
- Profile, Logout

---

### 5. Maintenance Officer (ID 21)

**Description:** Manages the full maintenance workflow — requests, approvals, workshop, and vehicle/driver records.

| Area | Permission | Action |
|------|-----------|--------|
| **Dashboard** | `dashboard.view` | View dashboard |
| **Maintenance** | `maintenance.view` | View maintenance requests |
| **Maintenance** | `maintenance.create` | Create maintenance requests |
| **Maintenance** | `maintenance.approve` | Approve maintenance requests |
| **Workshop** | `workshop.manage` | Manage workshop operations |
| **Vehicles** | `vehicle.view` | View vehicle list |
| **Vehicles** | `vehicle.create` | Add vehicles |
| **Vehicles** | `vehicle.edit` | Edit vehicles |
| **Vehicles** | `vehicle.assign` | Assign vehicles |
| **Drivers** | `driver.view` | View drivers |
| **Drivers** | `driver.create` | Add drivers |
| **Drivers** | `driver.assign` | Assign drivers |
| **Driver Medical** | `driver.medical.view` | View medical records |
| **Driver Medical** | `driver.medical.create` | Add/edit medical records |
| **Driver Certification** | `driver.certification.view` | View certifications |
| **Driver Certification** | `driver.certification.create` | Add/edit certifications |
| **Driver Training** | `driver.training.view` | View training history |
| **Driver Training** | `driver.training.create` | Add/edit training |
| **Driver Violation** | `driver.violation.view` | View violations |
| **Driver Violation** | `driver.violation.create` | Add violations |
| **Driver Off-Duty** | `driver.off_duty.view/create/edit` | Manage off-duty records |
| **Reports** | `report.view` | View reports overview & TCO |
| **Data** | `data.export` / `data.import` | Import/export data |

**Menu Access:**
- Dashboard
- Fleet: Vehicles, Drivers, Driver Off-Duty
- Maintenance: Maintenance, Service Schedules, Workshop, Parts, Tyres
- Reports: Overview, Vehicle Reports, Driver Reports, Workshop Reports, Maintenance Reports, TCO Report, Data Import/Export
- Profile, Logout

---

### 6. Documentation Officer (ID 22)

**Description:** Manages vehicle documentation, compliance records, insurance policies, and vehicle registration/profile data.

| Area | Permission | Action |
|------|-----------|--------|
| **Dashboard** | `dashboard.view` | View dashboard |
| **Compliance** | `compliance.view` | View compliance records |
| **Compliance** | `compliance.create` | Create compliance records |
| **Insurance** | `insurance.view` | View insurance policies |
| **Insurance** | `insurance.create` | Create insurance policies |
| **Insurance** | `insurance.edit` | Edit insurance policies |
| **Insurer Setup** | `insurer.view` | View insurers |
| **Insurer Setup** | `insurer.create` | Create insurers |
| **Insurer Setup** | `insurer.edit` | Edit insurers |
| **Vehicles** | `vehicle.view` | View vehicle list |
| **Vehicles** | `vehicle.create` | Add vehicles |
| **Vehicles** | `vehicle.edit` | Edit vehicles |
| **Vehicles** | `vehicle.assign` | Assign vehicles |
| **Driver Scorecard** | `driver_scorecard.view` | View driver scorecard |
| **Reports** | `report.view` | View reports overview |
| **Data** | `data.export` / `data.import` | Import/export data |

**Menu Access:**
- Dashboard
- Fleet: Vehicles, Insurance
- Logistics: Compliance
- Settings: Compliance Setup, States, LGAs, Branches, Departments, Regions, Cities, Locations, Issuing Authorities, Issuing Offices, Compliance Vendors, Projects, Contract Types, Accounts, Owners, Insurer Setup
- Reports: Overview, Compliance Reports, Vehicle Reports, TCO Report, Data Import/Export
- Profile, Logout

---

### 7. Safety & Insurance Officer (ID 24)

**Description:** Manages incidents, insurance claims, and vehicle records. Focused on safety compliance and insurance portfolio.

| Area | Permission | Action |
|------|-----------|--------|
| **Dashboard** | `dashboard.view` | View dashboard |
| **Incidents** | `incident.view` | View incidents/accidents |
| **Incidents** | `incident.create` | Create incident reports |
| **Incidents** | `incident.edit` | Edit incident reports |
| **Insurance** | `insurance.view` | View insurance policies |
| **Insurance** | `insurance.create` | Create insurance policies |
| **Insurance** | `insurance.edit` | Edit insurance policies |
| **Vehicles** | `vehicle.view` | View vehicle list |
| **Vehicles** | `vehicle.create` | Add vehicles |
| **Vehicles** | `vehicle.edit` | Edit vehicles |
| **Vehicles** | `vehicle.assign` | Assign vehicles |
| **Driver Scorecard** | `driver_scorecard.view` | View driver scorecard |
| **Reports** | `report.view` | View reports overview |
| **Data** | `data.export` / `data.import` | Import/export data |

**Menu Access:**
- Dashboard
- Fleet: Vehicles, Insurance, Incidents
- Logistics: Expenses
- Settings: Insurer Setup
- Reports: Overview, Vehicle Reports, Driver Scorecard, TCO Report, Data Import/Export
- Profile, Logout

---

## Legacy Roles (for reference)

These roles exist in the database for backward compatibility with workflow stages, maintenance governance, and historical assignments.

| # | Role ID | Role Name | Permissions | Purpose |
|---|---------|-----------|-------------|---------|
| 1 | 2 | Operations | 43 | Day-to-day fleet operations |
| 2 | 3 | Workshop | 44 | Workshop/maintenance execution |
| 3 | 4 | Compliance | 43 | Regulatory compliance management |
| 4 | 5 | Finance | 43 | Financial/expense oversight |
| 5 | 6 | Fleet Officer | 58 | Fleet coordination & requisition approval |
| 6 | 7 | Fleet Manager | 60 | Fleet strategy & driver assignment |
| 7 | 8 | Maintenance Supervisor | 50 | Maintenance workflow supervision |
| 8 | 9 | Procurement Officer | 48 | Parts/supplies procurement |
| 9 | 10 | HOD | 50 | Department head oversight |
| 10 | 11 | QC | 48 | Quality control inspections |
| 11 | 12 | Internal Auditor | 47 | Audit log review |
| 12 | 13 | Maintenance Manager | 49 | Maintenance department management |
| 13 | 14 | Driver | 46 | Driver self-service portal |
| 14 | 15 | Finance Manager | 50 | Budget/expense approval |
| 15 | 16 | Vendor | 47 | External vendor access |
| 16 | 17 | Fleet Operations | 56 | Fleet operational management |
| 17 | 18 | Maintenance Lead | 50 | Maintenance team lead |
| 18 | 19 | Procurement & Finance | 50 | Joint procurement/finance role |
| 19 | 20 | Quality & Oversight | 51 | Quality assurance & oversight |

---

## Actions by Permission Group

| Module | View | Create | Edit | Delete | Approve | Other |
|--------|------|--------|------|--------|---------|-------|
| Vehicles | `vehicle.view` | `vehicle.create` | `vehicle.edit` | `vehicle.delete` | — | `vehicle.assign`, `vehicle.profile.view` |
| Drivers | `driver.view` | `driver.create` | — | `driver.delete` | — | `driver.assign` |
| Fuel | `fuel.view` | `fuel.create` | — | — | `fuel.approve` | — |
| Fuel Cards | `fuel_card.view` | `fuel_card.create` | — | — | — | — |
| Maintenance | `maintenance.view` | `maintenance.create` | — | — | `maintenance.approve` | — |
| Workshop | — | — | — | — | — | `workshop.manage` |
| Parts | `part.view` | `part.create` | `part.edit` | `part.delete` | — | — |
| Tyres | `tyre.view` | `tyre.create` | `tyre.edit` | `tyre.delete` | — | — |
| Trips | `trip.view` | `trip.create` | `trip.edit` | `trip.delete` | — | — |
| Insurance | `insurance.view` | `insurance.create` | `insurance.edit` | `insurance.delete` | — | — |
| Incidents | `incident.view` | `incident.create` | `incident.edit` | `incident.delete` | — | — |
| Expenses | `expense.view` | `expense.create` | `expense.edit` | `expense.delete` | — | — |
| Compliance | `compliance.view` | `compliance.create` | — | `compliance.delete` | — | — |
| Vehicle Inspection | `vehicle_inspection.view` | `vehicle_inspection.create` | `vehicle_inspection.edit` | `vehicle_inspection.delete` | — | — |
| Vehicle Request | `vehicle_request.view` | `vehicle_request.create` | — | — | `vehicle_request.approve` | `vehicle_request.assign` |
| Driver Medical | `driver.medical.view` | `driver.medical.create` | — | `driver.medical.delete` | — | — |
| Driver Certification | `driver.certification.view` | `driver.certification.create` | — | `driver.certification.delete` | — | — |
| Driver Training | `driver.training.view` | `driver.training.create` | — | `driver.training.delete` | — | — |
| Driver Violation | `driver.violation.view` | `driver.violation.create` | — | `driver.violation.delete` | — | — |
| Driver Off-Duty | `driver.off_duty.view` | `driver.off_duty.create` | `driver.off_duty.edit` | `driver.off_duty.delete` | — | — |
| GPS Tracking | `gps_tracking.view` | — | — | — | — | `gps_tracking.history`, `gps_tracking.geofence`, `gps_tracking.api` |
| AI Insights | `ai_insights.view` | — | — | — | — | `ai_insights.chat`, `ai_insights.dismiss` |
| AI Allocation | — | — | — | — | — | `allocation.ai_view`, `allocation.ai_override` |
| Users | `user.view` | `user.create` | `user.edit` | `user.delete` | — | `user.manage` |
| Reports | `report.view` | — | — | — | — | — |
| Audit | `audit.view` | — | — | — | — | `audit.verify`, `audit.retention.manage`, `audit.retention.run` |
| Workflow | `workflow.templates.view` | — | — | — | `workflow.approve`, `workflow.approve_custom` | `workflow.templates.manage` |
| Data | — | — | — | — | — | `data.export`, `data.import` |
| Dashboard | `dashboard.view` | — | — | — | — | — |

---

## Menu-to-Permission Mapping

| Menu Page | Permission Required |
|-----------|-------------------|
| Dashboard | `dashboard.view` |
| Fleet > Vehicles | `vehicle.view` |
| Fleet > Drivers | `driver.view` |
| Fleet > Driver Off-Duty | `driver.off_duty.view` |
| Fleet > Insurance | `insurance.view` |
| Fleet > Incidents | `incident.view` |
| Fleet > GPS Tracking | `gps_tracking.view` |
| Fleet > Vehicle Inspection | `vehicle_inspection.view` |
| Fuel > Fuel Vouchers | `fuel.view` |
| Fuel > Fuel Cards | `fuel_card.view` |
| Fuel > Fuel Cash Wallet | `fuel.view` |
| Fuel > Station Consumption Analysis | `fuel.view` |
| Maintenance | `maintenance.view` |
| Maintenance > Service Schedules | `maintenance.create` |
| Maintenance > Workshop | `workshop.view` |
| Maintenance > Parts | `part.view` |
| Maintenance > Tyres | `tyre.view` |
| Logistics > Trips | `trip.view` |
| Logistics > Vehicle Requisition | `vehicle_request.view` |
| Logistics > Approvals | Always visible |
| Logistics > Expenses | `expense.view` |
| Logistics > Compliance | `compliance.view` |
| Intelligence > AI Insights | `ai_insights.view` |
| Settings (parent) | Always visible |
| Settings > Overview | Always visible |
| Settings > Compliance Setup | `compliance.view` |
| Settings > States, LGAs, Branches, etc. | `compliance.view` |
| Settings > Fuel Setup | `fuel.view` |
| Settings > Company Setup | `user.manage` |
| Settings > Users | `user.view` |
| Settings > Permissions | `user.manage` |
| Settings > Insurer Setup | `insurer.view` |
| Settings > Supplier Setup | `supplier.view` |
| Settings > Part Catalog Setup | `part_catalog.view` |
| Settings > Bin Location Setup | `bin_location.view` |
| Settings > Tyre Brand/Model Setup | `tyre_brand.view` / `tyre_model.view` |
| Settings > Tracker Integrations | `tracker_integration.view` |
| Settings > Alert Delivery | `user.manage` |
| Settings > Workflow Templates | `workflow.templates.view` |
| Reports (parent) | Always visible |
| Reports > Overview | `report.view` |
| Reports > Compliance Reports | `compliance.view` |
| Reports > Vehicle Reports | `vehicle.view` |
| Reports > Driver Reports | `driver.view` |
| Reports > Workshop Reports | Always visible |
| Reports > Maintenance Reports | `maintenance.view` |
| Reports > Fuel Reports (6 pages) | `fuel.view` |
| Reports > TCO Report | `report.view` |
| Reports > Data Import/Export | `data.export` |
| Reports > Audit Logs | `audit.view` |
| Reports > Driver Scorecard | `driver_scorecard.view` |
| My Profile | Always visible |