docs(spec,plan): SP30 Dashboard Recent batches widget
This commit is contained in:
Nora
@@ -0,0 +1,100 @@
|
||||
# SP30 — Dashboard "Recent batches" widget: glance how the last few billed
|
||||
|
||||
> **Status:** Approved, 2026-07-02.
|
||||
> **Branch:** `sp30-recent-batches-widget`
|
||||
> **Spec → plan → implement → atomic merge into main.**
|
||||
|
||||
## Goal
|
||||
|
||||
The Dashboard already shows six-month KPIs (billed, denial rate, etc.) but the operator has no way to see **how the last few batches actually billed** without clicking through to `/batches`. Add a single Dashboard card that lists the 5 most recently parsed batches with one-line outcome per batch — so the operator can spot a batch that landed entirely rejected (or has a sudden spike in rejections) at a glance, the moment they log in.
|
||||
|
||||
## Scope
|
||||
|
||||
### Backend — 1 file modified (`backend/src/cyclone/api.py`)
|
||||
|
||||
**`list_batches` handler (`api.py:1769-1808`):**
|
||||
- Extend each returned item with billing-outcome fields, computed via a single batched SQL query per request (no N+1):
|
||||
- `acceptedCount` (int)
|
||||
- `rejectedCount` (int)
|
||||
- `pendingCount` (int)
|
||||
- `billedTotal` (float)
|
||||
- `topRejectionReason` (string|null, truncated to 60 chars)
|
||||
- `hasProblem` (bool — true when `rejectedCount > 0` or any 277CA A4/A6/A7 claim on the batch)
|
||||
- New helper `_batch_summary_billing_outcomes(records)` runs one GROUP BY query and one rejection-reason probe. Mirrors the existing `_batch_summary_claim_count` / `_batch_summary_claim_ids` helpers (`api.py:1740-1764`).
|
||||
|
||||
### Backend — 1 test file extended (`backend/tests/test_api_gets.py`)
|
||||
|
||||
**+2 tests after the existing `test_batches_*` block at lines 47-101:**
|
||||
- `test_batches_includes_billing_outcome` — seed one batch with 3 claims (1 paid $100, 1 rejected $50 reason="999 AK5 R", 1 submitted $75); `GET /api/batches`; assert `acceptedCount=1, rejectedCount=1, pendingCount=1, billedTotal=225.0, topRejectionReason="999 AK5 R", hasProblem=True`.
|
||||
- `test_batches_835_kind_returns_zero_billed_and_no_rejection` — seed one 835 batch; assert `acceptedCount=0, rejectedCount=0, billedTotal=0, topRejectionReason=null, hasProblem=False`.
|
||||
|
||||
Reuses the `seeded_store` fixture (line 27) and the direct ORM-insert pattern from `test_dashboard_kpis.py:36-91`.
|
||||
|
||||
### Frontend — 1 type extension + 1 new component + 1 layout wire-up
|
||||
|
||||
**`src/lib/api.ts:245-259`** — extend `BatchSummary` with 6 optional fields:
|
||||
```
|
||||
acceptedCount?, rejectedCount?, pendingCount?,
|
||||
billedTotal?, topRejectionReason?, hasProblem?
|
||||
```
|
||||
Optional preserves backward compat with existing tests in `Upload.history.test.tsx`, `Batches.test.tsx`, `BatchDiff.test.tsx`.
|
||||
|
||||
**`src/components/RecentBatchesWidget.tsx`** (NEW, ~120 LOC):
|
||||
- Card chrome mirroring the Dashboard "Recent activity" Card.
|
||||
- Header: `<Layers />` icon + "Recent batches" title + counter chip "{N} latest".
|
||||
- Empty state: "No batches yet." (matches ActivityFeed).
|
||||
- Row markup: status icon (CheckCircle2 / AlertTriangle) + filename + (kind · time · top rejection reason) + billed/accepted breakdown (or "N payments" for 835).
|
||||
- Click → `onRowClick(id)`; Enter key → same. Mirrors `Dashboard.tsx:300-307`.
|
||||
|
||||
**`src/pages/Dashboard.tsx`** — insert the widget as a full-width row BETWEEN the KPI tile row (line 245) and the "Activity + Top providers" grid (line 247):
|
||||
- `const recentBatchesQuery = useBatches(5);` — queryKey `["batches", 5]` (distinct from `["batches", null]` used by Upload).
|
||||
- `animationDelay: ${sectionBase + 200}ms` so it lands after the KPI stagger and before the Activity row.
|
||||
- onRowClick → `navigate('/batches?batch=' + id)`.
|
||||
|
||||
### Frontend — 1 test file added + 1 extended
|
||||
|
||||
**`src/components/RecentBatchesWidget.test.tsx`** (NEW, 3 tests):
|
||||
- empty state
|
||||
- 2-batch render (one clean, one with rejections) — verifies icon tint, billed total, accepted count, click + Enter key handler
|
||||
- 835 row renders "N payments" not $
|
||||
|
||||
**`src/pages/Dashboard.test.tsx`** (+1 test):
|
||||
- widget renders, row click navigates to `/batches?batch=ID`.
|
||||
|
||||
## Decisions
|
||||
|
||||
- **D1 — widget shows 5 batches, not "today only" or "last 24h".** 5 is the natural at-a-glance cap. Hard-coded constant `RECENT_BATCHES_LIMIT = 5` in the page.
|
||||
- **D2 — backend returns billing outcome on EVERY `/api/batches` row, not a separate `/api/batches/summary` endpoint.** The query cost is bounded by the existing `limit` and is one extra GROUP BY — no N+1. Returning on the list endpoint means future surfaces (Batches page, Upload History) can use the same fields without another endpoint.
|
||||
- **D3 — `hasProblem` drives the visible status, not `rejectedCount > 0` directly.** 277CA `A4/A6/A7` payer-rejected claims also count as problems. Mirrors the Inbox `rejected + payer_rejected` aggregation.
|
||||
- **D4 — 835 (ERA) rows show "N payments" instead of a $ figure.** The `Remittance` table has no batch-level `total_charge` aggregate; payments count is the honest, glanceable signal.
|
||||
- **D5 — full-width row above the Activity grid, not a 2/3 + 1/3 split.** The widget is the operator's primary "how's it going?" affordance; full width reads as the headline.
|
||||
|
||||
## Out of scope (deferred)
|
||||
|
||||
- Trend sparkline per batch (last N parse throughput).
|
||||
- Click-to-filter the widget itself by status.
|
||||
- Live-tail `batch_parsed` event wiring (no such event exists yet).
|
||||
- A "missing-ack-alarm" surfacing on claims SUBMITTED >24h with zero 999 acks (separate UX concern).
|
||||
|
||||
## Tech Stack
|
||||
|
||||
Python 3.11+, FastAPI, SQLAlchemy 2.x, SQLite (encrypted via SQLCipher), React 18 + TypeScript + Vite, TanStack Query, lucide-react. Same as SP29.
|
||||
|
||||
## File footprint
|
||||
|
||||
**Estimated 7 files changed, ~270 LOC.**
|
||||
|
||||
- Backend modified (1): `backend/src/cyclone/api.py` (+~60 LOC).
|
||||
- Backend test extended (1): `backend/tests/test_api_gets.py` (+~70 LOC).
|
||||
- Frontend type extended (1): `src/lib/api.ts` (+~8 LOC).
|
||||
- Frontend component added (1): `src/components/RecentBatchesWidget.tsx` (NEW, ~120 LOC).
|
||||
- Frontend layout wire-up (1): `src/pages/Dashboard.tsx` (+~20 LOC).
|
||||
- Frontend test added (1): `src/components/RecentBatchesWidget.test.tsx` (NEW, ~150 LOC).
|
||||
- Frontend test extended (1): `src/pages/Dashboard.test.tsx` (+~40 LOC).
|
||||
|
||||
## Risks
|
||||
|
||||
- **Aggregate query cost on `/api/batches`** — bounded by the existing `limit` (default 100, capped at 1000); one GROUP BY ≤60k rows is sub-50ms on SQLite.
|
||||
- **Backwards compat of `BatchSummary`** — new fields are optional, so every existing test that constructs `BatchSummary` continues to pass.
|
||||
- **`topRejectionReason` truncation** — capped at 60 chars in the backend; tested with one assertion on a long reason.
|
||||
- **Dashboard layout choreography** — widget uses `animationDelay: sectionBase + 200ms`; tested visually in the Playwright smoke test.
|
||||
Reference in New Issue
Block a user