Quality Control (مراقبة الجودة)

Quality Control (QC) ensures analytical accuracy by running control materials with known values alongside patient samples. The LIS module supports QC lot management, result recording with Westgard rule evaluation, and Levey-Jennings chart data generation.

QC Lot Attributes

Field	Type	Required	Description
id	integer	auto	Primary key
lot_number	string	yes	Manufacturer lot number
name	string	yes	Lot name (English)
name_ar	string	no	Lot name (Arabic)
investigation_id	FK	yes	Investigation this lot is for
manufacturer	string	no	Control material manufacturer
expiry_date	date	no	Lot expiration date
target_mean	decimal(12,4)	yes	Expected mean value
target_sd	decimal(12,4)	yes	Expected standard deviation
unit	string	no	Measurement unit
level	integer	no	QC level (1, 2, 3)
is_active	boolean	no	Active status (default: true)

QC Result Attributes

Field	Type	Required	Description
id	integer	auto	Primary key
qc_lot_id	FK	yes	Parent QC lot
value	decimal(12,4)	yes	Measured QC value
sd_from_mean	decimal(12,4)	auto	Standard deviations from mean
status	enum	auto	pass, warning, fail
shift	enum	no	morning, evening, night
violated_rules	JSON	auto	Array of violated Westgard rules
comment	text	no	Technician comment
performed_at	datetime	yes	When the QC was run
performed_by	FK	yes	User who ran the QC
reviewed_by	FK	no	Supervisor who reviewed

ER Diagram

API Endpoints

Method	Endpoint	Description	Permission
GET	/api/lis/qc-lots	List QC lots	lis.qc-lots.view
POST	/api/lis/qc-lots	Create QC lot	lis.qc-lots.create
GET	/api/lis/qc-lots/{id}	Get QC lot details	lis.qc-lots.view
PUT	/api/lis/qc-lots/{id}	Update QC lot	lis.qc-lots.update
DELETE	/api/lis/qc-lots/{id}	Delete QC lot	lis.qc-lots.delete
GET	/api/lis/qc-lots/{id}/results	List QC results	lis.qc-lots.view
POST	/api/lis/qc-lots/{id}/results	Record QC result	lis.qc-lots.create
DELETE	/api/lis/qc-lots/{id}/results/{rid}	Delete QC result	lis.qc-lots.delete
GET	/api/lis/qc-lots/{id}/levey-jennings	Levey-Jennings chart data	lis.qc-lots.view

Request / Response Examples

Create QC Lot

curl

curl -X POST /api/lis/qc-lots \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "lot_number": "LOT-2026-001",
    "name": "Normal Control - Glucose",
    "name_ar": "مادة ضبط عادية - جلوكوز",
    "investigation_id": 5,
    "manufacturer": "Bio-Rad",
    "expiry_date": "2027-06-30",
    "target_mean": 95.0,
    "target_sd": 3.5,
    "unit": "mg/dL",
    "level": 1
  }'

Dart

final response = await dio.post('/api/lis/qc-lots', data: {
  'lot_number': 'LOT-2026-001',
  'name': 'Normal Control - Glucose',
  'name_ar': 'مادة ضبط عادية - جلوكوز',
  'investigation_id': 5,
  'manufacturer': 'Bio-Rad',
  'expiry_date': '2027-06-30',
  'target_mean': 95.0,
  'target_sd': 3.5,
  'unit': 'mg/dL',
  'level': 1,
});

Record QC Result

curl

curl -X POST /api/lis/qc-lots/1/results \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 97.2,
    "shift": "morning",
    "performed_at": "2026-03-01T08:30:00Z",
    "performed_by": 1
  }'

Dart

final response = await dio.post('/api/lis/qc-lots/1/results', data: {
  'value': 97.2,
  'shift': 'morning',
  'performed_at': '2026-03-01T08:30:00Z',
  'performed_by': 1,
});

Get Levey-Jennings Data

curl

curl -G /api/lis/qc-lots/1/levey-jennings \
  -H "Authorization: Bearer {token}"

Dart

final response = await dio.get('/api/lis/qc-lots/1/levey-jennings');

Westgard Rules

The system evaluates QC results against the following Westgard multi-rules:

Rule	Description	Status
1-2s	Single result exceeds mean +/- 2SD	Warning
1-3s	Single result exceeds mean +/- 3SD	Fail
2-2s	Two consecutive results exceed mean +/- 2SD (same side)	Fail
R-4s	Range between two consecutive results exceeds 4SD	Fail
4-1s	Four consecutive results on the same side of the mean beyond 1SD	Warning
10x	Ten consecutive results on the same side of the mean	Fail

Business Rules

1. SD calculation -- sd_from_mean is calculated as (value - target_mean) / target_sd.
2. Automatic status -- QC status (pass, warning, fail) is set automatically based on Westgard rule evaluation.
3. Violated rules -- The violated_rules JSON array lists which Westgard rules were triggered.
4. Levey-Jennings -- The chart endpoint returns all data points with SD lines for visualization.
5. Shift tracking -- QC results are tracked by shift (morning, evening, night) for trend analysis.