Lab Requests (طلبات الفحص)

Lab Requests represent test orders placed by doctors for patients. Each request contains one or more investigations and tracks the order through its lifecycle from creation to completion or cancellation.

Entity Attributes

Field	Type	Required	Description
id	integer	auto	Primary key
request_number	string	auto	Auto-generated request number
patient_id	FK	yes	Patient being tested
doctor_id	FK	yes	Ordering doctor
priority	enum	yes	routine, urgent, stat
status	enum	auto	pending, sample_collected, in_progress, partial_result, completed, cancelled
source	enum	yes	walk_in, in_patient, emergency, external
clinical_info	text	no	Clinical information / reason for test
notes	text	no	Additional notes
total_amount	decimal(12,3)	auto	Sum of investigation prices
discount_amount	decimal(12,3)	no	Total discount applied
net_amount	decimal(12,3)	auto	Total minus discount
branch_id	FK	no	Branch where request was placed
requested_at	datetime	auto	When the request was created
completed_at	datetime	auto	When all results are released
cancelled_at	datetime	auto	When the request was cancelled
cancellation_reason	string	no	Reason for cancellation

Request Investigation (Pivot)

Field	Type	Description
lab_request_id	FK	Parent request
investigation_id	FK	Ordered investigation
status	string	Per-investigation status
price	decimal(12,3)	Investigation price
discount	decimal(12,3)	Per-investigation discount
net_price	decimal(12,3)	Price minus discount
notes	text	Investigation-specific notes

Status Workflow

API Endpoints

Method	Endpoint	Description	Permission
GET	/api/lis/requests	List requests (paginated)	lis.requests.view
POST	/api/lis/requests	Create a request	lis.requests.create
GET	/api/lis/requests/{id}	Get request details	lis.requests.view
PUT	/api/lis/requests/{id}	Update a request	lis.requests.update
POST	/api/lis/requests/{id}/cancel	Cancel a request	lis.requests.update
POST	/api/lis/requests/{id}/investigations	Add investigation	lis.requests.update
DELETE	/api/lis/requests/{id}/investigations/{inv_id}	Remove investigation	lis.requests.update

Query Parameters (List)

Parameter	Type	Description
search	string	Search by request number or patient name
status	string	Filter by status
priority	string	Filter by priority
source	string	Filter by source
patient_id	integer	Filter by patient
doctor_id	integer	Filter by doctor
from	date	Start date filter
to	date	End date filter

Request / Response Examples

Create Request

curl

curl -X POST /api/lis/requests \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": 1,
    "doctor_id": 1,
    "priority": "routine",
    "source": "walk_in",
    "clinical_info": "Annual checkup",
    "investigations": [
      {"investigation_id": 1},
      {"investigation_id": 5, "notes": "Fasting sample"}
    ],
    "branch_id": 1
  }'

Dart

final response = await dio.post('/api/lis/requests', data: {
  'patient_id': 1,
  'doctor_id': 1,
  'priority': 'routine',
  'source': 'walk_in',
  'clinical_info': 'Annual checkup',
  'investigations': [
    {'investigation_id': 1},
    {'investigation_id': 5, 'notes': 'Fasting sample'},
  ],
  'branch_id': 1,
});

Cancel Request

curl

curl -X POST /api/lis/requests/1/cancel \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"cancellation_reason": "Patient did not arrive"}'

Dart

final response = await dio.post('/api/lis/requests/1/cancel', data: {
  'cancellation_reason': 'Patient did not arrive',
});

Add Investigation to Request

curl

curl -X POST /api/lis/requests/1/investigations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"investigation_id": 10}'

Dart

final response = await dio.post('/api/lis/requests/1/investigations', data: {
  'investigation_id': 10,
});

Business Rules

1. No delete -- Requests cannot be deleted, only cancelled.
2. Cancel restrictions -- Only requests with status pending or sample_collected can be cancelled.
3. Panel expansion -- When a panel investigation is added, all its member investigations are also added.
4. Price calculation -- total_amount is automatically calculated from investigation prices at the time of creation.
5. Add/remove investigations -- Investigations can be added or removed from active requests. Amounts are recalculated.