🛠️ Structural Fix: Sample ↔ Investigation Linkage

المشكلة في كلمة

دلوقتي مفيش جدول صريح يربط الـ sample بالـ investigations اللي عليها. النظام بيستنتج الرابطة من ٣ آليات مختلفة (section، specimen_type، deferred JSON). ده بيخلي:

تأجيل تحليل واحد من panel = بيرجع البنل كله بدل التحليل ده
Aliquot يفترض إن كل tests القسم في الـ child الواحد
الـ FE يضطر يـ "يخمن" بـ filterBillableTests + panel parent inference
الـ result creation listener يحسب الـ investigations يدوياً من الـ section

الحل: جدول صريح `lab_sample_investigations`

CREATE TABLE lab_sample_investigations (
  id BIGINT PK,
  lab_sample_id BIGINT FK → lab_samples,
  lab_investigation_id BIGINT FK → lab_investigations,
  lab_request_investigation_id BIGINT FK → lab_request_investigations (NULLABLE),
  status ENUM('pending','collected','rejected','deferred','recollected'),
  deferred_reason TEXT NULL,
  rejection_reason TEXT NULL,
  created_at, updated_at, deleted_at,
  UNIQUE(lab_sample_id, lab_investigation_id, deleted_at)
)

كل sample بقى متضمن قائمة صريحة بالـ tests اللي عليها. صفر inference.

الـ Flow الجديد

الـ Action	قبل (الحالي)	بعد (الجديد)
Create initial sample	sample بدون investigations؛ يستنتج من section	إنشاء sample + إنشاء rows في `sample_investigations` لكل تحليل تابع له
Aliquot	group by section في الـ FE/listener	قسم الـ `sample_investigations` على الـ children
Defer test	sample جديد is_deferred=true + JSON	sample جديد + نقل الـ row للسامبل الجديد بـ status='deferred'
Recollect	sample جديد + overload JSON كـ "scoped"	sample جديد + نقل الـ rows بـ status='pending'
Collect	sample.status = collected	sample.status + كل `sample_investigations` → 'collected'
Create results (listener)	يحسب الـ investigations من section_id/specimen_type	قراءة مباشرة من `sample.investigations`
FE Display tube codes	`filterBillableTests` + panel logic معقد	قراءة مباشرة من `sample.investigations`

الـ Migration Phases (٥ مراحل)

١Backend: Schema + Backfill (لا تأثير على المستخدم)

Migration: إنشاء lab_sample_investigations
Backfill: data migration يملأ الجدول من البيانات الحالية:
- للسامبلز العادية: يضيف rows لكل investigation تابعة لنفس الـ section/specimen
- للسامبلز المؤجلة: يضيف rows من deferred_investigation_ids بـ status='deferred'
Model: LabSampleInvestigation + relationship على LabSample::investigations()
Eager loading في الـ index endpoints

٢Backend: Writers

LabSampleController::store() — إنشاء rows في الـ pivot وقت إنشاء sample
LabSampleService::aliquot() — نقل الـ rows من parent للـ children حسب section
LabSampleController::defer() — نقل الـ rows من sample قائم → sample جديد بـ status='deferred'
LabSampleService::recollect() — نقل الـ rows من deferred sample → pending sample
LabSampleController::reject() — تحديث الـ status على الـ rows
LabSampleService::collect() — تحديث الـ status على الـ rows

٣Backend: Readers + Listener

LabSampleResource — include investigations relation
GenerateResultsOnSampleReceived listener — قراءة من $sample->investigations مباشرة
Kanban controller — استخدم $sample->investigations بدلاً من section query

٤Frontend

LisSample model: إضافة investigations: SampleInvestigation[]
collection-worklist: الـ tubes builder يقرأ من sample.investigations مباشرة — لا filterBillableTests
Defer dialog: يبقى نفس الـ panel-aware structure (panel parent header + members)
Recollect handler: يستخدم investigation_ids فقط — لا workaround PUT
Display: kanban + results يقرأوا من sample.investigations

٥Cleanup (later)

إزالة is_deferred + deferred_investigation_ids من lab_samples (بعد ما الكل يستقر)
إزالة filterBillableTests/buildPanelMemberMap من الـ FE utilities لو مش مستخدمة

الـ Risks

Backfill عملاق: لو في ١٠٠٠+ sample قائم، الـ data migration يلزم يخلص بدقة. هنعمل dry-run أولاً.
الكود الموجود: أي endpoint بيستخدم الـ JSON الـ deprecated مش هيتعطّل لأن الـ columns لسة موجودة — الـ Phase ٥ هتشيلهم بعد التأكد.
Kanban listener: الـ listener بيستخدم section. لازم نتأكد إن الـ pivot rows كلها متربطة بشكل صحيح قبل ما نغير الـ listener.

الترتيب التنفيذي

Phase 1 (BE schema + backfill) — اختبار على dev
Phase 2 (BE writers) — الـ defer/recollect أولاً، aliquot ثانياً
Phase 3 (BE readers + listener)
Phase 4 (FE) — UI يقرأ من الـ relation الجديد
Final test: defer TG من Lipid Panel، recollect، verify TG يظهر لوحده
Phase 5 (Cleanup) — بعد ما الـ user يأكد إن الكل شغّال