HealthPack

هذا هو المخطط الذي أفتحه أولًا. لا يتواصل العملاء إلا مع edge-gateway، الذي يتحقق من كل JWT عبر Keycloak قبل تمرير الطلب: تذهب استدعاءات REST مباشرة إلى خدمة النطاق، ويذهب GraphQL إلى BFF، وتذهب ترقية WebSocket إلى chat-service. لا شيء في الخلف يعيد التحقق من الهوية؛ البوابة هي المكان الوحيد الذي يفعل ذلك، وكل ما عداها يثق في البيانات التي تمررها.

الأسهم المزدوجة السميكة هي gRPC، وهي تتجمع حول terminology-service لسبب وجيه: فهي تُستدعى في كل كتابة سريرية تقريبًا (التحقق من رمز ICD-10، وفحص تداخل دوائي، وتحديد رمز LOINC)، لذا هي المكان الوحيد الذي سيُحس فيه ببطء البروتوكول في كل مكان. الأسهم المنقطة هي Kafka و RabbitMQ، والمخطط في حقيقته حجة للإبقاء عليهما منفصلين: يوزع Kafka حدثًا واحدًا على خمسة مستهلكين مختلفين (فـ lab.result.finalized وحده يغذي الجانب السريري والفوترة والمساعد الذكي واشتراكات GraphQL)، بينما يحمل RabbitMQ الأوامر إلى عامل واحد بالضبط — ملف PDF يُنشأ، أو إشعار يُرسل.

اقرأه من الأعلى إلى الأسفل وستحكي الطبقات قصتها بنفسها: حافة لا تفعل سوى التحقق والتوجيه، وطبقة تركيب لا توجد إلا لتوفير رحلات الذهاب والإياب على الواجهة الأمامية، وسبع خدمات نطاق تملك كل منها قاعدة Postgres واحدة ولا شيء غيرها، وخدمة gRPC داخلية واحدة خلفها جميعًا، وثلاثة عمال غير متزامنين لا يستدعيهم أي عميل مباشرة.

كل شيء في HealthPack يعود في النهاية إلى Patient، لذا كان هذا أول نموذج صممته. العلاقة التي تستحق التوقف عندها هي Appointment "1" --> "0..1" Encounter : produces: الموعد حجز، واللقاء هو الزيارة الفعلية، وهما سجلان منفصلان عن قصد. قد يحجز مريض موعدًا ولا يحضر؛ وقد ينتج عن زيارة بلا موعد لقاءٌ لا يقف خلفه أي موعد. ودمجهما كان سيجعل تمثيل الغياب والزيارات دون موعد أمرًا مستحيلًا بشكل نظيف.

يتفرع Consent مباشرة من Patient بدل أن يُدفن في جدول إعدادات، لأن المساعد الذكي يتحقق منه في المسار الحرج لكل سؤال يجيب عنه — إذ يُستدعى isActiveFor(ConsentScope) قبل استرجاع أي وثيقة، لا بعده. ويملك Encounter كلًّا من Observation وCondition عبر التركيب (المعيّن الممتلئ)، أي أنهما لا يمكن أن يبقيا بعد الزيارة التي سُجّلا فيها — فالقياس له دائمًا تاريخ وسياق سريري، ولا يطفو منفصلًا أبدًا.

الأسهم المتقطعة الثلاثة التي تلتقي عند DocumentJob هي جوهر هذا المخطط: LabOrder وPrescription وInvoice مفاهيم سريرية أو مالية لا علاقة بينها، لكنها تنهي حياتها بالطريقة نفسها — بإنشاء ملف PDF. ونمذجة هذا الالتقاء صراحة سمحت بكتابة document-service مرة واحدة وبشكل عام، بدل ثلاث مرات بثلاثة مسارات PDF مختلفة بفوارق دقيقة.

يحمل DocumentJob مفتاح idempotencyKey لسبب ملموس: قد يتلقى مستهلك RabbitMQ الرسالة نفسها مرتين (هذا هو الاتفاق الذي يقدمه RabbitMQ — التسليم مرة واحدة على الأقل، لا مرة واحدة على الأكثر)، ويجب ألا تُنشأ وصفة الطبيب وتُوقَّع وتُحفظ مرتين بسبب استدعاء شبكي أُعيدت محاولته. ويوجد عداد attempts والدالة markFailed(String) في المهمة نفسها كي تظهر أي عملية إنشاء عالقة كبيانات، لا كفراغ صامت.

