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

## Trang chủ

# Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam — VN Core FHIR Implementation Guide

VN Core là bộ Hướng dẫn Triển khai HL7 FHIR R4 cốt lõi cho liên thông dữ liệu y tế tại Việt Nam — phiên bản hiện hành `v0.5.0`.

> Đây là bản **Draft for Community Review** do Omi HealthTech xây dựng. Phiên bản này chưa được cơ quan nhà nước phê duyệt chính thức. Cộng đồng y tế số Việt Nam được khuyến khích sử dụng thử nghiệm và gửi phản hồi qua [info@hl7.org.vn](mailto:info@hl7.org.vn).

-------

## Phạm vi

VN Core FHIR Implementation Guide (IG) xác định lớp `Profiles`, `Extensions`, `CodeSystems`, `ValueSets`, `NamingSystems`, `SearchParameters`, `CapabilityStatements` và guidance cốt lõi cho việc trao đổi dữ liệu y tế tại Việt Nam theo [HL7 FHIR R4 (4.0.1)](https://hl7.org/fhir/R4/).

Phiên bản hiện hành được tổ chức theo nguyên tắc:

* giữ `VN Core Base` là lõi FHIR ổn định cho liên thông dùng chung
* tách `BHYT Submission` thành lớp riêng cho liên thông hồ sơ thanh toán
* tách các gói thuật ngữ lớn khỏi lõi để giảm thay đổi phá vỡ tương thích
* công bố guidance riêng cho `Must Support`, search, identifier, legal basis, security và conformance theo actor

## Quy mô phiên bản hiện hành

| | | |
| :--- | :--- | :--- |
| `Profiles` | 52 | Bao gồm các profile lâm sàng, hành chính, tài chính, tài liệu và quản trị |
| `Extensions` | 44 cục bộ + 3 chuẩn HL7 | Ưu tiên tái sử dụng extension chuẩn của HL7 cho Patient |
| `CodeSystems` | 70 | Bao gồm các bộ mã nền tảng, BHYT, nghề nghiệp, địa chỉ và hỗ trợ validation |
| `ValueSets` | 75 | Đi cùng các CodeSystem đang dùng trong IG |
| `NamingSystems` | 22 | Bao gồm CCCD, BHYT, BHXH, GKS, GPHN, CCHN, CSKCB,`MA_LK`,`MA_LUOT_KCB` |
| `SearchParameters` | 19 | Bao gồm các tham số nghiệp vụ hiện hành;`VNeID`chỉ còn là artifact lịch sử`retired` |
| `CapabilityStatements` | 5 | 1 mức cơ sở + 4 theo từng vai trò triển khai |
| `OperationDefinitions` | 3 | `$validate-bhyt-claim`,`$submit-bhyt-claim`,`$reverse-bhyt-claim` |
| `Examples` | 152 tệp / 154 thực thể | Bao gồm positive và negative fixtures cho lớp`BHYT Submission` |

## Mô hình package

| | | |
| :--- | :--- | :--- |
| `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 |

Chi tiết xem tại [Kiến trúc gói phát hành](package-architecture.md).

## Các quyết định nền tảng

* `CCCD` là primary citizen identifier; `VNeID` chỉ được giữ ở lớp ứng dụng người dân hoặc integration/authentication layer.
* `VN Core Base` và `BHYT Submission` phải được tách ranh giới để semantic cốt lõi không bị chi phối bởi logic gửi nhận hồ sơ thanh toán.
* `NamingSystems`, `CodeSystems` và `ValueSets` được coi là hạ tầng của liên thông, không phải phần phụ lục.
* Guidance theo actor, security baseline và release governance là một phần của conformance, không phải tài liệu ngoài lề.

## Bắt đầu từ đâu

| | |
| :--- | :--- |
| Cài thử, build cục bộ và tạo resource đầu tiên | [Bắt đầu nhanh](getting-started.md) |
| Xác định package, vai trò triển khai và mức yêu cầu tối thiểu | [Tuân thủ theo vai trò triển khai](conformance-by-actor.md) |
| Chốt định danh,`system URI`, trạng thái hiện hành/lịch sử/ngừng dùng | [Danh mục định danh](identifier-registry.md) |
| Chốt quy tắc triển khai chung cho tên, địa chỉ, định danh, Organization/Location | [Hướng dẫn chung](general-guidance.md) |
| Chốt hành vi search và validation | [Hành vi tìm kiếm](search-behavior.md),[Hướng dẫn kiểm tra hợp lệ](validation-guidance.md) |
| Tra cứu căn cứ pháp lý và security baseline | [Cơ sở pháp lý](legal-basis.md),[Bảo mật và quyền riêng tư](security.md) |

## Bản đồ nội dung

| | |
| :--- | :--- |
| [Bắt đầu nhanh](getting-started.md) | Quy trình cài thử, build và validate đầu tiên |
| [Kiến trúc gói phát hành](package-architecture.md) | Ranh giới của 5 package và cách tiêu thụ |
| [Tuân thủ theo vai trò triển khai](conformance-by-actor.md) | Ma trận actor, package và`CapabilityStatements` |
| [Hướng dẫn chung](general-guidance.md) | Quy tắc chung cho name, address, identifier, Organization/Location |
| [Danh mục định danh](identifier-registry.md) | Registry thực dụng của các`NamingSystems` |
| [Hướng dẫn thuật ngữ](terminology-guidance.md) | Cách dùng`CodeSystems`,`ValueSets`và package thuật ngữ |
| [Bảo mật và quyền riêng tư](security.md) | Legal baseline và technical baseline cho dữ liệu nhạy cảm |
| [Ổn định và tuân thủ](stability-and-conformance.md) | Maturity model, conformance model và package stability |
| [Phát hành và quản trị](release-governance.md) | Ngưỡng phát hành và policy`hiện hành / lịch sử / ngừng dùng` |
| [Tải xuống](downloads.md) | Gói phát hành và các bộ định nghĩa |
| [Lịch sử thay đổi](changelog.md) | Delta theo từng phiên bản |

## Trạng thái phát hành

**Ưu tiên trước thí điểm**: Trước giai đoạn thí điểm, VN Core ưu tiên quản trị dữ liệu, định danh theo CCCD, EMR/HSSK, Đồng bộ BHYT, lớp ứng dụng người dân và tích hợp, LGSP/API facade và nền tảng an toàn trước khi mở rộng thêm phạm vi tài nguyên.

| | | |
| :--- | :--- | :--- |
| `v0.3.0` | Lịch sử | Bản công bố công khai trước Wave 2, dùng làm baseline thí điểm |
| `v0.4.0` | Lịch sử | Wave 2 (2026-04-14): bổ sung CĐHA/Dược/Khoa phòng, device group và cập nhật terminology nền |
| `v0.5.0` | Hiện hành | Structured legal reference framework (`VNLegalDocumentRefCS`101 văn bản), hardening device cluster, future-effective marker, audit tooling; 52 profiles, 70 CodeSystems, 75 ValueSets, 5 ConceptMaps |
| `v0.6.0` | Dự kiến (Q1/2027) | Phủ EMR toàn quốc theo TT 13/2025 (deadline 31/12/2026); SNOMED CT VN Đợt 3 (QĐ 2805 Allergy + Finding); YHCT mapping đầy đủ (QĐ 2552 + QĐ 3080) |
| `v1.0.0` | Mục tiêu (Q3/2027) | Phiên bản ổn định sau pilot: implementation reports từ ≥5 CSKCB, conformance testing đầy đủ, ConceptMap XML đầu ra KCB (QĐ 3176/QĐ-BYT, 12 loại XML1-XML12) ↔ FHIR hoàn chỉnh; sẵn sàng hồ sơ HL7 Affiliate Việt Nam |

Chi tiết lịch sử thay đổi xem tại [Lịch sử thay đổi](changelog.md) và [Phát hành và quản trị](release-governance.md).

-------

## Governance và đóng góp

VN Core được xây dựng và duy trì bởi **Omi HealthTech** (OmiGroup). Nội dung được công bố dưới giấy phép `CC-BY-4.0`.

Phiên bản `0.5.0` (Draft for Community Review, 2026-05-01) là bản hiện hành, tập trung vào structured legal references, device cluster hardening và audit tooling cho căn cứ pháp lý 2025-2026.

### Contribution protocol

| | |
| :--- | :--- |
| [info@hl7.org.vn](mailto:info@hl7.org.vn) | Góp ý nội dung, phản biện pháp lý, đề xuất phạm vi |
| Repo public, issue và pull request | Sẽ công bố sau khi governance và kênh đóng góp được chốt |

Review từ bệnh viện, nhà cung cấp HIS/EMR/LIS, chuyên gia y tế, reviewer pháp lý và nhóm QA là đầu vào chính cho các vòng chỉnh sửa tiếp theo.

-------

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

| | |
| :--- | :--- |
| Bắt đầu cài đặt và chạy thử resource đầu tiên | [Bắt đầu nhanh](getting-started.md) |
| Hiểu kiến trúc 5 gói mô-đun và 1 gói tổng hợp | [Kiến trúc gói phát hành](package-architecture.md) |
| Xác định vai trò triển khai và CapabilityStatement | [Tuân thủ theo vai trò](conformance-by-actor.md) |
| Tra cứu hồ sơ, phần mở rộng, thuật ngữ và định danh | [Hồ sơ](profiles.md),[Phần mở rộng](extensions.md),[Thuật ngữ](terminology.md),[Định danh](identifier-registry.md) |
| Tra cứu căn cứ pháp lý và baseline bảo mật | [Cơ sở pháp lý](legal-basis.md),[Bảo mật và quyền riêng tư](security.md) |

-------

## English Summary

This page is the canonical entry point for VN Core. It summarizes the current release scope, package structure, artifact counts, governance, contribution channels, and the guidance pages implementers should read next. The `0.5.0` release (Draft for Community Review, 2026-05-01) adds structured legal references, device cluster hardening, future-effective markers, and audit tooling for 2025-2026 regulations. VN Core is built and maintained by Omi HealthTech (OmiGroup) under CC-BY-4.0; the public site `hl7.org.vn` provides project context.

