WFDASH-WEBAPP/docs/rep-performance-data-source.md

# Rep Performance Report — Data Source & Provenance

> **Audience:** anyone who asks where the numbers come from — a manager, an
> auditor, a customer-facing colleague.
> **Scope:** `/reports/rep-performance` (summary, per-rep detail, team
> comparison) and the PDF download.
> **Author context:** WFDash is the operator app (Next.js + PocketBase). This doc
> describes where every figure on the report originates, so the report can be
> defended without reading the code.

---

## TL;DR

The report is **two separate things stitched together**, and it matters that
you can tell them apart:

| | **A — Activity** | **B — Time log** |
|---|---|---|
| What it is | Quotes, orders, delivery notes, customers, companies | "Where the time went", visit map, hours per place |
| Source | **WFDASH itself** (PocketBase) | **Hardwired vehicle tracker** (GPS unit in the truck) |
| Entered by | Reps working in the app; some quotes arrive by email automation | A CSV export from the tracker portal, imported by a manager |
| On a phone? | No — server-side database | No — a fixed vehicle unit, not a personal phone |
| Pages in the PDF | 1, 3, 4, 5, 6 | 2 (and the map behind it) |

**The charts anyone is likely to challenge — quotes loaded, orders placed,
customers visited, companies — are all Section A, and every one of them is a
read-only count of rows that already exist in WFDASH.** Nothing on those pages
is typed in by a person for reporting purposes; the report only counts work
the reps already did in the normal course of business.

The only non-WFDASH input is Section B, and it is confined to two clearly
labelled pages.

---

## 1. Topology — where the data physically comes from

```
        WHO ENTERS THE DATA
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
  Reps working in the app   n8n email intake
   quotes · orders          quotes from RFQ mail
        │                       │
        │     order_items       │
        │  (cancellation check) │
        │                       │
        └───────────┬───────────┘
                    ▼
          ┌───────────────────┐
          │  delivery_notes   │  raised & completed
          └─────────┬─────────┘
                    ▼
 ══════════════════════════════════════════════════════
      WFDASH  →  POCKETBASE          (system of record)
      quotes · quotes_items · orders · order_items
      delivery_notes · customers · companies · users
 ══════════════════════════════════════════════════════
                    │
                    │  read-only counts — nothing is created
                    ▼
          ┌───────────────────┐
          │   REP PERFORMANCE │
          │   REPORT          │  (this document)
          └─────────┬─────────┘
                    ▼
            screen  ·  PDF download
```

---

## 2. Section A — Activity metrics (system of record)

Every row below is a **count of existing WFDASH records** inside the selected
date window. The report creates nothing, edits nothing, and nobody enters a
"report number" anywhere.

| Report column | Collection | Field counted | Rule |
|---|---|---|---|
| **Quotes loaded (QL)** | `quotes` | `created` | Any quote created in the window. |
| **Quotes done (QD)** | `quotes` | `created` + `status` | Quote **and** `claimed_by` set **and** status is `emailed`, `approved` or `sent`. |
| **Orders placed (OP)** | `orders` | `created` | Order in the window, **minus** any order with at least one `order_items` row marked `cancelled`. |
| **Delivery notes (DN)** | `delivery_notes` | `created` | DN in the window, excluding `cancelled`. |
| **Orders received (OR)** | `delivery_notes` | `created` + `status` | DN in the window with status `completed`. |
| **Customers / Companies** | `customers`, `companies` | — | Derived from the rows above; customers roll up to the company on the customer record. |
| **Total** | — | — | Plain sum of the five metrics above. Not weighted, not scored. |

**Code of record:** `src/lib/server/rep-performance-service.ts` (the counting
loop is `loadActivity`). The `QD` status list and the order-rep resolver are
imported from `src/lib/server/boss-dashboard-service.ts`, so this report and
the boss dashboard cannot drift apart.

### Date filtering

Every collection is filtered on the same generated window:

```
created >= "<from> 00:00:00.000Z" && created < "<to+1 day> 00:00:00.000Z"
```

The upper bound is pushed out one day so the last day is **inclusive** — a
common off-by-one that would otherwise silently drop activity on the final day
of the month.

