Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.6.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à kiểm tra hợp lệ tài nguyên đầ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 gói.

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

Repo công khai sẽ được công bố sau khi quản trị và kênh đóng góp được chốt. Trong giai đoạn thí điểm, nhóm triển khai nhận gói nguồn trực tiếp từ Omi HealthTech hoặc qua kênh rà soát được chỉ định.

# 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 tài nguyên đầ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": "Nguyễn Văn An",
    "family": "Nguyễn",
    "given": ["Văn", "An"]
  }],
  "gender": "male",
  "birthDate": "1990-05-15",
  "address": [{
    "use": "home",
    "text": "123 Nguyễn Huệ, Phường Ngọc Hà, Hà Nội",
    "state": "Hà Nội",
    "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": "Thành phố Hà Nội"
        }
      },
      {
        "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": "Phường Ngọc Hà"
        }
      }
    ]
  }],
  "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"
        }]
      }
    }
  ]
}

Kiểm tra hợp lệ tài nguyên

# 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 gói

# Build từ source (khuyến nghị cho phiên bản công bố hiện hành 0.6.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.6.0)
# npm --registry https://packages.fhir.org install [email protected]

Checklist tích hợp

• Cài FHIR server và tải VN Core package lên
• Chốt gói tổng hợp hay gói mô-đun (core.base, bhyt.submission, terminology.clinical, terminology.traditional-medicine)
• Ánh xạ dữ liệu HIS nội bộ sang tài nguyên FHIR theo hồ sơ VN Core
• Kiểm tra hợp lệ 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 định danh: CCCD (12 số), BHYT (3 định dạng), CSKCB (5 số)
• Kiểm tra các trường mã hóa: ICD-10 VN, LOINC VN, SNOMED CT VN
• Kiểm tra địa chỉ: tỉnh (34 đơn vị NQ 202/2025/QH15), xã/phường
• Kiểm tra phần mở rộng: dân tộc, tôn giáo, nghề nghiệp (nếu có dữ liệu)
• Kiểm thử đầu cuối: 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.

Xử lý lỗi bước đầu

Nếu lỗi không có trong bảng trên, xem Hướng dẫn kiểm tra hợp lệ hoặc liên hệ [email protected].

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.