fleetops/docs/tickets-inc-overhaul-plan.md

# Overhaul FleetOps Tickets → INC operations dashboard

## Context

The FleetOps SPA's **Tickets** tab is currently a full-bleed MapLibre map showing
combined **INC (red) + CRQ (blue)** ticket circles plus live FleetNow vehicles, fed
by the legacy `GET /webhook/tickets` (→ `reporting.fn_tickets_for_map`). Meanwhile,
the `16_fleettickets` repo has designed and documented a richer **INC operations
dashboard** (Phase 2): an open-ticket layer + windowed closed overlay + derived SLA
states + ticket metric cards, served by a new `reporting.fn_inc_dashboard(...)`
function and exposed at `GET /webhook/inc-dashboard`.

We are overhauling the SPA to that documented design. Per the user: **erase the
existing INC + CRQ ticket view and rebuild INC first** (CRQ deferred). INC is fully
documented; CRQ reuses the same machinery later.

**Key blocker found:** `GET /webhook/inc-dashboard` currently **404s** — the DB
function lives in `16_fleettickets/migrations/09_inc_dashboard_fn.sql` but the HTTP
wrapper is not in the `dashboard_api` service. The legacy `/webhook/tickets` returns
200 with live INC+CRQ data (INC ingest is live: 21,301 records, freshness current).

**Decisions (confirmed with user):**
- **Endpoint first, then SPA** — build/verify the API endpoint (+ DB function) and
  confirm it returns real data, *then* overhaul the SPA against the live endpoint.
- **Layout:** dashboard cards + map (matches the existing Logistics/Fuel tabs) — top
  filterbar (cluster / status / window), a metric-cards row, a large map card, and
  by-status / by-cluster tables below.

## Reference docs (source of truth)
- `16_fleettickets/docs/dashboard-api-contract.md` — endpoint params, response shape,
  field semantics (mttr=minutes, sla_state derived, coords `[lng,lat]`, map-vs-metrics gap).
- `16_fleettickets/docs/phase-2-dashboard.md` — `fn_inc_dashboard` signature + metrics.

---

## Phase A — API endpoint (separate repo: `tracksolid_timescale_grafana_prod`)

> File: `~/Downloads/projects/tracksolid_timescale_grafana_prod/dashboard_api_rev.py`.
> Deployed by scp + ssh to the remote host; **staging** instance
> (`fleetapi.fivetitude.com`) runs read-only as `dashboard_ro`. These steps touch a
> live server and may need the user to run the scp/ssh deploy via `! <cmd>`.

### A1. Verify / apply the DB function
- Confirm `reporting.fn_inc_dashboard` exists in the live DB. If absent, apply via
  `16_fleettickets/run_migrations.py` (needs the **write** `DATABASE_URL`; applies
  `09_inc_dashboard_fn.sql`, and `08`/`10` if not already in `tickets.schema_migrations`).
  Migrations are idempotent + ledgered, so re-running is safe.
- Sanity check in psql: `SELECT reporting.fn_inc_dashboard();` → valid JSON
  (open/closed FeatureCollections, metrics, `window.preset='today'`, freshness).

### A2. Add the `/webhook/inc-dashboard` handler
Mirror the existing `tickets()` handler (`dashboard_api_rev.py:275-304`): one
passthrough SQL call, JSON body returned unchanged. Reuse `get_conn`, `_clean`.

```python
from fastapi import FastAPI, Request, Query   # add Query to existing import (line 46)

@app.get("/webhook/inc-dashboard")
def inc_dashboard(
    cluster: str | None = None,
    status:  str | None = None,
    window:  str = "today",
    from_:   str | None = Query(None, alias="from"),   # 'from' is reserved
    to:      str | None = None,
):
    # Validation per the contract:
    #  - window not in {today,week,month,custom}        -> 400
    #  - window == 'custom' with neither from nor to    -> 400
    #  - from/to unparseable, or from >= to             -> 400
    # If either from/to is present, the SQL treats it as custom (window overridden).
    try:
        with get_conn() as conn, conn.cursor() as cur:
            cur.execute(
                "SELECT reporting.fn_inc_dashboard(%s, %s, %s, %s, %s)",
                (_clean(cluster), _clean(status), window,
                 _clean(from_), _clean(to)),
            )
            payload = cur.fetchone()[0] or {}
        return JSONResponse(payload)          # passthrough, unchanged
    except Exception:
        log.exception("inc-dashboard failed")
        return JSONResponse({"error": {"type": "unknown",
            "message": "INC dashboard is unavailable. Try again in a few seconds."}})
```
- Pass `from`/`to` as ISO-8601 strings; PostgreSQL casts text → `timestamptz` on the
  function call. Validate parseability API-side (e.g. `datetime.fromisoformat`) to
  return clean `400`s rather than a 500 from the DB.
- Leave the legacy `/webhook/tickets` handler in place (CRQ / fallback may use it).

### A3. Deploy + verify
- Deploy to staging: scp `dashboard_api_rev.py` → host, scp the staging deploy
  script, `ssh … bash ~/deploy_dashboard_api_staging.sh` (recreates the container).
- Verify against `https://fleetapi.fivetitude.com`:
  - `GET /webhook/inc-dashboard` → 200, documented shape, `open`/`closed` FCs.
  - `?window=month`, `?cluster=MUIGAI%20INN`, `?status=ACCEPTED`,
    `?from=…%2B03:00&to=…%2B03:00` → counts sane; `open` not time-filtered.
  - `?window=bogus` → 400; `?window=custom` (no from/to) → 400.

---

## Phase B — SPA overhaul (`15_fleetops/src/index.html`, single file)