---

## 3. Who gets the credit (attribution)

This is the part most worth explaining, because "whose number is it?" is the
usual challenge.

| Metric | Credited to |
|---|---|
| Quotes loaded, Delivery notes, Orders received | The rep who **owns the customer** (`customers.rep`) |
| Quotes done | The rep who **claimed the quote** (`quotes.claimed_by`) |
| Orders placed | The rep on the **order itself** (`orders.rep`) — *not* the customer's owner |

Orders deliberately follow the order's own rep field, matching the boss
dashboard. A rep who is covering someone else's customers shows their orders
under their own name, which is the behaviour the business expects.

### ⚠️ Known quirk worth knowing about

`orders.rep` is a **free-text field** that over the years holds *either* a
PocketBase user id *or* a person's name. The report resolves both: exact user
id first, then a case-insensitive name match. This is not a cosmetic detail —
for Tiaan in September 2026 it is the difference between 1 order and 27:

| How you look it up | Result |
|---|---|
| `orders.rep = "<user id>"` | 1 |
| `orders.rep = "Tiaan"` | 26 |
| **Report total** | **27** |

If someone queries the database themselves and gets a small number, this is
why.

---

## 4. Section B — The time log (vehicle tracker, not WFDASH)

Stated plainly: **the "where the time went" page is not sourced from WFDASH.**
It is sourced from a GPS tracking unit fitted to the vehicle. It is kept in a
separate section of the report for exactly this reason, and it should be
presented differently from Section A if it is challenged.

### 4.1 How it gets in

1. A manager downloads a **"Travel History" CSV** from the tracker's web portal.
2. They upload it on the report page (*Import time log*).
3. The file is parsed and written into PocketBase as `rep_trip_legs` — **one
   row per tracker interval, with no interpretation applied at import time.**

```
   ══════ SEPARATE PROVENANCE — NOT WFDASH ══════

┌────────────────────────────────┐   hardwired unit in the truck,
│ Vehicle GPS tracker            │   logs position every few minutes
│ (vehicle registered in         │
│  users.tracker_vehicle_id)     │
└────────────────────────────────┘
                 │   manager downloads the CSV from the tracker
                 │   portal, then uploads it on the report page
                 ▼
┌────────────────────────────────┐   one row per tracker interval,
│ rep_trip_legs                  │   stored in PocketBase as a copy
│ (raw, un-interpreted)          │
└────────────────────────────────┘
                 │   read-time derivation:
                 │   work-hours clip · 250 m clustering ·
                 │   company matching · operator labels
                 ▼
┌────────────────────────────────┐   PDF page 2 + the visit map
│ "Where the time went"          │
└────────────────────────────────┘
```

Storing raw and deriving at read time is deliberate: if company coordinates or
weekend rules are corrected tomorrow, historical reports improve immediately
with **no re-import**.

Which vehicle belongs to which rep is recorded on the user
(`users.tracker_vehicle_id`, e.g. `MW13TCGP`), so a CSV cannot be silently
attached to the wrong person.

Re-importing a file **replaces only the dates that file covers**, so importing
October does not destroy September.

### 4.2 What is derived (and therefore arguable)

| Derived value | Rule | Why it exists |
|---|---|---|
| Work hours | 07:30–17:00, local (SAST, UTC+2, no DST) | One global default across the fleet. |
| Weekends | **Excluded** | A truck is often out or parked at weekends for reasons unrelated to selling. One flag flips this back on. |
| Noise filter | Stops under **5 minutes** dropped | Traffic lights, gate checks, GPS drift. Applied at *period* level, so a place survives or drops whole rather than losing a 4-minute sliver. |
| Clustering | Points within **250 m** of each other become one "place" | Keeps neighbouring mine gates apart while absorbing GPS jitter when parked. |
| Place name | Matched against **`companies.coordinates` within 750 m** | `customers.coordinates` is deliberately **ignored** — those are residential addresses, and reporting "visited: a customer's house" would be worse than no name. |
| Unnamed places | Operator-assigned labels, stored in `place_overrides`, matched by proximity (300 m) | Most company records have no coordinates yet, so an unnamed place is a placeholder the manager can name on the map. |

