# CompressorIQ — User Manual

**Version:** 0.2 (MVP)  
**Audience:** Service managers / planners and field technicians.

This manual describes each major screen, what it is for, and how to use it. The companion file **`CompressorIQ_User_Guide_Screenshots.pdf`** shows the same pages visually. A **combined PDF** (`CompressorIQ_User_Manual.pdf`) may include this text plus those screenshots—see your administrator or project `scripts/build_combined_manual_pdf.py`.

---

## How this application is organized

CompressorIQ helps you:

1. **See** fleet-wide and per-compressor maintenance history and signals.
2. **Predict / assess** risk using rules and optional AI (health assessment, recommendations).
3. **Prescribe** step-by-step work (workflows attached to recommendations or generated by category).
4. **Dispatch** work orders to technicians and **execute** them in the field.

There are two primary **personas**:

| Persona | Primary goals | Main pages |
|--------|----------------|------------|
| **Manager** | Prioritize units, create and assign work, import data, review AI insights | Dashboard, Compressors, Service Records, **Work orders**, Workflows, Upload |
| **Technician** | See assigned jobs, follow steps, record progress | **My work**, Notifications |

Everyone can use **Dashboard** and **Notifications**; role is about *workflow*, not a separate login today.

---

# Part 1 — Manager persona

Use Part 1 when you oversee the fleet, decide what work to do, assign people, and keep data current.

## 1. Dashboard

**What you see**

- **Fleet overview:** Totals (events, compressors, run hours), preventive/corrective mix, top issue categories, and **machines needing attention** (recent elevated activity).
- **Recent service events:** A short list of the latest work across the fleet.
- **Compressor selector:** Dropdown labeled like “Select Compressor.” Choosing **“All Fleet (Overview)”** keeps the overview; choosing a unit opens **detail** for that asset.

**Why it matters**

This is your situational awareness screen: where to focus before opening or assigning work orders.

**Typical steps**

1. Scan KPIs and “machines needing attention.”
2. Optionally pick a compressor to review detail, health assessment, and recommendations for that unit.
3. Use **Run Assessment** / **Re-assess** to refresh AI/rule-based health output when preparing a decision.
4. If the assessment creates **system work orders** (severe alerts), follow the banner link to **Work orders** to assign them.

**Tips**

- If assessment opens new system work orders, they appear with source **System**; assign a technician when ready.
- API or database issues can delay loading—confirm the API is running if the page hangs.

---

## 2. Compressors (`/machines`)

**What you see**

- A list of compressor **assets** and, when selected, **detail** (stats, last service), **timeline** of service events, and **issue frequency** (categories and counts).

**Why it matters**

Use this for investigations: “What happened on this unit?” before you write a work order or answer a customer.

**Typical steps**

1. Find the unit (list or search behavior depends on your build).
2. Open timeline and issues to understand repeat failures or recent repairs.
3. Switch to **Work orders** to open a corrective or follow-up job if needed.

---

## 3. Service Records (`/service-records`)

**What you see**

- Searchable / browsable **historical service events** (orders, categories, dates, costs where available).

**Why it matters**

Audits, warranty questions, and root-cause review start here—not from Work orders.

**Typical steps**

1. Filter or search for the unit or date range you care about.
2. Open a record for full narrative and linked data.
3. Do **not** confuse this with dispatch: new field work is created under **Work orders**.

---

## 4. Work orders (`/work-orders`) — core manager workflow

**What you see**

- **Fleet queue:** Table of work orders with title, unit, **source**, **status**, assignee, dates.
- **Filters:** Status and compressor to narrow the list.
- **New work order:** Form for compressor, title, description, source, optional link to a **recommendation**, optional **issue category**, optional assignee.
- **Detail panel:** When a row is selected—assign technician, change status, skim **workflow steps** that the technician will see.

**Sources (important)**

- **Predictive** — tied to analytics / recommendations.
- **System** — created automatically (e.g. from health assessment alerts); still needs assignment unless your process auto-assigns elsewhere.
- **Ad hoc** — you create manually for anything outside automated flows.

**Why it matters**

This is where **dispatch** happens: turning analysis into assigned, trackable work with step-by-step guidance.

**Typical steps**

1. Triage the queue (open → in progress → completed).
2. **New work order:** choose compressor and title; link a recommendation if the job comes from AI/engine output; otherwise set **issue category** (or general) so steps generate correctly.
3. Assign a technician from the directory (populated from imported data).
4. Update status as the field reports progress (or let technicians drive status from **My work** where implemented).

**Tips**

- Linking a **recommendation** copies its workflow steps onto the work order snapshot.
- Without a recommendation, steps come from templates by **issue category** (e.g. detonation vs general).

---

## 5. Notifications (`/notifications`)

**What you see**

- A list of **fleet-wide** notices (e.g. system-created work orders) and **assignment** notices targeted to a technician.
- Filters: unread vs all; **Mark all read** to clear.

