xDev Asia

Chi tiết Resource Patient (demographics, identifiers, contact, link), Practitioner và PractitionerRole, Organization, Location, Endpoint. Thực hành tạo, đọc, cập nhật Patient trên FHIR Server.

HL7 FHIR - Chuẩn Dữ liệu Y tế từ Cơ bản đến Nâng cao

Phần 2: FHIR Resources cốt lõi

xdev.asia

Xem bản video

1. Patient Resource — Trung tâm dữ liệu y tế

Patient là Resource quan trọng nhất trong FHIR — hầu hết mọi dữ liệu lâm sàng đều liên kết với một Patient. Đây cũng là Resource đầu tiên đạt cấp Normative (stable, backward-compatible).

Cấu trúc Patient Resource

Element	Type	Cardinality	Mô tả
identifier	Identifier[]	0..*	Mã định danh (CCCD, BHYT, MRN...)
active	boolean	0..1	Record có đang hoạt động?
name	HumanName[]	0..*	Họ tên bệnh nhân
telecom	ContactPoint[]	0..*	SĐT, email
gender	code	0..1	male \| female \| other \| unknown
birthDate	date	0..1	Ngày sinh
deceased[x]	boolean/dateTime	0..1	Đã mất?
address	Address[]	0..*	Địa chỉ
maritalStatus	CodeableConcept	0..1	Tình trạng hôn nhân
multipleBirth[x]	boolean/integer	0..1	Sinh đôi/ba?
photo	Attachment[]	0..*	Ảnh đại diện
contact	BackboneElement[]	0..*	Người liên hệ
communication	BackboneElement[]	0..*	Ngôn ngữ giao tiếp
generalPractitioner	Reference[]	0..*	Bác sĩ chăm sóc chính
managingOrganization	Reference	0..1	Tổ chức quản lý hồ sơ
link	BackboneElement[]	0..*	Liên kết đến record khác (merge)

Đọc lại cột "Số lượng" một lần nữa. Không có phần tử nào của Patient bắt đầu bằng 1 — nghĩa là { "resourceType": "Patient" } là một bản ghi hợp lệ đầy đủ theo base spec R5. Không tên, không mã, không ngày sinh: validator vẫn xanh và server vẫn nhận.

Đừng vì thế kết luận rằng specification không bắt buộc gì bao giờ. Ngay trong Patient, hai phần tử con của link là 1..1: Patient.link.other (trỏ tới bản ghi nào) và Patient.link.type (quan hệ gì). Ranh giới rất rõ — specification bắt buộc ở chỗ mà thiếu thì câu trở nên vô nghĩa (một link không có đích thì không còn là link), còn danh tính bệnh nhân thì để mở, vì đó là chính sách của tổ chức, không phải ngữ pháp của chuẩn.

Hệ quả thực tế: trường nào bắt buộc, siết bằng profile ra sao, so trùng bệnh nhân thế nào, và mã bệnh nhân của tổ chức định nghĩa ra sao — bốn thứ đó quyết định chất lượng dữ liệu, và không thứ nào nằm trong base spec.

Patient Resource cho bệnh nhân Việt Nam — Ví dụ đầy đủ

{
  "resourceType": "Patient",
  "id": "vn-patient-001",
  "meta": {
    "profile": ["http://fhir.vn/StructureDefinition/vn-core-patient"]
  },
  "identifier": [
    {
      "use": "official",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "NI",
          "display": "National unique individual identifier"
        }]
      },
      "system": "http://fhir.vn/sid/cccd",
      "value": "001085012345"
    },
    {
      "use": "secondary",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "SB",
          "display": "Social Beneficiary Identifier"
        }]
      },
      "system": "http://fhir.vn/sid/bhyt",
      "value": "DN4850112340001"
    },
    {
      "use": "usual",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "MR",
          "display": "Medical record number"
        }]
      },
      "system": "http://benhvien-a.vn/sid/mrn",
      "value": "BN-2026-00123"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "text": "Nguyễn Văn An",
      "family": "Nguyễn",
      "given": ["Văn", "An"]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "+84901234567",
      "use": "mobile",
      "rank": 1
    },
    {
      "system": "email",
      "value": "[email protected]",
      "use": "home"
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "text": "123 Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM",
      "line": ["123 Lê Lợi"],
      "city": "Thành phố Hồ Chí Minh",
      "district": "Quận 1",
      "state": "Thành phố Hồ Chí Minh",
      "postalCode": "700000",
      "country": "VN"
    }
  ],
  "maritalStatus": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
      "code": "M",
      "display": "Married"
    }],
    "text": "Đã kết hôn"
  },
  "contact": [
    {
      "relationship": [{
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
          "code": "N",
          "display": "Next-of-Kin"
        }]
      }],
      "name": {
        "text": "Trần Thị Bình",
        "family": "Trần",
        "given": ["Thị", "Bình"]
      },
      "telecom": [{
        "system": "phone",
        "value": "+84907654321"
      }]
    }
  ],
  "communication": [{
    "language": {
      "coding": [{
        "system": "urn:ietf:bcp:47",
        "code": "vi",
        "display": "Vietnamese"
      }]
    },
    "preferred": true
  }],
  "managingOrganization": {
    "reference": "Organization/benhvien-a",
    "display": "Bệnh viện Đại học Y Dược TP.HCM"
  }
}

