# Fleet Management System - User Manual

## 1. Overview

The Fleet Management System is used to manage vehicles, drivers, fuel, maintenance, workshops, compliance documents, logistics requests, approvals, reports, and administration setup.

The system is permission based. Users only see the menu items and actions allowed for their role. If a page or button is missing, contact an administrator to review your role permissions.

## 2. Getting Started

### 2.1 Sign in

1. Open the system URL in your browser.
2. Enter your email or username and password.
3. Click **Login**.

If you forget your password, use **Forgot Password** on the login page. Follow the password reset instructions sent by email.

### 2.2 Main navigation

After login, the sidebar contains the main work areas:

- **Dashboard**: Fleet overview, KPIs, alerts, and recent activity.
- **Fleet**: Vehicles, drivers, insurance, incidents, and GPS tracking.
- **Fuel**: Fuel vouchers and fuel cards.
- **Maintenance**: Maintenance jobs, service schedules, workshops, parts, and tyres.
- **Logistics**: Trips, vehicle requisitions, approvals, expenses, and compliance.
- **Intelligence**: AI insights and recommendations.
- **Settings**: Company, users, permissions, setup tables, alerts, and workflow templates.
- **Reports**: Operational reports, exports, audit logs, and scorecards.
- **My Profile**: Your user profile.
- **Logout**: Sign out of the system.

## 3. Common Screen Controls

Most list pages use the same pattern:

- **KPI cards** show totals and status summaries.
- **Search box** filters records by common fields.
- **Status/date filters** narrow the list.
- **Add/New button** creates a new record.
- **Pencil icon** edits a record.
- **Trash icon** deletes or removes a record when permitted.
- **Power icon** activates or deactivates setup records.
- **Eye icon** views details.
- **Export buttons** download records where export is available.

Always save changes before closing a modal. For workflow actions, comments may be required for rejection, return, cancellation, or override decisions.

## 4. Dashboard

Use the dashboard as the daily command center.

Typical dashboard information includes:

- Total fleet and active vehicle counts.
- Maintenance and compliance alerts.
- Fuel, trip, and operations summaries.
- Recent audit or activity entries.
- Upcoming expiries and operational exceptions.

Review the dashboard at the start of each day to identify overdue documents, pending approvals, and active jobs that need attention.

## 5. Fleet Module

### 5.1 Vehicles

Use **Fleet > Vehicles** to maintain the vehicle register.

Common tasks:

1. Click **Add Vehicle** or the page's new-record button.
2. Enter plate number, type, model, ownership, branch, department, mileage, and other required information.
3. Save the record.
4. Use the edit button to update vehicle information.
5. Open a vehicle profile to review insurance, licenses, maintenance history, trip usage, and cost information.

Keep vehicle type, model, owner, branch, and department setup records up to date so vehicle forms have accurate dropdown options.

### 5.2 Drivers

Use **Fleet > Drivers** to manage driver records.

Common tasks:

- Add driver biodata and contact details.
- Upload or update driver photos where available.
- Track license details, training, certifications, medical records, and violations.
- Open a driver profile for a complete driver history.

Driver data supports assignment, scorecards, compliance checks, and operational reporting.

### 5.3 Insurance

Use **Fleet > Insurance** to record vehicle insurance policies.

For each policy, capture the vehicle, insurer, policy number, coverage dates, premium, and status. Update policy records before they expire so dashboard and reports remain accurate.

### 5.4 Incidents

Use **Fleet > Incidents** to log accidents, damage, traffic issues, or other vehicle incidents.

Capture the vehicle, driver, date, location, description, severity, cost impact, and follow-up status. Incident records feed driver performance and fleet risk reports.

### 5.5 GPS Tracking

Use **Fleet > GPS Tracking** to view or manage tracker-related vehicle information. Tracker providers and device integration settings are configured under **Settings > Tracker Integrations**.

## 6. Fuel Module

### 6.1 Fuel Vouchers

Use **Fuel > Fuel Vouchers** to record and manage fuel requests or voucher usage.

Typical workflow:

1. Create a fuel entry for a vehicle or driver.
2. Enter fuel station, quantity, unit price, odometer, and supporting details.
3. Submit or save the record.
4. Review approvals where required.
5. Use reports to monitor fuel consumption and exceptions.

### 6.2 Fuel Cards

