Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.10.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

Muốn chạy thử ngay trên máy mình? Repo có starter-kit/ (wiki quản trị dự án) — FHIR server bằng Docker, nạp gói theo đúng thứ tự phụ thuộc, 5 giao dịch mẫu và bảng "vai nào đọc kế hoạch kiểm thử nào" (10 phút).

Đang nâng cấp từ bản cũ? Xem Hướng dẫn di trú 0.7.0 → 0.10.0 — bảng đổi field-level cho ICD-10 edition 2026, trục Invoice và obligation theo actor.

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.

# Dùng runtime contributor/CI trong .nvmrc (ví dụ với nvm)
nvm use

# Cài bộ công cụ repo-local đúng lockfile
npm ci --prefix .github/tooling

# 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 bằng entrypoint chuẩn và PATH đã khoá
env PATH="$PWD/.github/tooling/node_modules/.bin:$PATH" make sushi
# Kết quả bắt buộc: SUSHI 0 lỗi; cảnh báo được phân loại trong hồ sơ QA

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

make sushi dùng SUSHI repo-local và áp lại grouping sau biên dịch. Khi thay nguồn terminology hoặc văn bản, làm theo chuỗi make regen-full của SOP; không gọi SUSHI trực tiếp và không sửa tay tài nguyên sinh trong input/resources/.

Build IG đầy đủ (tuỳ chọn)

# Chuẩn bị input-cache/publisher.jar đúng version; đối chiếu SHA-256 với
# binaries.igPublisherJar.sha256 trong governance/toolchain-pins.json
shasum -a 256 input-cache/publisher.jar

# Build phát triển (runtime contributor trong .nvmrc) → output/; không tạo hồ sơ phát hành
env PATH="$PWD/.github/tooling/node_modules/.bin:$PATH" \
  IG_PUBLISHER_TX=na bash scripts/build-ig.sh

# Chỉ maintainer chạy sau chuỗi txgw SOP §5.5 và lệnh phát hành tường minh, dưới đúng
# runtime release đã pin (Node/Java major trong tools của governance/toolchain-pins.json)
python3 scripts/validate-toolchain-pins.py
env PATH="$PWD/.github/tooling/node_modules/.bin:$PATH" \
  IG_PUBLISHER_TX=http://localhost:8090/fhir bash scripts/release-pipeline.sh

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

scripts/build-ig.sh là entrypoint phát triển và tự dò jekyll trong Homebrew Ruby gem bin khi cần. Bản phát hành chỉ đi qua scripts/release-pipeline.sh: pipeline phân loại QA, rồi maintainer commit tệp sinh, tạo evidence trên cây sạch, chạy validate-release-evidence.py --strict và commit evidence-only. Không biên dịch hoặc regen sau mốc evidence cuối.

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": "001090012345"
    },
    {
      "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": "0179012345"
    }
  ],
  "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

# Chuẩn bị .validator/validator_cli.jar đúng version; đối chiếu SHA-256 với
# binaries.fhirValidatorJar.sha256 trong governance/toolchain-pins.json
shasum -a 256 .validator/validator_cli.jar

# Tạo local package snapshot (nếu chưa có)
env PATH="$PWD/.github/tooling/node_modules/.bin:$PATH" \
  IG_PUBLISHER_TX=na bash scripts/build-ig.sh

# Validate bằng local package snapshot
java -jar .validator/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 hiện hành 0.10.0)
env PATH="$PWD/.github/tooling/node_modules/.bin:$PATH" make sushi

# 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.10.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 (hl7.fhir.vn.core) hay một trong 8 gói mô-đun: core.base, legal, terminology.clinical, terminology.traditional-medicine, pharmacy, bhyt.submission, patient-access, device
• Á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 chữ số), BHYT (10 chữ số hiện hành hoặc 15 ký tự lịch sử), CSKCB (5 chữ số)
• Kiểm tra các trường mã hoá: 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 quickstart covers prerequisites, local build, first validation, and next guidance. Install repository-local SUSHI from .github/tooling; run it through the pinned PATH with make sushi. Use scripts/build-ig.sh with explicit IG_PUBLISHER_TX=na for development. Release only after SOP §5.5, explicit authorization, and scripts/release-pipeline.sh; pinned jars and clean-tree strict evidence are required.