لا يحفظ RagQuery الإجابة فقط، بل يحتفظ بـ inputTokens وcacheReadTokens إلى جانب List~Citation~، لأن إجابة RAG بلا مصدر ليست معلومة تستحق أن تُعرض على طبيب، وعدد الرموز دون رقم القراءة من الذاكرة المؤقتة لا يخبرك شيئًا عمّا إذا كان التخزين المؤقت للتعليمات يعمل فعلًا في بيئة الإنتاج. ويحمل كل Citation نطاق صفحات، لا معرّف وثيقة فحسب، حتى يتمكن المساعد من الإشارة إلى الفقرة التي يقتبس منها بالضبط.

AuditRecord هو الصنف الوحيد في هذا المخطط الذي يشير إلى نفسه: AuditRecord --> AuditRecord : prevHash chain. تُحسب قيمة hash لكل سجل من حقوله الخاصة مضافًا إليها تجزئة السجل السابق، لذا فإن تعديل أي قيد سابق — ولو حقلًا واحدًا — يكسر كل التجزئات التي تليه. والدالة verifyChain(AuditRecord prev) هي ما يستدعيه المدقق فعلًا، وهي إما تؤكد السلسلة أو تخبرك بالضبط أين انكسرت.

هذا أقرب إلى خريطة لمن يستدعي من بشكل متزامن منه إلى مخطط أصناف. وأسهم الاعتماد الثلاثة ..> المتجهة إلى TerminologyService من ClinicalService وPharmacyService والشيفرة القريبة من SchedulingService تؤكد قرار التصميم الذي ألمح إليه المخطط العام: استعلامات المصطلحات هي الاستدعاء المتزامن الوحيد العابر لكل الخدمات حقًا، ولهذا بالضبط تعتمد تلك الخدمة على gRPC وحده لا على REST.

يستحق BffGraphQlResolvers قراءة متأنية: فـ batchLoadPatients(Set~UUID~) : CompletableFuture~Map~ هي دالة التجميع في DataLoader، وتوقيعها هو السبب الكامل في تجنب طبقة GraphQL لاستعلامات N+1 — إذ تطلب المحللات مريضًا واحدًا في كل مرة، ويجمع DataLoader المعرّفات خلال دورة واحدة من حلقة الأحداث، ثم تجلبها هذه الدالة كلها في استدعاء gRPC واحد. وتُرجع onVitalsUpdated وonLabResultReady قيمة Flux لا قيمة مفردة — فهي اشتراكات GraphQL يغذيها مستهلكو Kafka في الخلفية، لا الاستطلاع المتكرر.

لاحظ ما يغيب عن كل دالة هنا: لا توجد أي createX أو getX معروضة للعميل. DocumentService.onRenderCommand، وNotificationService.onNotifyCommand وonCriticalValue، وAiRagService.onDocumentTextExtracted — كل نقطة دخول تبدأ بـ on، لأن كل نقطة دخول معالج رسائل لا نقطة نهاية. يستطيع العميل الاستعلام عن حالة مهمة عبر واجهة REST صغيرة، لكنه لا يستطيع أبدًا أن يطلب من هذه الخدمات فعل شيء مباشرة؛ كل ما يمكنه هو أن يطلب ذلك من طابور.

يمثل ChatService ..> AiRagService : gRPC server-stream الاستدعاء الوحيد الذي يبدو متزامنًا في مخطط غير متزامن في مجمله، وهو موجود لأن رد المحادثة يجب أن يبدو فوريًا — فتمريره عبر Kafka سيضيف قفزة طابور سيلاحظها المستخدم وهو ينتظر ظهور الرموز. أما AiRagService.evaluateGoldenSet() فدالة بلا مستدعٍ ظاهر هنا عن قصد: إذ تستدعيها منظومة CI لا النظام أثناء تشغيله، لتقييم جودة الإجابات مقابل مجموعة ثابتة من أزواج الأسئلة والأجوبة قبل نشر أي تغيير.

هذا هو التسلسل الذي يبرر الجمع بين GraphQL و gRPC برمته. يفتح الطبيب لوحة تحكم تحتاج البيانات الشخصية للمرضى ولقاءاتهم ونتائج تحاليلهم — ثلاث خدمات، وربما عشرات المرضى على الشاشة في آن واحد. الخطوة 10، «DataLoader collects all IDs in one event-loop tick»، هي اللحظة الحاسمة: بدل نمط N+1 الساذج (استدعاء لكل مريض ولكل حقل)، يُوضع طلب كل محلل لمعرّف ما في طابور خلال دورة واحدة، ثم يُرسل الجميع دفعة واحدة.

