التقنية في الصحة الأدلة التقنية

خادم FHIR على سيرفرك: تجربة عملية مع HAPI FHIR

كيف تشغل سيرفر FHIR يحفظ في PostgreSQL ويتحقق من البيانات بدليل نفيس، مع البحث بالأسماء العربية والنسخ والمعاملات.

خادم FHIR على سيرفرك: تجربة عملية مع HAPI FHIR

في مقال تبادل البيانات الصحية: HL7 وFHIR شغلنا سيرفر HAPI FHIR بإعداده الافتراضي، وأنشأنا مريضة وزيارة ونتائج، ورأينا أن السيرفر يحفظ ملاحظة دون رمز إذا لم نفعل التحقق. وكان ذلك السيرفر يحفظ كل شيء في قاعدة H2 داخل الذاكرة، أي أن كل ما كتبناه يختفي عند إعادة التشغيل، وكان يقبل أي مورد من أي أحد، ولا يعرف شيئاً عن القواعد التي تفرضها منصة نفيس NPHIES على المريض في السعودية. وإذا كنت مطوراً في مستشفى أو في شركة ناشئة تبني تطبيقاً صحياً، فالسؤال الذي يأتي بعد ذلك مباشرة هو: كيف أشغل سيرفر FHIR حقيقياً على سيرفري، يحفظ البيانات في قاعدة بيانات أعرفها، ويحتفظ بكل نسخة من كل سجل، ويرفض البيانات التي لا تطابق دليل التنفيذ الذي يلزمني، ويبحث في الأسماء العربية كما يتوقع الموظف في الاستقبال؟

وهذا هو موضوع هذا المقال. وسوف نناقش فيه ما يلي:

  • متى تحتاج سيرفر FHIR خاصاً بك، وكيف يحفظ HAPI الموارد في قاعدة البيانات من الداخل.
  • تشغيل HAPI FHIR مع قاعدة PostgreSQL على Docker، وتحميل دليل تنفيذ نفيس عند التشغيل.
  • إنشاء مريضة باسم عربي، وزيارة، ونتيجتي مختبر، وتشخيص بنظامي ترميز، بمراجع مشروطة Conditional References.
  • معاملات البحث Search Parameters المتقدمة: البحث المتسلسل Chaining، والبحث العكسي _has، و_include، والصفحات Paging.
  • مشكلة حقيقية في البحث بالأسماء العربية (الهمزة والتاء المربوطة)، وكيف حللناها بمعامل بحث مخصص.
  • النسخ Versioning والتاريخ History، والقفل المتفائل Optimistic Locking بالرأس If-Match، والحذف.
  • التحقق Validation من المريض مقابل ملف تعريف نفيس، وقراءة أخطاء OperationOutcome وإصلاحها، ثم رفض البيانات الخاطئة عند الكتابة بالرمز 422.
  • حزم المعاملات Transaction Bundles: الكل أو لا شيء، ولماذا تتكرر البيانات عند إعادة الإرسال وكيف تمنع ذلك.
  • SMART on FHIR من المعيار: ما الذي ينقص سيرفرنا قبل أن يصل إليه تطبيق خارجي.

متى تحتاج سيرفر FHIR خاصاً بك؟

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

أما الحالات التي تحتاج فيها سيرفراً يحفظ الموارد نفسها Native FHIR Store فهي كما يلي:

  • تطبيق صحي جديد ليس له نظام قديم: عيادة افتراضية، أو منصة متابعة مرضى السكري، أو تطبيق للعلاج الطبيعي، وتريد أن يكون نموذج البيانات من البداية هو FHIR بدل أن تخترع جداولك ثم تترجمها لاحقاً.
  • مستودع تكامل في المستشفى: البيانات تأتي من المختبر والأشعة والصيدلية برسائل HL7 v2، ويحولها محرك الواجهات إلى موارد FHIR تحفظ في سيرفر واحد تقرأ منه التطبيقات الجديدة ولوحات المؤشرات.
  • بيئة اختبار لتكامل مع جهة خارجية: قبل أن ترسل أول رسالة إلى منصة وطنية تريد أن تتحقق من مواردك مقابل دليل التنفيذ الخاص بها على سيرفرك أنت.
  • البحث والتحليل: نسخة من البيانات بشكل موحد يقرأ منها فريق البيانات، بعد إخفاء الهوية.

ومشروع HAPI FHIR JPA Server Starter هو أشهر سيرفر مفتوح المصدر من هذا النوع، وهو مبني على مكتبة HAPI FHIR بلغة Java برخصة Apache-2.0، ويحفظ الموارد في قاعدة بيانات علائقية عبر JPA وHibernate كما يشرح توثيق خادم JPA. والسيرفر نفسه يأتي جاهزاً في Image رسمية على Docker Hub، وسوف نستخدم الإصدار v8.12.0-2 وهو آخر إصدار منشور وقت كتابة المقال.

كيف يحفظ HAPI الموارد في قاعدة البيانات؟

قبل أن نبدأ من المفيد أن تعرف ما سوف تراه في قاعدة البيانات، لأن أغلب أسئلة الأداء والبحث التي سوف تقابلها لاحقاً جوابها هنا. فقد يتساءل البعض: هل يحفظ HAPI كل نوع مورد في جدول خاص به، جدول للمرضى وجدول للزيارات وهكذا؟ والإجابة لا، فالسيرفر يدعم 146 نوعاً من الموارد في R4، ولو أنشأ جدولاً لكل نوع بأعمدة لكل حقل لاحتاج مئات الجداول وآلاف الأعمدة، ولتغيرت كلها مع كل إصدار من المعيار. لذلك يتبع HAPI تصميماً آخر يشرحه توثيق المخطط Schema:

  • جدول hfj_resource: سطر واحد لكل مورد مهما كان نوعه، فيه النوع والمعرف ورقم آخر نسخة ووقت الحذف إن حذف.
  • جدول hfj_res_ver: سطر لكل نسخة من كل مورد، وفيه نص المورد كاملاً بصيغة JSON. وهذا هو المكان الذي يعيش فيه المحتوى الفعلي، والنسخ القديمة لا تحذف عند التعديل.
  • جداول الفهارس hfj_spidx_*: لكل نوع من معاملات البحث جدول، مثل hfj_spidx_string للنصوص كالأسماء، وhfj_spidx_token للرموز والمعرفات، وhfj_spidx_date للتواريخ، وhfj_spidx_quantity للقيم بوحداتها. وعند حفظ أي مورد يستخرج السيرفر منه قيم معاملات البحث المعرفة له ويضعها في هذه الجداول.
  • جدول hfj_res_link: المراجع بين الموارد، مثل أن الملاحظة 1598 تشير إلى المريضة 1596، وهو الذي يجعل البحث المتسلسل و_include ممكناً.

وبالتالي فالبحث في HAPI لا يقرأ ملفات JSON أبداً، وإنما يستعلم من جداول الفهارس ثم يجلب النسخ الحالية من hfj_res_ver. وهذا يعني شيئين مهمين سوف نراهما في المختبر: أن أي حقل ليس له معامل بحث معرف لا تستطيع البحث فيه مهما كان موجوداً في JSON، وأن طريقة استخراج القيمة إلى جدول الفهرس وتطبيعها Normalization هي التي تحدد ماذا يطابق بحثك وماذا لا يطابق، وهذا بالضبط ما سوف يواجهنا مع الأسماء العربية.

والصورة التالية تبين مكونات المختبر:

مخطط المختبر: حاوية عميل فيها curl وjq ترسل طلبات REST إلى سيرفر HAPI FHIR 8.12.0 على المنفذ 8080 داخل شبكة Docker، والسيرفر يحمل عند التشغيل حزمة دليل نفيس nphies-fs 1.0.0 من portal.nphies.sa، ويحفظ في PostgreSQL 17 في Volume دائم، وداخل القاعدة جدول hfj_resource لكل مورد وhfj_res_ver لكل نسخة وجداول hfj_spidx للفهارس، والمنفذ 9552 مفتوح على 127.0.0.1 فقط لواجهة الاختبار
مكونات المختبر: عميل، وسيرفر HAPI يحمل دليل نفيس، وقاعدة PostgreSQL دائمة

تجهيز المختبر: HAPI مع PostgreSQL

نبدأ بمجلد فيه ثلاثة ملفات. الأول ملف Compose فيه خدمتان: قاعدة PostgreSQL بإصدار 17 مع Volume دائم وفحص صحة Health Check، وسيرفر HAPI لا يبدأ إلا بعد أن تصبح القاعدة جاهزة:

name: fhir-lab
services:
  db:
    image: postgres:17-alpine
    container_name: fhir-db
    environment:
      POSTGRES_DB: hapi
      POSTGRES_USER: hapi
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
    volumes:
      - fhir-pg:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hapi -d hapi"]
      interval: 5s
      retries: 10

  hapi:
    image: hapiproject/hapi:v8.12.0-2
    container_name: fhir-hapi
    depends_on:
      db:
        condition: service_healthy
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/hapi
      SPRING_DATASOURCE_USERNAME: hapi
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
      SPRING_DATASOURCE_DRIVERCLASSNAME: org.postgresql.Driver
      HIBERNATE_DIALECT: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgresDialect
      SPRING_CONFIG_ADDITIONAL_LOCATION: file:/config/hapi.yaml
    volumes:
      - ./hapi.yaml:/config/hapi.yaml:ro
    ports:
      - "127.0.0.1:9552:8080"

volumes:
  fhir-pg:
    name: fhir-pg

في الإعداد أعلاه لاحظ التالي:

  • الإعداد الافتراضي داخل الـ Image يستخدم H2 في الذاكرة، ونغيره بمتغيرات البيئة التي يقرؤها Spring Boot: رابط JDBC واسم المستخدم وكلمة المرور والمشغل Driver. والمتغير HIBERNATE_DIALECT مهم، لأن ملف الإعداد داخل الـ Image يقول صراحة إن اللهجة Dialect تكتشف تلقائياً إلا مع H2 وPostgreSQL، ولكل منهما لهجة خاصة من HAPI يجب أن تحددها بنفسك.
  • المنفذ مربوط على 127.0.0.1 فقط، والسبب أن هذا السيرفر كما سوف نرى لا يطلب أي تسجيل دخول، فلا تفتحه على الشبكة أبداً.
  • كلمة مرور القاعدة تأتي من ملف .env وليست مكتوبة في الملف، وإذا نسيتها يرفض Compose التشغيل برسالة واضحة بسبب الصيغة :?.

والملف الثاني hapi.yaml يضيف إعداداتنا فوق الإعداد الافتراضي، ولا يستبدله، بفضل المتغير SPRING_CONFIG_ADDITIONAL_LOCATION:

hapi:
  fhir:
    fhir_version: R4
    # allow PUT with ids chosen by the client (such as MRN-24017), not only numbers
    client_id_strategy: ALPHANUMERIC
    # NPHIES implementation guide (HL7 Saudi Arabia), downloaded and installed at start
    install_transitive_ig_dependencies: true
    implementationguides:
      nphies:
        name: nphies-fs
        version: 1.0.0
        packageUrl: https://portal.nphies.sa/ig/package.tgz
        installMode: STORE_AND_INSTALL
        reloadExisting: false

والجزء المهم هنا هو implementationguides: نطلب من السيرفر أن ينزل عند التشغيل حزمة دليل التنفيذ الذي نشرته منصة نفيس، وهي ملف package.tgz بصيغة حزم FHIR القياسية، ويحفظ ما فيها من ملفات التعريف Profiles وقوائم القيم ValueSets وأنظمة الرموز CodeSystems كموارد في قاعدته. وقبل أن نشغله قمنا بقراءة ملف وصف الحزمة نفسه لنعرف ماذا سوف نحمل:

curl -s https://portal.nphies.sa/ig/package.manifest.json
{
  "version" : "1.0.0",
  "fhirVersion" : ["4.0.1"],
  "date" : "20251203142743",
  "name" : "nphies-fs",
  "jurisdiction" : "urn:iso:std:iso:3166#SA"
}

أي أن الحزمة هي الإصدار 1.0.0 من دليل الخدمات المالية الصحية، مبنية على FHIR 4.0.1 ومؤرخة في 3 ديسمبر 2025، وهذا يطابق ما في الصفحة الرئيسية للدليل التي تذكر أنه منشور باسم HL7 Saudi Arabia. والملف الثالث .env فيه كلمة مرور عشوائية، ثم نشغل كل شيء:

echo "DB_PASSWORD=$(openssl rand -hex 16)" > .env
docker compose up -d
docker logs -f fhir-hapi 2>&1 | grep -E "Installing package|Started Application"
... PackageInstallerSvcImpl        : Installing package: nphies-fs#1.0.0
... ca.uhn.fhir.jpa.starter.Application      : Started Application in 288.964 seconds (process running for 295.745)

نعم، قرابة خمس دقائق في أول تشغيل، والسبب أن السيرفر ينشئ مخطط القاعدة كاملاً لأول مرة، ثم ينزل الحزمة ويفهرس كل مورد فيها، وقد عددنا في السجل 379 سطراً من نوع Indexing ... Package[nphies-fs#1.0.0]. وعند إعادة التشغيل لاحقاً احتاج 177 ثانية، لأن المخطط موجود والسجل يقول Package nphies-fs#1.0.0 is already installed. لذلك لا تفترض أن السيرفر تعطل إذا لم يرد في الدقيقة الأولى، وانتظر السطر Started Application.

⚠️
بعد التشغيل امتلأ السجل برسائل ERROR من مهمة اسمها PRE_EXPAND_VALUESET فيها HSEARCH800001: Hibernate Search was not initialized. وهذه مهمة في الخلفية تحاول أن تحسب مسبقاً محتوى قوائم القيم الكبيرة، وتحتاج فهرس بحث نصي Lucene أو Elasticsearch غير مفعل في الإعداد الافتراضي. ولم تمنعنا من أي خطوة في هذا المقال، فالتحقق من الرموز في القوائم الصغيرة يحسبها عند الطلب، ولكن إذا حملت أنظمة رموز ضخمة مثل LOINC أو SNOMED CT في الإنتاج فستحتاج تفعيل هذا الفهرس كما في قسم Hibernate Search في ملف الإعداد.

ولماذا بدأ أول مورد أنشأناه بالمعرف 1596 وليس 1؟ لأن موارد الحزمة نفسها أخذت الأرقام قبله، وهذا ما وجدناه عندما عددنا الموارد بحسب النوع في القاعدة بعد انتهاء المختبر:

docker exec fhir-db psql -U hapi -d hapi -c "select res_type, count(*) from hfj_resource group by res_type order by 2 desc limit 4"
      res_type       | count
---------------------+-------
 Binary              |   380
 ValueSet            |    82
 CodeSystem          |    78
 StructureDefinition |    56

أي 56 تعريف بنية StructureDefinition (ملفات التعريف والامتدادات Extensions)، و82 قائمة قيم، و78 نظام رموز، ومعها 380 ملفاً ثنائياً Binary هي ملفات الحزمة الأصلية.

حاوية العميل Client Container

بقية المختبر طلبات HTTP، ونرسلها من Container صغيرة فيها curl وjq وعميل PostgreSQL على نفس شبكة Compose، حتى لا تحتاج تثبيت شيء على جهازك:

FROM alpine:3.24
RUN apk add --no-cache curl jq bash postgresql17-client
WORKDIR /lab
docker build -t fhir-client -f client.Dockerfile .
docker run --rm -it --network fhir-lab_default -e B=http://hapi:8080/fhir -v "$PWD:/lab" fhir-client bash
curl -s $B/metadata | jq -r '[.software.name, .software.version, .fhirVersion, (.rest[0].resource|length)] | @tsv'
HAPI FHIR Server	8.12.0	4.0.1	146

كل الأوامر التالية تعمل داخل هذه الحاوية، والمتغير $B هو العنوان الأساسي للسيرفر.

المريضة الأولى: اسم عربي ومعرف Identifier من نظامين

نحتاج مريضة لعيادة افتراضية في مثالنا، والبيانات كلها وهمية. ونضع للمريضة اسمين: الاسم الرسمي بالعربية كما في الهوية، والاسم باللاتينية كما يكتب في التقارير الدولية، وكلاهما في المصفوفة name بنوع HumanName مع الحقل use الذي يفرق بينهما:

{
  "resourceType": "Patient",
  "identifier": [
    { "system": "https://clinic.example.org/mrn", "value": "MRN-24017" }
  ],
  "active": true,
  "name": [
    { "use": "official", "text": "نورة عبدالله الأحمد", "family": "الأحمد", "given": ["نورة", "عبدالله"] },
    { "use": "usual", "text": "Noura Abdullah Alahmad", "family": "Alahmad", "given": ["Noura", "Abdullah"] }
  ],
  "telecom": [ { "system": "phone", "value": "+966500000000", "use": "mobile" } ],
  "gender": "female",
  "birthDate": "1984-03-12"
}

ولاحظ أن family هو اسم العائلة وحده، وgiven مصفوفة فيها الاسم الأول واسم الأب، وأن text هو الاسم كاملاً كما يعرض. ثم نرسل المريضة مرتين بنفس الطلب، مع الرأس If-None-Exist الذي يجعل الإنشاء مشروطاً:

for n in 1 2; do
  curl -s -i -X POST "$B/Patient" -H "Content-Type: application/fhir+json" \
    -H "If-None-Exist: identifier=https://clinic.example.org/mrn|MRN-24017" \
    --data-binary @patient.json | tr -d "\r" | grep -i -E "^HTTP|^location|^etag"
done
HTTP/1.1 201
ETag: W/"1"
Location: http://hapi:8080/fhir/Patient/1596/_history/1
HTTP/1.1 200
ETag: W/"1"
Location: http://hapi:8080/fhir/Patient/1596/_history/1

في المخرج أعلاه لاحظ التالي:

  • الطلب الأول رجع 201 أي أنشئ المورد برقم 1596 ونسخة 1، والثاني رجع 200 ونفس الرقم، أي أن السيرفر بحث بالمعرف أولاً فوجد المريضة ولم ينشئ أخرى. وهذا السلوك منصوص عليه في صفحة واجهة REST في المعيار: صفر نتائج يعني إنشاء، ونتيجة واحدة يعني 200 دون إنشاء، وأكثر من نتيجة يعني الخطأ 412.
  • الرأس ETag: W/"1" هو رقم النسخة، وسوف نحتاجه في قسم النسخ.
  • الرقم 1596 هو المعرف المنطقي Logical ID داخل هذا السيرفر، أما رقم الملف الطبي MRN-24017 فهو معرف تجاري Business Identifier أصدرته العيادة، والفرق بينهما مهم: الأول قد يختلف بين سيرفر وآخر، والثاني هو ما يعرفه الناس وتربط به الأنظمة.

الزيارة والنتائج والتشخيص بمراجع مشروطة Conditional References

المريضة زارت العيادة تشكو من عطش شديد وكثرة التبول، فطلب الطبيب تحليل السكر التراكمي والسكر الصائم، ثم سجل التشخيص. ولكي نربط الزيارة بالمريضة نحتاج المرجع Patient/1596، ولكن النظام الذي يرسل الزيارة في الواقع (نظام المواعيد مثلاً) لا يعرف هذا الرقم، وإنما يعرف رقم الملف. لذلك نستخدم مرجعاً مشروطاً Conditional Reference بشكل رابط بحث بدل الرقم:

{
  "resourceType": "Encounter",
  "identifier": [ { "system": "https://clinic.example.org/visit", "value": "V-2026-11-0457" } ],
  "status": "finished",
  "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB", "display": "ambulatory" },
  "subject": { "reference": "Patient?identifier=https://clinic.example.org/mrn|MRN-24017" },
  "period": { "start": "2026-11-16T09:00:00+03:00", "end": "2026-11-16T09:40:00+03:00" },
  "reasonCode": [ { "text": "عطش شديد وكثرة التبول منذ شهرين" } ]
}
curl -s -X POST "$B/Encounter" -H "Content-Type: application/fhir+json" --data-binary @encounter.json | jq -c '{id, version: .meta.versionId, subject}'
{"id":"1597","version":"1","subject":{"reference":"Patient/1596"}}

السيرفر نفذ البحث Patient?identifier=... عند الحفظ، ووجد نتيجة واحدة، فاستبدل المرجع بالرقم الحقيقي Patient/1596. وإذا لم يجد شيئاً أو وجد أكثر من نتيجة فإنه يرفض الطلب، وهذا أفضل بكثير من أن يربط الزيارة بمريض خطأ.

ثم النتيجتان بنفس الطريقة، كل منهما مرمزة برمز LOINC ووحدة UCUM، وتشير إلى المريضة وإلى الزيارة. وهذا ملف السكر التراكمي، وملف السكر الصائم مثله بالرمز 1558-6 والقيمة 162 mg/dL:

