Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.4.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

4 bước để cài thử VN Core, build cục bộ và validate resource đầu tiên.

Quy mô phiên bản hiện hành xem tại Trang chủ.

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

Kiến trúc tổng quan

Sơ đồ này nhấn mạnh 3 điểm: VN Core được biên soạn từ một workspace thống nhất, artifact được tách rõ giữa profiles/extensions/terminology/examples, và các gói phát hành đi ra nhiều lớp triển khai khác nhau thay vì ép mọi nhu cầu vào cùng một package.

Thành phần chính

Khi triển khai thật, 3 lớp hướng dẫn bắt buộc phải đọc:

• Định danh: Danh mục định danh + Ánh xạ URI/OID
• Tìm kiếm: Tìm kiếm chuỗi và Unicode + Hành vi tìm kiếm
• Tuân thủ: Hướng dẫn Must Support + Phát hành và quản trị

Gói cài đặt triển khai

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

Yêu cầu hệ thống

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

# Repo cố định major version của Node tại đây
cat .nvmrc

# Cài Jekyll (cần cho IG Publisher full build)
# macOS/Homebrew Ruby được khuyến nghị để tránh dùng system Ruby 2.6
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
gem install jekyll bundler --no-document
export PATH="$(/opt/homebrew/opt/ruby/bin/gem env gemdir)/bin:$PATH"
jekyll --version

# Biên dịch FSH → JSON
./scripts/validate.sh --quick
# Kết quả dự kiến: build sạch, 0 lỗi, 0 cảnh báo

# Sinh các gói phát hành
python3 scripts/build-split-packages.py

./scripts/validate.sh --quick sẽ tự sinh lại các tài nguyên JSON thuật ngữ lớn trong input/resources/ trước khi gọi SUSHI. Nếu chỉ chạy sushi . trực tiếp, cần bảo đảm các tài nguyên này đã được cập nhật từ dữ liệu nguồn.

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

_genonce.sh sẽ tự dò jekyll trong Homebrew Ruby gem bin nếu executable chưa có sẵn trong PATH.

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

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"
        }]
      }
    }
  ]
}

Validate resource

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

# Tạo local package snapshot (nếu chưa có)
bash _genonce.sh

# Validate bằng local package snapshot
java -jar validator_cli.jar patient.json \
  -ig output/package.tgz \
  -profile http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-patient

# Chạy thêm Tier 2 executable checks của repo
./scripts/validate-tier2.sh
./scripts/validate-security-baseline.sh
./scripts/validate-bhyt-roundtrip.sh
./scripts/validate-terminology-governance.sh

# Mở báo cáo coverage round-trip BHYT
open output/bhyt-roundtrip/index.html

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

Cài đặt package

# Build từ source (khuyến nghị cho phiên bản công bố hiện hành 0.4.0)
./scripts/validate.sh --quick

# Sinh các gói phát hành
python3 scripts/build-split-packages.py

# Sử dụng NPM package (khi đã publish lên registry — chưa áp dụng cho 0.4.0)
# npm --registry https://packages.fhir.org install hl7.fhir.vn.core@0.4.0

Checklist tích hợp

• Cài FHIR server và upload VN Core package
• Chốt gói tổng hợp hay gói mô-đun (core.base, bhyt.submission, terminology.clinical, terminology.traditional-medicine)
• 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
• Chạy validate-tier2.sh, validate-security-baseline.sh, validate-bhyt-roundtrip.sh, validate-terminology-governance.sh
• 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

Hướng dẫn tích hợp theo vai trò cụ thể xem Tuân thủ theo vai trò triển khai.

Troubleshooting bước đầu

Nếu lỗi không có trong bảng trên, xem Hướng dẫn Validation hoặc liên hệ info@hl7.org.vn.

Tài nguyên hỗ trợ

Liên hệ với các trang khác

English Summary

This page is the procedural quickstart for VN Core. It covers prerequisites, local build, a first validation flow, and the next canonical pages to read before deeper implementation. Actor-specific conformance, package boundary, security baseline, and BHYT gateway guidance are documented separately.