VN Core FHIR Implementation Guide — Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Bắt đầu nhanh

Bắt đầu nhanh — Getting Started

Hướng dẫn 4 bước để bắt đầu sử dụng VN Core FHIR IG trong hệ thống của bạn.

Bước 1: Hiểu cấu trúc VN Core

Kiến trúc tổng quan

                    ┌──────────────────────────┐
                    │      VN Core FHIR IG     │
                    │      (hl7.fhir.vn.core)  │
                    └──────────┬───────────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
     ┌────────▼───────┐ ┌─────▼──────┐ ┌───────▼──────┐
     │   23 Profiles  │ │ 20 Ext.    │ │  Terminology │
     │                │ │            │ │  42 CS + 43 VS│
     │ Patient        │ │ Ethnicity  │ │              │
     │ Practitioner   │ │ Religion   │ │ ICD-10 VN    │
     │ Organization   │ │ Province   │ │ SNOMED CT VN │
     │ Encounter      │ │ Ward       │ │ LOINC VN     │
     │ Condition      │ │ BHYT Type  │ │ YHCT (10 bộ) │
     │ Observation(3) │ │ Org Rank   │ │ ĐVHC (34+xã) │
     │ Coverage       │ │ ... +14    │ │ ... +30      │
     │ Claim/EOB      │ │            │ │              │
     │ ... +14        │ │            │ │              │
     └────────────────┘ └────────────┘ └──────────────┘

Thành phần chính

Bước 2: Cài đặt & Chạy thử

2.1. Yêu cầu hệ thống

2.2. Clone và biên dịch

# Clone repository
git clone https://github.com/HL7-org-vn/vncore-ig.git
cd vncore-ig

# Cài SUSHI (nếu chưa có)
npm install -g fsh-sushi

# Biên dịch FSH → JSON
sushi .
# Kết quả: 175 resources, 0 errors, 0 warnings

2.3. Build IG đầy đủ (tùy chọn)

# Tải IG Publisher (lần đầu, ~200MB)
bash _updatePublisher.sh -y

# Build toàn bộ IG → thư mục output/
bash _genonce.sh

# Xem kết quả
open output/index.html    # Website IG
open output/qa.html       # Báo cáo QA

Bước 3: Tạo resource đầu tiên

3.1. Tạo Patient (bệnh nhân Việt Nam)

Ví dụ JSON — bệnh nhân có CCCD, thẻ BHYT, dân tộc Kinh:

{
  "resourceType": "Patient",
  "meta": {
    "profile": ["http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-patient"]
  },
  "identifier": [
    {
      "type": {
        "coding": [{
          "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-identifier-type-cs",
          "code": "CCCD"
        }]
      },
      "system": "http://fhir.hl7.org.vn/core/sid/cccd",
      "value": "001099012345"
    },
    {
      "type": {
        "coding": [{
          "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-identifier-type-cs",
          "code": "BHYT"
        }]
      },
      "system": "http://fhir.hl7.org.vn/core/sid/bhyt",
      "value": "DN4010199012345"
    }
  ],
  "name": [{
    "use": "official",
    "text": "Nguyen Van An",
    "family": "Nguyen",
    "given": ["Van", "An"]
  }],
  "gender": "male",
  "birthDate": "1990-05-15",
  "address": [{
    "use": "home",
    "text": "123 Nguyen Hue, Phuong Ngoc Ha, Ha Noi",
    "state": "Ha Noi",
    "extension": [
      {
        "url": "http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province",
        "valueCoding": {
          "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-province-cs",
          "code": "01",
          "display": "Ha Noi"
        }
      },
      {
        "url": "http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward",
        "valueCoding": {
          "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-ward-cs",
          "code": "00008",
          "display": "Phuong Ngoc Ha"
        }
      }
    ]
  }],
  "extension": [
    {
      "url": "http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ethnicity",
      "valueCodeableConcept": {
        "coding": [{
          "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-ethnicity-cs",
          "code": "01",
          "display": "Kinh"
        }]
      }
    }
  ]
}

3.2. Validate resource

Sử dụng FHIR Validator:

# Tải validator (lần đầu)
wget https://github.com/hapifhir/org.hl7.fhir.core/releases/latest/download/validator_cli.jar

# Validate
java -jar validator_cli.jar patient.json \
  -ig hl7.fhir.vn.core#0.1.0 \
  -profile http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-patient

Bước 4: Tích hợp vào hệ thống

4.1. FHIR Server

Các FHIR server phổ biến hỗ trợ custom IG:

4.2. Cài đặt package

# Sử dụng NPM package (khi đã publish)
npm --registry https://packages.fhir.org install hl7.fhir.vn.core@0.1.0

# Hoặc build từ source
sushi .
# Package tạo tại: fsh-generated/resources/

4.3. Tích hợp HIS/EMR

  ┌─────────────┐         ┌──────────────┐         ┌─────────────┐
  │   HIS/EMR   │  JSON   │  FHIR Server │  FHIR   │  Bên nhận   │
  │  (nội bộ)   │────────▶│  + VN Core   │────────▶│  (BHXH,     │
  │             │         │  profiles    │         │   Sở Y tế,  │
  │  DB nội bộ  │         │  validation  │         │   VNeID)    │
  └─────────────┘         └──────────────┘         └─────────────┘
       │                         │
       │  Mapping layer          │  CapabilityStatement
       │  (HIS fields → FHIR)   │  (VNCoreServer)
       ▼                         ▼
  - Mã BN → Patient.identifier   - 20 resource types
  - Mã CCCD → identifier[CCCD]   - Search parameters
  - Mã BHYT → identifier[BHYT]   - SMART-on-FHIR auth
  - Họ tên → name.text/family/given
  - ICD-10 → Condition.code

4.4. Checklist tích hợp

• Cài FHIR server và upload VN Core package
• Map dữ liệu HIS nội bộ sang FHIR resources theo VN Core profiles
• Validate mẫu dữ liệu với FHIR Validator + VN Core IG
• Kiểm tra identifier: CCCD (12 số), BHYT (3 format), CSKCB (5 số)
• Kiểm tra coded fields: ICD-10 VN, LOINC VN, SNOMED CT VN
• Kiểm tra address: tỉnh (34 đơn vị NQ 202/2025), xã/phường
• Kiểm tra extensions: dân tộc, tôn giáo, nghề nghiệp (nếu có dữ liệu)
• Test end-to-end: tạo Patient → Encounter → Condition → phản hồi đúng

Tài nguyên hỗ trợ

English Summary

This Getting Started guide provides a 4-step path to using VN Core FHIR IG: (1) Understand the architecture — 23 profiles, 20 extensions, 42 CodeSystems, 43 ValueSets covering Vietnamese healthcare; (2) Install prerequisites (Node.js, SUSHI, Java) and compile the IG; (3) Create your first FHIR resource using VN Core profiles with Vietnamese-specific identifiers (CCCD, BHYT), address structure (province + ward per NQ 202/2025), and extensions (ethnicity, religion); (4) Integrate with your HIS/EMR by deploying a FHIR server with VN Core package, mapping internal data to FHIR resources, and validating against VN Core profiles. The guide includes a complete JSON example for a Vietnamese patient and an integration checklist.