Use **Fuel > Fuel Cards** to manage fuel cards assigned to vehicles, drivers, or operational units.

Track card number, provider, assigned vehicle or user, status, limits, and usage. Deactivate cards that are lost, expired, or no longer in use.

### 6.3 Fuel Setup

Use **Settings > Fuel Setup** to configure fuel-related reference data, rules, or approval settings used by the fuel module.

## 7. Maintenance Module

Use **Maintenance > Maintenance** to manage vehicle repairs and work orders.

High-level maintenance flow:

1. Log a complaint or maintenance issue.
2. Approve or reject the complaint.
3. Raise a work order with line items.
4. Send RFQs to workshops or select a workshop.
5. Capture and vet quotes.
6. Approve the final amount.
7. Send the job order to the workshop.
8. Mark work done.
9. Inspect the work.
10. Validate internal control and close the job.
11. Raise and approve payment requisition where required.
12. Record payment status.

The maintenance page includes stage filters, job action buttons, RFQ management, timeline history, and PDF generation for work orders and job orders.

For the detailed 16-stage maintenance workflow, see `docs/maintenance_user_manual.md`.

### 7.1 Service Schedules

Use **Maintenance > Service Schedules** to create preventive maintenance intervals.

Common tasks:

- Add scheduled tasks by vehicle, mileage, date, or interval.
- Edit intervals when maintenance plans change.
- Generate preventive maintenance jobs from due schedules.

### 7.2 Workshop

Use **Maintenance > Workshop** to manage workshop-facing job activity. Workshop users can review assigned jobs and update permitted job statuses.

### 7.3 Parts

Use **Maintenance > Parts** to manage spare parts stock and usage. Part catalog, suppliers, and bin locations are configured under **Settings**.

### 7.4 Tyres

Use **Maintenance > Tyres** to manage tyre inventory and lifecycle.

Common tyre actions include:

- Add tyres into stock.
- Fit tyres to vehicles.
- Remove fitted tyres.
- Retread tyres.
- Scrap tyres.
- Edit or delete tyre records when permitted.

Tyre brands and tyre models are configured under **Settings**.

## 8. Logistics Module

### 8.1 Trips

Use **Logistics > Trips** to record journeys.

Typical workflow:

1. Create a trip with vehicle, driver, route, purpose, and start details.
2. Save the trip.
3. End the trip when completed.
4. Enter final mileage or trip completion details where required.

Trip records support utilization, driver, cost, and operational reports.

### 8.2 Vehicle Requisition

Use **Logistics > Vehicle Requisition** to request vehicles for journeys or assignments.

Request workflow:

1. Click **New Vehicle Request**.
2. Enter pickup location, destination, journey purpose, dates, passenger count, priority, notes, and supporting document if needed.
3. Click **Save Draft** to keep the request editable, or **Submit** to send it for approval.
4. Approvers review pending requests and can approve, reject, or return them.
5. After approval, an authorized user assigns a vehicle and optional driver.
6. Use **Get Recommendations** in the assignment modal to view AI-suggested vehicle matches when available.

Request statuses include draft, pending, approved, rejected, returned, assigned, in progress, completed, and cancelled.

### 8.3 Approvals

Use **Logistics > Approvals** to review workflow items awaiting your action. Open each item, read the details, add comments where required, and approve, reject, return, or resubmit based on your role.

### 8.4 Expenses

Use **Logistics > Expenses** to record operational expenses connected to vehicles, trips, drivers, or fleet activities. Keep descriptions, amounts, dates, and supporting details clear for reporting and audit review.

### 8.5 Compliance

Use **Logistics > Compliance** to track vehicle documents and renewals such as licenses, permits, roadworthiness, or other regulatory requirements.

Common tasks:

1. Create a new compliance renewal record.
2. Select vehicle, document type, issuing authority or office, vendor, validity dates, and cost.
3. Save the renewal.
4. Update or delete records when corrections are needed and your role permits it.

Use compliance reports to find expired, expiring, and active documents.

## 9. Intelligence

Use **Intelligence > AI Insights** to review system-generated suggestions and risk indicators.

Insight categories may include:

- Overdue maintenance.
- Abnormal fuel consumption.
- Underutilized vehicles.
- Driver incident alerts.
- Route optimization opportunities.

Users with the right permissions can dismiss insights or use AI chat features where enabled.

## 10. Reports

