docs: refresh README roadmap (SP4/6/7 shipped, add Next up) + commit SP6 plan

- Mark SP4 as fully shipped (batch diff, search, CSV, a11y all landed)
- Add SP6 (Inbox) and SP7 (Per-line reconciliation) sections
- Add SP6 + SP7 endpoint inventories
- Note next up: outbound 837P serializer

The workflow-automation plan was authored but never committed; the
features it specified have shipped, so commit it for the historical
record alongside this README refresh.
This commit is contained in:
Tyler
2026-06-20 19:58:26 -06:00
parent ceeb8b664d
commit 27c1680830
2 changed files with 2796 additions and 14 deletions
+94 -14
View File
@@ -275,7 +275,7 @@ backup API).
## Roadmap ## Roadmap
Sub-projects 2, 3, 4, and 5 are **shipped**. Next up: Sub-projects 2 through 7 are **shipped**. Next up:
- **Sub-project 3 (shipped) — More 837P/835 features.** - **Sub-project 3 (shipped) — More 837P/835 features.**
- **837P validation rules:** R034 enforces `REF*G1` on frequency-code - **837P validation rules:** R034 enforces `REF*G1` on frequency-code
@@ -294,20 +294,36 @@ Sub-projects 2, 3, 4, and 5 are **shipped**. Next up:
builds a 270 from a JSON payload (subscriber, provider, payer, builds a 270 from a JSON payload (subscriber, provider, payer,
service type); `POST /api/eligibility/parse-271` ingests the service type); `POST /api/eligibility/parse-271` ingests the
response and returns structured `coverage_benefits`. response and returns structured `coverage_benefits`.
- **Sub-project 4 (partially shipped) — Frontend features.** - **TA1 interchange ACK:** parser + persistence + API for the
- **Per-claim detail drawer (shipped):** click any row on the Claims envelope-level TA1 acknowledgment (separate from the 999
page to open a side-panel drawer with the full claim context — transaction-set ACK).
state + amount header, validation panel, service lines, diagnoses, - **Sub-project 4 (shipped) — Frontend features.**
parties (billing provider, subscriber, payer), raw X12 segments, - **Per-claim detail drawer:** click any row on the Claims page to
matched remittance summary, and a vertical state-history timeline. open a side-panel drawer with the full claim context — state +
URL is synced (`?claim=...`) so links and back-button restore the amount header, validation panel, service lines, diagnoses, parties
drawer. Keyboard nav: `j`/`k` move between claims, `esc` closes, (billing provider, subscriber, payer), raw X12 segments, matched
`?` opens the cheatsheet overlay. Skeleton + error + not-found remittance summary, and a vertical state-history timeline. URL is
(404) states are all distinct. Powered by a new backend endpoint synced (`?claim=...`) so links and back-button restore the drawer.
Keyboard nav: `j`/`k` move between claims, `esc` closes, `?` opens
the cheatsheet overlay. Skeleton + error + not-found (404) states
are all distinct. Powered by a new backend endpoint
`GET /api/claims/{claim_id}` that returns the full drawer payload `GET /api/claims/{claim_id}` that returns the full drawer payload
in a single round-trip. in a single round-trip.
- **Remaining SP4:** batch diff view, advanced filters (date range, - **Remit drawer:** mirror of the claim drawer for remittances —
multi-status, saved filter sets). payer + provider header, financial summary, claim-payments table,
CAS adjustments panel, parties grid, raw X12 segments. URL is
synced (`?remit=...`).
- **Batch diff view:** side-by-side comparison of two batches
(added / removed / changed claims) reachable from the Batches
page. Powers the `BatchDetail` and `BatchDiff` views.
- **Global Cmd-K search:** cross-resource search across claims,
remittances, and activity; opens from anywhere via the keyboard
shortcut.
- **CSV export:** per-page export buttons (claims, remittances, lanes)
that stream CSV directly from the backend.
- **Accessibility + print styles:** keyboard navigation focus rings,
`aria` roles, and `@media print` stylesheets for paper-friendly
output.
- **Sub-project 5 (shipped) — Live updates.** - **Sub-project 5 (shipped) — Live updates.**
- The Claims, Remittances, and Activity pages stream new rows in - The Claims, Remittances, and Activity pages stream new rows in
real time over Server-Sent Events encoded as newline-delimited real time over Server-Sent Events encoded as newline-delimited
@@ -321,8 +337,42 @@ Sub-projects 2, 3, 4, and 5 are **shipped**. Next up:
`error` / `closed` — and offers a manual **↻ Reconnect** button `error` / `closed` — and offers a manual **↻ Reconnect** button
on `stalled` or `error`. Stale connections (no event for 30s, on `stalled` or `error`. Stale connections (no event for 30s,
heartbeat included) flip to `stalled` automatically; the heartbeat included) flip to `stalled` automatically; the
back-off ladder on errors is 1s → 2s → 4s → 8s → 16s → 30s back-off ladder on errors is `1s → 2s → 4s → 8s → 16s → 30s`
capped. See the "Live updates" section below for details. capped. See the "Live updates" section below for details.
- **Sub-project 6 (shipped) — Inbox workflow automation.**
- **Ticker-Tape inbox (`/inbox`):** four lanes ordered by urgency —
**Rejected** (claims whose 999 rejected them), **Candidates**
(remits that didn't auto-match a claim), **Unmatched** (claims
still waiting for a remit), and **Done today** (terminal
transitions in the last 24 hours). The page subscribes to the
claim and remittance tail streams so new rejected claims land in
the Rejected lane within a fraction of a second.
- **4-field weighted scoring:** every candidate remit is scored on
patient control number (40), service date (25), charge amount
(20), and provider NPI (15). Tiers: strong (≥75, Match enabled),
weak (5074, dimmed), hidden (<50).
- **Bulk actions:** multi-select rows in any lane to dismiss
candidates, resubmit rejected claims, or export the lane as CSV
in a single round-trip.
- **Sub-project 7 (shipped) — Per-line adjustment audit.**
- Every 835 CAS segment is tied back to the specific 837 service
line it adjudicates, instead of being aggregated to the claim
level. The match runs **eagerly** at 835 ingest time so the audit
trail is stable across re-reads.
- New endpoints surface the per-line projection: `GET
/api/claims/{id}/line-reconciliation` for the dedicated tab in
the ClaimDrawer; the existing claim + remit detail endpoints
gained slim `lineReconciliation[]` / `serviceLinePayments[]` /
`claimLevelAdjustments[]` fields; the inbox lanes include
`matched_lines` / `total_lines` badges on matched remittances.
- The ClaimDrawer gains a **Line Reconciliation** tab (alongside
Details) that pairs every 837 SV1 line with its 835 SVC composite
and surfaces per-line CAS reasons + unmatched-line warnings.
- See the "Per-Line Adjustment Audit" section below for details.
**Next up:** outbound 837P serializer — closes the resubmit loop
(rejected claim → corrected 837P back to payer). Design spec at
`docs/superpowers/specs/2026-06-20-cyclone-serialize-837-design.md`.
### SP3 endpoints ### SP3 endpoints
@@ -361,6 +411,36 @@ ACKs and lets you download the regenerated 999 text.
- `GET /api/activity/stream` — same shape for activity events - `GET /api/activity/stream` — same shape for activity events
(subscribes to `activity_recorded`, default `limit=50`). (subscribes to `activity_recorded`, default `limit=50`).
### SP6 endpoints (inbox)
- `GET /api/inbox/lanes` — all four lanes (rejected, candidates,
unmatched, done_today) in a single round-trip, with row-level
scoring and matched-remit context.
- `POST /api/inbox/candidates/{remit_id}/match` — manual match of a
candidate remit to one of its scored claims; `409` if the claim
state moved out from under us.
- `POST /api/inbox/candidates/dismiss` — `{pairs: [{claim_id,
remit_id}]}`. Session-scoped, no DB persistence.
- `POST /api/inbox/rejected/resubmit` — `{claim_ids: [...]}`. `200`
with `conflicts` for non-rejected claims in the batch.
- `GET /api/inbox/export.csv?lane=<lane>` — streams CSV of the
lane's rows.
### SP7 endpoints (per-line reconciliation)
- `GET /api/claims/{id}/line-reconciliation` — dedicated view for
the ClaimDrawer's Line Reconciliation tab; returns the slim
per-line projection (`summary` + `lines[]`).
- `GET /api/claims/{id}` — now includes a slim `lineReconciliation[]`
so the ServiceLinesTable can show paid + adjustments columns
without a second fetch.
- `GET /api/remittances/{id}` — now includes `serviceLinePayments[]`
+ `claimLevelAdjustments[]`; the CAS panel renders per-line + claim
level separately.
- `GET /api/inbox/lanes` — `matched_remittance` payload gained
`matched_lines` + `total_lines` so the MatchedRemitCard can badge
partial matches.
## License ## License
No license file yet; this is internal-use software. Add a `LICENSE` file No license file yet; this is internal-use software. Add a `LICENSE` file
File diff suppressed because it is too large Load Diff