# LIS Tier 1 Features — Design Document

**Date:** 2026-03-07
**Status:** Approved
**Project:** LIS (Support Project ID: 3)

## Goal

Implement the 4 highest-impact LIS features: Result Report Printing, Barcode Label Printing, Results Grid Entry, and External Lab Portal.

---

## Feature 1: Result Report Printing

### Report Template (Fixed, Configurable Content)

```
┌──────────────────────────────────────────┐
│  [LOGO]   Lab Name (from company)        │
│           Address / Phone / Email         │
│           License # (from settings)       │
├──────────────────────────────────────────┤
│  Patient: Name    MRN: XXX    Age/Gender │
│  Doctor: Dr. Name    Request#: LR-XXX    │
│  Date: 2026-03-07    Priority: Routine   │
├──────────────────────────────────────────┤
│  SECTION: Hematology                     │
│  ┌──────┬────────┬──────┬───────┬─────┐ │
│  │ Test │ Result │ Unit │ Range │Flag │  │
│  ├──────┼────────┼──────┼───────┼─────┤ │
│  │ WBC  │ 11.5   │ K/uL │ 4-11 │ H   │  │
│  │ RBC  │ 4.8    │ M/uL │ 4-6  │     │  │
│  └──────┴────────┴──────┴───────┴─────┘ │
├──────────────────────────────────────────┤
│  [Signature Image]     [QR Code]         │
│  Dr. Name              Verified at:      │
│  Title                 /verify/HASH      │
├──────────────────────────────────────────┤
│  Footer text (disclaimer)                │
└──────────────────────────────────────────┘
```

### Print Modes
- **Per Request** — all sections on one report (default)
- **Per Section** — separate PDF per section
- Default mode configurable in LIS Settings

### Settings (stored via `lis_settings` API)
- `report_mode`: `per_request` | `per_section`
- `report_header_text`: custom text under lab name
- `report_footer_text`: disclaimer text
- `report_license_number`: lab license #
- `report_show_qr`: boolean
- `report_show_signature`: boolean
- `report_show_previous_result`: boolean

### Print Locations
1. **Results page** — print icon per request (only released results)
2. **Requests list** — print icon per request (if has released results)
3. **Print Queue** — new `/lab/print-queue` route, batch select + print all

### Doctor Signature
- Signature image if uploaded in doctor profile, falls back to text name+title

### QR Code
- Links to verification URL confirming report authenticity
- Format: `https://moonui.elbaset.com/app/verify/{hash}`

### Technical
- jsPDF programmatic build (no html2canvas)
- Embedded Arabic font (Amiri or Noto Arabic)
- RTL text support
- Grouped by section, abnormal flags in red
- QR code via `qrcode` npm package

---

## Feature 2: Barcode Label Printing

### Label Content
```
┌─────────────────────────┐
│ |||||||||||||||||||||||  │  Barcode (Code128)
│ 260307ZKRVJM            │  Barcode text
│ حازم حمدي  | M | 35y    │  Patient, gender, age
│ CBC, Lipid Panel         │  Test names (truncated)
│ Blood - EDTA             │  Specimen type
│ LR-2026-00021            │  Request number
└─────────────────────────┘
```

### When to Print
- **Auto-prompt after request creation** — wizard shows "Print Labels?" with sample count
- **Manual from Samples page** — select samples → print labels
- **Manual from Requests list** — print labels icon per request

### Label Count
- One label per specimen type per request
- Configurable duplicate copies (1x, 2x, 3x)

### Settings
- `label_auto_print`: boolean
- `label_copies`: 1 | 2 | 3

### Technical
- jsPDF with small page size (configurable, default 50mm x 25mm)
- JsBarcode for Code128 generation
- Opens browser print dialog

---

## Feature 3: Results Grid Entry

### Layout
```
┌─────────────────────────────────────────────────────────────┐
│ [Date: ◄►]  [Search: barcode/request#/patient]              │
│ [Section: All ▼]  [Status: Pending ▼]                      │
├─────────────────────────────────────────────────────────────┤
│ Request    │ Patient      │ Test        │ Result │ Unit│Flag│
├────────────┼──────────────┼─────────────┼────────┼─────┼────┤
│ LR-00021   │ حازم حمدي    │ WBC         │ [11.5] │K/uL │ H  │
│            │              │ RBC         │ [4.8 ] │M/uL │    │
│            │              │ HGB         │ [14.2] │g/dL │    │
├────────────┼──────────────┼─────────────┼────────┼─────┼────┤
│ LR-00022   │ emad ghali   │ Glucose     │ [    ] │mg/dL│    │
│            │              │ Creatinine  │ [    ] │mg/dL│    │
└────────────┴──────────────┴─────────────┴────────┴─────┴────┘
│ [Tab]=next  [Enter]=save & next  [Ctrl+Enter]=save all     │
│ [Validate Selected] [Approve Selected] [Release Selected]  │
└─────────────────────────────────────────────────────────────┘
```

### Key UX Features
- **Tab/Enter navigation** — tab moves to next field, Enter saves and moves down
- **Auto-flag** — real-time abnormal flag as user types (H/L/Critical with color)
- **Inline normal range** — tooltip shows reference range for patient's age/gender
- **Row grouping** — grouped by request with visual separators
- **Batch actions** — select multiple → Validate All / Approve All / Release All
- **Status filter** — Pending / Entered / Validated / Approved pipeline
- **Barcode scan** — scan barcode in search → jumps to that request's results

### Replaces
Current accordion-based results page. Detail dialog stays for history/notes.

---

## Feature 4: External Lab Portal

### Access
- Each external lab gets: email, password, portal URL
- URL: `https://moonui.elbaset.com/app/lab-portal`
- Restricted role `external_lab` — sees only their referrals

### Portal Screen
```
┌──────────────────────────────────────────────────┐
│  [Lab Logo]  Welcome, Al-Noor Lab                │
│  Pending: 12  │  Completed: 45                   │
├──────────────────────────────────────────────────┤
│ [Tab: Pending]  [Tab: Completed]                 │
├──────────────────────────────────────────────────┤
│ Referral#  │ Patient   │ Tests        │ Sent At  │
├────────────┼───────────┼──────────────┼──────────┤
│ REF-0012   │ حازم حمدي │ Vitamin D    │ Mar 6    │
│            │           │ TSH          │          │
│  [Enter Results]                                 │
└──────────────────────────────────────────────────┘
```

### Result Entry
- Click "Enter Results" → inline grid
- Submit → status = `results_received`
- Lab staff gets notification → validate/approve/release as normal

### Internal Flow
- Staff can also enter results from Referrals page
- Both paths feed same result pipeline

### Backend Needs (Tickets)
- `POST /api/lis/external-lab-portal/login`
- `GET /api/lis/external-lab-portal/referrals`
- `POST /api/lis/external-lab-portal/referrals/{id}/results`
- Add `portal_email`, `portal_is_active` to `lis_external_labs`

### Frontend
- New route: `/lab-portal` — standalone layout, no sidebar
- Clean minimal UI, bilingual AR/EN toggle