تطلق كتلة par التي تليها ثلاثة استدعاءات مجمّعة بالتوازي — gRPC batchGet إلى patient-service، وgRPC batchGetEncounters إلى clinical-service، واستدعاء REST إلى lab-service — وتُظهر patient-service الانضباط نفسه داخليًا: MGET على Redis أولًا، ثم استعلام PostgreSQL فقط لما لم يكن في الذاكرة المؤقتة. والملاحظة في الأسفل تلخص المكسب بوضوح: استدعاء gRPC واحد لكل خدمة، لا لكل صف مريض، مهما كان عدد المرضى على الشاشة.

هنا يُلغى نمطان من الأعطال بالتصميم، لا يُكتشفان بعد وقوعهما. يمنع SET slot-hold NX EX 120 في Redis شخصين من التسابق على الفترة نفسها خلال الثواني التي يستغرقها ملء الاستمارة، وINSERT في Postgres أسفله محمي بقيد استبعاد على (practitioner_id, time_range) — فحتى لو اجتاز طلبان فحص Redis بطريقة ما، ترفض قاعدة البيانات نفسها الكتابة الثانية. صحة التزامن موجودة في المكان الوحيد القادر فعلًا على ضمانها: قاعدة البيانات، لا شيفرة تطبيق تأمل أنها تحققت في الوقت المناسب.

النصف الثاني هو نمط outbox قيد العمل: إدراج الموعد وإدراج outbox يتمان في معاملة قاعدة البيانات نفسها، لذا فإن حالة «نجح الحجز لكن لم يعلم به أحد» ليست حالة يمكن أن يقع فيها النظام — إذ يلتقط مستطلِع يعمل مستقلًا عن الطلب سطر outbox وينشر appointment.booked متى كان جاهزًا. ومن هناك يسلك التذكير المسار البطيء عن قصد: تنفذ آلية TTL مع dead-letter exchange في RabbitMQ مهلة الأربع والعشرين ساعة، وإذا فشل مزود الإشعارات، تُرفض الرسالة مع إعادتها إلى الطابور وتتراجع بشكل أُسّي قبل أن تستقر في dead-letter queue بدل أن تختفي.

هذا هو التدفق الذي يدور حوله المشروع كله في الحقيقة — وهو الموصوف في الجملة الافتتاحية للمشروع. يتحدث جهاز المختبر بلغة HL7 v2، وهي صيغة من عام 1989 تحللها lab-service بواسطة HAPI HL7v2 وتتحقق منها وفق LOINC قبل حفظ أي شيء. ويأتي القرار المثير مباشرة بعد ذلك: بدل أن تقرر lab-service بنفسها ما هو حرج، فإنها تنشر الواقعة — lab.result.finalized — وتتولى طوبولوجيا Kafka Streams منفصلة، مقسمة حسب معرّف المريض مع إزالة للتكرار في نافذة منزلقة مدتها 15 دقيقة، مهمة الحكم. فصل الكشف عن التسجيل مقصود، حتى يمكن تغيير منطق التنبيه دون المساس بالخدمة التي تملك البيانات.

حين تتجاوز قيمة ما العتبة الحرجة، يتوزع نشر واحد على lab.critical-value على ثلاثة مستهلكين بالتوازي: توجهه notification-service إلى طابور ذي أولوية يتجاوز ساعات الهدوء كليًا، وتدفع chat-service إطار STOMP مباشرة إلى أي جلسة مفتوحة لدى الطبيب، ويحدّث اشتراك GraphQL لوحة تحكمه مباشرة. ثلاثة مسارات تسليم مختلفة، وحدث واحد، حتى يراه الطبيب أيًّا كانت الطريقة التي ينظر بها إلى النظام في تلك اللحظة.

التحقق من عدم التكرار في الأعلى هو أول ما يحدث، قبل أي عمل فعلي: تبحث document-service عن idempotencyKey الوارد في Postgres، فإن كان قد أُنشئ من قبل، تؤكد استلام الرسالة ولا تفعل شيئًا آخر. هذا الاستعلام الوحيد هو ما يجعل إعادة RabbitMQ تسليم أمر الإنشاء نفسه آمنة، دون أن ينتج أبدًا ملفي PDF موقّعين للوصفة نفسها.

