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

## Hướng dẫn chung

# Hướng dẫn chung — General Guidance

Các quy tắc nền dưới đây áp dụng chung cho VN Core: cách biểu diễn tên, địa chỉ, định danh, pattern datatype và ranh giới giữa guidance chung với các trang chuyên đề.

## Baseline quốc tế trước, Việt hóa sau

VN Core hiện tại đi theo nguyên tắc: **dùng baseline quốc tế trước, rồi chỉ Việt hóa ở nơi thật sự cần**.

* Với resource và datatype, ưu tiên FHIR R4, `IPS` và extension chuẩn của HL7 nếu đã diễn đạt đúng ngữ nghĩa.
* Chỉ localize khi Việt Nam có khác biệt thật về pháp lý, workflow, định danh, địa chỉ hành chính hoặc bộ mã vận hành.
* Nếu một khác biệt chỉ là cách hiển thị, cách search hoặc cách mapping gateway, nên giải quyết ở guidance hoặc lớp triển khai trước khi tạo thêm profile/extension.

## Pattern dùng lại xuyên suốt nhiều hồ sơ

Không để mỗi profile tự định nghĩa lại một pattern cho cùng một datatype. Các pattern dùng lại được giữ ở narrative pages và governance thay vì lặp lại trong từng profile:

| | | |
| :--- | :--- | :--- |
| `Identifier` | Chốt trạng thái hiện hành/lịch sử/ngừng dùng,`system URI`, search và precedence | [Danh mục định danh](identifier-registry.md),[Ánh xạ URI/OID](identifier-registry.md#ánh-xạ-uri-và-oid) |
| `Address` | Chốt mô hình 2 cấp mới, dữ liệu legacy cấp huyện và quy tắc địa chỉ Việt Nam | Trang này,[Kiểm tra hợp lệ](validation-guidance.md) |
| `Coding`/`CodeableConcept` | Chốt cách kết hợp mã quốc tế, mã Việt Nam,`text`,`display`, translation | [Hướng dẫn thuật ngữ](terminology-guidance.md) |
| `Dosage` | Chốt đường hướng reusable semantics cho medication workflow, không lặp tùy tiện ở từng profile | [Hồ sơ](profiles.md),[Hướng dẫn thuật ngữ](terminology-guidance.md) |

-------

## Must Support (MS)

Chi tiết cách diễn giải và cẩm nang HIS -> FHIR đã được tách sang trang riêng: [Hướng dẫn Must Support](must-support-guidance.md).

### Định nghĩa

Trong VN Core IG, khi một element được đánh dấu **Must Support** (MS), nghĩa là:

* **Hệ thống gửi (Sender)**: Nếu có dữ liệu cho element đó, **PHẢI** gửi kèm trong resource
* **Hệ thống nhận (Receiver)**: **PHẢI** có khả năng xử lý và lưu trữ dữ liệu của element đó mà không gây lỗi

Must Support **KHÔNG** có nghĩa là element đó bắt buộc phải có giá trị (required). Một element có thể vừa MS vừa `0..1` — nghĩa là không bắt buộc có, nhưng nếu có thì phải hỗ trợ.

### Ví dụ — Must Support

| | | | |
| :--- | :--- | :--- | :--- |
| `Patient.identifier[CCCD]` | 1..1 | MS | Slice CCCD là bắt buộc; nếu chưa có giá trị thực tế thì dùng`data-absent-reason`và lý do bất khả kháng hợp lệ |
| `Patient.name` | 1..* | MS | Bắt buộc có và phải hỗ trợ |
| `Patient.birthDate` | 0..1 | MS | Không bắt buộc, nhưng hệ thống phải xử lý được |

### Xử lý khi thiếu dữ liệu

Khi element MS không có giá trị, hệ thống nên:

* Sử dụng Data Absent Reason extension (`http://hl7.org/fhir/StructureDefinition/data-absent-reason`) nếu cần giải thích lý do thiếu
* Không tạo element rỗng (empty element) — bỏ qua hoàn toàn

-------

## Tên tiếng Việt trong FHIR

### Cấu trúc HumanName

Tên tiếng Việt có cấu trúc: **Họ + Tên đệm + Tên gọi**. Ánh xạ sang FHIR:

| | | |
| :--- | :--- | :--- |
| Họ | `HumanName.family` | "Nguyễn" |
| Tên đệm + Tên gọi | `HumanName.given`(mảng) | ["Văn", "An"] |
| Họ tên đầy đủ | `HumanName.text` | "Nguyễn Văn An" |

### Quy tắc

1. **`text` luôn bắt buộc**— chứa họ tên đầy đủ theo thứ tự Việt Nam (Họ trước, Tên sau)
1. **`family`**= Họ (phần đầu tiên)
1. **`given`**= mảng chứa tên đệm và tên gọi, theo đúng thứ tự
1. **Dấu tiếng Việt**: PHẢI giữ nguyên dấu Unicode (UTF-8). Không bỏ dấu, không chuyển ASCII
1. **`use`**=`official`cho tên chính thức trên CCCD/giấy tờ

### Ví dụ — Tên

```
{
  "name": [{
    "use": "official",
    "text": "Nguyễn Văn An",
    "family": "Nguyễn",
    "given": ["Văn", "An"]
  }]
}

```

### Trường hợp đặc biệt

* **Tên 2 chữ** (không có đệm): `given` chỉ có 1 phần tử. Ví dụ: Bảo Đại → `family: "Bảo"`, `given: ["Đại"]`
* **Họ kép**: `family` chứa toàn bộ họ kép. Ví dụ: "Tôn Thất" → `family: "Tôn Thất"`
* **Người nước ngoài**: Dùng tên theo hộ chiếu, `use: "official"`

-------

## Địa chỉ Việt Nam

### Cấu trúc VNCoreAddress

Địa chỉ Việt Nam sau NQ 202/2025 có **2 cấp chính** (tỉnh + xã), nhưng VN Core vẫn hỗ trợ tương thích ngược:

| | | | |
| :--- | :--- | :--- | :--- |
| Tỉnh/TP | Extension`vn-ext-province` | `VNProvinceCS`(34 mã) | **Bắt buộc**cho địa chỉ VN |
| Huyện/Quận | `Address.district` | `VNDistrictCS` | Đã ngừng dùng trong mô hình mới, nhưng vẫn hỗ trợ dữ liệu cũ |
| Xã/Phường | Extension`vn-ext-ward` | `VNWardCS` | Cấp 2 chính thức |
| Số nhà, đường | `Address.line` | — | Text tự do |
| Quốc gia | `Address.country` | ISO 3166 | "VN" |

### Tương thích ngược

* Hệ thống CŨ (trước 01/7/2025) có thể vẫn gửi mã huyện theo danh mục 63 tỉnh
* Hệ thống NHẬN nên chấp nhận cả mã cũ và mới
* `VNDistrictCS` giữ lại mã huyện cũ với `status = inactive` để hỗ trợ dữ liệu lịch sử

-------

## Hệ thống định danh (Identifier)

Để tra cứu tập trung các `NamingSystem`, xem thêm [Danh mục định danh](identifier-registry.md). Để bắc cầu với `OID` hoặc hệ thống cũ, xem [Ánh xạ URI/OID](identifier-registry.md#ánh-xạ-uri-và-oid).

### Thứ tự ưu tiên

| | | | |
| :--- | :--- | :--- | :--- |
| Số CCCD | `$VN-CCCD` | **Cao nhất** | 12 chữ số, trục định danh chính |
| Mã số BHXH | — | Cao | 10 chữ số, liên thông BHXH |
| Số thẻ BHYT | `$VN-BHYT` | Cao | 12 số (CCCD) / 10 số (BHXH) / 15 ký tự (cũ) |
| GPHN | `$VN-GPHN` | Trung bình | Định danh hành nghề hiện hành cho người hành nghề |
| CCHN | `$VN-CCHN` | Lịch sử | Chỉ giữ để chuyển đổi và tra cứu dữ liệu đã lập theo khung cũ |
| Mã CSKCB | `$VN-CSKCB` | Trung bình | Dùng cho cơ sở y tế |
| MRN | `$VN-MRN` | Bệnh viện | Mã bệnh nhân nội bộ |
| `XML1_ID`/ mã phản hồi gateway BHYT | `$VN-BHYT-GATEWAY-RESPONSE-ID` | Lớp BHYT Submission | Dùng cho`ClaimResponse.identifier`, không thay thế`MA_LK` |

**`CCCD`**: CCCD là định danh cá nhân lõi cho công dân Việt Nam trong VN Core.
 **`VNeID`**: VNeID là tài khoản định danh điện tử và kênh truy cập của ứng dụng người dân; chỉ nên dùng ở lớp ứng dụng người dân, xác thực hoặc tích hợp, không dùng song song với CCCD như một định danh người bệnh chính.

### Khi chưa có CCCD

VN Core vẫn giữ `identifier[CCCD]` là lát cắt định danh chính. Tuy nhiên, khi chưa có giá trị CCCD thực tế, cần tách ba tình huống:

| | |
| :--- | :--- |
| Ca cấp cứu / bất khả kháng / chưa xác định được danh tính | Giữ slice`identifier[CCCD]`với`data-absent-reason`và khai`forceMajeureReason`hợp lệ |
| Trẻ sơ sinh / trẻ nhỏ chưa có CCCD nhưng đã có giấy khai sinh | Giữ slice`identifier[CCCD]`với`data-absent-reason`; bổ sung`identifier[GKS]` |
| Người nước ngoài hoặc người bệnh dùng định danh thay thế hợp lệ | Giữ slice`identifier[CCCD]`với`data-absent-reason`; bổ sung`identifier[HC]`và`citizenship`phù hợp |

Không nên dùng `forceMajeureReason` để mô tả người bệnh có định danh thay thế hợp lệ như hộ chiếu hoặc giấy khai sinh.

### Cấu trúc CCCD

Số CCCD 12 chữ số mã hóa thông tin:

* Vị trí 1-3: Mã prefix nơi đăng ký khai sinh theo danh mục BCA
* Vị trí 4: Giới tính + thế kỷ sinh (0=Nam/19xx, 1=Nữ/19xx, 2=Nam/20xx, 3=Nữ/20xx)
* Vị trí 5-6: 2 chữ số cuối năm sinh
* Vị trí 7-12: Số ngẫu nhiên

`Mã prefix BCA` này là terminology hỗ trợ validation cho CCCD đã cấp và **không** thay thế cho `VNProvinceCS` dùng trong địa chỉ hành chính hiện hành.

Chi tiết kiểm tra hợp lệ: xem [Hướng dẫn kiểm tra hợp lệ](validation-guidance.md)

### Tìm kiếm và so khớp định danh

* Với CCCD, BHYT, BHXH, GPHN, CCHN, `MA_LK`, `MA_LUOT_KCB` và mã phản hồi gateway BHYT, nên coi tìm kiếm là truy vấn nghiệp vụ chính xác theo kiểu `token` khi hệ thống công bố search tương ứng.
* Không nên biến tìm kiếm theo định danh thành tìm kiếm mờ theo văn bản tự do.
* Các hành vi normalize như bỏ khoảng trắng hoặc chuẩn hóa dấu gạch nối chỉ nên là hành vi nội bộ và cần công bố rõ nếu có.

Chi tiết xem [Hành vi tìm kiếm](search-behavior.md).

-------

## Organization và Location

### Không trộn 4 khái niệm khác nhau

Khi triển khai `Organization` và `Location`, VN Core tách riêng:

| | | |
| :--- | :--- | :--- |
| Hạng pháp lý của cơ sở KCB | `vn-ext-org-rank` | Chỉ cho cơ sở KCB theo TT 06/2024 |
| Hạng pháp lý của đơn vị y tế không phải cơ sở KCB | `vn-ext-health-unit-rank` | Cho y tế dự phòng, TTYT, kiểm nghiệm, kiểm định |
| Cấp KCB hiện hành | `vn-ext-facility-care-level` | 3 cấp theo Luật KCB 2023 + NĐ 96/2023 |
| Tuyến chuyên môn kỹ thuật lịch sử | `vn-ext-legacy-technical-line` | Chỉ dùng cho dữ liệu cũ / chuyển đổi |

`vn-ext-org-level` chỉ biểu diễn **cấp quản lý hành chính y tế hiện hành**, không thay cho tuyến kỹ thuật cũ.

### Khuyến nghị điền dữ liệu

* Bệnh viện/phòng khám: ưu tiên `organizationType`, `organizationLevel`, `facilityCareLevel`; chỉ điền `organizationRank` khi có căn cứ pháp lý rõ.
* Trạm y tế: thường không có hạng pháp lý, nên dùng `organizationRankStatus = not-applicable` nếu cần diễn đạt rõ.
* CDC/đơn vị dự phòng/kiểm nghiệm: dùng `healthUnitRank`, không dùng `organizationRank`.
* `Location` không mang hạng pháp lý; chỉ nên mang `facilityCareLevel` khi địa điểm được quản trị như một phân hệ chuyên môn riêng.

Chi tiết: xem [Quản trị Organization và Location](organization-location-governance.md).

-------

## Mức độ ràng buộc (Binding Strength)

VN Core IG sử dụng các mức binding theo FHIR:

| | | |
| :--- | :--- | :--- |
| **Required** | PHẢI dùng đúng code trong ValueSet | `VNEthnicityVS`(54 dân tộc) |
| **Extensible** | NÊN dùng code trong ValueSet, cho phép bổ sung nếu không tìm thấy | `VNConditionCodeVS`(ICD-10 VN) |
| **Preferred** | KHUYÊN dùng, nhưng chấp nhận code khác | — |
| **Example** | Chỉ mang tính minh họa | — |

-------

## Quy ước URL

| | | |
| :--- | :--- | :--- |
| Hồ sơ (Profile) | `http://fhir.hl7.org.vn/core/StructureDefinition/{id}` | `.../vn-core-patient` |
| Phần mở rộng (Extension) | `http://fhir.hl7.org.vn/core/StructureDefinition/{id}` | `.../vn-ext-ethnicity` |
| CodeSystem | `http://fhir.hl7.org.vn/core/CodeSystem/{id}` | `.../vn-ethnicity-cs` |
| ValueSet | `http://fhir.hl7.org.vn/core/ValueSet/{id}` | `.../vn-ethnicity-vs` |
| NamingSystem | `http://fhir.hl7.org.vn/core/NamingSystem/{id}` | `.../vn-cccd-ns` |

-------

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

| | |
| :--- | :--- |
| Hiểu quy tắc tìm kiếm chuỗi có dấu tiếng Việt và chuẩn hóa Unicode | [Tìm kiếm chuỗi và Unicode](string-search-guidance.md) |
| Nắm hành vi tìm kiếm của FHIR server và cách so khớp định danh | [Hành vi tìm kiếm](search-behavior.md) |
| Tra cứu tập trung các NamingSystem và ánh xạ URI/OID | [Danh mục định danh](identifier-registry.md) |
| Diễn giải Must Support và cẩm nang ánh xạ HIS → FHIR | [Hướng dẫn Must Support](must-support-guidance.md) |
| Quy trình phát hành, versioning và quản trị IG | [Phát hành và quản trị](release-governance.md) |

-------

## English Summary

This page defines the general reusable rules for VN Core. It covers Vietnamese names, address modeling, identifier precedence, Organization/Location separation, and binding basics that apply across multiple profiles. Detailed Must Support interpretation is documented on its own page.