### B1. Erase the existing INC/CRQ view
Remove from `src/index.html`:
- **Markup:** the full-bleed map section `#view-tickets` (lines ~374-390).
- **JS — drop:** `loadTickets()` (calls `/webhook/tickets`), the **CRQ** circle layer,
  combined INC/CRQ summary handling, `showTicketPopup()` (rebuild for INC),
  `TICKET_COLORS`, `ticketStats.crq`.
- **CSS:** keep the map/marker/popup blocks (lines ~182-252) — reused; rename `#tk-*`
  selectors only if the new markup changes ids.

### B2. Keep + reuse (do NOT reinvent)
The vehicle overlay machinery stays — the contract says the SPA overlays FleetNow:
- `loadLive()` (`/webhook/live-positions`, 15s poll), `upsertVeh()`, `showVehPopup()`,
  `vehState()`, `ccColor()`, `pastel()`, `plateTail()`, `BASEMAP`,
  `COST_CENTRE_COLORS`, `CC_PALETTE`, `escapeHtml`, `updateVehScale()`,
  `initTicketsMap()` (rename → `initIncMap()`), the layers-panel builder, the MapLibre
  popup CSS, and the warm-dark palette.
- Filterbar markup/behaviour pattern from the Logistics/Fuel tabs (`.filterbar`,
  custom-range show/hide at `index.html:467-471`, `.card`/`.span*` grid, table
  renderers, `num()`/`intg()`).

### B3. New markup — `#view-tickets` (dashboard cards + map)
- **Filterbar:** `Cluster` select, `Status` select, `Window` select
  (Today / This week / This month / Custom) + custom start/end date inputs (reuse the
  `.ff.custom` show/hide), `Apply`, refresh `↻`.
- **`<main>` 12-col grid:**
  - Metric cards row: **Open now**, **Closed in window**, **Open SLA** (breached /
    at-risk / ok / unknown), **Closed SLA** (compliant / breached), **Avg MTTR**
    (minutes → show as h), **Closure rate** (`per_day_avg` + a small Chart.js sparkline
    from `closure_rate.series`).
  - **Map card** (`.span12`, tall): MapLibre map with layer toggles + SLA legend.
  - **By status** table + **By cluster** table (`.span6` each) from
    `metrics.by_status` / `metrics.by_cluster`.
  - **Freshness** line (exported_at / records_ingested / ingested_at) under the map.

### B4. New JS — INC data + map
- **State:** `incQs()` builds query (`cluster`, `status`, `window`, and `from`/`to`
  when custom). `loadInc()` → `fetch(${API_BASE}/webhook/inc-dashboard?…)`.
- **Dropdowns:** populate `Cluster` / `Status` from the first unfiltered response's
  `metrics.by_cluster` / `metrics.by_status` keys (no dedicated filters endpoint
  exists); keep stable thereafter.
- **Map layers** on one or two GeoJSON sources:
  - **Open INC** — circle layer colored by `sla_state`
    (`breached`=`--danger`, `at_risk`=`--warn`, `ok`=`--live`, `unknown`=`--parked`);
    data = `open.features`.
  - **Closed INC** — distinct dimmed style (e.g. hollow grey), data = `closed.features`;
    toggleable (default off).
  - **Vehicles** — existing DOM markers via `loadLive()`.
  - Layer panel: Open INC / Closed INC / Vehicles toggles + SLA color legend.
- **Popups:** open → `ticket_id`, `normalized_status`, `cluster · region`,
  `assigned_team`/`owner`, `sla_state` + `hours_open`, `geo_source`
  (note "approx — cluster" when `geo_source==='cluster'`). closed → add `closed_at`,
  `mttr` (min→h), `sla_status`.
- **Header KPI strip:** repurpose `renderTicketKpis()` → `renderIncKpis()` showing INC
  metrics (Open now, Breached, Closed in window, Avg MTTR). Update `switchTab()` so the
  `tickets` case calls `initIncMap()` + `loadInc()` (lazy, like Fuel).
- **Filters:** `Apply`/`↻`/window-change → `loadInc()`. Keep the 15s vehicle poll;
  `loadInc()` is on-demand (open layer changes at most hourly).
- **Caveat to honor:** `open.features.length` may be `< metrics.open_now` (un-geocoded
  rows) — drive map from `features`, drive cards/tables from `metrics`.

---

## Verification (end-to-end)
1. **API (Phase A):** curl matrix above against `fleetapi.fivetitude.com` — shapes,
   filters, 400s. Compare `metrics.open_now` to `SELECT count(*) FROM tickets.inc
   WHERE is_actionable` (and `inc_open_sla` SLA distribution).
2. **SPA (Phase B):** serve `src/` locally (`python3 -m http.server` in `src/`, or the
   Caddy Docker image) with `API_BASE=https://fleetapi.fivetitude.com`. Open the
   **Tickets** tab and confirm:
   - Metric cards + header KPIs populate; by-status / by-cluster tables match `metrics`.
   - Map shows SLA-colored open INC + live vehicles; toggling Closed INC overlays the
     windowed closed set; SLA legend correct.
   - Changing Cluster / Status / Window + Apply refetches and updates cards, tables,
     and both layers; custom range shows date inputs and bounds the closed overlay.
   - Hover popups show the documented fields (open vs closed).
   - No console calls to `/webhook/tickets`; only `/webhook/inc-dashboard` +
     `/webhook/live-positions`.

## Out of scope (future)
- **CRQ** rebuild (deferred; reuses the same pattern once a CRQ feed/function exists).
- Open-backlog-over-time / observed transitions (needs `16_fleettickets` history
  capture — not built). Nearest-vehicle dispatch off `geog`.