**Why it matters**

Managers stay aware of automated work and can confirm technicians were notified when assigned.

**Typical steps**

1. Review unread items after assessments or bulk assignments.
2. Mark read when processed.

---

## 6. Workflows (`/workflow`)

**What you see**

- **Recommendations** across machines: issue hints, confidence, status, links into detailed workflow views.

**Why it matters**

Bridges **insight** → **work order**: you confirm the recommendation, then create or link a work order.

**Typical steps**

1. Sort or scan for high-confidence or urgent items.
2. Open detail to read prescribed steps and evidence.
3. Create a work order from **Work orders** and link the same recommendation when applicable.

---

## 7. Upload Data (`/upload`)

**What you see**

- File upload for maintenance spreadsheets; status of processing; list of past uploads (where implemented).

**Why it matters**

Fresh data powers analytics, technician directory, and dashboards.

**Typical steps**

1. Use the template/format your team agreed on.
2. Upload and wait for completion.
3. Verify **Dashboard** / **Compressors** reflect new events.

---

# Part 2 — Technician persona

Use Part 2 when you perform work in the field and need clear instructions and ownership of tasks.

## 1. My work (`/my-work`)

**What you see**

- **You are:** Dropdown to select **your name** (stored in the browser so it persists).
- **Assigned to me:** Work orders assigned to you (typically open / in progress).
- **Job detail:** Title, unit, description, and **steps** with instructions, rationale, and required evidence.
- Checkboxes to mark steps complete; **Mark work order complete** when done.

**Why it matters**

This is your single queue for **actionable** work—the same steps the manager saw in preview are what you execute.

**Typical steps**

1. Select your name.
2. Open a work order from the list.
3. Follow steps in order; capture evidence as requested (photos, readings, notes—per step text).
4. Mark the work order complete when the job is finished and documented.

**Tips**

- If the list is empty, nothing is assigned to you—contact your manager or check **Notifications**.
- Technician names come from **imported** service data; if you are missing, ask for a data refresh or admin update.

---

## 2. Notifications (`/notifications`)

**What you see**

- Same page as managers, but your **technician** selection (on **My work**) affects which targeted alerts you care about.
- You see **broadcast** (fleet) items plus items **assigned to you** (e.g. new assignment).

**Why it matters**

You learn when new work is assigned without refreshing **My work** constantly.

**Typical steps**

1. Open notifications when prompted or daily.
2. Mark items read after you have opened the work order in **My work**.

---

## 3. Dashboard (technician use)

**What you see**

- Same fleet and per-compressor views as managers.

**Why it matters (for technicians)**

Optional **context** before a job: recent events, health assessment, and alerts for the unit you are about to service.

**Typical steps**

1. Select the compressor you are visiting.
2. Skim assessment and alerts; run **Re-assess** only if you need a fresh snapshot.
3. Perform the actual work in **My work**.

---

## 4. Workflows (optional for technicians)

**What you see**

- Recommendation list and detail—read-only insight.

**Why it matters**

Background on *why* a work order was opened; execution remains under **My work**.

---

# Part 3 — Concepts and troubleshooting

## Work order status

| Status | Meaning |
|--------|---------|
| Open | Not started or not yet picked up in the field |
| In progress | Work underway (e.g. a step completed) |
| Completed | Job finished |
| Cancelled | Superseded or not needed |

## Automated system work orders

When **health assessment** finds **high/critical** alerts (configurable), the system may create **system** work orders with deduplication per compressor and alert. Managers should **assign** technicians and track completion.

## API key (if enabled)

If your deployment uses an **API key**, the browser must send the matching key for mutating operations. If actions fail with 401, check with your administrator.

## Troubleshooting

| Problem | What to try |
|--------|-------------|
| Blank or loading forever | Confirm API URL and that backend is running; check network tab for errors |
| No technicians in dropdown | Ensure maintenance data has been imported so technician records exist |
| No jobs under My work | Confirm manager assigned you on Work orders |
| Slow UI in development | Avoid cloud-synced project folders; use local disk if possible |

---

---

## Regenerating the PDF manuals (admin / developer)

1. **Screenshots only:** `python scripts/capture_screenshots_pdf.py` — updates `CompressorIQ_User_Guide_Screenshots.pdf` and copies it to `frontend/public/`.

2. **Full manual (this text + screenshots):** install `reportlab` and `pypdf`, then run:

   ```bash
   pip install -r scripts/requirements-manual-pdf.txt
   python scripts/build_combined_manual_pdf.py
   ```

   This writes `CompressorIQ_User_Manual.pdf` at the project root and copies it to `frontend/public/` for the sidebar link **Manual PDF (text + screens)**.

3. After editing **`USER_MANUAL.md`**, copy it to **`frontend/public/USER_MANUAL.md`** (or rely on your deploy process) so the in-app **User manual** page stays current.

---

*End of CompressorIQ User Manual*