**Consequence to be honest about:** a place only carries a company name if the
company has usable coordinates **or** someone has mapped it manually. Unmapped
places show as a raw location, not as a company. The time log is a strong
signal on *how the time was spent*; it is only as good as the mapping for
*naming* it.

---

## 5. How to verify any number yourself

The report is read-only, so anyone with admin access can reproduce its figures
directly from the database. Worked example — **Tiaan, September 2026**, the
exact period in the sample PDF:

| Report says | Raw PocketBase query | Result |
|---|---|---|
| Orders placed = 27 | `orders` where `rep` = id **or** `"Tiaan"`, created in Sept | 1 + 26 = **27** ✓ |
| Delivery notes = 3 | `delivery_notes` where `customer.rep` = Tiaan, `status != "cancelled"` | **3** ✓ |
| Orders received = 2 | same, `status == "completed"` | **2** ✓ |
| Time log rows = 692 | `rep_trip_legs` where `rep` = Tiaan | **692** ✓ |

The same check works in the WFDASH admin UI, or via the PocketBase admin API
with a filter such as:

```
customer.rep = "54uj39i4juqkh9x" && created >= "2026-09-01 00:00:00.000Z"
            && created < "2026-10-01 00:00:00.000Z" && status != "cancelled"
```

Every metric is a plain count of rows returned by a filter like this one. There
is no spreadsheet step, no manual tally, and no intermediate cache to explain.

---

## 6. Which reps appear

The rep list is **not hardcoded**. Someone appears on the report if they own a
customer, claimed a quote in the period, or carry the `REP` user type. This
means:

- a new rep shows up without a code deploy;
- a rep with no activity in the period drops off naturally;
- accounts matching `test` / `qa` / `demo` are filtered out automatically.

The summary page can additionally hide low-activity reps via the **Min total**
control; this is a display filter only and does not change any underlying total.

---

## 7. Honest limitations

Stated up front so nobody is caught out:

1. **"Orders received" is approximated by completed delivery notes.** The
   natural source would be `order_items.delivered_at`, but that field is empty
   on every current record, so a completed DN is used instead. If delivery-note
   completion is not always entered promptly, this figure runs behind reality.
2. **Order cancellation is coarse.** An order with *any* cancelled line is
   excluded entirely, not just the cancelled portion.
3. **The time log's place names depend on manual mapping** (section 4.2).
4. **Work hours are a single fleet-wide default**, not per-rep shifts.
5. **The report reflects the selected period only.** A quote loaded in August
   and sent in September counts its *completed* event in September.

---

## 8. Where the code lives

| Concern | File |
|---|---|
| Counting, attribution, company rollups | `src/lib/server/rep-performance-service.ts` |
| Shared status rules (kept in step with boss dashboard) | `src/lib/server/boss-dashboard-service.ts` |
| Tracker CSV parsing | `src/lib/server/travel-history-parser.ts` |
| Time log import + read-time derivation | `src/lib/server/rep-time-log-service.ts` |
| PDF layout (A4 portrait, 6 pages) | `src/lib/pdf/rep-performance-detail-document.tsx` |
| API surface | `src/app/api/v1/reports/rep-performance/**` |
| Schema for tracker data | `scripts/migrations/2026-09-28-create-rep-trip-legs.ts` |
| Schema for operator place labels | `scripts/migrations/2026-09-28-create-place-overrides.ts` |

Both the counting service and the CSV parser are covered by unit tests
(`rep-performance-service.test.ts`, `travel-history-parser.test.ts`), so the
rules in this document are enforced by the build rather than by memory.

---

## 9. One-paragraph answer

> "The report counts records in our own WFDASH database. Quotes loaded, orders
> placed and delivery notes are rows the reps created in the app while doing
> their jobs — we just count them. Customers and companies are read straight
> off those rows. The one exception is the 'where the time went' page, which
> comes from the GPS unit fitted to the truck, exported as a CSV and imported
> manually; it's a separate page for that reason. You can reproduce any number
> in section A yourself by filtering the database on the rep and the date
> range — the queries are in section 5."