Samples (العينات)

Samples represent biological specimens collected from patients. Each sample is linked to a lab request and a specimen type, and progresses through collection, receiving at the lab, and eventual processing or rejection.

Entity Attributes

Field	Type	Required	Description
id	integer	auto	Primary key
sample_number	string	auto	Auto-generated sample number
barcode	string	auto	Sample barcode for tracking
lab_request_id	FK	yes	Associated lab request
patient_id	FK	yes	Patient who provided the sample
specimen_type_id	FK	yes	Type of specimen collected
status	enum	auto	pending, collected, received, processing, completed, rejected
collected_at	datetime	auto	When sample was collected
collected_by	FK	auto	User who collected the sample
received_at	datetime	auto	When sample was received at the lab
received_by	FK	auto	User who received the sample
rejected_at	datetime	auto	When sample was rejected
rejected_by	FK	auto	User who rejected the sample
rejection_reason	string	no	Reason for rejection
notes	text	no	Sample notes
branch_id	FK	no	Branch location
created_at	datetime	auto	Creation timestamp
updated_at	datetime	auto	Last update timestamp

Status Workflow

API Endpoints

Method	Endpoint	Description	Permission
GET	/api/lis/samples	List samples (paginated)	lis.samples.view
POST	/api/lis/samples	Create a sample	lis.samples.create
GET	/api/lis/samples/{id}	Get sample details	lis.samples.view
POST	/api/lis/samples/{id}/collect	Mark sample as collected	lis.samples.update
POST	/api/lis/samples/{id}/receive	Receive sample at the lab	lis.samples.update
POST	/api/lis/samples/{id}/reject	Reject sample	lis.samples.update

Query Parameters (List)

Parameter	Type	Description
search	string	Search by sample number or barcode
status	string	Filter by status
patient_id	integer	Filter by patient
lab_request_id	integer	Filter by lab request
specimen_type_id	integer	Filter by specimen type
from	date	Start date filter
to	date	End date filter

Request / Response Examples

Create Sample

curl

curl -X POST /api/lis/samples \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "lab_request_id": 1,
    "patient_id": 1,
    "specimen_type_id": 1,
    "branch_id": 1
  }'

Dart

final response = await dio.post('/api/lis/samples', data: {
  'lab_request_id': 1,
  'patient_id': 1,
  'specimen_type_id': 1,
  'branch_id': 1,
});

Collect Sample

curl

curl -X POST /api/lis/samples/1/collect \
  -H "Authorization: Bearer {token}"

Dart

final response = await dio.post('/api/lis/samples/1/collect');

Reject Sample

curl

curl -X POST /api/lis/samples/1/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"rejection_reason": "Hemolyzed sample"}'

Dart

final response = await dio.post('/api/lis/samples/1/reject', data: {
  'rejection_reason': 'Hemolyzed sample',
});

Business Rules

1. Status transitions -- collect only from pending; receive only from collected; reject from collected or received.
2. Auto-tracking -- Collection, receiving, and rejection timestamps and user IDs are automatically recorded.
3. Barcode -- Each sample gets a unique barcode for physical tracking and machine interfacing.
4. Chain of custody -- Every status change can be tracked via Compliance - Custody Logs.
5. Rejection -- Rejected samples require a new sample to be collected.