Refactored all api endpoints to /bus/xxxxx

monitoring_ui/docs/transit_api/PHASE4_DEFERRED_FIXES.md

@@ -0,0 +1,111 @@
+# Phase 4 — Deferred Fixes & DB/Code Alignment
+
+**Goal:** clear the items Phase 3 deliberately preserved or surfaced, and which
+are real behavioral defects once the code runs against the live PostgreSQL at
+`PG_HOST`. **No endpoint or JSON shape changes** unless a stage explicitly
+declares one and updates the docs/READMEs accordingly.
+
+**Prerequisite:** Phase 3 module split landed (repo layer, bootstrap `index.js`,
+`/bus/` + legacy alias mounts, `search_path="transit.bus"`).
+
+## 1. Verified-failing items (triage from Phase 3 verification)
+
+| # | Item | Where | Current behavior | Why it matters |
+| --- | --- | --- | --- | --- |
+| 1 | `GET /bus/schedules` → 500 `column s.bus_id does not exist` | `repo/schedules.js` list query | Query expects a `bus_id` column the live DB lacks | The core read endpoint is broken on the live DB in both old and new code |
+| 2 | Mock `markStopPassed` → 500 `delayMinutes is not defined` | `repo/schedules.js` / `.mock.js` | Mock branch reads an undeclared variable | `/driver/schedules/:id/stops/:order/passed` always 500s in mock mode |
+| 3 | `bulk` endpoints + lines reorder/open `db.pool.connect()` before `try` | `repo/weekly.js`, `repo/adminSchedules.js`, `repo/lines.js` | With PG unreachable they hang instead of failing fast | Production blast-radius if the DB flaps |
+| 4 | Dead `overview` enrichment branch | original handler; NOT copied to `repo/schedules.mock.js` | Unreachable code in original | Left as-is during Phase 3; decide delete or rework |
+| 5 | Legacy root-alias mount | `index.js` (Double-mount `/` + `Deprecation` header) | Serves every route twice | Only Windows XP driver still needs it; plan its removal |
+
+## 2. Rules
+
+1. One fix per stage; verify against **live DB** where the stage touches PG.
+2. Every mock-side fix MUST be mirrored with identical behavior in the PG branch
+   (and vice versa) so both modes stay byte-identical for the same logical input.
+3. Do not normalize mock vs PG response casing (that was the Phase 3 contract);
+   fix *fairness* (both modes behave alike), not shape.
+4. Any endpoint whose JSON shape must change requires a doc update in this file
+   and in `transit_api/README.md`, and gets a note for the consuming clients
+   (`admin_ui`, `monitoring_ui`, `windows_xp_driver_ui`).
+5. `node --check` + `grep -rn DEV_MOCK index.js routes/` (must stay clean) after
+   every stage.
+
+## 3. Stages
+
+### Stage A — alive `schedules` read path (DB/query alignment)
+
+- Inspect real schema: `\d "transit.bus".schedules` (and `shifts`) at
+  `PG_HOST`. Determine whether `bus_id` was renamed/never added and whether the
+  code or the data is canonical (other clients: `admin_ui`, `monitoring_ui`
+  also read schedules — check what columns they rely on).
+- Decide: (a) add/migrate the column (`ALTER TABLE` + backfill from
+  `bus_line_id`/related), or (b) adjust the query. Prefer fixing the data model
+  so the API and all consumers see one shape.
+- Re-run the Phase 3 live parity sweep; `GET /bus/schedules*` must now return
+  200 with real rows in BOTH original-equivalent and refactored code paths.
+- Gate: `GET /bus/schedules`, `/bus/schedules/overview`, `/bus/schedules/:id`
+  all 200 on live DB; `GET /bus/schedules/recurring` unchanged in response
+  shape if it already worked.
+
+### Stage B — mock `markStopPassed` fairness
+
+- Fix the undeclared `delayMinutes` read in the mock branch (compute the same
+  duration the PG branch derives from the `schedule_stop_progress` row/stop
+  times). Produces 200 instead of 500 in mock mode, matching PG mode.
+- Gate: harness2 (mock mode) for `POST .../passed` → 200; PG mode unchanged.
+
+### Stage C — fail-fast PG connects
+
+- Move `db.pool.connect()` inside `try` for the open-connect endpoints so an
+  unreachable DB yields the same 500/timeout the non-open endpoints already do;
+  preserve short-circuit ordering so `try` + connect can't double-acquire.
+- Verify order/behavior parity pre/post on live DB with PG up; with PG down the
+  endpoint fails fast instead of hanging.
+- Gate: same responses as Phase 3 harness when PG reachable; NEW: explicit
+  PG-down test shows quick 500 (differential documented here).
+
+### Stage D — dead-code cleanup
+
+- Delete the unreachable `overview` enrichment in the original-style handler
+  (now only exists as the pg-branch / historical code); confirm no hidden
+  column the live DB lacks was being referenced only there.
+- Recommend: keep the `schedule_stop_progress` upsert the pg branch needs;
+  remove nothing else.
+- Gate: `grep` clean; overview 200 on live DB.
+
+### Stage E — retire legacy alias (deferred decision)
+
+- Reconfirm at project level whether the Windows XP driver is still deployed
+  (`windows_xp_driver_ui/driver_xp.c`). If yes: **do not do this stage**, keep
+  the `Deprecation` header and re-schedule. If no: remove the `/` double-mount
+  from `index.js`, add 404 for legacy paths, update `BUS_API_PREFIX_REFACTOR.md`.
+- Gate: `GET /schedules` → 404; `GET /bus/schedules` → 200; no route uses `/`.
+
+## 4. Verification (gate after every stage)
+
+```bash
+cd transit_api
+node --check index.js && node --check lib/*.js routes/*.js repo/*.js mock/store.js
+grep -rn DEV_MOCK index.js routes/ || echo "clean"
+# live DB (PG at .env PG_HOST):
+node index.js   # prod
+curl -s http://localhost:5001/health                       # database:"ok"
+curl -s http://localhost:5001/bus/schedules                # stage A: 200 JSON
+# mock:
+DEV_MOCK=1 node index.js                                   # stage B/C mock fairness
+```
+
+Re-run `/tmp/opencode/live-parity.js` (read-only old-vs-new) and the Phase 3
+harness after each stage; all prior byte-parity results must stay green except
+for the specific fix the stage documents.
+
+## 5. Definition of done
+
+1. `GET /bus/schedules`, `.overview`, `/:id`, recurring all 200 on live DB.
+2. Mock and PG modes behave identically for every endpoint (harness, not just
+   shape).
+3. PG-down produces fast, clear 500s (no hangs) on the connect-before-try
+   endpoints.
+4. No dead code; legacy alias decision recorded in this repo.
+5. Per-stage differential reports appended here.