# Maintenance Module — User Manual

## Overview

The Maintenance Module manages the complete lifecycle of vehicle repairs from complaint logging through to final workshop payment. Each job progresses through a **16-stage workflow**. At each stage, role-specific action buttons determine what happens next.

### Access

Navigate to **Maintenance** in the sidebar. The page shows:
- **4 KPI cards** (Total Jobs, Active Jobs, In Workshop, Awaiting Approval)
- **Stage filter** dropdown to narrow jobs by workflow stage
- **Search bar** to find jobs by vehicle, complaint, or workshop
- **Jobs table** with action buttons per row

### Roles

| Role | Primary Responsibilities |
|------|------------------------|
| **Driver** | Log complaints |
| **Fleet Officer** | Log complaints, view jobs |
| **Admin** | Full access, all actions |
| **Fleet Manager** | Approve complaints, inspect work |
| **Maintenance Supervisor** | Review complaints, raise work orders, send job orders |
| **Procurement Officer** | Invite RFQ vendors, vet quotes |
| **Finance Manager** | Approve amounts, manage requisitions and payments |
| **HOD** | Override policy gates, approve amounts |
| **QC** | Inspect completed work |
| **Internal Auditor** | Validate internal control, close jobs |
| **Workshop / Vendor** | Mark work done |

---

## Workflow Reference

### 1. Complaint Logged

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Approve Complaint** | Maintenance Review | Fleet Manager, Maintenance Supervisor | Comment |
| **Reject Complaint** | Cancelled | Fleet Manager, Maintenance Supervisor | Comment |

Click the **Approve Complaint** or **Reject Complaint** button on the job row. A modal opens where you enter your comment justifying the decision.

**Editing**: You can edit the complaint details (vehicle, description, mileage) via the pencil icon while it's at this stage.

---

### 2. Maintenance Review

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Raise Work Order** | Work Order Raised | Maintenance Supervisor | Line items + Work Order number |

This is where the job becomes operational. Click **Raise Work Order** to open the action modal. You must:

1. Add **line items** — each repair item with description and cost (e.g., "Replace brake pads — 15,000")
2. Enter a **Work Order Number** in the form
3. The stage dropdown will not allow "Work Order Raised" without a work order number

---

### 3. Work Order Raised

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Send RFQ** | RFQ Sent | Procurement Officer, Maintenance Supervisor | Workshop selected |
| **Send Job Order** | Workshop In Progress | Maintenance Supervisor | RFQ sent + final workshop + line items |

Two paths are available:

**Path A — RFQ (Recommended):** Click **Send RFQ** to begin the competitive bidding process. This invites workshop vendors to submit quotes.

**Path B — Direct:** Click **Send Job Order** to bypass RFQ and send the job straight to a workshop. This button is **disabled** unless RFQ vendors and a final workshop have already been selected (used for simple jobs or reopened jobs).

---

### 4. RFQ Sent

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| Invite vendors | stays RFQ Sent | Procurement Officer | Workshop selected |
| Vendor submits quote | Quote Submitted | Vendor (via system) | Amount |

At this stage, the **RFQ Manager** (list-check icon) is your primary tool.

**How to use the RFQ Manager:**

1. Click the **RFQ Manager icon** (list-check) on the job row
2. **Invite vendors:** Select a workshop from the dropdown and click **Add Vendor**. An email invitation is sent automatically. Repeat for all vendors (policy minimum: 3).
3. **Capture quotes:** When a workshop responds, select their RFQ entry in the table. Upload their quote PDF and enter line items (description + cost). Click **Upload Quote**.
4. **Select final workshop:** Once you have 2+ comparable quotes, click **Select as Final** on the best quote. This marks that workshop as the winner.

The RFQ Manager shows policy status panels indicating whether you've met minimum vendor/quote requirements.

---

### 5. Quote Submitted

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Vet Selected Quote** | Quote Vetted | Procurement Officer | Final workshop + amount (HOD override optional) |
| **Approve Final Amount** | Job Order Approved | Finance Manager, HOD | Final workshop + amount |

**Vet Selected Quote:** Opens the vetting panel showing all quotes side-by-side. Enter the vetted amount (may differ from quoted amount) and a vetting note. If policy minimums aren't met, use **HOD Override** (checkbox + reason).

**Approve Final Amount:** Finance or HOD can approve directly from this stage, skipping the vetting step. Enter the approved amount and an approval note.

---

### 6. Quote Vetted

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Approve Final Amount** | Job Order Approved | Finance Manager, HOD | Final workshop + amount |

Same as step 5 — enter the approved amount and note. This is the final financial approval before the job goes to the workshop.

---

### 7. Job Order Approved

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Send Job Order** | Workshop In Progress | Maintenance Supervisor | — |
| **Suspend Job Order** | Suspended | Maintenance Manager, Finance Manager | Comment |
| **Cancel Job Order** | Cancelled | HOD, Finance Manager | Comment |

**Send Job Order** is the primary action — the approved job order is dispatched to the selected workshop. The vehicle is now officially at the workshop.

**Suspend** pauses the job. **Cancel** terminates it permanently.

---