Identifier Patterns cho Việt Nam

Loại ID	System (URL)	Ví dụ value
Căn cước công dân (CCCD)	http://fhir.vn/sid/cccd	001085012345
Thẻ BHYT	http://fhir.vn/sid/bhyt	DN4850112340001
Mã bệnh nhân (MRN)	http://benhvien.vn/sid/mrn	BN-2026-00123
Hộ chiếu	http://fhir.vn/sid/passport	C1234567

2. Practitioner Resource — Nhân viên y tế

Practitioner đại diện cho bất kỳ cá nhân nào tham gia vào việc chăm sóc sức khỏe: bác sĩ, điều dưỡng, dược sĩ, kỹ thuật viên...

{
  "resourceType": "Practitioner",
  "id": "dr-tran-001",
  "identifier": [{
    "system": "http://fhir.vn/sid/physician-license",
    "value": "BS-TPHCM-2010-00456"
  }],
  "active": true,
  "name": [{
    "use": "official",
    "text": "TS.BS Trần Minh Đức",
    "family": "Trần",
    "given": ["Minh", "Đức"],
    "prefix": ["TS.BS"]
  }],
  "telecom": [{
    "system": "phone",
    "value": "+84909876543",
    "use": "work"
  }],
  "gender": "male",
  "birthDate": "1978-05-20",
  "qualification": [
    {
      "identifier": [{
        "system": "http://fhir.vn/sid/medical-degree",
        "value": "BSCK2-NKH-2010"
      }],
      "code": {
        "coding": [{
          "system": "http://fhir.vn/CodeSystem/qualification",
          "code": "BSCK2",
          "display": "Bác sĩ Chuyên khoa II"
        }]
      },
      "issuer": {
        "display": "Đại học Y Dược TP.HCM"
      }
    }
  ],
  "communication": [{
    "coding": [{
      "system": "urn:ietf:bcp:47",
      "code": "vi"
    }]
  }]
}

PractitionerRole — Vai trò cụ thể

PractitionerRole mô tả vai trò của Practitioner tại một Organization cụ thể. Một bác sĩ có thể có nhiều PractitionerRoles (làm việc ở nhiều nơi).

{
  "resourceType": "PractitionerRole",
  "id": "dr-tran-role-bva",
  "active": true,
  "practitioner": {
    "reference": "Practitioner/dr-tran-001",
    "display": "TS.BS Trần Minh Đức"
  },
  "organization": {
    "reference": "Organization/benhvien-a",
    "display": "Bệnh viện A"
  },
  "code": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/practitioner-role",
      "code": "doctor",
      "display": "Doctor"
    }]
  }],
  "specialty": [{
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "394579002",
      "display": "Cardiology"
    }],
    "text": "Tim mạch"
  }],
  "location": [{
    "reference": "Location/phong-kham-tim-mach"
  }],
  "availableTime": [{
    "daysOfWeek": ["mon", "tue", "wed", "thu", "fri"],
    "availableStartTime": "07:30:00",
    "availableEndTime": "16:30:00"
  }]
}

3. Organization Resource — Cơ sở y tế

