LIS — Gap Analysis & Plan

🎯 المبدأ — ما الذي يتغير وما الذي يبقى ثابتاً

قبل ما نطبخ — قاعدة المشروع الذهبية: الـ Flow ثابت تماماً. اللي بيختلف بس نقطتين.

① الوضع الحالي — الأنواع الموجودة

الـ ResultType enum يدعم 5 أنواع. كل نوع له تعامل خاص في 5 صفحات (investigation form, kanban, results entry, validation worklist, PDF report). أي نوع جديد لازم يـ "يتعلم" في كل المسارات دي.

② الـ Critical Paths في الكود

كل نوع جديد لازم يـ تتبع في الأماكن الـ 7 دي. هنا الـ baseline اللي الـ agents فحصوها.

file النوع الجديد ① — File / Multi-file Upload

المختبر يرفع ملف أو أكتر كنتيجة (مثل تقارير أشعة، PDFs من جهاز خارجي، صور كاميرا ميكروسكوب). العميل يـ download من بوابته.

1. Schema — استخدام الـ attachments القائمة (polymorphic)

مفيش جدول جديد. الـ attachments القائمة في Core polymorphic أصلاً، نـ morph عليها LabResult.

// migration: add file_settings JSON to lab_investigations
$table->json('file_settings')->nullable();
// { max_files: 10, max_size_mb: 10, allowed_mime: ["application/pdf", "image/*"], required_min: 1 }

// LabResult model — new relation:
public function attachments() {
    return $this->morphMany(Attachment::class, 'attachable');
}

2. Investigation form

• إضافة { label: 'RESULT_FILE', value: 'file' } في resultTypeOptions
• لما يختار file يظهر panel فيه: max files, max size MB, allowed mime types (multiselect), min required
• إخفاء الـ Normal Ranges tab (مفيش معنى للـ abnormal flag)

3. Result entry UI

component جديد ResultFileCellComponent يستخدم PrimeNG p-fileUpload (multiple, custom mode). يظهر:

• drag & drop area
• thumbnail للصور، أيقونة mime للـ PDF/DOC
• delete-with-confirm لكل ملف
• عداد إجمالي الحجم + التحقق client-side من file_settings

4. API contract

إعادة استخدام endpoint الـ attachments العام (موجود أصلاً)، مع endpoint LIS صغير للـ transition:

POST /api/core/attachments        (multipart, موجود)
GET  /api/core/attachments?attachable_type=...
POST /api/lis/results/{id}/finalize-files   ← جديد
    → يفحص count >= required_min
    → يـ set result_value = "{n} files"
    → ينقل الـ status من pending → entered

5. Report / Portal

6. الحالات الحرجة

• بعد الـ Release: منع رفع جديد (gate في AttachmentController::store لما المرفق LabResult)
• الـ Retract: النسخة المرتجعة تـ delete، النسخة الجديدة تبدأ فاضية
• Formulas: الـ triggerFormulaCalculations يتخطى الـ file results
• Cleanup: أمر artisan أسبوعي يـ hard-delete الـ soft-deleted attachments بعد 90 يوم

7. Permissions

• lis.results.upload-file
• lis.results.delete-file

🎨 Mockup ① — Investigation form (الـ admin بيعرّف تحليل جديد نوعه File)

🎨 Mockup ② — Result entry (الفني بيرفع الملفات)

🎨 Mockup ③ — Patient portal (العميل بيشوف ويـ download)

culture النوع الجديد ② — Urine Culture & Sensitivity

تقرير ميكروبيولوجي structured: عينة → نمو → كائن (أو أكتر) → matrix من المضادات الحيوية (S/I/R + MIC). الـ TAT أيام مش دقايق.

الـ Industry Context

تقرير C&S القياسي فيه:

• Colony count — مثل 10⁵ CFU/mL
• Organisms — قائمة الكائنات المعزولة (E.coli, S.aureus, …)
• AST (Antibiotic Susceptibility Test) — لكل كائن جدول مضادات بـ verdict S Sensitive / I Intermediate / R Resistant + اختياري MIC قيمة
• Interpretation — تعليق نصي للطبيب

1. Schema — result_payload JSON على lab_results

// migration:
$table->json('result_payload')->nullable();

// payload shape:
{
  "version": 1,
  "incubation_started_at": "2026-05-22T08:00:00Z",
  "incubation_hours": 48,
  "macroscopy": "Cloudy urine, RBCs +",
  "growth_type": "pure|mixed|no_growth|contaminated",
  "interpretation": "Significant bacteriuria...",
  "organisms": [
    {
      "name": "Escherichia coli",
      "colony_count": "1e5",
      "colony_count_unit": "CFU/mL",
      "ast": [
        { "antibiotic_id": 12, "code": "NIT", "result": "S", "mic": "16", "mic_unit": "µg/mL" },
        { "antibiotic_id": 13, "code": "AMP", "result": "R", "mic": null }
      ]
    }
  ]
}