### 8. Workshop In Progress

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Mark Work Done** | Inspection | Workshop/Vendor, Maintenance Supervisor | — |
| **Suspend Job Order** | Suspended | Maintenance Manager, Finance Manager | Comment |

The workshop performs the repairs. When complete, click **Mark Work Done**.

---

### 9. Inspection

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Confirm Work Done** | Internal Control | QC, Fleet Manager | Comment |
| **Reject Work Done** | Workshop In Progress (back) | QC, Fleet Manager | Comment (rework) |

QC or Fleet Manager inspects the vehicle.

- **Confirm Work Done:** Pass — the repair is satisfactory. Enter an inspection comment.
- **Reject Work Done:** Fail — the vehicle goes back to the workshop for rework. Enter the reason.

---

### 10. Internal Control

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Validate Internal Control** | Closed | Internal Auditor | Comment |
| **Close Job Order** | Closed | (alt path) | Comment |

Internal Auditor reviews the complete job — documentation, pricing, process compliance. Click **Validate Internal Control** to close the job officially.

---

### 11. Closed

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Raise Requisition** | Requisition Raised | Finance Manager, HOD | Requisition status = Pending |
| **Send Job Order** | Workshop In Progress | (reopen) | — |

**Raise Requisition** generates the payment requisition for the workshop. This is the bridge between maintenance completion and financial closure.

**Send Job Order** here reopens a closed job and sends it back to the workshop (e.g., if additional repairs are needed).

---

### 12. Requisition Raised

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Approve Requisition** | Requisition Approved | Finance Manager, HOD | — |
| **Reject Requisition** | Requisition Rejected | Finance Manager, HOD | Comment |

Finance reviews the requisition.

- **Approve:** Payment is authorised.
- **Reject:** Payment is denied. Provide a reason. The job returns to Workshop In Progress.

---

### 13. Requisition Approved

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Make Payment** | Payment Made | Finance Manager, HOD | — |
| **Payment Not Made** | Payment Not Made | Finance Manager, HOD | Comment |

Record the payment outcome.

- **Make Payment:** Payment completed.
- **Payment Not Made:** Payment was not made. Enter the reason.

---

### 14. Requisition Rejected

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Send Job Order** | Workshop In Progress | (rework path) | — |

If the requisition was rejected, you can send the job back to the workshop to address the rejection reason.

---

### 15. Payment Made

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Rate Job Order** | stays Payment Made | Finance Manager, HOD | Comment |

Optional — leave a post-completion rating and comment about the workshop and repair quality.

---

### 16. Suspended

| Action | → Stage | Who | Requires |
|--------|---------|-----|----------|
| **Send Job Order** | Workshop In Progress | Maintenance Manager | — |
| **Cancel Job Order** | Cancelled | HOD, Finance Manager | Comment |

From suspension, the job can be **resumed** (back to workshop) or **cancelled** permanently.

---

## The RFQ Manager Modal

Opened via the list-check icon on any job row from **Work Order Raised** onward. Key sections:

| Section | Purpose |
|---------|---------|
| **Work Scope** | Shows the line items from the work order |
| **Vendor Table** | Lists all invited workshops, their quote status, amounts, actions |
| **Quote Capture** | Upload a quote PDF + line items for a selected vendor |
| **Policy Status** | Shows vendors invited / quotes received against minimum requirements |
| **Recommendation** | Highlights the lowest comparable quote |

**Buttons in the table:**
- **Select as Final** — marks a workshop as the winner (rejects others automatically)
- **Resend Invite** — re-sends the email invitation to a vendor
- **Upload Quote** — capture a vendor's quote (file + line items)

---

## HOD Override

When an action modal has a **HOD Override** checkbox:
- Check it if policy minimums (3 vendors, 2 quotes) aren't met
- Enter the **override reason**
- The action proceeds despite the policy gap
- All overrides are logged in the audit trail

Available on: Submit Quote, Vet Quote, Approve Final Amount.

---

## PDF Generation

On any job row, the PDF dropdown (file icon) offers:

| Document | When available |
|----------|---------------|
| Preview Work Order | After work order raised |
| Work Order PDF | After work order raised |
| Preview Job Order | After job order approved |
| Job Order PDF | After job order approved |

PDFs include vehicle info, workshop details, line items, cost breakdown, and signature blocks.

---

## Editing a Job

The **pencil icon** (edit) on a job row lets you update:
- Vehicle, driver, complaint details
- Mileage readings
- Dates, workshop, description

**Cannot edit:** Workflow stage or status — stage changes must go through the action buttons.

The edit button is **hidden** after "Quote Submitted" to prevent modifying an in-flight quote process.

---

## Timeline

The **clock icon** opens the job timeline — a chronological log of every action taken, including:
- Stage transitions (from → to)
- Amount changes
- Comments entered
- Who performed the action

---

## Tips

- Use the **stage filter** dropdown to focus on jobs needing your attention
- The **KPI cards** update automatically when you apply filters
- Always add comments — they appear in the timeline for audit purposes
- When stuck at a policy gate, check if you have **HOD Override** available
- Use **CSV export** on report pages for offline analysis