## Hi OpenELIS community!
The DIGI-UW team has been talking to labs running Ope…nELIS Global and a consistent piece of feedback is: the **morning workplan routine is too fragmented**. Four different workplan screens, no connection to reagent QC, no persistence between sessions. We've put together a unified redesign with an interactive mockup, and we'd really appreciate help from the community to build it.
This is a bigger feature than its sibling ([Analyzer Manual QC](https://github.com/DIGI-UW/OpenELIS-Global-2/issues/3490)) — there's enough work here for a couple of people to collaborate. If you've wanted a focused project that touches real clinical workflow, **we'd love for you to pick it up!**
## What this is actually about
Picture a lab at the start of the day. Overnight, dozens of test requests have piled up — blood glucose, liver panels, CBCs, urine tests. A tech has to figure out which ones to run together in a **batch** (same chemistry, same instrument, same time), grab the right **reagent** (the bottle of chemistry that makes the test work), and make sure that reagent lot has passed QC today. If it hasn't, she has to run QC first or pick a different lot.
Today, this is spread across four separate workplan screens (By Test / By Panel / By Lab Unit / By Priority) showing the same pending tests sliced four ways. There's no connection to the reagent tracking. QC status lives in yet another module. Techs click between screens, flip through paper logs, and rely on memory. When someone forgets, patient samples get run with reagent that wasn't QC'd today — and nobody finds out until an auditor notices, or a result comes back wrong.
The redesign puts it all in one place. The tech picks any mix of filters (test, panel, lab unit, priority, date), selects the pending tests she wants to run together, names the batch, picks a reagent lot — and **right there** sees whether that lot's QC is valid today. If it's overdue, she can enter QC inline without leaving the page. If she has to proceed anyway (a STAT sample that can't wait), the system automatically creates a follow-up record (a **Non-Conforming Event**, or NCE) so the gap gets investigated later. Batches stick around across sessions so she doesn't lose her work if she logs out.
**Who it helps:** techs who want one screen instead of four, supervisors who want full audit trails, and patients whose results come from verified-working reagent.
## Have a look at the design
- **Interactive mockup** — click through it here: https://digi-uw.github.io/openelis-work/#/quality/batch-workplan-reagent-qc
- Try: Pending Tests → select a few tests → Create Batch → then switch to the Batches page.
- The overdue-QC batch is auto-expanded so you can see the warning + inline QC form.
- **Written spec (FRS):** [`designs/quality/batch-workplan-reagent-qc.md`](https://github.com/DIGI-UW/openelis-work/blob/main/designs/quality/batch-workplan-reagent-qc.md)
- **Carbon React mockup source:** [`designs/quality/batch-workplan-reagent-qc.jsx`](https://github.com/DIGI-UW/openelis-work/blob/main/designs/quality/batch-workplan-reagent-qc.jsx)
## Suggested reading order if you're picking this up
1. Play with the live mockup first — it shows the two-page flow and the auto-expand behavior.
2. FRS §1–2 for the "why".
3. FRS §4 is the big one — 8 sub-sections across unified list, batch creation, reagent/lot assignment, lifecycle, QC integration, inline QC entry, override + NCE generation, and workplan generation.
4. FRS §5 (Data Model) — three new entities (`TestBatch`, `TestBatchItem`, `QcRun`) plus QC-frequency fields on `Reagent`. `QcRun` is shared with the Analyzer Manual QC feature, so coordinate if both are being built at the same time.
5. FRS §6 lists 15 API endpoints.
6. FRS §8 (Business Rules) has the tricky bits — BR-002 (QC validity), BR-004 (override triggers NCE), BR-010 (can't generate without reagent+lot).
7. The `.jsx` mockup shows the Carbon components (two-page nav, `BatchTile` with step indicator, `LotCard` with FIFO badge, inline `QcRecordForm`).
## Where in this repo
- Frontend: Carbon React. The four existing workplan sub-pages live under `frontend/` — search for `Workplan` routes. Plan the migration so old URLs still resolve during rollout.
- Backend: Java Spring. Workplan, reagent, QC, and NCE services under `src/main/java/`.
- The FIFO-ordered lot selection pattern already exists on the Results Entry page (mentioned in FRS §4.3) — reuse it, don't reinvent.
- The mockup is in a separate repo: clone https://github.com/DIGI-UW/openelis-work and follow `mockup-viewer/README.md` to run it locally.
## Acceptance criteria
From FRS §12 — tick these off as you go.
### Functional
- [ ] User with `workplan.view` permission can access the unified Batch Workplan page
- [ ] The four old workplan sub-pages (By Test, By Panel, By Lab Unit, By Priority) are replaced by the single unified page
- [ ] User can filter pending tests by Test, Panel, Lab Unit, Priority, and Date Range simultaneously
- [ ] User can select tests and create a batch, assigning a reagent and lot
- [ ] Selected lot displays QC status (Pass/Overdue/Failed/Not Run) with correct Carbon Tag color
- [ ] User can enter QC results inline from the batch Tile without navigating away
- [ ] QC status updates immediately after saving a QC result
- [ ] QC override modal appears when generating a workplan with invalid QC on the lot
- [ ] NCE is automatically created when user proceeds through QC override
- [ ] NCE Tag appears on the batch Tile and links to the NCE detail page
- [ ] User without `qc.override` permission sees the "Proceed" button disabled with tooltip
- [ ] Batches persist across logout/login — user sees their batches on return
- [ ] "Clear All Batches" removes all user's batches with confirmation
- [ ] A test cannot be added to two batches simultaneously — error message shown
- [ ] Expired lots are grayed out and not selectable
- [ ] FIFO ordering and badges match the Results Page reagent lot selection pattern
- [ ] Batch status transitions: Draft → Active (on generate) → Completed (all tests done)
### Non-functional
- [ ] All UI strings use i18n keys — no hardcoded English
- [ ] Page loads within 2 seconds with up to 500 pending tests
- [ ] Permissions enforced at API level (HTTP 403 for unauthorized access)
- [ ] Feature tested with the French language file
- [ ] QC results entered via workplan appear in the QC module's history
### Integration
- [ ] NCE records created via QC override appear in the NCE module dashboard
- [ ] QC results are shared with the QC module (single source of truth in `QcRun` table)
- [ ] Reagent QC Frequency Rules are read from the reagent definition configured in Admin
- [ ] Lot expiration and FIFO logic is consistent with the Results Entry reagent lot selection
## Questions? Want to claim it?
Just comment on the issue — say hi, ask anything, or say "I'll take the frontend" / "I'll take the backend" / "I'll take the whole thing". We'll help you get oriented. Thanks for looking at it!
