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)
2. Order Management (P0)
3. Specimen Management (P0)
4. Result Management (P0)
5. Patient Visit (P1)
6. Instrument Integration (P1)
7. Quality Control (P2)
8. Calibration (P2)
9. Audit Trail (P2)
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