Use **Reports** to review and export operational information.

Available report areas include:

- **Overview**: General report landing page.
- **Compliance Reports**: Document status and expiry reports.
- **Vehicle Reports**: Fleet and vehicle register views.
- **Driver Reports**: Driver records and compliance views.
- **Workshop Reports**: Workshop and repair activity.
- **Maintenance Reports**: Maintenance jobs and workflow status.
- **Fuel Request Report**: Fuel request and voucher reporting.
- **TCO Report**: Total cost of ownership by vehicle.
- **Data Import/Export**: Import and export utilities.
- **Audit Logs**: Immutable activity history and verification tools.
- **Driver Scorecard**: Driver performance and risk scoring.

Use filters before exporting so downloaded files contain the exact period or category needed.

## 11. Administration and Setup

Administration pages are normally restricted to administrators or module managers.

### 11.1 Company Setup

Use **Settings > Company Setup** to maintain company identity and business information used in documents, alerts, and generated outputs.

### 11.2 Users

Use **Settings > Users** to manage system users.

Common tasks:

- Create users.
- Edit names, contact details, and role assignments.
- Activate or deactivate accounts.
- Review access if a user cannot see a menu item or action.

### 11.3 Permissions

Use **Settings > Permissions** to manage role permissions.

Permissions determine which pages, buttons, and API actions a user can access. Changes should be made carefully because they affect operational controls and audit accountability.

### 11.4 Setup Tables

Use setup pages to maintain dropdown values used across the system.

Common setup areas include:

- States, LGAs, regions, cities, and locations.
- Branches, departments, projects, and contract types.
- Vehicle types and vehicle models.
- Insurers, suppliers, compliance vendors, accounts, and owners.
- Issuing authorities and issuing offices.
- Part catalog, bin locations, tyre brands, and tyre models.
- Tracker integrations.

Keep setup records active only when they should remain available for new transactions.

### 11.5 Alert Delivery

Use **Settings > Alert Delivery** to review alert delivery activity and provider responses. Email delivery depends on the mail configuration described in `README_MAIL.md`.

### 11.6 Workflow Templates

Use **Settings > Workflow Templates** to configure reusable approval workflows. Only authorized users should modify templates because they control routing and approval behavior.

## 12. My Profile

Use **My Profile** to review or update your own profile information. If password update is available on your installation, use a strong password and keep it private.

## 13. Data Import and Export

Use **Reports > Data Import/Export** for bulk data movement.

General guidance:

- Download or prepare the correct template before importing.
- Keep column headers unchanged.
- Validate dates, numbers, vehicle plates, and required lookup values.
- Import a small sample first when working with a new file format.
- Review the result message and correct failed rows before retrying.

Exports are useful for offline analysis, reconciliation, and management reporting.

## 14. Audit and Accountability

The system records important actions in audit logs, including user actions, workflow transitions, comments, and selected data changes.

Good audit practice:

- Use your own login only.
- Add clear comments for approvals, rejections, returns, overrides, and cancellations.
- Do not share passwords.
- Review audit logs when investigating disputes or process exceptions.

## 15. Troubleshooting

### I cannot see a menu item

Your role may not have the required permission. Ask an administrator to check **Settings > Users** and **Settings > Permissions**.

### A Save button fails or shows "Unauthorized"

You may have view access but not create, edit, approve, or delete access. Contact an administrator.

### A dropdown is empty

The related setup table may not have active records. Check the relevant setup page, such as vehicle types, departments, suppliers, insurers, or issuing authorities.

### I cannot submit or approve a workflow

Check that all required fields are filled. Some actions require comments, line items, final workshop selection, approved amounts, or policy override reasons.

### Email alerts are not being delivered

Ask an administrator to verify SMTP settings and mail delivery configuration. The project mail setup notes are in `README_MAIL.md`.

### A report does not show expected records

Clear filters, check the date range, confirm record status, and verify that your role has access to the report category.

## 16. Recommended Daily Routine

1. Review **Dashboard** for alerts and pending work.
2. Check **Approvals** for items awaiting your action.
3. Review expiring documents in **Compliance** or **Reports > Compliance Reports**.
4. Review active maintenance jobs and delayed stages.
5. Monitor fuel usage and exceptions.
6. Update trips, requisitions, incidents, and expenses before end of day.
7. Export or review reports needed for management follow-up.