2. Master data — جدول lab_antibiotics جديد

lab_antibiotics
  id, company_id, code, name, name_ar, abbreviation,
  drug_class (penicillin/quinolone/...), is_active, sort_order

seed بـ ~60 مضاد من CLSI starter. ميصحش نـ overload lab_investigations لأن المضادات مش tests يـ billable.

3. Investigation config

عمود JSON جديد culture_config على lab_investigations:

{
  "default_antibiotic_ids": [12, 13, 14, 15],
  "default_incubation_hours": 48,
  "growth_types_allowed": ["pure", "mixed", "no_growth", "contaminated"]
}

4. Result entry UI — Dialog منفصل

الـ resultType === 'culture' ميظهرش inline input. يظهر زر "Enter culture" يفتح CultureResultDialogComponent:

┌─ Specimen header (read-only) ────────────────────┐
│ Patient · MRN · Test code · Barcode · Day 2/3    │
├─ Growth ────────────────────────────────────────┤
│ ( ) No growth   ( ) Pure   (•) Mixed flora      │
│ Macroscopy: [textarea]                          │
│ Incubation started: [datetime]  Hours: [48]     │
├─ Organisms ──────────────────── [+ Add organism]┤
│ ┌ Organism 1 ────────────────────────── [X] ──┐ │
│ │ Name: [autocomplete: E.coli, ...]           │ │
│ │ Colony count: [1e5] [CFU/mL ▾]              │ │
│ │ AST grid:                                   │ │
│ │ ┌────────────┬───┬───┬───┬──────┬──────┐    │ │
│ │ │ Antibiotic │ S │ I │ R │ MIC  │ Unit │    │ │
│ │ │ Nitrofur.  │(•)│( )│( )│ 16   │µg/mL │    │ │
│ │ │ Ampicillin │( )│( )│(•)│      │      │    │ │
│ │ └────────────┴───┴───┴───┴──────┴──────┘    │ │
│ └─────────────────────────────────────────────┘ │
│ Interpretation: [textarea, optional]            │
├──────────── [Save draft] [Submit] ──────────────┤

5. API contract

تعديل POST /lis/results/{id}/enter ليقبل result_payload اختياري:

POST /lis/results/{id}/enter
{
  "result_value": "E. coli 1e5 CFU/mL — S to NIT, R to AMP",  // ملخص للقوائم
  "result_payload": { ...culture payload },                    // مطلوب لـ culture
  "comment": "..."
}

قاعدة validation جديدة: لو investigation.result_type === 'culture' فالـ result_payload required.

6. Report rendering

• سطر macroscopy
• سطر growth_type
• لكل كائن: عنوان bold + جدول AST مع cells ملوّنة SIR
• سطر interpretation italic
• CLSI legend في الـ footer

7. الحالات الحرجة

• No growth: ميتطلبش organisms array
• Contaminated: زر "Reject & re-collect" مباشر
• Save draft: الـ entered writable لحد الـ provisional submit
• Panel containing culture: ممنوع في v1 (validation يرفض)

8. Permissions

إعادة استخدام lis.results.enter|validate|approve|release. صلاحية واحدة جديدة بس:

• lis.antibiotics.view / .manage — للـ CRUD page الجديد

🎨 Mockup ① — Investigation form (admin بيعرّف Urine C&S)

🎨 Mockup ② — Result entry dialog (الفني يدخل نتيجة C&S كاملة)

🎨 Mockup ③ — Report rendering (الـ PDF/HTML اللي العميل بيشوفه)

histopathology النوع الجديد ③ — Histopathology Report

تقرير باثولوجي طويل ومفصل (نص + صور slides + كود ICD). الـ TAT أيام، فيه مراجعة من باثولوجي ثاني (peer review). أشبه بـ Word document متعدد الأقسام مع صور مرفقة.

1. Schema — جدول جديد lab_histopath_results

هنا الـ structure ثابت ومعقد ومفيد للبحث/التدقيق، فجدول dedicated أفضل من JSON.

lab_histopath_results
  id, company_id, lab_result_id (FK unique),
  gross_description TEXT,
  microscopic_description TEXT,
  diagnosis TEXT,
  comment TEXT,
  recommendation TEXT,
  icd_code VARCHAR(20),
  icd_o_code VARCHAR(20),
  tnm_stage VARCHAR(50),
  margin_status VARCHAR(50),
  ihc_markers JSON,                     -- {ER:"+",PR:"-",HER2:"2+"}
  specimen_received_at TIMESTAMP,
  grossing_at TIMESTAMP,
  draft_saved_at TIMESTAMP,
  peer_reviewed_by BIGINT, peer_reviewed_at TIMESTAMP,
  signed_off_by BIGINT, signed_off_at TIMESTAMP,
  created_by, updated_by, timestamps, softDeletes

الصور تستخدم attachments القائمة (نفس النمط بتاع الـ file type).

2. Investigation form