بعد هذا الحاجز، يتكون المسار في الحقيقة من مسارين متتاليين. الأول ينشئ الملف، ويطبق عليه ملف أرشفة PDF/A، ويوقعه بتطبيق PAdES من BouncyCastle، ويخزن الكائن في MinIO حسب قيمة sha256 الخاصة به. ولا يبدأ الثاني إلا بعد أن يكتمل الأول تمامًا: يستخرج PDFBox النص من ملف PDF الذي كُتب للتو، وينشر document.text-extracted، وهذا الحدث وحده هو ما يجعل الوثيقة قابلة للاسترجاع من طرف مساعد المحادثة أصلًا — مقسمة إلى أجزاء، ومحوّلة إلى متجهات عبر Voyage AI، ومُدرجة في pgvector مع معرّف المريض كبيانات وصفية، وهو ما يسمح لاحقًا لاستعلام RAG بأن يقتصر على وثائق مريض واحد دون سواه.

ترتيب العمليات هنا هو حجة الخصوصية كلها مجسّدة: تستدعي ai-service الدالة hasConsent(patientId, AI_ASSIST) لدى identity-service قبل تحويل السؤال إلى متجه، وقبل الاستعلام في pgvector، وقبل قراءة كلمة واحدة من ملف المريض. والموافقة الملغاة تُرجع PERMISSION_DENIED عند تلك النقطة وتتوقف المحادثة هناك — فلا يصل المساعد أبدًا إلى مرحلة يكون لديه فيها ما يحتاج إلى إخفائه.

بعد اجتياز الموافقة، يقتصر الاسترجاع على ذلك المريض وحده (topK 8، مع التصفية حسب patientId)، ويُنقّى السياق المسترجع من البيانات الصحية الشخصية قبل بناء التعليمات — فلا يرى النموذج أبدًا من التفاصيل المعرِّفة أكثر مما تتطلبه الإجابة. وملاحظة cache_control في خطوة بناء التعليمات مهمة للتكلفة بقدر أهميتها للسرعة: فتعليمات النظام ومتن الإرشادات السريرية ثابتان في كل سؤال يطرحه الفريق المعالج لهذا المريض، لذا يحوّل التخزين المؤقت للتعليمات لدى Anthropic معظم ذلك السياق إلى قراءة من الذاكرة المؤقتة بدل احتسابه من جديد، ويُسجَّل cacheReadTokens تحديدًا للتحقق من أن ذلك يحدث فعلًا بدل افتراضه. ومن هناك تصبح الحلقة مجرد تمرير مباشر: يبث Claude أحداث content_block_delta، وتعيد ai-service توجيه كل منها عبر تدفق gRPC من الخادم، وتحوّله chat-service إلى إطار STOMP، ويعرضه المتصفح تدريجيًا، فتظهر الإجابة كما يكتب الإنسان بدل أن تصل كتلة واحدة بعد انتظار.

يوجد تتابع الذاكرة المؤقتة Caffeine ثم Redis لأن validateCode تُستدعى في كل كتابة سريرية تقريبًا عبر النظام كله، واستعلام مصطلحات يذهب إلى Postgres في كل مرة سيبطئ كل تلك الكتابات دون مبرر — فمجموعات الرموز بالكاد تتغير، لذا فإن ذاكرة مؤقتة محلية L1 داخل العملية تدعمها ذاكرة مشتركة L2 هي الحل البديهي، وكل إخفاق يملأ المستويين في طريق العودة حتى يستفيد الطلب التالي في أي مكان من العنقود.

أما فحص التداخل نفسه فهو ما يجعل لهذا المخطط مكانه: النتيجة المتعارضة لا تُفشل الطلب، بل تُرجع 422 مع التعارض المحدد، ويمكن للطبيب تجاوزها — لكن فقط بتقديم مبرر يُحفظ مع الوصفة مع علامة تجاوز صريحة. لا شيء يُمنع في صمت ولا شيء يُسمح به في صمت؛ كل وصفة متنازع عليها تترك أثرًا لمن تجاوز ماذا ولماذا. والنشران الأخيران في الأسفل — prescription.issued إلى Kafka، وأمر إنشاء إلى RabbitMQ — هما بالضبط حيث يبدأ المخطط 4d.