clqms-be/USER_STORIES.md

# CLQMS User Stories

> Clinical Laboratory Quality Management System - User Stories
>
> Version: 1.0
> Last Updated: 2026-01-28

---

## How to Read These Stories

Each user story follows this format:

**Story ID**: [Module]-[Number]
**Priority**: P0 (Must-have) | P1 (Should-have) | P2 (Nice-to-have) | P3 (Future)

```
As a [actor/role],
I want [feature/action],
So that [benefit/value].
```

**Acceptance Criteria:**
- [ ] Criteria 1
- [ ] Criteria 2

---

## Table of Contents

1. [Master Data Management (P0)](#1-master-data-management-p0)
2. [Order Management (P0)](#2-order-management-p0)
3. [Specimen Management (P0)](#3-specimen-management-p0)
4. [Result Management (P0)](#4-result-management-p0)
5. [Patient Visit (P1)](#5-patient-visit-p1)
6. [Instrument Integration (P1)](#6-instrument-integration-p1)
7. [Quality Control (P2)](#7-quality-control-p2)
8. [Calibration (P2)](#8-calibration-p2)
9. [Audit Trail (P2)](#9-audit-trail-p2)
10. [Inventory & Billing (P3)](#10--inventory--billing-p3)

---

## 1. Master Data Management (P0)

> **Note**: All master data stories are P0 because they are foundational prerequisites for all transactional workflows.

### VS-001: Manage Value Set Definitions
**Priority**: P0

As a **system administrator**,
I want **to manage value set definitions**,
So that **I can define and maintain lookup value categories used throughout the system**.

**Acceptance Criteria:**
- [ ] Create new value set definition with name, description, and metadata
- [ ] Update existing value set definition
- [ ] Delete value set definition (soft delete)
- [ ] List all value set definitions with pagination
- [ ] Retrieve single value set definition by ID
- [ ] Value set definitions include: name, description, category, active status
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/valuesetdef`

---

### VS-002: Manage Value Set Values
**Priority**: P0

As a **system administrator**,
I want **to manage individual values within value sets**,
So that **I can maintain the lookup options available for dropdown selections**.

**Acceptance Criteria:**
- [ ] Create new value set value with key, label, and sort order
- [ ] Update existing value set value
- [ ] Delete value set value (soft delete)
- [ ] List all values for a specific value set definition
- [ ] Filter values by active/inactive status
- [ ] Values can be marked as default
- [ ] Sort order controls display sequence in dropdowns
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/valueset`

---

### VS-003: Use JSON-Based Static Lookups
**Priority**: P0

As a **developer**,
I want **to access static lookup values from JSON files**,
So that **I can quickly load commonly-used reference data without database queries**.

**Acceptance Criteria:**
- [ ] ValueSet library provides `get($key)` method returning dropdown options
- [ ] ValueSet library provides `getRaw($key)` method returning raw JSON data
- [ ] ValueSet library provides `getLabel($key, $value)` to get text label
- [ ] ValueSet library provides `transformLabels($records, $mappings)` for batch label conversion
- [ ] JSON files stored in `app/Libraries/Data/*.json`
- [ ] Lookup results cached for performance (>95% cache hit rate)
- [ ] Cache can be cleared via `ValueSet::clearCache()`
- [ ] Common lookups include: sex, marital_status, race, ethnic, order_status, specimen_type, result_type

---

### VS-004: Refresh Value Set Cache
**Priority**: P0

As a **system administrator**,
I want **to refresh the value set cache after making changes**,
So that **the system immediately reflects updated lookup values**.

**Acceptance Criteria:**
- [ ] API endpoint: POST `/api/valueset/refresh`
- [ ] Cache refresh requires authentication
- [ ] Cache refresh returns success status
- [ ] All ValueSet library calls return fresh data after refresh

---

### TD-001: Manage Test Site Definitions
**Priority**: P0

As a **lab manager**,
I want **to define which tests are available at each laboratory site**,
So that **orders can only include tests appropriate for the testing location**.

**Acceptance Criteria:**
- [ ] Create test definition for a site
- [ ] Update test site definition
- [ ] Delete test site definition
- [ ] List all tests available at a specific site
- [ ] Filter tests by discipline, department, or specimen type
- [ ] Mark tests as active/inactive per site
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/testdefsite`

---

### TD-002: Manage Technical Test Specifications
**Priority**: P0

As a **lab technical specialist**,
I want **to define technical specifications for each test**,
So that **the system knows how to process, validate, and report test results**.

**Acceptance Criteria:**
- [ ] Define specimen type requirements
- [ ] Define container requirements
- [ ] Define result type (numeric, text, valueset, range)
- [ ] Define expected units of measure
- [ ] Define decimal precision
- [ ] Define result format options
- [ ] Link to reference range definitions
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/testdeftech`

---

### TD-003: Define Calculated Test Formulas
**Priority**: P0

As a **lab technical specialist**,
I want **to create formulas for calculated tests**,
So that **the system can automatically compute derived values from other test results**.

**Acceptance Criteria:**
- [ ] Create formula for calculated test
- [ ] Formula language supports basic arithmetic (+, -, *, /)
- [ ] Formula can reference other test results by TestID
- [ ] Formula can include constants and parentheses
- [ ] Formula validation catches circular references
- [ ] Formula calculation triggered when all dependencies are available
- [ ] Calculated results flagged as "CALC" type
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/testdefcal`

---

### TD-004: Manage Test Groups and Panels
**Priority**: P0

As a **lab manager**,
I want **to group individual tests into panels and profiles**,
So that **clinicians can order commonly-related tests as a single group**.

**Acceptance Criteria:**
- [ ] Create test group with name and description
- [ ] Add multiple tests to a group
- [ ] Remove tests from a group
- [ ] Mark group as type "GROUP" (panel) or "TITLE" (section header)
- [ ] Groups can include other groups (nested panels)
- [ ] Ordering a group automatically orders all component tests
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/testdefgrp`

---

### TD-005: Map Instruments to Tests
**Priority**: P0

As a **lab technical specialist**,
I want **to map laboratory instruments to specific tests**,
So that **instrument results can be correctly matched to patient tests**.

**Acceptance Criteria:**
- [ ] Create instrument-to-test mapping
- [ ] Define instrument test code (from analyzer)
- [ ] Define corresponding CLQMS TestID
- [ ] Define result transformation rules (if needed)
- [ ] Specify unit conversions (if needed)
- [ ] One instrument test can map to multiple CLQMS tests
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/testmap`

---

### TD-006: Auto-Select Calculated Test Parameters
**Priority**: P0

As a **laboratory information system**,
I want **to automatically add parameters required for calculated tests**,
So that **all necessary data is collected when calculated tests are ordered**.

**Acceptance Criteria:**
- [ ] System analyzes formulas for all calculated tests in order
- [ ] System identifies parameter dependencies
- [ ] System automatically adds missing parameters to order
- [ ] User notified of auto-added parameters
- [ ] Parameters cannot be removed if required by calculated test
- [ ] Dependency chain is recursive (parameters may have their own dependencies)

---

### RR-001: Manage Numeric Reference Ranges
**Priority**: P0

As a **lab technical specialist**,
I want **to define numeric reference ranges with age and sex criteria**,
So that **the system can automatically flag abnormal test results**.

**Acceptance Criteria:**
- [ ] Create reference range for a test
- [ ] Define minimum and maximum normal values
- [ ] Define age range (birth to death)
- [ ] Define sex criteria (male, female, both)
- [ ] Define race/ethnicity criteria (optional)
- [ ] System auto-flags results outside range as "abnormal"
- [ ] System finds matching range based on patient demographics
- [ ] Supports critical value thresholds
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/refnum`

---

### RR-002: Manage Threshold Reference Ranges
**Priority**: P0

As a **lab technical specialist**,
I want **to define critical value thresholds**,
So that **the system can generate urgent alerts for dangerous results**.

**Acceptance Criteria:**
- [ ] Create threshold range for a test
- [ ] Define critical low and critical high values
- [ ] Define panic values requiring immediate notification
- [ ] Threshold overrides standard reference range
- [ ] System flags threshold results as "critical"
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/refthold`

---

### RR-003: Manage Text Reference Ranges
**Priority**: P0

As a **lab technical specialist**,
I want **to define acceptable text values for qualitative tests**,
So that **the system can validate text-based results**.

**Acceptance Criteria:**
- [ ] Create text reference range for a test
- [ ] Define list of acceptable text values
- [ ] Define default/normal value
- [ ] Define abnormal values
- [ ] System validates entered text against acceptable values
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/reftxt`

---

### RR-004: Manage Value Set Reference Ranges
**Priority**: P0

As a **lab technical specialist**,
I want **to define reference ranges based on value set codes**,
So that **dropdown-based results can be validated**.

**Acceptance Criteria:**
- [ ] Create value set reference range
- [ ] Link to specific value set definition
- [ ] Mark which values are normal vs abnormal
- [ ] Define default normal value
- [ ] System flags non-default values as abnormal (optional)
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/refvset`

---

### ORG-001: Manage Accounts
**Priority**: P0

As a **system administrator**,
I want **to manage laboratory accounts**,
So that **the system can track orders and results by customer organization**.

**Acceptance Criteria:**
- [ ] Create account with name, code, and contact information
- [ ] Update account details
- [ ] Soft delete account
- [ ] List all accounts with pagination
- [ ] Assign sites to accounts
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/account`

---

### ORG-002: Manage Sites
**Priority**: P0

As a **system administrator**,
I want **to manage laboratory sites**,
So that **multi-location laboratories can track data by physical location**.

**Acceptance Criteria:**
- [ ] Create site with name, type, and location
- [ ] Define site type (hospital, clinic, reference lab, etc.)
- [ ] Link site to parent account
- [ ] Define site address and contact
- [ ] Update and soft delete sites
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/site`

---

### ORG-003: Manage Locations
**Priority**: P0

As a **system administrator**,
I want **to manage physical locations within sites**,
So that **specimens and orders can be tracked to specific areas**.

**Acceptance Criteria:**
- [ ] Create location within a site
- [ ] Define location type (phlebotomy, reception, lab, storage, etc.)
- [ ] Define location hierarchy (building, floor, room)
- [ ] Update and soft delete locations
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/location`

---

### ORG-004: Manage Disciplines
**Priority**: P0

As a **lab manager**,
I want **to manage laboratory disciplines**,
So that **tests can be organized by clinical discipline**.

**Acceptance Criteria:**
- [ ] Create discipline (e.g., Chemistry, Hematology, Microbiology)
- [ ] Define discipline code and description
- [ ] Link departments to disciplines
- [ ] Update and soft delete disciplines
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/discipline`

---

### ORG-005: Manage Departments
**Priority**: P0

As a **lab manager**,
I want **to manage laboratory departments**,
So that **tests and staff can be organized by sub-discipline**.

**Acceptance Criteria:**
- [ ] Create department within a discipline
- [ ] Define department code and description
- [ ] Link department to parent discipline
- [ ] Update and soft delete departments
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/department`

---

### ORG-006: Manage Workstations
**Priority**: P0

As a **lab manager**,
I want **to manage laboratory workstations**,
So that **orders and results can be tracked to specific instruments or work areas**.

**Acceptance Criteria:**
- [ ] Create workstation with name and type
- [ ] Link workstation to department
- [ ] Define workstation as manual or automated
- [ ] Link automated workstations to instruments
- [ ] Update and soft delete workstations
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/workstation`

---

### SPEC-001: Manage Container Definitions
**Priority**: P0

As a **lab technical specialist**,
I want **to define specimen container types**,
So that **the system can track appropriate containers for each specimen type**.

**Acceptance Criteria:**
- [ ] Create container definition
- [ ] Define container class (tube, cup, slide, etc.)
- [ ] Define container size
- [ ] Define cap color
- [ ] Define additive requirements
- [ ] Define minimum and maximum volumes
- [ ] Update and soft delete containers
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/containerdef`

---

### SPEC-002: Manage Specimen Types
**Priority**: P0

As a **lab technical specialist**,
I want **to define specimen types**,
So that **orders can specify the required biological material**.

**Acceptance Criteria:**
- [ ] Create specimen type (Blood, Urine, Tissue, etc.)
- [ ] Define specimen type code
- [ ] Link to appropriate container types
- [ ] Define collection methods
- [ ] Define storage requirements
- [ ] Update and soft delete specimen types
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/specimentype`

---

### SPEC-003: Manage Collection Methods
**Priority**: P0

As a **lab technical specialist**,
I want **to define specimen collection methods**,
So that **phlebotomy procedures can be standardized**.

**Acceptance Criteria:**
- [ ] Create collection method (Venipuncture, Catheter, etc.)
- [ ] Define method code and description
- [ ] Link to appropriate specimen types
- [ ] Update and soft delete collection methods
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/collectionmethod`

---

### SPEC-004: Manage Container Classes and Sizes
**Priority**: P0

As a **lab technical specialist**,
I want **to define container classes and sizes**,
So that **specimen containers can be consistently categorized**.

**Acceptance Criteria:**
- [ ] Container classes: tube, cup, vial, slide, bag, etc.
- [ ] Container sizes with volume capacity
- [ ] Size units (mL, L, etc.)
- [ ] Link sizes to container classes
- [ ] Manage cap color options
- [ ] API endpoints: GET/POST/PATCH/DELETE for container class and size lookup tables

---

## 2. Order Management (P0)

### ORD-001: Create Laboratory Order
**Priority**: P0

As a **ordering provider or clinical staff**,
I want **to create a laboratory order for a patient**,
So that **the laboratory can perform requested tests**.

**Acceptance Criteria:**
- [ ] Create order via POST `/api/ordertest`
- [ ] Order requires patient identification (InternalPID)
- [ ] Order requires priority (Stat/Routine/ASAP)
- [ ] Order requires ordering provider identification
- [ ] System generates unique OrderID in format: LLYYMMDDXXXXX
  - LL: Lab location code
  - YYMMDD: Date
  - XXXXX: Sequential number
- [ ] Order includes one or more tests
- [ ] Initial order status is "ORD" (ordered)
- [ ] Order date/time recorded in UTC
- [ ] Response includes: OrderID, InternalPID, OrderStatus, list of tests

---

### ORD-002: Update Order Details
**Priority**: P0

As a **laboratory staff**,
I want **to modify order details before verification**,
So that **the order can be corrected if information was entered incorrectly**.

**Acceptance Criteria:**
- [ ] Update order via PATCH `/api/ordertest/:id`
- [ ] Can update priority
- [ ] Can update ordering provider
- [ ] Can add tests to order
- [ ] Can remove tests from order (before specimen collection)
- [ ] Updates prevented if order is verified
- [ ] Update timestamp recorded in UTC

---

### ORD-003: Delete Order
**Priority**: P0

As a **laboratory staff**,
I want **to cancel an order**,
So that **tests are not performed on cancelled orders**.

**Acceptance Criteria:**
- [ ] Delete order via DELETE `/api/ordertest/:id`
- [ ] Delete is soft delete (DelDate set, not actual deletion)
- [ ] Deleted orders not displayed in standard queries
- [ ] Delete prevented if specimens have been collected
- [ ] Delete reason must be recorded
- [ ] Deleted orders can be retrieved with include_deleted flag

---

### ORD-004: Track Order Status
**Priority**: P0

As a **laboratory staff and clinician**,
I want **to track order status through the testing workflow**,
So that **I know the current state of the order**.

**Acceptance Criteria:**
- [ ] Order status workflow: ORD → SCH → ANA → VER → REV → REP
  - ORD: Ordered
  - SCH: Scheduled
  - ANA: Analyzing
  - VER: Technical verification complete
  - REV: Clinical review complete
  - REP: Reported (final)
- [ ] Status can be updated via PATCH `/api/ordertest/:id/status`
- [ ] Status update requires authentication
- [ ] Status change recorded with user ID and timestamp
- [ ] Status history tracked via audit trail
- [ ] Current status included in all order responses

---

### ORD-005: Assign Order Priority
**Priority**: P0

As a **ordering provider or lab staff**,
I want **to mark orders as urgent**,
So that **critical tests are performed first**.

**Acceptance Criteria:**
- [ ] Priority options: Stat (S), Routine (R), ASAP (A)
- [ ] Stat orders appear at top of worklists
- [ ] Priority can be updated before specimen collection
- [ ] Priority displayed on all order views
- [ ] Default priority is Routine

---

### ORD-006: Attach Documents to Order
**Priority**: P0

As a **clinical staff**,
I want **to attach documents or images to an order**,
So that **relevant clinical information is available to laboratory staff**.

**Acceptance Criteria:**
- [ ] Upload attachments via POST `/api/ordertest/:id/attachments`
- [ ] Supported file types: PDF, images (PNG, JPG), documents
- [ ] File size limits enforced
- [ ] Attachments linked to ordercom/orderatt tables
- [ ] Attachment metadata includes: filename, type, size, uploader, timestamp
- [ ] Attachments can be retrieved via GET `/api/ordertest/:id/attachments`

---

### ORD-007: Map Multiple Tests to Order
**Priority**: P0

As a **ordering provider**,
I want **to include multiple tests in a single order**,
So that **related tests are performed on the same specimen**.

**Acceptance Criteria:**
- [ ] Order can include multiple tests
- [ ] Tests can be individual tests or panels
- [ ] Panels expand to component tests
- [ ] Orderitem table links OrderID to TestID
- [ ] All tests in order initially have same status
- [ ] Individual test status can be tracked independently

---

### ORD-008: Auto-Select Calculated Test Parameters
**Priority**: P0

As a **laboratory information system**,
I want **to automatically add required parameters for calculated tests**,
So that **all necessary data is collected**.

**Acceptance Criteria:**
- [ ] System detects calculated tests in order
- [ ] System analyzes formulas for calculated tests
- [ ] System adds missing parameters to order
- [ ] User notified of auto-added parameters
- [ ] Parameters cannot be removed if required
- [ ] Dependency tracking is recursive

---

### ORD-009: Identify Ordering Provider
**Priority**: P0

As a **laboratory system**,
I want **to track which provider ordered each test**,
So that **results can be sent back and questions can be directed appropriately**.

**Acceptance Criteria:**
- [ ] Order requires ordering provider identification
- [ ] Provider can be identified by ID or name
- [ ] Provider contact information stored
- [ ] Provider included in result reports
- [ ] Results can be filtered by ordering provider

---

### ORD-010: Track Order Date/Time in UTC
**Priority**: P0

As a **laboratory system**,
I want **to normalize all timestamps to UTC**,
So that **times are consistent across multiple time zones**.

**Acceptance Criteria:**
- [ ] Order date stored in UTC in database
- [ ] Order dates returned as UTC ISO 8601 format in API
- [ ] Input dates automatically converted to UTC
- [ ] Timezone information preserved in metadata
- [ ] Display can show local time based on user preference

---

## 3. Specimen Management (P0)

### SPM-001: Create Specimen from Order
**Priority**: P0

As a **phlebotomist or lab staff**,
I want **to create a specimen record for an order**,
So that **the specimen can be tracked through the laboratory workflow**.

**Acceptance Criteria:**
- [ ] Create specimen via POST `/api/specimen`
- [ ] Specimen requires OrderID
- [ ] Specimen requires SpecimenType
- [ ] System generates unique SpecimenID = OrderID + SpecimenTypeCode(3) + ContainerCode(1)
- [ ] Specimen linked to order
- [ ] Initial specimen status is "COLLECTED"
- [ ] Collection date/time recorded in UTC

---

### SPM-002: Mark Specimen as Collected
**Priority**: P0

As a **phlebotomist**,
I want **to record specimen collection**,
So that **the laboratory knows the specimen is ready for processing**.

**Acceptance Criteria:**
- [ ] Update specimen status to "COLLECTED"
- [ ] Record collection date/time
- [ ] Record collector ID
- [ ] Record collection location
- [ ] Record collection method (venipuncture, catheter, etc.)
- [ ] Collection activity logged to specmenactivity table

---

### SPM-003: Track Specimen In-Transit
**Priority**: P0

As a **courier or lab staff**,
I want **to mark specimen as in-transit**,
So that **the specimen location is known during transport**.

**Acceptance Criteria:**
- [ ] Update specimen status to "IN_TRANSIT"
- [ ] Record dispatch date/time
- [ ] Record courier/staff ID
- [ ] Record destination location
- [ ] Expected arrival time can be recorded
- [ ] Transit activity logged to specmenactivity table

---

### SPM-004: Receive or Reject Specimen
**Priority**: P0

As a **laboratory reception staff**,
I want **to receive specimens and verify acceptability**,
So that **unacceptable specimens are not processed**.

**Acceptance Criteria:**
- [ ] Update specimen status to "RECEIVED" or "REJECTED"
- [ ] Record reception date/time
- [ ] Record receiver ID
- [ ] If rejected, record rejection reason
- [ ] Rejection reasons: insufficient quantity, hemolysis, clotting, wrong container, etc.
- [ ] Rejected specimens cannot proceed to analysis
- [ ] Reception activity logged to specmenactivity table

---

### SPM-005: Prepare Specimen for Analysis
**Priority**: P0

As a **lab technician**,
I want **to record specimen preparation steps**,
So that **the specimen processing history is documented**.

**Acceptance Criteria:**
- [ ] Update specimen status to "PREPARATION"
- [ ] Preparation types: centrifuge, aliquot, pretreatment, stain, etc.
- [ ] Record preparation date/time
- [ ] Record technician ID
- [ ] Preparation activity logged to specmenactivity table
- [ ] Multiple preparation steps can be recorded

---

### SPM-006: Store Specimen
**Priority**: P0

As a **lab technician**,
I want **to record specimen storage location**,
So that **the specimen can be retrieved if needed**.

**Acceptance Criteria:**
- [ ] Update specimen status to "STORED"
- [ ] Record storage date/time
- [ ] Record storage location (freezer, refrigerator, room)
- [ ] Record technician ID
- [ ] Storage activity logged to specmenactivity table
- [ ] Storage conditions (temperature) can be recorded

---

### SPM-007: Dispatch Specimen for Referral
**Priority**: P0

As a **lab staff**,
I want **to dispatch specimen to reference laboratory**,
So that **tests not performed in-house can be completed**.

**Acceptance Criteria:**
- [ ] Update specimen status to "DISPATCHED"
- [ ] Record dispatch date/time
- [ ] Record destination (reference lab)
- [ ] Record courier/tracking information
- [ ] Dispatch activity logged to specmenactivity table
- [ ] Dispatched specimens can be tracked

---

### SPM-008: Track Specimen Condition
**Priority**: P0

As a **lab staff**,
I want **to flag specimen condition issues**,
So that **result quality issues can be identified**.

**Acceptance Criteria:**
- [ ] Condition flags can be recorded: HEM (hemolysis), ITC (insufficient), LIP (lipemic)
- [ ] Multiple conditions can be flagged
- [ ] Conditions can be recorded at any stage
- [ ] Conditions displayed on specimen and result views
- [ ] Conditions included in result reports
- [ ] Critical conditions prevent analysis

---

### SPM-009: Log Specimen Activity
**Priority**: P0

As a **laboratory system**,
I want **to maintain complete audit trail for specimen**,
So that **all specimen handling is documented**.

**Acceptance Criteria:**
- [ ] All status changes logged to specmenactivity table
- [ ] Activity record includes: SID, activity type, timestamp, user ID
- [ ] Activity history can be retrieved via GET `/api/specimen/:id/activity`
- [ ] Activity history displayed chronologically
- [ ] Activity cannot be deleted or modified

---

### SPM-010: Link Tests to Specimens
**Priority**: P0

As a **laboratory system**,
I want **to map tests to specific specimens**,
So that **results can be linked to the correct biological material**.

**Acceptance Criteria:**
- [ ] Tests from order can be assigned to specimen(s)
- [ ] One order can have multiple specimens
- [ ] Tests can be split across multiple specimens
- [ ] Test-to-specimen mapping stored in specimen table
- [ ] Results reference the specimen ID
- [ ] Result reports show specimen information for each test

---

## 4. Result Management (P0)

### RES-001: Enter Numeric Results
**Priority**: P0

As a **lab technician or instrument**,
I want **to enter numeric test results**,
So that **quantitative measurements are recorded**.

**Acceptance Criteria:**
- [ ] Create result via POST `/api/patresult`
- [ ] Result type: numeric
- [ ] Requires OrderID, TestID, ResultValue, ResultUnit
- [ ] ResultValue must be valid number
- [ ] ResultUnit must match test definition
- [ ] Decimal precision enforced
- [ ] Initial status is "ENTRY"
- [ ] UTC timestamp recorded

---

### RES-002: Enter Text Results
**Priority**: P0

As a **lab technician or pathologist**,
I want **to enter text-based results**,
So that **qualitative or descriptive findings can be recorded**.

**Acceptance Criteria:**
- [ ] Create result via POST `/api/patresult`
- [ ] Result type: text
- [ ] Requires OrderID, TestID, ResultValue (text)
- [ ] Text can be free-form or coded
- [ ] Text length limits enforced
- [ ] Initial status is "ENTRY"
- [ ] UTC timestamp recorded

---

### RES-003: Enter Value Set Results
**Priority**: P0

As a **lab technician**,
I want **to select results from dropdown options**,
So that **coded results ensure consistency**.

**Acceptance Criteria:**
- [ ] Create result via POST `/api/patresult`
- [ ] Result type: valueset
- [ ] Dropdown populated from linked value set
- [ ] Requires OrderID, TestID, ResultValue (code)
- [ ] Code must be valid value from value set
- [ ] Initial status is "ENTRY"
- [ ] UTC timestamp recorded

---

### RES-004: Enter Range Results
**Priority**: P0

As a **lab technician**,
I want **to enter range-based results**,
So that **measurements with min/max can be recorded**.

**Acceptance Criteria:**
- [ ] Create result via POST `/api/patresult`
- [ ] Result type: range
- [ ] Requires OrderID, TestID, ResultMin, ResultMax, ResultUnit
- [ ] Both min and max must be valid numbers
- [ ] ResultUnit must match test definition
- [ ] Initial status is "ENTRY"
- [ ] UTC timestamp recorded

---

### RES-005: Validate Against Reference Ranges
**Priority**: P0

As a **laboratory system**,
I want **to automatically flag results outside reference ranges**,
So that **abnormal results are highlighted for review**.

**Acceptance Criteria:**
- [ ] System retrieves reference range for test based on patient age/sex
- [ ] Numeric results compared to min/max
- [ ] Text results compared to acceptable values
- [ ] Value set results compared to normal/abnormal flags
- [ ] Results outside range flagged as "abnormal"
- [ ] Flag displayed on result entry and review screens
- [ ] Flag included in result reports

---

### RES-006: Flag Critical Values
**Priority**: P0

As a **laboratory system**,
I want **to identify critical values**,
So that **urgent results are immediately brought to attention**.

**Acceptance Criteria:**
- [ ] Critical values defined in threshold reference ranges
- [ ] Results exceeding critical thresholds flagged as "critical"
- [ ] Critical flag visually prominent in UI
- [ ] Critical results require acknowledgment
- [ ] Critical results require notification to ordering provider
- [ ] Critical notification logged

---

### RES-007: Technical Verification
**Priority**: P0

As a **lab technician or technologist**,
I want **to verify results for technical accuracy**,
So that **results are validated before clinical review**.

**Acceptance Criteria:**
- [ ] Update result status to "VER" via PATCH `/api/patresult/:id/status`
- [ ] Verification requires authenticated user
- [ ] Verifier ID recorded
- [ ] Verification timestamp recorded in UTC
- [ ] Verification requires review of reference range flags
- [ ] Verification requires review of critical values
- [ ] Bulk verification allowed for multiple results
- [ ] Verification can be reversed before clinical review

---

### RES-008: Clinical Review
**Priority**: P0

As a **pathologist or clinical reviewer**,
I want **to review results for clinical interpretation**,
So that **results are validated before reporting**.

**Acceptance Criteria:**
- [ ] Update result status to "REV" via PATCH `/api/patresult/:id/status`
- [ ] Review requires authenticated user with clinical role
- [ ] Reviewer ID recorded
- [ ] Review timestamp recorded in UTC
- [ ] Review can add clinical comments
- [ ] Review can override reference range flags with justification
- [ ] Bulk review allowed for multiple results
- [ ] Review can be reversed before reporting

---

### RES-009: Report Final Results
**Priority**: P0

As a **laboratory staff**,
I want **to finalize results for reporting**,
So that **results can be sent to clinicians**.

**Acceptance Criteria:**
- [ ] Update result status to "REP" via PATCH `/api/patresult/:id/status`
- [ ] Finalization requires clinical review complete
- [ ] Finalization timestamp recorded in UTC
- [ ] Finalizer ID recorded
- [ ] Finalized results cannot be modified (only addendum)
- [ ] Finalized results trigger report generation
- [ ] Finalized results sent to ordering provider
- [ ] Bulk finalization allowed for multiple results

---

### RES-010: Track Result Reruns
**Priority**: P0

As a **lab technician**,
I want **to record result reruns**,
So that **quality issues and repeated measurements are documented**.

**Acceptance Criteria:**
- [ ] Rerun count tracked via AspCnt field
- [ ] Rerun reason can be recorded
- [ ] Rerun timestamp recorded
- [ ] All reruns preserved (no overwriting)
- [ ] Final result selected from reruns
- [ ] Rerun history displayed with result
- [ ] Rerun cannot occur after result verification

---

### RES-011: Add Result Comments
**Priority**: P0

As a **lab technician or pathologist**,
I want **to add comments to results**,
So that **additional context and notes are preserved**.

**Acceptance Criteria:**
- [ ] Add comment via POST `/api/patresult/:id/comments`
- [ ] Comment requires text and user ID
- [ ] Comment timestamp recorded in UTC
- [ ] Comment type flag: technical, clinical, administrative
- [ ] Comments displayed with result
- [ ] Comments included in result reports
- [ ] Comments cannot be deleted (only appended)

---

### RES-012: Manage Result Details
**Priority**: P0

As a **lab technician**,
I want **to add multiple detail parameters to a result**,
So that **complex multi-part results can be recorded**.

**Acceptance Criteria:**
- [ ] Add detail via POST `/api/patresult/:id/details`
- [ ] Detail requires ParameterID and Value
- [ ] Multiple details can be added to one result
- [ ] Details can be numeric, text, or coded
- [ ] Details linked to patresultdetail table
- [ ] Details displayed with main result
- [ ] Details included in result reports

---

## 5. Patient Visit (P1)

### VIS-001: Create Patient Visit
**Priority**: P1

As a **admission or registration staff**,
I want **to create a patient visit record**,
So that **orders and results can be linked to an encounter**.

**Acceptance Criteria:**
- [ ] Create visit via POST `/api/patvisit`
- [ ] Visit requires patient identification (InternalPID)
- [ ] Visit type: inpatient, outpatient, emergency
- [ ] Visit number generated
- [ ] Admission date/time recorded in UTC
- [ ] Discharge date/time nullable (open until discharged)
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/patvisit`

---

### VIS-002: Link Orders to Visit
**Priority**: P1

As a **laboratory or clinical staff**,
I want **to associate orders with a patient visit**,
So that **laboratory work is organized by encounter**.

**Acceptance Criteria:**
- [ ] Orders can be linked to visit during creation
- [ ] Orders can be updated to link to visit
- [ ] Visit ID included in order record
- [ ] Orders can be queried by visit
- [ ] Visit details displayed with orders

---

### VIS-003: Track ADT Events
**Priority**: P1

As a **hospital staff**,
I want **to record patient admission, discharge, and transfer**,
So that **patient location is known throughout the stay**.

**Acceptance Criteria:**
- [ ] Record admission event
- [ ] Record discharge event
- [ ] Record transfer event
- [ ] Each event requires timestamp (UTC) and location
- [ ] ADT events logged to patvisit table
- [ ] Current location always available
- [ ] ADT history queryable

---

### VIS-004: Link Diagnosis to Visit
**Priority**: P1

As a **clinical staff**,
I want **to record patient diagnoses**,
So that **laboratory results can be correlated with clinical conditions**.

**Acceptance Criteria:**
- [ ] Add diagnosis via POST `/api/patvisit/:id/diagnosis`
- [ ] Diagnosis requires ICD code or text
- [ ] Diagnosis type: admission, principal, secondary
- [ ] Multiple diagnoses can be added
- [ ] Diagnoses stored in patdiag table
- [ ] Diagnoses displayed with visit

---

### VIS-005: Track Insurance Information
**Priority**: P1

As a **registration or billing staff**,
I want **to record patient insurance**,
So that **billing information is available**.

**Acceptance Criteria:**
- [ ] Add insurance via POST `/api/patvisit/:id/insurance`
- [ ] Insurance requires: company, policy number, group number
- [ ] Insurance type: primary, secondary, tertiary
- [ ] Multiple insurance policies can be added
- [ ] Insurance stored in patinsurance table
- [ ] Insurance displayed with visit

---

## 6. Instrument Integration (P1)

### EDGE-001: Receive Instrument Results
**Priority**: P1

As a **laboratory instrument via tiny-edge**,
I want **to send results to CLQMS**,
So that **results are automatically recorded in the system**.

**Acceptance Criteria:**
- [ ] Receive results via POST `/api/edge/results`
- [ ] Request includes: instrument ID, sample ID, results array
- [ ] Each result includes: test code, value, unit, timestamp
- [ ] Raw results stored in edgeres table
- [ ] Results queued for processing
- [ ] Acknowledgment returned to instrument
- [ ] Authentication required (API key or JWT)

---

### EDGE-002: Store Raw Edge Results
**Priority**: P1

As a **laboratory system**,
I want **to preserve raw instrument results**,
So that **original data is available for troubleshooting and audit**.

**Acceptance Criteria:**
- [ ] Raw results stored in edgeres table
- [ ] Raw data includes: instrument, sample, test code, value, unit, flags
- [ ] Raw data is immutable (no updates or deletes)
- [ ] Raw data linked to processed result
- [ ] Raw data queryable for troubleshooting

---

### EDGE-003: Log Instrument Status
**Priority**: P1

As a **laboratory instrument**,
I want **to send status updates**,
So that **instrument health is monitored**.

**Acceptance Criteria:**
- [ ] Send status via POST `/api/edge/status`
- [ ] Status includes: instrument ID, status code, message, timestamp
- [ ] Status stored in edgestatus table
- [ ] Status types: ready, busy, error, maintenance, offline
- [ ] Status history queryable
- [ ] Alerts triggered for error status

---

### EDGE-004: Acknowledge Order Delivery
**Priority**: P1

As a **laboratory instrument**,
I want **to acknowledge order receipt**,
So that **the system knows the order was received**.

**Acceptance Criteria:**
- [ ] Acknowledge via POST `/api/edge/orders/:id/ack`
- [ ] Acknowledgment includes: order ID, instrument ID, timestamp
- [ ] Acknowledgment stored in edgeack table
- [ ] Order marked as "acknowledged" in system
- [ ] Missing acknowledgments flagged

---

### EDGE-005: Fetch Pending Orders
**Priority**: P1

As a **laboratory instrument via tiny-edge**,
I want **to retrieve pending orders**,
So that **the instrument knows which samples to process**.

**Acceptance Criteria:**
- [ ] Fetch orders via GET `/api/edge/orders`
- [ ] Can filter by instrument ID
- [ ] Can filter by specimen status
- [ ] Response includes: OrderID, SampleID, tests, priority
- [ ] Only orders not yet acknowledged returned
- [ ] Orders marked as "sent" after retrieval

---

### EDGE-006: Acknowledge Order Delivery
**Priority**: P1

As a **laboratory instrument**,
I want **to confirm order receipt**,
So that **the system can track order delivery**.

**Acceptance Criteria:**
- [ ] Acknowledge via POST `/api/edge/orders/:id/ack`
- [ ] Acknowledgment requires instrument ID
- [ ] Acknowledgment timestamp recorded
- [ ] Acknowledgment stored in edgeack table
- [ ] Failed acknowledgments retried

---

### EDGE-007: Process Edge Results to Patient Results
**Priority**: P1

As a **laboratory system**,
I want **to automatically process raw edge results into patient results**,
So that **instrument results become part of the patient record**.

**Acceptance Criteria:**
- [ ] System polls edgeres table for unprocessed results
- [ ] Test code mapped to TestID via testmap
- [ ] Sample ID mapped to OrderID/SpecimenID
- [ ] Result value and unit converted if needed
- [ ] Reference range validation performed
- [ ] Result created in patresult table with status "ENTRY"
- [ ] Raw result marked as processed
- [ ] Processing errors logged

---

## 7. Quality Control (P2)

### QC-001: Enter QC Results
**Priority**: P2

As a **lab technician**,
I want **to enter quality control results**,
So that **instrument performance is monitored**.

**Acceptance Criteria:**
- [ ] Create QC result via POST `/api/qcresult`
- [ ] QC result requires: instrument, lot number, level, test, value
- [ ] QC results stored in calres table
- [ ] QC result timestamp recorded in UTC
- [ ] QC result linked to QC material lot
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/qcresult`

---

### QC-002: Prepare Levey-Jennings Data
**Priority**: P2

As a **lab manager or quality officer**,
I want **to retrieve Levey-Jennings chart data**,
So that **QC trends can be visualized**.

**Acceptance Criteria:**
- [ ] Get QC data via GET `/api/qcresult/levey-jennings`
- [ ] Requires instrument, test, lot, level, date range
- [ ] Returns: mean, SD, values, timestamps
- [ ] Data formatted for charting libraries
- [ ] Includes control limits (±2SD, ±3SD)

---

### QC-003: Validate QC Results
**Priority**: P2

As a **laboratory system**,
I want **to automatically validate QC results**,
So that **out-of-control QC is flagged**.

**Acceptance Criteria:**
- [ ] System applies Westgard rules (or 2SD rule)
- [ ] Rules: 1:2s warning, 1:3s rejection, 2:2s rejection, etc.
- [ ] Out-of-control QC flagged
- [ ] Flagged QC prevents patient result release
- [ ] QC override requires justification

---

### QC-004: Calculate Sigma Metrics
**Priority**: P2

As a **lab manager or quality officer**,
I want **to calculate sigma metrics**,
So that **method performance can be evaluated**.

**Acceptance Criteria:**
- [ ] Calculate via GET `/api/qcresult/sigma`
- [ ] Requires: test, total allowable error (TEa), CV, bias
- [ ] Formula: Sigma = (TEa - bias) / CV
- [ ] Returns sigma value and quality ranking
- [ ] Rankings: world class (>6), excellent (5), good (4), marginal (3), poor (<3)

---

### QC-005: Query QC History
**Priority**: P2

As a **lab manager or quality officer**,
I want **to review QC history**,
So that **long-term trends can be analyzed**.

**Acceptance Criteria:**
- [ ] Query via GET `/api/qcresult/history`
- [ ] Can filter by instrument, test, lot, date range
- [ ] Returns all QC results with timestamps
- [ ] Includes calculated statistics (mean, SD, CV)
- [ ] Results downloadable as CSV

---

## 8. Calibration (P2)

### CAL-001: Enter Calibration Results
**Priority**: P2

As a **lab technician**,
I want **to record calibration results**,
So that **instrument calibration is documented**.

**Acceptance Criteria:**
- [ ] Create calibration via POST `/api/calibration`
- [ ] Calibration requires: instrument, test, calibrator, factor, result
- [ ] Calibration stored in calres table
- [ ] Calibration timestamp recorded in UTC
- [ ] Calibration type: initial, periodic, after maintenance
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/calibration`

---

### CAL-002: Query Calibration History
**Priority**: P2

As a **lab manager or quality officer**,
I want **to review calibration history**,
So that **instrument performance over time is documented**.

**Acceptance Criteria:**
- [ ] Query via GET `/api/calibration/history`
- [ ] Can filter by instrument, test, date range
- [ ] Returns all calibrations with factors and results
- [ ] Includes calibration type and technician
- [ ] Results downloadable as CSV

---

### CAL-003: Validate Calibration
**Priority**: P2

As a **laboratory system**,
I want **to validate calibration results**,
So that **out-of-spec calibration is flagged**.

**Acceptance Criteria:**
- [ ] Calibration result compared to acceptable range
- [ ] Out-of-spec calibration flagged
- [ ] Flagged calibration prevents patient testing
- [ ] Calibration override requires justification
- [ ] Calibration failure triggers maintenance request

---

## 9. Audit Trail (P2)

### AUD-001: Automatic Audit Logging
**Priority**: P2

As a **laboratory system**,
I want **to automatically log all data changes**,
So that **complete audit trail is maintained**.

**Acceptance Criteria:**
- [ ] Middleware intercepts all create/update/delete operations
- [ ] Audit record includes: table, record ID, action, user, timestamp
- [ ] Before and after values captured
- [ ] IP address and user agent logged
- [ ] Audit records stored in audit table
- [ ] Audit records are immutable

---

### AUD-002: Track What/Who/When
**Priority**: P2

As a **compliance officer or auditor**,
I want **to see complete change history**,
So that **data provenance is documented**.

**Acceptance Criteria:**
- [ ] Query via GET `/api/audit`
- [ ] Can filter by table, record, user, date range, action
- [ ] Returns: action, table, record, user, timestamp, before, after
- [ ] Results sorted chronologically
- [ ] Supports pagination

---

### AUD-003: Log Security Events
**Priority**: P2

As a **laboratory system**,
I want **to log authentication and authorization events**,
So that **security incidents can be investigated**.

**Acceptance Criteria:**
- [ ] Login attempts logged (success and failure)
- [ ] Logout events logged
- [ ] Failed authorization attempts logged
- [ ] Password changes logged
- [ ] Permission changes logged
- [ ] Events include: user, IP, timestamp, result

---

### AUD-004: Query Audit Logs
**Priority**: P2

As a **compliance officer or auditor**,
I want **to search audit logs**,
So that **specific events can be investigated**.

**Acceptance Criteria:**
- [ ] Query via GET `/api/audit/search`
- [ ] Search parameters: table, record, user, action, date range, keyword
- [ ] Returns matching audit records
- [ ] Results sorted by relevance or chronology
- [ ] Supports export to CSV/JSON

---

## 10. Inventory & Billing (P3)

### INV-001: Manage Counters
**Priority**: P3

As a **system administrator**,
I want **to manage system counters**,
So that **sequential IDs can be generated**.

**Acceptance Criteria:**
- [ ] Create counter via POST `/api/counter`
- [ ] Counter requires: name, prefix, current value
- [ ] Counter can be incremented
- [ ] Counter can be reset
- [ ] Counters used for OrderID, SpecimenID, ResultID generation
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/counter`

---

### INV-002: Manage Product Catalog
**Priority**: P3

As a **inventory manager**,
I want **to maintain product catalog**,
So that **reagents and consumables are tracked**.

**Acceptance Criteria:**
- [ ] Create product via POST `/api/product`
- [ ] Product requires: name, code, category, unit
- [ ] Product includes: manufacturer, catalog number
- [ ] Products can be marked as active/inactive
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/product`

---

### INV-003: Track Reagent Lots
**Priority**: P3

As a **inventory manager**,
I want **to track reagent lot numbers and expiration**,
So that **QC can be linked to specific lots**.

**Acceptance Criteria:**
- [ ] Create lot via POST `/api/reagentlot`
- [ ] Lot requires: product, lot number, expiration date
- [ ] Lot includes: received date, quantity, location
- [ ] Lots can be marked as open/closed
- [ ] Expired lots flagged
- [ ] API endpoints: GET/POST/PATCH/DELETE `/api/reagentlot`

---

### INV-004: Track Consumable Usage
**Priority**: P3

As a **lab technician**,
I want **to record consumable usage**,
So that **inventory is accurate**.

**Acceptance Criteria:**
- [ ] Create usage record via POST `/api/consumableusage`
- [ ] Usage requires: product, quantity, test or order
- [ ] Usage timestamp recorded
- [ ] Usage linked to user ID
- [ ] Usage updates inventory quantity
- [ ] Low inventory alerts triggered

---

### INV-005: Export Billing Data
**Priority**: P3

As a **billing staff**,
I want **to export completed orders for billing**,
So that **charges can be generated**.

**Acceptance Criteria:**
- [ ] Export via GET `/api/billing/export`
- [ ] Can filter by date range, account, order status
- [ ] Export includes: OrderID, PatientID, tests, dates
- [ ] Export format: CSV, JSON, or HL7
- [ ] Billing codes included (CPT, LOINC)
- [ ] Export marks orders as "billed"

---

### INV-006: Select Service Class
**Priority**: P3

As a **ordering provider**,
I want **to select service class for billing**,
So that **appropriate pricing is applied**.

**Acceptance Criteria:**
- [ ] Service class options: routine, urgent, stat, research, etc.
- [ ] Service class selected during order creation
- [ ] Service class affects billing tier
- [ ] Service class included in billing export
- [ ] Service class can be updated before billing

---

## Summary Statistics

**Total User Stories**: 103

**By Priority:**
- P0 (Must-have): 75
- P1 (Should-have): 10
- P2 (Nice-to-have): 13
- P3 (Future): 5

**By Module:**
- Master Data: 28 stories
- Order Management: 10 stories
- Specimen Management: 10 stories
- Result Management: 12 stories
- Patient Visit: 5 stories
- Instrument Integration: 7 stories
- Quality Control: 5 stories
- Calibration: 3 stories
- Audit Trail: 4 stories
- Inventory & Billing: 6 stories

---

## User Story Mapping

### MVP Sprint 1: Foundation (Weeks 1-4)
- All Master Data stories (28 stories)

### MVP Sprint 2: Orders & Specimens (Weeks 5-8)
- Order Management stories (10 stories)
- Specimen Management stories (10 stories)

### MVP Sprint 3: Results (Weeks 9-12)
- Result Management stories (12 stories)

### MVP Sprint 4: Integration (Weeks 13-16)
- Patient Visit stories (5 stories)
- Instrument Integration stories (7 stories)

### Post-MVP: Enhancement (Weeks 17+)
- Quality Control stories (5 stories)
- Calibration stories (3 stories)
- Audit Trail stories (4 stories)
- Inventory & Billing stories (6 stories)

---

**Document Status**: Draft for Review
**Last Updated**: 2026-01-28
**Next Review**: Prior to Sprint 1 kickoff