{
  "resourceType": "Observation",
  "status": "final",
  "category": [ { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory" } ] } ],
  "code": { "coding": [ { "system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c/Hemoglobin.total in Blood" } ], "text": "السكر التراكمي HbA1c" },
  "subject": { "reference": "Patient?identifier=https://clinic.example.org/mrn|MRN-24017" },
  "encounter": { "reference": "Encounter?identifier=https://clinic.example.org/visit|V-2026-11-0457" },
  "effectiveDateTime": "2026-11-16T09:15:00+03:00",
  "valueQuantity": { "value": 8.1, "unit": "%", "system": "http://unitsofmeasure.org", "code": "%" }
}

أما التشخيص فهو المورد Condition، ونضع في حقل code رمزين لنفس المعنى من نظامين: SNOMED CT للتوثيق السريري الدقيق، وICD-10 للإحصاء والفوترة. وهذا مسموح لأن CodeableConcept يقبل عدة coding تصف نفس المفهوم:

"code": {
  "coding": [
    { "system": "http://snomed.info/sct", "code": "44054006", "display": "Diabetes mellitus type 2" },
    { "system": "http://hl7.org/fhir/sid/icd-10", "code": "E11.9" }
  ],
  "text": "السكري من النوع الثاني"
}
for f in obs-hba1c.json obs-glucose.json condition.json; do
  curl -s -X POST "$B/$(jq -r .resourceType $f)" -H "Content-Type: application/fhir+json" --data-binary @$f |
    jq -c '{type: .resourceType, id, subject: .subject.reference, encounter: .encounter.reference}'
done
{"type":"Observation","id":"1598","subject":"Patient/1596","encounter":"Encounter/1597"}
{"type":"Observation","id":"1599","subject":"Patient/1596","encounter":"Encounter/1597"}
{"type":"Condition","id":"1600","subject":"Patient/1596","encounter":"Encounter/1597"}

والصورة التالية تبين ما أصبح في السيرفر بأرقامه الحقيقية، والحقول التي تربط الموارد ببعضها:

مخطط الموارد: Patient/1596 نورة عبدالله الأحمد برقم الملف MRN-24017، وEncounter/1597 زيارة عيادة AMB تشير إليها بالحقل subject، وObservation/1598 السكر التراكمي 4548-4 بقيمة 8.1 بالمئة، وObservation/1599 السكر الصائم 1558-6 بقيمة 162 mg/dL، وCondition/1600 السكري من النوع الثاني برمزي SNOMED 44054006 وICD-10 E11.9، وكلها تشير إلى المريضة بالحقل subject وإلى الزيارة بالحقل encounter
الموارد التي أنشأناها، والمراجع المشروطة تحولت إلى أرقام حقيقية عند الحفظ

معاملات البحث Search Parameters: ما بعد البحث بالرمز

في المقال السابق بحثنا بالمعرف وبالرمز وبالتاريخ، واستخدمنا _include و_revinclude. وهنا نأخذ الاستعلامات التي سوف تحتاجها عندما تبني شاشة حقيقية، وكلها من صفحة البحث في المعيار:

echo "# 1 chained"   # results of the patient whose MRN is MRN-24017, without knowing her id
curl -s -G "$B/Observation" --data-urlencode "subject:Patient.identifier=https://clinic.example.org/mrn|MRN-24017" \
  --data-urlencode "_elements=code,valueQuantity" | jq -c '.entry[].resource | [.id, .code.coding[0].code, .valueQuantity.value, .valueQuantity.unit]'
echo "# 2 value"     # HbA1c above 6.5 %
curl -s -G "$B/Observation" --data-urlencode "code=http://loinc.org|4548-4" --data-urlencode "value-quantity=gt6.5||%" | jq -c '[.total, [.entry[]?.resource.id]]'
echo "# 3 _has"      # patients who have a type 2 diabetes condition
curl -s -G "$B/Patient" --data-urlencode "_has:Condition:subject:code=http://snomed.info/sct|44054006" \
  --data-urlencode "_elements=name" | jq -c '[.total, [.entry[]?.resource | .id, .name[0].text]]'
echo "# 4 icd"       # the same condition found by its ICD-10 code
curl -s -G "$B/Condition" --data-urlencode "code=http://hl7.org/fhir/sid/icd-10|E11.9" | jq -c '[.total, [.entry[]?.resource.id]]'
echo "# 5 include"   # results with their encounter and patient in one answer, newest first
curl -s -G "$B/Observation" --data-urlencode "patient=1596" --data-urlencode "_include=Observation:encounter" \
  --data-urlencode "_include=Observation:subject" --data-urlencode "_sort=-date" | jq -c '.entry[] | [.search.mode, .resource.resourceType, .resource.id]'
# 1 chained
["1598","4548-4",8.1,"%"]
["1599","1558-6",162,"mg/dL"]
# 2 value
[1,["1598"]]
# 3 _has
[1,["1596","نورة عبدالله الأحمد"]]
# 4 icd
[1,["1600"]]
# 5 include
["match","Observation","1598"]
["match","Observation","1599"]
["include","Patient","1596"]
["include","Encounter","1597"]

في المخرج أعلاه لاحظ التالي:

  • البحث المتسلسل Chained Search بالشكل subject:Patient.identifier يبحث في المورد المشار إليه، فالتطبيق الذي يعرف رقم الملف فقط يصل إلى النتائج في طلب واحد بدل طلبين. والمعامل _elements يرجع الحقول المطلوبة فقط، وهذا يخفف الرد في الشاشات التي تعرض قوائم طويلة.
  • بحث القيمة gt6.5||% يتكون من ثلاثة أجزاء: المقارنة والرقم، ثم النظام فارغاً، ثم الوحدة. ورجعت نتيجة السكر التراكمي فقط، لأن السكر الصائم له رمز آخر.
  • البحث العكسي _has هو عكس السلسلة: «أعطني المرضى الذين يشير إليهم تشخيص من نوع كذا». وهذا هو الاستعلام الذي تبني به قائمة مرضى السكري في العيادة، أو سجل المرضى لبرنامج متابعة.
  • التشخيص 1600 وجدناه برمز SNOMED في الاستعلام الثالث وبرمز ICD-10 في الرابع، لأن كل coding في الحقل يفهرس على حدة. وهذه فائدة عملية لوضع الرمزين معاً: فريق الفوترة يبحث بالأول وفريق الجودة بالثاني.
  • في الاستعلام الخامس يخبرك الحقل search.mode أي المدخلات طابقت البحث (match) وأيها جاء ملحقاً (include)، فلا تعرض المريضة في الشاشة كأنها نتيجة.

وماذا يحدث إذا أخطأت في اسم المعامل؟ السيرفر لا يتجاهله بصمت، وإنما يرفض الطلب ويذكر لك القائمة الصحيحة:

curl -s -i -G "$B/Observation" --data-urlencode "loinc=4548-4" | tr -d "\r" | sed -n "1p"
curl -s -G "$B/Observation" --data-urlencode "loinc=4548-4" | jq -r ".issue[0].diagnostics" | cut -c1-400
HTTP/1.1 400
HAPI-0524: Unknown search parameter "loinc" for resource type "Observation". Valid search parameters for this search are: [_id, _lastUpdated, _profile, _security, _source, _tag, based-on, category, code, code-value-concept, code-value-date, code-value-quantity, code-value-string, combo-code, combo-code-value-concept, combo-code-value-quantity, combo-data-absent-reason, combo-value-concept, combo-v

وهذا سلوك جيد، لأن السيرفر الذي يتجاهل المعامل المجهول يرجع كل الملاحظات، فيظن التطبيق أن كلها نتائج سكر. والمعيار يسمح للعميل أن يطلب أحد السلوكين بالرأس Prefer: handling=strict أو handling=lenient، فاختر الصارم في أي تطبيق سريري.

وأخيراً الصفحات Paging. فالسيرفر لا يرجع كل النتائج في رد واحد، وإنما صفحة بحجم _count ورابط للصفحة التالية:

curl -s -G "$B/Observation" --data-urlencode "patient=1596" --data-urlencode "_count=1" | jq -c '{total, link: [.link[] | {relation, url}], first: .entry[0].resource.id}'
{"total":2,"link":[{"relation":"self","url":"http://hapi:8080/fhir/Observation?_count=1&patient=1596"},{"relation":"next","url":"http://hapi:8080/fhir?_getpages=c16ecb3b-77c4-409a-ae9d-68ebbd75b755&_getpagesoffset=1&_count=1&_pretty=true&_bundletype=searchset"}],"first":"1598"}

لاحظ أن رابط الصفحة التالية ليس استعلاماً جديداً، وإنما معرف لنتيجة بحث محفوظة في السيرفر _getpages. لذلك استخدم الرابط next كما هو ولا تبنه بنفسك بإضافة offset، والسبب أن السيرفر يضمن لك بهذه الطريقة نفس ترتيب النتائج بين الصفحات. ولاحظ أيضاً أن العنوان في الروابط هو hapi:8080 لأن هذا هو الاسم الذي وصل به طلبنا داخل الشبكة، وخلف Reverse Proxy في الإنتاج يجب أن تضبط عنوان السيرفر server_address في الإعداد حتى لا يرجع روابط داخلية لا يصل إليها العميل.

البحث بالأسماء العربية Arabic Names: الهمزة التي لا تطابق

موظف الاستقبال في أي عيادة عربية يكتب الاسم كما يسمعه، فيكتب «الاحمد» دون همزة، أو «نوره» بالهاء بدل التاء المربوطة. فهل يجد السيرفر المريضة؟ جربنا عشرة أشكال من البحث على نفس المريضة، وطلبنا العدد فقط بالمعامل _summary=count:

for q in "name=نورة" "name=نو" "family=الأحمد" "family=الاحمد" "name=نُورة" "name=نوره" \
         "family:exact=الاحمد" "family:exact=الأحمد" "name:contains=حمد" "name=noura"; do
  n=$(curl -s -G "$B/Patient" --data-urlencode "${q%%=*}=${q#*=}" --data-urlencode "_summary=count" | jq .total)
  printf "%-24s %s\n" "$q" "$n"
done
name=نورة            1
name=نو                1
family=الأحمد      1
family=الاحمد      0
name=نُورة          0
name=نوره            0
family:exact=الاحمد 0
family:exact=الأحمد 1
name:contains=حمد     1
name=noura               1

(الأعمدة غير مصطفة في المخرج لأن عرض الحروف العربية في الطرفية يختلف عن عدد البايتات التي يحسبها printf.) والنتيجة كما يلي:

البحثالنتيجةالسبب
name=نووجدهابحث النصوص في FHIR يطابق بداية الكلمة افتراضياً
name=nouraوجدهاالحروف اللاتينية تحول إلى حروف كبيرة قبل المقارنة
family=الاحمدلم يجدهاالهمزة على الألف لا تزال
name=نورهلم يجدهاالتاء المربوطة والهاء حرفان مختلفان
name=نُورةلم يجدهاالحركة في البحث لا تحذف
name:contains=حمدوجدهاالبحث داخل الكلمة، وهو أبطأ على قاعدة كبيرة

ولكي نفهم السبب ننظر في جدول الفهرس نفسه، حيث يحفظ HAPI لكل اسم قيمتين: القيمة كما هي، والقيمة بعد التطبيع التي يبحث فيها، ومعها الترميز الست عشري Hex للبايتات:

docker exec fhir-db psql -U hapi -d hapi -c "select sp_name, sp_value_exact, sp_value_normalized, encode(convert_to(sp_value_normalized,'UTF8'),'hex') as hex from hfj_spidx_string where res_id=1596 and sp_name in ('family','given') order by sp_name"
 sp_name |     sp_value_exact     |  sp_value_normalized   |                                     hex
---------+------------------------+------------------------+------------------------------------------------------------------------------
 family  | الأحمد                 | الأحمد                 | d8a7d984d8a7d994d8add985d8af
 family  | Alahmad                | ALAHMAD                | 414c41484d4144
 given   | Noura                  | NOURA                  | 4e4f555241
 given   | Abdullah               | ABDULLAH               | 414244554c4c4148
 given   | نورة                   | نورة                   | d986d988d8b1d8a9
 given   | عبدالله                | عبدالله                | d8b9d8a8d8afd8a7d984d984d987

انظر إلى بايتات «الأحمد» بعد التطبيع: d8a7 d984 d8a7 d994 ...، أي ألف، ثم لام، ثم ألف، ثم d994 وهو الحرف U+0654 أي الهمزة فوق الحرف كعلامة مستقلة. فالسيرفر فكك «أ» إلى ألف وهمزة بصيغة Unicode التي تسمى NFD، ثم حذف من النتيجة العلامات التي يعرفها، وهي علامات الحروف اللاتينية مثل الحركات فوق é وü، ولكنه ترك الهمزة العربية لأنها في نطاق آخر من Unicode. وقد شرحنا هذه الصيغ في مقال ترميز النصوص وUnicode. والنتيجة أن «الأحمد» المحفوظة لا تساوي «الاحمد» في البحث، وأن الاسم اللاتيني يطابق بأي حالة أحرف بينما العربي لا يتسامح مع أي فرق.

مخطط تطبيع الاسم: الاسم المحفوظ الأحمد يتحول عند الفهرسة إلى ألف ولام وألف ثم الهمزة U+0654 كعلامة منفصلة ثم حاء وميم ودال، والبحث بالاحمد دون همزة لا يطابق، والاسم اللاتيني Alahmad يتحول إلى ALAHMAD فيطابق أي حالة أحرف. وتحته الحل: معامل البحث name-ar يوحد أشكال الهمزة إلى ألف والتاء المربوطة إلى هاء والألف المقصورة إلى ياء عند الفهرسة، والتطبيق يطبق نفس التوحيد على نص البحث قبل إرساله
لماذا لا تجد «الاحمد» المريضة «الأحمد»، وكيف يحل معامل بحث مخصص ذلك

الحل: معامل بحث مخصص Custom SearchParameter يوحد الحروف

الحل البسيط هو أن تطلب من الموظفين كتابة الأسماء بالهمزات الصحيحة دائماً، وهذا لا يعمل في الواقع، والسبب أن نفس الاسم يأتي من الهوية بشكل ومن نظام المختبر بشكل آخر. والحل الثاني أن تبحث بـ :contains على جزء من الاسم، وهذا يحل بعض الحالات ويرجع نتائج كثيرة غير مطلوبة، ويصبح بطيئاً على مئات الآلاف من المرضى. أما الحل الأنسب فهو أن تضيف معامل بحث خاصاً بك عبر المورد SearchParameter، يحسب قيمة موحدة من الاسم بتعبير FHIRPath عند الحفظ:

{
  "resourceType": "SearchParameter",
  "url": "https://clinic.example.org/fhir/SearchParameter/patient-name-ar",
  "name": "name-ar",
  "status": "active",
  "description": "Arabic given and family names with hamza forms, taa marbuta and alef maksura unified",
  "code": "name-ar",
  "base": [ "Patient" ],
  "type": "string",
  "expression": "Patient.name.select(family | given).select($this.replace('أ', 'ا').replace('إ', 'ا').replace('آ', 'ا').replace('ة', 'ه').replace('ى', 'ي'))"
}

التعبير يأخذ اسم العائلة والأسماء الأولى من كل HumanName، ثم يستبدل في كل منها أشكال الهمزة على الألف بألف، والتاء المربوطة بهاء، والألف المقصورة بياء. ونرسله ثم نبحث مباشرة:

curl -s -X POST "$B/SearchParameter" -H "Content-Type: application/fhir+json" --data-binary @sp-name-ar.json | jq -c '{resourceType,id}'
for q in "name-ar=الاحمد" "name-ar=نوره" "name-ar=نورة" "name-ar=الأحمد"; do
  n=$(curl -s -G "$B/Patient" --data-urlencode "${q%%=*}=${q#*=}" --data-urlencode "_summary=count" | jq .total)
  printf "%-24s %s\n" "$q" "$n"
done
{"resourceType":"SearchParameter","id":"1601"}
name-ar=الاحمد     1
name-ar=نوره         1
name-ar=نورة         0
name-ar=الأحمد     0

عند حفظ المعامل الجديد شغل HAPI بنفسه مهمة إعادة فهرسة Reindex للمرضى الموجودين، وظهر في السجل Finished $reindex work chunk with 1 resources، فلم نحتج أن نعيد إرسال المريضة. ولاحظ النتيجتين الأخيرتين: البحث بـ «نورة» و«الأحمد» بشكلهما الصحيح لم يجد شيئاً، والسبب أن القيمة المفهرسة أصبحت «نوره» و«الاحمد»، كما يظهر في الجدول:

docker exec fhir-db psql -U hapi -d hapi -c "select sp_name, sp_value_exact from hfj_spidx_string where res_id=1596 and sp_name='name-ar'"
 sp_name | sp_value_exact
---------+----------------
 name-ar | الاحمد
 name-ar | نوره
 name-ar | Alahmad
 name-ar | Abdullah
 name-ar | عبدالله
 name-ar | Noura
(6 rows)

وهذا هو الدرس: التوحيد يجب أن يطبق على الطرفين. فالمعامل يوحد ما يحفظ، والتطبيق يجب أن يطبق نفس الاستبدالات الخمسة على نص البحث قبل أن يرسله، ويحذف الحركات منه أيضاً، ثم يرسله إلى name-ar. وبهذا يجد الموظف المريضة مهما كتب الهمزة. وإذا احتجت أكثر من ذلك، مثل التسامح مع الأخطاء الإملائية أو «عبد الله» بمسافة، فهذا عمل محرك بحث نصي كامل، وقد شرحنا ذلك في مقال البحث في النصوص العربية. ولا تنس أن تضع المعامل الجديد في ملف إعداد أو سكربت تهيئة يحفظ مع المشروع، فهو مورد في القاعدة، ولن يكون موجوداً في سيرفر جديد إلا إذا أنشأته.

النسخ Versioning والقفل المتفائل Optimistic Locking

السجل الطبي لا يقبل أن تختفي القيمة القديمة عند التعديل، فإذا قرر طبيب علاجاً بناء على رقم هاتف أو عنوان أو حساسية مسجلة، فيجب أن تعرف لاحقاً ماذا كان مكتوباً وقتها. لذلك كل تعديل في FHIR يصنع نسخة جديدة برقم versionId، وتبقى النسخ القديمة متاحة. ولكن هناك مشكلة رئيسية في أي نظام يعدل فيه أكثر من شخص نفس السجل: موظف الاستقبال يفتح ملف المريضة ليعدل الهاتف، وفي نفس الوقت تفتحه الممرضة لتضيف العنوان، وكل منهما يحفظ نسخته الكاملة من المورد. فمن يحفظ أخيراً يمسح تعديل الآخر دون أن يعلم، وهذا ما يسمى التحديث الضائع Lost Update. والحل في المعيار هو القفل المتفائل: العميل يرسل مع التعديل رقم النسخة التي قرأها في الرأس If-Match، والسيرفر يرفض التعديل إذا تغيرت النسخة في الأثناء. ونجرب الحالتين:

curl -s "$B/Patient/1596" > /tmp/p1.json          # both users read version 1
jq '.telecom[0].value = "+966511111111"' /tmp/p1.json > /tmp/p2.json
echo "# reception: update with If-Match 1"
curl -s -i -X PUT "$B/Patient/1596" -H "Content-Type: application/fhir+json" -H 'If-Match: W/"1"' --data-binary @/tmp/p2.json | tr -d "\r" | grep -i -E "^HTTP|^etag"
jq '.address = [{"use":"home","country":"SA"}]' /tmp/p1.json > /tmp/p3.json
echo "# nurse: stale update with If-Match 1"
curl -s -i -X PUT "$B/Patient/1596" -H "Content-Type: application/fhir+json" -H 'If-Match: W/"1"' --data-binary @/tmp/p3.json | tr -d "\r" | grep -i -E "^HTTP"
curl -s -X PUT "$B/Patient/1596" -H "Content-Type: application/fhir+json" -H 'If-Match: W/"1"' --data-binary @/tmp/p3.json | jq -c '.issue[] | {severity, code, diagnostics}'
# reception: update with If-Match 1
HTTP/1.1 200
ETag: W/"2"
# nurse: stale update with If-Match 1
HTTP/1.1 409
{"severity":"error","code":"processing","diagnostics":"HAPI-0550: HAPI-0989: Trying to update Patient/1596/_history/1 but this is not the current version"}

الاستقبال حفظ النسخة 2، والممرضة التي ما زالت تحمل النسخة 1 رفض طلبها برسالة واضحة: تحاول تعديل النسخة 1 وهي ليست النسخة الحالية. والتطبيق الصحيح عند هذا الخطأ يقرأ المورد من جديد، ويعرض للمستخدم ما تغير، ثم يعيد تطبيق تعديله على النسخة الجديدة.

💡
المعيار في صفحة واجهة REST يقول إن السيرفر يرجع 412 Precondition Failed عندما لا يطابق If-Match النسخة الحالية، ويذكر أن 409 Conflict قد يرجع عندما يكتشف السيرفر أن التعديل لا يمكن تنفيذه. وHAPI في تجربتنا رجع 409. لذلك اكتب كود العميل بحيث يعامل الرمزين كتعارض نسخ، ولا تعتمد على رقم واحد إذا كان تطبيقك سوف يتصل بسيرفرات من موردين مختلفين.

والآن ماذا يحدث إذا أرسلت الممرضة نفس التعديل دون If-Match، كما تفعل أغلب التطبيقات البسيطة؟ نأخذ النسخة القديمة نفسها ونرسلها:

curl -s "$B/Patient/1596/_history/1" | jq 'del(.meta) | .address = [{"use":"home","country":"SA"}]' > /tmp/p3.json
curl -s -i -X PUT "$B/Patient/1596" -H "Content-Type: application/fhir+json" --data-binary @/tmp/p3.json | tr -d "\r" | grep -i -E "^HTTP|^etag"
curl -s "$B/Patient/1596" | jq -c '[.meta.versionId, .telecom[0].value, .address]'
HTTP/1.1 200
ETag: W/"3"
["3","+966500000000",[{"use":"home","country":"SA"}]]

قبل السيرفر التعديل وأنشأ النسخة 3، ولكن انظر إلى الهاتف: رجع إلى الرقم القديم +966500000000، أي أن تعديل الاستقبال ضاع دون أي خطأ، وهذا هو التحديث الضائع أمامك. والسيرفر لم يخطئ، فقد طلبنا منه أن يضع هذا المورد كاملاً مكان الحالي. لذلك أرسل If-Match في كل تعديل يأتي من شاشة يعمل عليها البشر. والمعيار يسمح للسيرفر أن يجعل ذلك إلزامياً برفض أي PUT دون If-Match بالرمز 400. ثم نصلح الهاتف بالطريقة الصحيحة ونقرأ التاريخ:

curl -s "$B/Patient/1596" | jq '.telecom[0].value = "+966511111111"' > /tmp/p4.json
curl -s -i -X PUT "$B/Patient/1596" -H "Content-Type: application/fhir+json" -H 'If-Match: W/"3"' --data-binary @/tmp/p4.json | tr -d "\r" | grep -i -E "^HTTP|^etag"
curl -s "$B/Patient/1596/_history" | jq -c '.entry[] | [.resource.meta.versionId, .resource.meta.lastUpdated, .resource.telecom[0].value]'
curl -s "$B/Patient/1596/_history/1" | jq -c '[.meta.versionId, .telecom[0].value]'
HTTP/1.1 200
ETag: W/"4"
["4","2026-11-18T10:41:14.939+00:00","+966511111111"]
["3","2026-11-18T10:40:51.176+00:00","+966500000000"]
["2","2026-11-18T10:40:26.665+00:00","+966511111111"]
["1","2026-11-18T10:35:53.365+00:00","+966500000000"]
["1","+966500000000"]

الطلب _history يرجع كل النسخ من الأحدث إلى الأقدم، والطلب _history/1 يقرأ نسخة محددة ويسمى vread. والتاريخ نفسه يحكي القصة كاملة: الهاتف تغير في النسخة 2، ثم رجع خطأ في 3، ثم أصلح في 4. وواجهة الاختبار التي تأتي مع HAPI تعرض نفس التاريخ:

واجهة الاختبار في HAPI FHIR: طلب GET إلى Patient/1596/_history ورد HTTP 200 مع الرؤوس، والحزمة فيها أربع نسخ Patient/1596/_history/4 و3 و2 و1 بأوقات 10:41:14 و10:40:51 و10:40:26 و10:35:53، وبجانب كل نسخة زرا Read وUpdate، وعلى اليسار قائمة أنواع الموارد وعدد كل منها مثل Binary 380 وValueSet 82 وCodeSystem 78 وStructureDefinition 56
تاريخ المريضة 1596 في واجهة الاختبار: أربع نسخ لا تحذف منها واحدة

وفي القاعدة نرى نفس النسخ الأربع كأسطر مستقلة، وكل سطر فيه نص المورد كاملاً:

docker exec fhir-db psql -U hapi -d hapi -c "select res_id, res_ver, res_encoding, length(res_text_vc) as json_chars, res_updated from hfj_res_ver where res_id=1596 order by res_ver"
 res_id | res_ver | res_encoding | json_chars |       res_updated
--------+---------+--------------+------------+-------------------------
   1596 |       1 | JSON         |        430 | 2026-11-18 10:35:53.365
   1596 |       2 | JSON         |        430 | 2026-11-18 10:40:26.665
   1596 |       3 | JSON         |        472 | 2026-11-18 10:40:51.176
   1596 |       4 | JSON         |        472 | 2026-11-18 10:41:14.939
(4 rows)
خط زمني لنسخ المريضة 1596: النسخة 1 بالهاتف القديم، ثم الاستقبال يحفظ النسخة 2 بالهاتف الجديد مع If-Match 1 ويرجع 200، ثم الممرضة ترسل تعديل العنوان مع If-Match 1 فيرفض بالرمز 409، ثم ترسله دون If-Match فيقبل كنسخة 3 ويرجع الهاتف القديم وهذا هو التحديث الضائع، ثم الإصلاح بالنسخة 4 مع If-Match 3، وكل النسخ محفوظة في جدول hfj_res_ver
القفل المتفائل: If-Match يمنع التحديث الضائع، وغيابه يسمح به دون أي خطأ

الحذف Delete: 410 وليس 404

لنفرض أن نتيجة السكر الصائم أدخلت لمريضة خطأ. نحذفها ثم نحاول قراءتها:

curl -s -i -X DELETE "$B/Observation/1599" | tr -d "\r" | grep -i -E "^HTTP"
curl -s -i "$B/Observation/1599" | tr -d "\r" | grep -i -E "^HTTP"; curl -s "$B/Observation/1599" | jq -r '.issue[0].diagnostics'
curl -s "$B/Observation/1599/_history" | jq -c '.entry[] | [.request.method // "-", .response.status // "-", .resource.meta.versionId // "(deleted)", .fullUrl]'
HTTP/1.1 200
HTTP/1.1 410
Resource was deleted at 2026-11-18T10:41:15.094+00:00
["DELETE","200 OK","(deleted)","http://hapi:8080/fhir/Observation/1599"]
["POST","201 Created","1","http://hapi:8080/fhir/Observation/1599"]

القراءة بعد الحذف ترجع 410 Gone وليس 404، أي أن السيرفر يعرف أن هذا المورد كان موجوداً وحذف، والتاريخ يحتفظ بالنسخة الأصلية وبحدث الحذف نفسه. وفي القاعدة بقي المورد بسطر فيه وقت الحذف res_deleted_at، ولا يزول نهائياً إلا بعملية $expunge التي يجب أن تكون معطلة أو محصورة بمدير النظام. ولكن انتبه: في السجلات السريرية الحذف ليس الطريقة الصحيحة لإلغاء نتيجة خاطئة. فالطبيب الذي رأى النتيجة قبل حذفها قد يكون بنى عليها قراراً، والتطبيقات التي نسختها لا تعرف أنها حذفت. لذلك المعيار يعرف للملاحظة الحالة entered-in-error، وهي تعديل عادي يصنع نسخة جديدة ويبقي المورد قابلاً للبحث والقراءة مع علامة واضحة أنه خطأ، كما في قائمة حالات الملاحظة في المعيار. استخدم الحذف للبيانات التجريبية فقط.

هل بقيت البيانات بعد إعادة التشغيل Restart؟

هذا هو الفرق الأساسي عن المقال السابق، ونتحقق منه بإعادة تشغيل السيرفر ثم قراءة المريضة:

docker compose restart hapi
# wait for "Started Application" (177 seconds here), then:
curl -s "$B/Patient/1596" | jq -c '[.id, .meta.versionId, .name[0].text]'
["1596","4","نورة عبدالله الأحمد"]

المريضة بنسختها الرابعة واسمها العربي كما هو، لأن كل شيء في PostgreSQL على Volume دائم. وقاعدة المختبر كلها مع حزمة نفيس كانت 46 MB فقط، أما السيرفر نفسه فكان يستخدم 2.9 GiB من الذاكرة بحسب docker stats، والسبب أن Java تحجز من الذاكرة بحسب ذاكرة الجهاز إذا لم تحدد لها حداً. لذلك حدد ذاكرة الـ Container وحجم الـ Heap في الإنتاج بدل أن تتركها تأخذ ما تريد. والنسخ الاحتياطي هنا هو نسخ قاعدة PostgreSQL نفسها بطريقة متسقة، كما شرحنا في مقال نسخ قواعد البيانات بشكل متسق، وليس نسخ ملفات المجلد والسيرفر يعمل.

التحقق Validation مقابل ملف تعريف نفيس

المورد الأساسي Patient في المعيار مرن جداً، فكل حقوله اختيارية تقريباً. أما منصة نفيس فتضيق هذا المورد في ملف تعريف Profile اسمه Nphies Patient: حقول إلزامية، وأنواع معرفات محددة، وامتدادات Extensions خاصة بالمملكة، وقوائم قيم مغلقة. والحزمة التي حملناها فيها هذا الملف، فنستطيع أن نسأل السيرفر: لو أرسلنا مريضتنا كما هي، ماذا ستقول قواعد نفيس؟ والعملية $validate تفحص دون أن تحفظ، ونكتب لها سكربتاً صغيراً يطبع كل مشكلة في سطر:

#!/bin/bash
# validate a resource file against the NPHIES Patient profile and print each issue on one line
# usage: ./validate.sh patient.json
P=http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient
curl -s -X POST "$B/Patient/\$validate?profile=$P" \
  -H "Content-Type: application/fhir+json" --data-binary @"$1" |
  jq -r '.issue[] | "\(.severity)\t\(.expression[0] // "-")\t\(.diagnostics)"'
./validate.sh patient.json
error	Patient.identifier[0]	This element does not match any known slice defined in the profile http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0 and slicing is CLOSED: Patient.identifier[0]: Does not match slice 'iqama' (discriminator: type.coding.where((system = 'http://terminology.hl7.org/CodeSystem/v2-0203') and (code = 'PRC')).exists()), Patient.identifier[0]: Does not match slice 'passport' (discriminator: type.coding.where((system = 'http://terminology.hl7.org/CodeSystem/v2-0203') and (code = 'PPN')).exists()), Patient.identifier[0]: Does not match slice 'nationalid' (discriminator: type.coding.where((system = 'http://terminology.hl7.org/CodeSystem/v2-0203') and (code = 'NI')).exists()), Patient.identifier[0]: Does not match slice 'visa' (discriminator: type.coding.where((system = 'http://terminology.hl7.org/CodeSystem/v2-0203') and (code = 'VP') and (display = 'Visitor Permit')).exists()), Patient.identifier[0]: Does not match slice 'medicalrecord' (discriminator: type.coding.where((system = 'http://terminology.hl7.org/CodeSystem/v2-0203') and (code = 'MR')).exists())
error	Patient	Patient.id: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient	Patient.meta: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient	Patient.extension: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient	Slice 'Patient.extension:occupation' for extension 'http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/extension-occupation': a matching slice is required, but not found (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0). Note that other slices are allowed in addition to this required slice
error	Patient	Patient.name: max allowed = 1, but found 2 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient	Patient.maritalStatus: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient.identifier[0]	Identifier.type: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/DP-Identifier-B|1.0.0)
error	Patient.identifier[0]	Patient.identifier.type: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient.gender	Patient.gender.extension: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient.gender	Slice 'Patient.gender.extension:ksa-administrative-gender' for extension 'http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/extension-ksa-administrative-gender': a matching slice is required, but not found (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0). Note that other slices are allowed in addition to this required slice
warning	Patient	Constraint failed: dom-6: 'A resource should have narrative for robust management' (defined in http://hl7.org/fhir/StructureDefinition/DomainResource) (Best Practice Recommendation)

أحد عشر خطأ في مورد قبله السيرفر قبل قليل دون أي ملاحظة. وهذه الرسائل تبدو مخيفة في البداية، ولكن كل سطر فيها له نفس البنية: الخطورة، ثم المكان في المورد بتعبير FHIRPath، ثم الوصف ومن أي ملف تعريف جاءت القاعدة. ونقرؤها مجمعة كما يلي:

الخطأمعناهالإصلاح
identifier[0] لا يطابق أي شريحة، وIdentifier.type ناقصالمعرفات في نفيس مقسمة إلى شرائح Slices مغلقة: إقامة PRC، وجواز PPN، وهوية وطنية NI، وتأشيرة VP، وملف طبي MR، ويفرق بينها الحقل type. ومعرفنا ليس له نوع، فلا ينتمي لأي شريحةنضيف type من الجدول v2-0203 لكل معرف
Patient.id وPatient.meta إلزاميانالمورد يجب أن يحمل معرفه ويعلن ملف التعريف الذي يطابقه في meta.profileنضيف id وmeta.profile
الامتداد occupation مطلوبالمهنة إلزامية في نفيس، وتأتي من قائمة رموز خاصة بهانضيف الامتداد برمز من القائمة
Patient.name: max allowed = 1نفيس يقبل اسماً واحداً فقط، بينما أرسلنا اسمين عربي ولاتينينرسل اسماً واحداً
maritalStatus إلزاميالحالة الاجتماعية مطلوبةنضيفها من قائمة القيم
gender.extension ناقصالجنس في FHIR قائمة من أربع قيم، ونفيس يضيف امتداداً بقائمة سعودية أدقنضيف الامتداد ksa-administrative-gender في _gender

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

ولكي نبني المورد الصحيح نظرنا في أمثلة المرضى المنشورة داخل الحزمة نفسها في المجلد package/example، وكلها تستخدم للإقامة النظام http://nphies.sa/identifier/iqama، ورموز المهنة والجنس قرأناها من ملفي CodeSystem في الحزمة. والنتيجة هذا الملف، وكل القيم فيه وهمية:

{
  "resourceType": "Patient",
  "id": "MRN-24017",
  "meta": { "profile": [ "http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0" ] },
  "extension": [
    { "url": "http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/extension-occupation",
      "valueCodeableConcept": { "coding": [ { "system": "http://nphies.sa/terminology/CodeSystem/occupation", "code": "education" } ] } }
  ],
  "identifier": [
    { "type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "PRC" } ] },
      "system": "http://nphies.sa/identifier/iqama", "value": "2000000017" },
    { "type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" } ] },
      "system": "https://clinic.example.org/mrn", "value": "MRN-24017" }
  ],
  "active": true,
  "name": [ { "use": "official", "text": "نورة عبدالله الأحمد", "family": "الأحمد", "given": [ "نورة", "عبدالله" ] } ],
  "telecom": [ { "system": "phone", "value": "+966511111111" } ],
  "gender": "female",
  "_gender": { "extension": [ { "url": "http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/extension-ksa-administrative-gender",
      "valueCodeableConcept": { "coding": [ { "system": "http://nphies.sa/terminology/CodeSystem/ksa-administrative-gender", "code": "female" } ] } } ] },
  "birthDate": "1984-03-12",
  "maritalStatus": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus", "code": "M" } ] }
}