{
  "resourceType": "Organization",
  "id": "benhvien-a",
  "identifier": [
    {
      "system": "http://fhir.vn/sid/facility-code",
      "value": "79001"
    },
    {
      "system": "http://fhir.vn/sid/bhxh-facility",
      "value": "79-001"
    }
  ],
  "active": true,
  "type": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/organization-type",
      "code": "prov",
      "display": "Healthcare Provider"
    }]
  }],
  "name": "Bệnh viện Đại học Y Dược TP.HCM",
  "alias": ["BV ĐHYD"],
  "telecom": [
    {
      "system": "phone",
      "value": "+842838554269",
      "use": "work"
    },
    {
      "system": "url",
      "value": "https://www.bvdhydtphcm.vn"
    }
  ],
  "address": [{
    "use": "work",
    "line": ["215 Hồng Bàng"],
    "city": "Thành phố Hồ Chí Minh",
    "district": "Quận 5",
    "country": "VN"
  }]
}

4. Location Resource — Vị trí

Location mô tả vị trí vật lý: phòng khám, khoa, giường bệnh, phòng mổ...

{
  "resourceType": "Location",
  "id": "phong-kham-tim-mach",
  "status": "active",
  "name": "Phòng khám Tim mạch - Tầng 3",
  "description": "Phòng khám chuyên khoa Tim mạch, tầng 3 tòa nhà B",
  "mode": "instance",
  "type": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
      "code": "CARD",
      "display": "Ambulatory Health Care Facilities; Clinic/Center; Rehabilitation: Cardiac Facilities"
    }]
  }],
  "telecom": [{
    "system": "phone",
    "value": "+842838554269-303"
  }],
  "address": {
    "line": ["Tầng 3, Tòa B, 215 Hồng Bàng"],
    "city": "TP.HCM",
    "country": "VN"
  },
  "physicalType": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
      "code": "ro",
      "display": "Room"
    }]
  },
  "managingOrganization": {
    "reference": "Organization/benhvien-a"
  }
}

5. Mối quan hệ giữa các Resources hành chính

┌──────────────────┐
│   Organization   │ ← Bệnh viện/Phòng khám
│   (benhvien-a)   │
└───────┬──────────┘
        │ managingOrganization
        ▼
┌──────────────────┐        ┌──────────────────────┐
│    Location      │◄───────│   PractitionerRole   │
│ (phong-kham-tm)  │        │  (dr-tran-role-bva)  │
└──────────────────┘        └───────┬──────────────┘
                                    │ practitioner
                                    ▼
                            ┌──────────────────┐
                            │  Practitioner    │
                            │  (dr-tran-001)   │
                            └──────────────────┘
                                    ▲ generalPractitioner
                                    │
                            ┌──────────────────┐
                            │    Patient       │
                            │ (vn-patient-001) │
                            └──────────────────┘

6. Thực hành: Tạo hệ thống Resources hoàn chỉnh

Hãy tạo một workflow thực tế: đăng ký bệnh nhân tại bệnh viện.

Bước 1: Tạo Organization

curl -X POST http://localhost:8080/fhir/Organization \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Organization","name":"Bệnh viện Đa khoa A","active":true}'
# Ghi lại id trả về → {org-id}

Bước 2: Tạo Practitioner

curl -X POST http://localhost:8080/fhir/Practitioner \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Practitioner","name":[{"family":"Trần","given":["Minh","Đức"],"prefix":["BS"]}],"active":true}'
# Ghi lại id trả về → {prac-id}

Bước 3: Tạo Patient liên kết với Organization và Practitioner

curl -X POST http://localhost:8080/fhir/Patient \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "name": [{"family":"Nguyễn","given":["Thị","Mai"]}],
    "gender": "female",
    "birthDate": "1992-08-10",
    "generalPractitioner": [{"reference":"Practitioner/{prac-id}"}],
    "managingOrganization": {"reference":"Organization/{org-id}"}
  }'

Bước 4: Verify — Tìm kiếm Patient với _include

# Tìm patient kèm thông tin Practitioner
curl -s "http://localhost:8080/fhir/Patient?_include=Patient:general-practitioner" | jq '.entry[].resource.resourceType'
# Kết quả: "Patient", "Practitioner"

7. Tóm tắt

Patient: trung tâm dữ liệu, chứa identifiers, demographics, contacts
Practitioner: thông tin cá nhân nhân viên y tế, bằng cấp, chứng chỉ
PractitionerRole: vai trò cụ thể tại tổ chức cụ thể (1 người nhiều role)
Organization: bệnh viện, phòng khám, khoa, phòng ban
Location: vị trí vật lý (phòng, tầng, giường)
Các Resources liên kết với nhau qua References
Sử dụng Identifiers phù hợp cho bối cảnh Việt Nam (CCCD, BHYT, MRN)

Bài 4: Patient, Practitioner, Organization - Resources hành chính