# Bắt đầu nhanh - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## 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ủ](index.md#quy-mô-phiên-bản-hiện-hành).

-------

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

### Kiến trúc tổng quan

![](getting-started-architecture-overview.svg)

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

| | | |
| :--- | :--- | :--- |
| **Hồ sơ** | Định nghĩa cấu trúc resource phù hợp Việt Nam | VNCorePatient: CCCD, tên tiếng Việt, dân tộc |
| **Phần mở rộng** | Thêm phần tử dữ liệu đặc thù Việt Nam | `vn-ext-ethnicity`: 54 dân tộc |
| **CodeSystems** | Bộ mã chuẩn hóa | VNEthnicityCS: mã 01=Kinh, 02=Tày… |
| **ValueSets** | Tập giá trị cho phép | VNEthnicityVS: bind từ VNEthnicityCS |
| **NamingSystems** | Định danh identifier | VN-CCCD:`http://fhir.hl7.org.vn/core/sid/cccd` |
| **Examples** | Dữ liệu mẫu | Bệnh nhân Nguyễn Văn An, BV Chợ Rẫy |

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](identifier-registry.md) + [Ánh xạ URI/OID](identifier-registry.md#ánh-xạ-uri-và-oid)
* Tìm kiếm: [Tìm kiếm chuỗi và Unicode](string-search-guidance.md) + [Hành vi tìm kiếm](search-behavior.md)
* Tuân thủ: [Hướng dẫn Must Support](must-support-guidance.md) + [Phát hành và quản trị](release-governance.md)

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

| | | |
| :--- | :--- | :--- |
| `hl7.fhir.vn.core` | Gói tổng hợp | Kiểm tra cục bộ, đào tạo, thử nghiệm nhanh và cài đặt trọn bộ |
| `hl7.fhir.vn.core.base` | Gói lõi ổn định | EMR, HIE, hồ sơ công dân, dữ liệu dùng chung và liên thông FHIR-native |
| `hl7.fhir.vn.bhyt.submission` | Gói liên thông hồ sơ thanh toán BHYT | Gateway, adapter, kiểm tra và ánh xạ hồ sơ thanh toán; phụ thuộc`hl7.fhir.vn.core.base` |
| `hl7.fhir.vn.terminology.clinical` | Gói thuật ngữ lâm sàng | ICD-10 VN, ICD-9-CM, SNOMED CT VN subset, CLS, LOINC, ConceptMap lâm sàng |
| `hl7.fhir.vn.terminology.traditional-medicine` | Gói thuật ngữ Y học cổ truyền | Toàn bộ bộ mã Y học cổ truyền hiện hành |
| `hl7.fhir.vn.device` | Gói thiết bị y tế | Danh pháp thiết bị,`DeviceDefinition`, regulatory workflow, UDI guidance, kiểm định, asset và procurement khi có use case |

-------

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

### Yêu cầu hệ thống

| | | |
| :--- | :--- | :--- |
| [Node.js](https://nodejs.org/) | 22.x (khuyến nghị) | Chạy SUSHI, khớp với CI |
| [SUSHI](https://fshschool.org/docs/sushi/) | >= 3.x | Biên dịch FSH → JSON |
| [Java JDK](https://adoptium.net/) | >= 17 | Chạy IG Publisher |
| [Ruby](https://www.ruby-lang.org/)+[Jekyll](https://jekyllrb.com/) | Homebrew Ruby >= 3.x | IG Publisher dùng Jekyll để render HTML |

### Clone và biên dịch

Repo public sẽ được công bố sau khi governance và kênh đóng góp được chốt. Trong giai đoạn thí điểm, nhóm triển khai nhận source package trực tiếp từ Omi HealthTech hoặc qua kênh review đượ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 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.5.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.5.0)
# npm --registry https://packages.fhir.org install hl7.fhir.vn.core@0.5.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](conformance-by-actor.md).

-------

## Troubleshooting bước đầu

| | | |
| :--- | :--- | :--- |
| `Unknown code in system`cho CCCD/BHYT | Dùng sai`system`URI — phải dùng`http://fhir.hl7.org.vn/core/sid/cccd` | [Registry định danh](identifier-registry.md) |
| `Profile validation error`trên Patient.name | Tiếng Việt có dấu không đúng encoding (phải là UTF-8 NFC) | [Tìm kiếm chuỗi & Unicode](string-search-guidance.md) |
| `Slice not found`trên Patient.identifier | Thiếu slice cho CCCD hoặc dùng sai discriminator | [Hướng dẫn Must Support](must-support-guidance.md) |
| `Code not found in ValueSet`trên địa chỉ | Mã tỉnh cũ (63 tỉnh) — phải dùng mã 34 tỉnh theo NQ 202/2025 | [Hướng dẫn chung](general-guidance.md) |
| `Coverage.period không hợp lệ` | Ngày hiệu lực BHYT phải theo format FHIR`YYYY-MM-DD`, không phải`DD/MM/YYYY` | [Liên thông hồ sơ BHYT](bhyt-submission.md) |
| Build SUSHI thành công nhưng IG Publisher báo lỗi | Thường là terminologies không resolve — kiểm tra`output/qa.html` | [Hướng dẫn Validation](validation-guidance.md) |

Nếu lỗi không có trong bảng trên, xem [Hướng dẫn Validation](validation-guidance.md) hoặc liên hệ [info@hl7.org.vn](mailto:info@hl7.org.vn).

-------

## Tài nguyên hỗ trợ

| | |
| :--- | :--- |
| **FHIR R4 Specification** | [hl7.org/fhir/R4/](https://hl7.org/fhir/R4/) |
| **FSH School** | [fshschool.org](https://fshschool.org/) |
| **FHIR Validator** | [confluence.hl7.org](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) |
| **SUSHI Documentation** | [fshschool.org/docs/sushi/](https://fshschool.org/docs/sushi/) |
| **VN Core — Liên hệ** | [info@hl7.org.vn](mailto:info@hl7.org.vn) |
| **Hướng dẫn kiểm tra hợp lệ** | [validation-guidance.html](validation-guidance.md) |
| **Tình huống lâm sàng** | [clinical-scenarios.html](clinical-scenarios.md) |

-------

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

| | |
| :--- | :--- |
| Xác định nghĩa vụ tuân thủ theo vai trò (Producer/Consumer/Gateway) | [Tuân thủ theo vai trò](conformance-by-actor.md) |
| Hiểu quy tắc nền chung về tên, địa chỉ, định danh và pattern datatype | [Hướng dẫn chung](general-guidance.md) |
| Tra cứu các NamingSystem và hệ thống định danh y tế Việt Nam | [Danh mục định danh](identifier-registry.md) |
| Diễn giải Must Support và cẩm nang ánh xạ HIS → FHIR | [Must Support](must-support-guidance.md) |
| Nắm hành vi tìm kiếm của FHIR server | [Tìm kiếm](search-behavior.md) |
| Thiết kế kiểm tra hợp lệ 3 tầng cho resource | [Validation](validation-guidance.md) |
| Triển khai liên thông hồ sơ BHYT với Cổng giám định BHXH | [Liên thông BHYT](bhyt-submission.md) |

-------

## 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.