لاحظ الحقل _gender الذي يبدأ بشرطة سفلية: في JSON لا تستطيع أن تضع امتداداً على قيمة بسيطة مثل النص "female"، لذلك يضع المعيار امتدادات القيمة البسيطة في حقل مجاور بنفس الاسم يبدأ بـ _. وهذا الشكل يربك من يراه لأول مرة، وهو موضح في صفحة الامتدادات. ولاحظ أيضاً أن رقم الملف بقي معرفاً ثانياً في الشريحة MR، فلم نخسر الربط مع نظام العيادة. ثم نتحقق مرة ثانية:

./validate.sh patient-nphies.json
information	Patient.maritalStatus	Code validation occurred using a ValueSet expansion that was pre-calculated at 2026-11-18T10:33:55.148+00:00
warning	Patient	Constraint failed: dom-6: 'A resource should have narrative for robust management' (defined in http://hl7.org/fhir/StructureDefinition/DomainResource) (Best Practice Recommendation)

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

curl -s -G "$B/ValueSet/\$expand" --data-urlencode "url=http://nphies.sa/terminology/ValueSet/ksa-marital-status" |
  jq -r '.expansion.total, (.expansion.contains[] | "\(.code)\t\(.display)\t\(.system)")'
6
D	Divorced	http://terminology.hl7.org/CodeSystem/v3-MaritalStatus
L	Legally Separated	http://terminology.hl7.org/CodeSystem/v3-MaritalStatus
M	Married	http://terminology.hl7.org/CodeSystem/v3-MaritalStatus
U	unmarried	http://terminology.hl7.org/CodeSystem/v3-MaritalStatus
W	Widowed	http://terminology.hl7.org/CodeSystem/v3-MaritalStatus
UNK	unknown	http://terminology.hl7.org/CodeSystem/v3-NullFlavor

وهذه الطريقة مفيدة عند بناء الشاشات: القائمة المنسدلة في نموذج تسجيل المريض تأتي من $expand على نفس القائمة التي يتحقق بها السيرفر، فلا يختار الموظف قيمة سوف ترفض لاحقاً.

رفض البيانات الخاطئة عند الكتابة Write Validation: الرمز 422

حتى الآن التحقق اختياري: من يريد يسأل $validate، ومن لا يريد يحفظ ما يشاء. ولكي يرفض السيرفر بنفسه أي مورد لا يطابق، نضيف إلى hapi.yaml ثلاثة أسطر ونعيد إنشاء الـ Container:

    # validate every create and update, and reject what fails
    validation:
      requests_enabled: true
docker compose up -d --force-recreate hapi

ثم نجرب ثلاث حالات: المريضة الصحيحة بمعرفها MRN-24017 الذي اخترناه نحن (ولهذا فعلنا client_id_strategy: ALPHANUMERIC)، ثم نفس المريضة بمهنة غير موجودة ودون حالة اجتماعية:

curl -s -i -X PUT "$B/Patient/MRN-24017" -H "Content-Type: application/fhir+json" --data-binary @patient-nphies.json | tr -d "\r" | grep -i -E "^HTTP|^etag"
jq '.extension[0].valueCodeableConcept.coding[0].code = "teacher" | del(.maritalStatus)' patient-nphies.json > /tmp/bad.json
curl -s -o /tmp/r.json -w "%{http_code}\n" -X PUT "$B/Patient/MRN-24017" -H "Content-Type: application/fhir+json" --data-binary @/tmp/bad.json
jq -r '.resourceType, (.issue[] | select(.severity=="error") | "\(.severity)\t\(.expression[0] // "-")\t\(.diagnostics)")' /tmp/r.json
HTTP/1.1 201
ETag: W/"1"
422
OperationOutcome
error	Patient	Patient.maritalStatus: minimum required = 1, but only found 0 (from http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition/patient|1.0.0)
error	Patient.extension[0].value.ofType(CodeableConcept)	Unable to validate code http://nphies.sa/terminology/CodeSystem/occupation#teacher - Code is not found in CodeSystem: http://nphies.sa/terminology/CodeSystem/occupation
error	Patient.extension[0].value.ofType(CodeableConcept)	None of the codings provided are in the value set 'Occupation' (http://nphies.sa/terminology/ValueSet/occupation|1.0.0), and a coding from this value set is required) (codes = http://nphies.sa/terminology/CodeSystem/occupation#teacher)

المريضة الصحيحة أنشئت بالرمز 201 بمعرفنا، والخاطئة رفضت بالرمز 422 Unprocessable Entity ومعها مورد OperationOutcome فيه الأخطاء الثلاثة. والفرق بين 400 و422 مهم في كود العميل: 400 يعني أن الطلب نفسه غير مفهوم (JSON مكسور أو معامل مجهول كما رأينا)، و422 يعني أن السيرفر فهم المورد ورفضه لأنه يخالف القواعد، فاعرض للمستخدم محتوى diagnostics وexpression ليعرف أي حقل يصلح.

والآن السؤال الأهم: ماذا لو أرسل نظام آخر نفس المريضة الخاطئة دون أن يعلن ملف تعريف نفيس في meta.profile؟

jq '.extension[0].valueCodeableConcept.coding[0].code = "teacher" | del(.maritalStatus) | del(.meta)' patient-nphies.json > /tmp/bad2.json
curl -s -X PUT "$B/Patient/MRN-24017" -H "Content-Type: application/fhir+json" --data-binary @/tmp/bad2.json |
  jq -r '.issue[] | "\(.severity)\t\(.expression[0] // "-")\t\(.diagnostics)"' | cut -c1-400
echo "# plain patient without the NPHIES extension"
jq 'del(.meta) | del(.extension) | del(.maritalStatus)' patient-nphies.json > /tmp/plain.json
curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$B/Patient/MRN-24017" -H "Content-Type: application/fhir+json" --data-binary @/tmp/plain.json
error	Patient.extension[0].value.ofType(CodeableConcept)	Unable to validate code http://nphies.sa/terminology/CodeSystem/occupation#teacher - Code is not found in CodeSystem: http://nphies.sa/terminology/CodeSystem/occupation
error	Patient.extension[0].value.ofType(CodeableConcept)	None of the codings provided are in the value set 'Occupation' (http://nphies.sa/terminology/ValueSet/occupation|1.0.0), and a coding from this value set is required) (codes = http://nphies.sa/terminology/CodeSystem/occupation#teacher)
warning	Patient.identifier[0].type	None of the codings provided are in the value set 'IdentifierType' (http://hl7.org/fhir/ValueSet/identifier-type|4.0.1), and a coding should come from this value set unless it has no suitable code (note that the validator cannot judge what is suitable) (codes = http://terminology.hl7.org/CodeSystem/v2-0203#PRC)
# plain patient without the NPHIES extension
200

في المخرج أعلاه لاحظ التالي:

  • دون meta.profile اختفى خطأ الحالة الاجتماعية، لأن السيرفر لم يعد يطبق ملف تعريف نفيس، وإنما المورد الأساسي الذي لا يشترطها.
  • ولكن خطأ المهنة بقي، والسبب أن الامتداد نفسه معرف في الحزمة المحملة، فكلما ظهر امتداد يعرفه السيرفر تحقق منه بقواعده أينما كان.
  • والمريضة التي حذفنا منها كل ما يخص نفيس قبلت بالرمز 200، وحلت محل النسخة الصحيحة، أي أن السيرفر لا يفرض ملف التعريف على من لا يعلنه.

والدرس أن تفعيل التحقق عند الكتابة لا يعني أن كل ما في السيرفر يطابق دليل نفيس، وإنما أن كل ما أعلن أنه يطابقه يطابقه فعلاً. فإذا أردت أن تفرض ملف تعريف على كل المرضى دون استثناء، فهذا قرار آخر يحتاج قاعدة في السيرفر، مثل Interceptor يرفض أي Patient ليس في meta.profile الخاص به ملف التعريف المطلوب، وتجد قائمة الـ Interceptors الجاهزة في توثيق HAPI. وفي أغلب المشاريع الأفضل ألا تفرض ملف تعريف منصة خارجية على سيرفرك الداخلي كله، وإنما تتحقق به في الطبقة التي ترسل إلى تلك المنصة. ثم أعدنا النسخة الصحيحة بنفس طلب PUT الأول فرجع 200.

ثلاث طبقات للتحقق: الأولى قراءة الصيغة Parsing ترفض JSON المكسور والقيم خارج القوائم المغلقة في المعيار، والثانية ملف التعريف Profile مثل Nphies Patient ويطبق فقط إذا أعلنه المورد في meta.profile أو طلب في $validate وقد وجد 11 خطأ في مريضتنا، والثالثة المصطلحات Terminology تفحص أن الرمز موجود في نظامه وقائمته مثل occupation#teacher المرفوض، وفي الأسفل نتائج الطلبات: الصحيحة 201، والخاطئة مع meta.profile 422، والخاطئة دون meta.profile 422 بسبب الامتداد فقط، والخالية من امتدادات نفيس 200
ماذا يفحص كل مستوى من التحقق، وماذا رجع لكل طلب أرسلناه

وتبقى طبقة لم نختبرها هنا وشرحناها في المقال السابق: السيرفر لا يحمل قاموس LOINC أو SNOMED CT، فلا يعرف إن كان الرمز 4548-4 موجوداً فعلاً. والحل ربطه بخادم مصطلحات Terminology Server، والأنظمة نفسها وتراخيصها موضوع مقال المصطلحات الطبية في نفس المرحلة.

حزم المعاملات Transaction Bundles: الكل أو لا شيء

في الواقع لا تصل بيانات الزيارة مورداً مورداً، وإنما دفعة واحدة: المريض والزيارة والقياسات والتشخيص. والحل البسيط أن ترسلها بأربعة طلبات متتالية، والمشكلة فيه أن الطلب الثالث إذا فشل يبقى في السيرفر مريض وزيارة دون قياسات، ولا يعرف أحد أن البيانات ناقصة. والحل في المعيار حزمة من النوع transaction كما في تعريف Bundle: السيرفر ينفذ كل ما فيها في معاملة واحدة في قاعدة البيانات، فإما أن تنجح كلها أو لا يحفظ شيء. والموارد داخل الحزمة يشير بعضها إلى بعض بمعرفات مؤقتة بالشكل urn:uuid:... يستبدلها السيرفر بالأرقام الحقيقية. وحزمتنا لمريض ثان، فيها أربعة مدخلات: المريض بإنشاء مشروط، ثم الزيارة، ثم قياس الضغط الانقباضي 152 mmHg برمز LOINC 8480-6، ثم تشخيص ارتفاع ضغط الدم برمزي SNOMED CT 38341003 وICD-10 I10. وهذا أول مدخلين منها:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:0b6f2a52-6f1e-4b8e-9d0e-6a1f0c2d1a01",
      "resource": {
        "resourceType": "Patient",
        "identifier": [ { "system": "https://clinic.example.org/mrn", "value": "MRN-24018" } ],
        "name": [ { "use": "official", "text": "خالد إبراهيم السالم", "family": "السالم", "given": [ "خالد", "إبراهيم" ] } ],
        "gender": "male",
        "birthDate": "1971-07-02"
      },
      "request": { "method": "POST", "url": "Patient", "ifNoneExist": "identifier=https://clinic.example.org/mrn|MRN-24018" }
    },
    {
      "fullUrl": "urn:uuid:0b6f2a52-6f1e-4b8e-9d0e-6a1f0c2d1a02",
      "resource": {
        "resourceType": "Encounter",
        "status": "finished",
        "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB" },
        "subject": { "reference": "urn:uuid:0b6f2a52-6f1e-4b8e-9d0e-6a1f0c2d1a01" },
        "period": { "start": "2026-11-17T10:00:00+03:00", "end": "2026-11-17T10:25:00+03:00" }
      },
      "request": { "method": "POST", "url": "Encounter" }
    }

نجرب العطل: إعادة إرسال نفس الحزمة Resend

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

echo "# send 1"; curl -s -X POST "$B" -H "Content-Type: application/fhir+json" --data-binary @visit-bundle.json | jq -r '.type, (.entry[].response | "\(.status)\t\(.location)")'
echo "# send 2"; curl -s -X POST "$B" -H "Content-Type: application/fhir+json" --data-binary @visit-bundle.json | jq -r '.entry[].response | "\(.status)\t\(.location)"'
# send 1
transaction-response
201 Created	Patient/1659/_history/1
201 Created	Encounter/1656/_history/1
201 Created	Observation/1657/_history/1
201 Created	Condition/1658/_history/1
# send 2
200 OK	Patient/1659/_history/1
201 Created	Encounter/1660/_history/1
201 Created	Observation/1661/_history/1
201 Created	Condition/1662/_history/1

المريض لم يتكرر بفضل ifNoneExist، ولكن الزيارة والقياس والتشخيص تكررت: أصبح للمريض زيارتان 1656 و1660 لنفس الموعد، وقراءتا ضغط، وتشخيصان. وهذا خطأ صامت، فالطبيب سوف يرى في الملف زيارتين، والتقرير سوف يعد مرضى الضغط مرتين. والسبب أن هذه الموارد ليس لها معرف تجاري يبحث به السيرفر، فكل POST إنشاء جديد. وهذه مشكلة Idempotency التي شرحناها في مقال Idempotency، وحلها هنا أن يكون لكل مورد معرف من النظام المرسل (رقم الزيارة، ورقم الطلب في المختبر، ورقم التشخيص)، وأن نستبدل POST بتحديث مشروط Conditional Update بالشكل PUT Encounter?identifier=...: إذا لم يوجد المورد أنشئ، وإذا وجد مورد واحد حدث. فبنينا نسخة ثانية من الحزمة لمريض ثالث، تحمل فيها الزيارة والقياس والتشخيص معرفات، والطلب فيها بهذا الشكل:

"request": { "method": "PUT", "url": "Encounter?identifier=https://clinic.example.org/visit|V-2026-11-0512" }
for n in 1 2; do echo "# send $n"
  curl -s -X POST "$B" -H "Content-Type: application/fhir+json" --data-binary @visit-bundle-v2.json | jq -r '.entry[].response | "\(.status)\t\(.location)"'
done
# send 1
201 Created	Patient/1667/_history/1
201 Created	Encounter/1668/_history/1
201 Created	Observation/1669/_history/1
201 Created	Condition/1670/_history/1
# send 2
200 OK	Patient/1667/_history/1
200 OK	Encounter/1668/_history/1
200 OK	Observation/1669/_history/1
200 OK	Condition/1670/_history/1

الإرسال الثاني رجع 200 لكل المدخلات وبنفس الأرقام، ولاحظ أن رقم النسخة بقي 1، فقد اكتشف HAPI أن المحتوى لم يتغير فلم يصنع نسخة جديدة فارغة المعنى. وبهذا تستطيع أن تعيد الإرسال بأمان مهما تكرر.

الكل أو لا شيء Rollback: حزمة فيها مرجع خاطئ

والآن نختبر الوعد الأساسي للمعاملة: نأخذ نسخة من الحزمة برقم ملف جديد MRN-24019، ونجعل القياس يشير إلى مريض غير موجود Patient/99999، ونعد الموارد قبل الإرسال وبعده. ونرسل الرأس Cache-Control: no-cache مع العد، لأن HAPI يعيد نتيجة البحث نفسها من ذاكرة مؤقتة لمدة دقيقة افتراضياً، وقد أعطانا في محاولة سابقة عدداً قديماً بسبب ذلك. والأعداد هنا 4 لكل نوع لأننا أرسلنا قبلها الحزم الثلاث في القسم السابق:

count() { for t in Patient Encounter Observation Condition; do
  printf "%s=%s " $t $(curl -s -H "Cache-Control: no-cache" "$B/$t?_summary=count" | jq .total); done; echo; }
jq '.entry[0].resource.identifier[0].value = "MRN-24019"
    | .entry[0].request.ifNoneExist = "identifier=https://clinic.example.org/mrn|MRN-24019"
    | .entry[2].resource.subject.reference = "Patient/99999"' visit-bundle.json > /tmp/broken.json
echo "# before"; count
curl -s -o /tmp/r.json -w "broken bundle: %{http_code}\n" -X POST "$B" -H "Content-Type: application/fhir+json" --data-binary @/tmp/broken.json
jq -r '.issue[] | "\(.severity)\t\(.diagnostics)"' /tmp/r.json
echo "# after"; count
curl -s -H "Cache-Control: no-cache" -G "$B/Patient" --data-urlencode "identifier=https://clinic.example.org/mrn|MRN-24019" | jq -c '{MRN_24019: .total}'
# before
Patient=4 Encounter=4 Observation=4 Condition=4
broken bundle: 400
error	HAPI-1094: Resource Patient/99999 not found, specified in path: Observation.subject
# after
Patient=4 Encounter=4 Observation=4 Condition=4
{"MRN_24019":0}

رفضت الحزمة كاملة بالرمز 400 مع سبب واضح، والأعداد لم تتغير، والمريض MRN-24019 الذي كان أول مدخل في الحزمة غير موجود، أي أن السيرفر تراجع عن إنشائه أيضاً. وهذا بالضبط ما نريده: لا توجد زيارة نصف محفوظة.

ثلاث حالات لحزمة المعاملة: الأولى حزمة فيها مرجع إلى Patient/99999 غير موجود فترفض كاملة بالرمز 400 ولا يحفظ حتى المريض الأول والأعداد تبقى 4 لكل نوع، والثانية إرسال الحزمة نفسها مرتين بطلبات POST فيتكرر المريض مرة واحدة فقط بسبب ifNoneExist بينما تتكرر الزيارة والقياس والتشخيص بأرقام جديدة 1660 و1661 و1662، والثالثة حزمة بتحديث مشروط PUT بالمعرف فيرجع الإرسال الثاني 200 بنفس الأرقام 1667 إلى 1670 ونفس النسخة 1
الحزمة إما تحفظ كلها أو لا شيء، والتكرار يمنعه المعرف والتحديث المشروط لا المعاملة

SMART on FHIR: ما الذي ينقص سيرفرنا؟

كل ما فعلناه في المختبر تم دون أي توكن، ونتحقق من ذلك بثلاثة طلبات:

curl -s -o /dev/null -w "smart-configuration: %{http_code}\n" "$B/.well-known/smart-configuration"
curl -s "$B/metadata" | jq -c '{security: .rest[0].security}'
curl -s -o /dev/null -w "read without token: %{http_code}\n" "$B/Patient/1596"
smart-configuration: 404
{"security":null}
read without token: 200

أي أن السيرفر لا ينشر ملف اكتشاف SMART، وبيان القدرات لا يذكر أي طريقة أمان، وأي أحد يصل إلى المنفذ يقرأ ملف المريضة كاملاً. وهذا طبيعي في سيرفر تجريبي، ولكنه يعني أن الأمان ليس شيئاً تفعله بخيار واحد في HAPI، وإنما طبقة تبنيها أمامه. وقد شرحنا في المقال السابق فكرة SMART App Launch ونطاقاته بلغة الموارد وPKCE، وفي مقال OAuth وOpenID Connect أساسها، لذلك نكتفي هنا بما يلزم سيرفرك ليكون جاهزاً لتطبيق خارجي بحسب المعيار:

  • سيرفر تفويض Authorization Server يصدر التوكن، مثل Keycloak أو غيره مما يدعم OAuth 2.0، وهو منفصل عن HAPI.
  • ملف الاكتشاف .well-known/smart-configuration على عنوان سيرفر FHIR نفسه، فيه عناوين التفويض والتوكن والقدرات المدعومة. وهو الذي رجع 404 عندنا.
  • طبقة تتحقق من التوكن في كل طلب وتطبق نطاقاته: التوكن الذي فيه patient/Observation.rs ومعه سياق المريض 1596 يجب ألا يقرأ ملاحظات المريض 1659. وهذه الطبقة إما Interceptor داخل HAPI، أو بوابة API أمامه، والمهم أن تكون الفلترة على مستوى المريض وليس على مستوى نوع المورد فقط.
  • للاتصال بين الأنظمة دون مستخدم، مثل محرك التكامل الذي يرسل الحزم، يعرف المعيار نمطاً خاصاً اسمه Backend Services: النظام يوقع طلب التوكن بمفتاح خاص ويحصل على نطاقات من نوع system/، فلا توجد كلمات مرور مشتركة في ملفات الإعداد.

وتذكر أن البيانات الصحية بيانات حساسة بنص نظام حماية البيانات الشخصية، وأن كل قراءة لملف مريض يجب أن تسجل كما شرحنا في مقال سجل التدقيق.

من المختبر إلى الإنتاج Production

الجدول التالي يجمع ما رأيناه في المختبر وما يقابله في سيرفر حقيقي:

البندما رأيناه في المختبرماذا تفعل في الإنتاج
قاعدة البياناتPostgreSQL 17 على Volume، والبيانات بقيت بعد إعادة التشغيلPostgreSQL بنسخ احتياطي متسق واختبار استعادة دوري
الذاكرة2.9 GiB دون حدحدد ذاكرة الـ Container وحجم الـ Heap، وراقبها
وقت التشغيل289 ثانية أول مرة و177 بعدهااضبط فحص الصحة ووقت الانتظار في المنسق على هذا، ولا تعده متعطلاً قبله
دليل التنفيذحزمة نفيس 1.0.0 من رابطها الرسمي عند كل تشغيلثبت الإصدار، واحفظ نسخة من الحزمة عندك حتى لا يتوقف التشغيل إذا تغير الرابط
التحققrequests_enabled رفض الخاطئ بالرمز 422، ولم يفرض ملف التعريف على من لا يعلنهفعله، وقرر صراحة أين تفرض ملف التعريف
الأسماء العربيةالهمزة والتاء المربوطة منعت المطابقةمعامل بحث موحد مع توحيد نص البحث في التطبيق
التعديلدون If-Match ضاع تعديل دون خطأاشترط If-Match في كل تعديل من الشاشات، وعامل 409 و412 كتعارض
التكرارإعادة إرسال الحزمة كررت الزيارةمعرف لكل مورد وتحديث مشروط
الأمانلا يوجد توكن، والقراءة مفتوحةسيرفر تفويض وSMART وتحقق من النطاق على مستوى المريض، والمنفذ غير مكشوف
الحذف410 والتاريخ باقعطل $expunge، واستخدم entered-in-error للنتائج الخاطئة
العناوينالروابط تحمل hapi:8080اضبط server_address على العنوان العام خلف الـ Reverse Proxy

أخطاء شائعة

  • الاعتماد على المعرف المنطقي بين الأنظمة: الرقم 1596 خاص بهذا السيرفر، ولو نقلت البيانات إلى سيرفر آخر لتغير. اربط الأنظمة بالمعرفات التجارية مع نظامها، مثل https://clinic.example.org/mrn|MRN-24017.
  • المعرف دون system: البحث بـ identifier=MRN-24017 وحده قد يطابق رقماً مماثلاً من مستشفى آخر في نفس السيرفر.
  • اختبار التحقق بمورد صحيح فقط: لا تعرف أن التحقق يعمل حتى ترى 422 لمورد خاطئ، كما فعلنا.
  • ظن أن تفعيل التحقق يفرض الدليل: رأينا مريضة دون امتدادات نفيس تقبل بالرمز 200.
  • إرسال PUT دون If-Match: يعمل دائماً، ولهذا هو خطر، فالتحديث الضائع لا يظهر في أي سجل خطأ.
  • POST داخل حزم تعاد: كل إعادة إرسال تنشئ نسخة مكررة من الزيارة والنتائج.
  • بناء رابط الصفحة التالية بنفسك: استخدم الرابط next كما يرجعه السيرفر.
  • البحث العربي دون توحيد: الموظف لا يجد المريض، فينشئ ملفاً جديداً، وهذه أشهر طريقة لتكرار ملفات المرضى.

تنظيف المختبر

docker compose down -v
docker rmi fhir-client

الخيار -v يحذف الـ Volume وفيه كل البيانات، فلا تستخدمه على سيرفر فيه بيانات تريدها.

تدريب عملي

  • أضف إلى المعامل name-ar حذف الحركات من الاسم المحفوظ أيضاً، ثم ابحث بالاسم مع حركة على النون نُورة بعد توحيده في التطبيق.
  • عدل نتيجة السكر التراكمي 1598 إلى الحالة entered-in-error بطلب PUT مع If-Match، ثم ابحث عن نتائج المريضة وقارن بما حدث مع الحذف.
  • تحقق من الزيارة 1597 مقابل ملف تعريف الزيارة في نفيس encounter بنفس سكربت التحقق بعد تغيير رابط ملف التعريف، واقرأ الأخطاء.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • HAPI JPA يحفظ كل الموارد في جدولين رئيسيين، واحد للمورد وواحد لكل نسخة، ويبحث في جداول فهارس منفصلة، لذلك لا تبحث إلا في معامل معرف، وطريقة التطبيع تحدد ما يطابق.
  • مع PostgreSQL بقيت البيانات بعد إعادة التشغيل، وحمل السيرفر دليل نفيس 1.0.0 من رابطه الرسمي، واحتاج قرابة خمس دقائق في أول تشغيل.
  • المراجع المشروطة والبحث المتسلسل و_has تجعل التطبيق يعمل بالمعرفات التجارية دون أن يعرف أرقام السيرفر.
  • البحث العربي لا يوحد الهمزة ولا التاء المربوطة، وحللناه بمعامل بحث مخصص بتعبير FHIRPath مع توحيد نص البحث في التطبيق.
  • If-Match رفض التعديل القديم بالرمز 409 (والمعيار يذكر 412)، وغيابه سمح بتحديث ضائع دون خطأ، والتاريخ احتفظ بكل النسخ.
  • مريضة صحيحة في المعيار الأساسي فيها 11 خطأ مقابل ملف تعريف نفيس، أوضحها أن نفيس يقبل اسماً واحداً، وبعد تفعيل التحقق رفض الخاطئ بالرمز 422، ولكن ملف التعريف لا يفرض على من لا يعلنه.
  • حزمة المعاملة إما تحفظ كلها أو لا شيء، ولكنها لا تمنع التكرار عند إعادة الإرسال، وإنما يمنعه المعرف والتحديث المشروط.
  • السيرفر بإعداده هذا مفتوح للقراءة دون توكن، وSMART on FHIR طبقة تبنيها أمامه.
دليلتبادل البيانات الصحية بين الأنظمة: HL7 وFHIRكيف تنتقل نتائج المختبر وبيانات المريض بين أنظمة المستشفى برسائل HL7 وواجهات FHIR، وكيف تبني ذلك وتختبره بنفسك.دليلالمصطلحات الطبية الموحدة: ICD وSNOMED CT وLOINCكيف تفهم الآلة أن الأسماء الطبية المختلفة مفهوم واحد، وكيف تختار نظام الرموز المناسب للتشخيص والتحليل والدواء، برموز حقيقية.دليلالمنصات الصحية في السعودية: نفيس NPHIES وصحتي ووصفتيمن يملك كل منصة صحية وطنية وماذا تفعل، من صحتي ومستشفى صحة الافتراضي إلى نفيس والسجل الموحد، وما يعنيه ذلك لمن يبني نظاماً.دليلالمستشفى من الداخل: خريطة الأنظمة HIS وEMRما هي أنظمة المستشفى من التسجيل والسجل الطبي إلى المختبر والأشعة والصيدلية والفوترة، وكيف تتصل ببعضها، ومن أين تبدأ.دليلIdempotency: كيف تجعل العملية آمنة عند تكرارهالماذا تصل الرسالة نفسها أكثر من مرة، وكيف تكتب مستهلكاً يطبقها مرة واحدة فقط مهما تكررت.دليلشرح OAuth وOpenID Connect للمبتدئينلماذا لا يجب أن يعرف أي تطبيق كلمة مرورك، وكيف يحل OAuth ذلك بتوكنات محدودة، وكيف يضيف OpenID Connect الدخول الموحد.دليلالبحث في النصوص العربية مع OpenSearch وMeilisearchلماذا يرجع البحث صفحة فارغة لمن يكتب «مستشفي» أو «اجازه»، وكيف تضبط محركك حتى يجد الكلمة بكل أشكالها.دليلAudit Trail: كيف تبني سجل تدقيق لا يقبل العبثكيف تصمم سجلاً يجيب عن سؤال من غير هذه الصلاحية ومتى، وتحميه من الحذف والتعديل بعد كتابته.

سجل التحديثات

  • 2026-11-18: كتابة المقال، وتنفيذ المختبر على HAPI FHIR 8.12.0 (hapiproject/hapi:v8.12.0-2) بإصدار FHIR R4 4.0.1 مع PostgreSQL 17.11 ودليل نفيس nphies-fs 1.0.0، وعميل alpine 3.24 فيه curl 8.23.0 وjq 1.8.2، على Docker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.