• إضافة 'histopathology' في resultTypeOptions
• investigation واحد generic لكل subspecialty (Breast biopsy، Prostate core، Lymph node…) كل واحد row منفصل في lab_investigations
• flags جديدة على lab_investigations: requires_peer_review، requires_grossing

3. Result entry UI — Dialog منبثق (نفس النمط بتاع culture)

الـ resultType === 'histopathology' ميظهرش inline input. من نفس مكان "Enter result" في الـ kanban / results page، يفتح HistopathResultDialogComponent — modal كبير فيه tabs. مفيش route جديد، مفيش page جديدة. UI tabs:

[Header: Patient | Request # | Specimen | Status]
[Tabs: Gross | Microscopic | Diagnosis | IHC/Staging | Images | Audit]
  - Gross: rich-text editor + specimen_received_at + grossing_at
  - Microscopic: rich-text editor
  - Diagnosis: rich-text editor + ICD code + ICD-O autocomplete
  - IHC/Staging: ihc_markers grid + TNM stage + margin status
  - Images: multi-upload drag-drop + captions
  - Audit: timestamps + signoff history
[Footer: [Save Draft] [Submit for Peer Review] [Sign-off & Release]]

4. Workflow — نفس الـ 5 statuses + signoff fields

• pending → entered: "Submit for Peer Review" — يـ set draft + يـ submit
• entered → validated: peer pathologist signs (يـ set peer_reviewed_by)
• validated → approved: consultant signoff (يـ set signed_off_by)
• approved → released: الإفراج للعميل

5. API contract — endpoints dedicated

PUT  /lis/results/{id}/histopath              ← حفظ draft / تحديث structured payload
POST /lis/results/{id}/histopath/submit       ← pending → entered
POST /lis/results/{id}/histopath/peer-review  ← entered → validated
POST /lis/results/{id}/histopath/images       ← multipart upload صور
DELETE /lis/results/{id}/histopath/images/{aid}

الـ approve و release standard endpoints بدون تغيير.

6. Report rendering — sub-report مستقل

التقرير العادي grid (سطر لكل نتيجة). تقرير الـ histopath narrative بصفحة كاملة. الحل:

• بعد الـ standard results grid، نضيف للكل result بـ result_type === 'histopathology' صفحة dedicated
• أقسام: Gross / Microscopic / Diagnosis / Comment / IHC / Staging
• 2-column image gallery
• زر "View Histopathology Report" في الـ patient portal يفتح نفس الـ sub-report

7. TAT / Lifecycle — نفس الـ Kanban العادي

8. Permissions — 3 صلاحيات جديدة

• lis.results.histopath.draft — أي باثولوجي يقدر يـ draft
• lis.results.histopath.peer_review — باثولوجي خبرة
• lis.results.histopath.signoff — consultant final approve

🎨 Mockup ① — Investigation form (admin بيعرّف Breast Biopsy)

🎨 Mockup ② — Result entry dialog (الباثولوجي بيكتب التقرير من kanban)

🎨 Mockup ③ — Images tab (نفس الصفحة)

🎨 Mockup ④ — Report sub-section (الـ histopath في الـ printed report)

⑥ البنية المشتركة (Shared Infrastructure)

قبل ما نشتغل على أي نوع، فيه قرارات معمارية مشتركة لازم تتقفل أولاً.

القرارات المعمارية الأساسية

الـ Master data الجديدة

• lab_antibiotics — جدول جديد + CRUD page + seeder CLSI
• lab_histopath_templates (optional v2) — قوالب نص جاهزة لكل subspecialty
• ICD code lookup — autocomplete (يفضل تكون موجودة في NPHIES module بالفعل، نتأكد)

⑦ خطة التذاكر — Backend (Ahmed) + Frontend (Hazem)

6 تذاكر إجمالاً (3 backend + 3 frontend). لازم الـ backend يتعمل أولاً، بعدها الـ frontend بـ parallel.

Backend Tickets — يـ assign لـ Ahmed (admin, id=3)

Frontend Tickets — Hazem (يبدأوا بعد ما الـ Backend يـ ship)

⑧ الترتيب الزمني والمخاطر

الترتيب الموصى به

المخاطر والـ Dependencies

القرارات اللي محتاجة موافقة قبل ما نبدأ

1. Quill OK؟ الـ rich-text editor للـ histopath. لو لا، البديل markdown.
2. الـ Antibiotic master data من سيد لـ CLSI ولا نسيب الـ admin يـ enter؟ هنا قرار workflow.
3. الـ Pathology Worklist صفحة منفصلة، ولا نـ extend الـ kanban بـ "Pathology" section؟ تم الحسم: ميفيش worklist منفصل — الـ histopath في نفس الـ kanban زي أي نوع تاني.
4. الـ Peer Review optional ولا required بـ default؟ الـ requires_peer_review flag يـ default false، الـ admin يـ enable لكل investigation.
5. الـ Culture يدعم Panels؟ الـ recommendation: لا في v1، نـ add لاحقاً لو محتاج.