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

Kiến trúc gói phát hành

Kiến trúc gói phát hành — Package Architecture

VN Core tách thành 9 gói phát hành với ranh giới rõ ràng giữa lõi, các lớp nghiệp vụ có nhịp thay đổi nhanh, thuật ngữ, thiết bị y tế và sổ đăng ký văn bản pháp lý.

Ranh giới gói là quy tắc quản trị của bản phát hành, không phải tiện ích đóng gói. Nếu một quyết định làm đổi ngữ nghĩa lõi, đổi lớp nghiệp vụ hoặc đổi nhịp phát hành, nó phải được phản ánh ở ranh giới này.

Nếu đang tìm điểm vào theo vai trò triển khai thay vì theo gói, xem thêm Tuân thủ theo vai trò triển khai.

Quy tắc ranh giới gói

• Không dồn toàn bộ artifact vào một gói đơn khối.
• Không trộn VN Core Base, BHYT Submission và các gói thuật ngữ vào cùng một lớp ngữ nghĩa.
• Không kéo logic cổng, lớp facade hoặc luồng gửi hồ sơ cho bên thanh toán ngược trở lại VN Core Base nếu đó không phải ngữ nghĩa lõi.

---

Ranh giới gói đang giữ những gì

Kiến trúc gói phát hành hiện hành được dùng để:

1. Giữ VN Core Base ổn định nhất có thể cho liên thông FHIR-native.
2. Tách BHYT Submission khỏi lõi để logic hướng đến bên thanh toán không làm lệch ngữ nghĩa dùng chung. 2b. Tách Pharmacy và Patient Access khỏi lõi từ bản 0.9.0 theo ADR-0020: hai trục này chịu các văn bản có chu kỳ sửa ngắn (TT 26/2025/TT-BYT, TT 55/2025/TT-BYT, QĐ 232/QĐ-TTYQG cho dược; QĐ 1332/QĐ-BYT, QĐ 2062/QĐ-BYT cho Sổ sức khoẻ điện tử và khám sức khoẻ), nên để trong lõi thì mỗi lần văn bản đổi lại buộc bump cả lõi.
3. Tách các gói thuật ngữ lớn khỏi lõi để giảm độ rung khi phát hành.
4. Tách gói hl7.fhir.vn.device cho danh pháp thiết bị, luồng danh mục/quản lý pháp quy và các lớp tài sản/mua sắm khi có ca sử dụng.
5. Giữ lớp gateway / API facade / LGSP ở hướng dẫn diễn giải, CapabilityStatement và tập lệnh kiểm tra thay vì tạo gói khi chưa có nhịp phát hành độc lập.
6. Duy trì một gói tổng hợp để kiểm tra cục bộ, đào tạo và cài đặt nhanh trong giai đoạn đầu.

---

Các gói phát hành

Gói	Vai trò	Dùng khi nào
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.pharmacy	Gói chuyên đề dược	Đơn thuốc điện tử ngoại trú và y học cổ truyền, cấp phát và bán thuốc theo đơn, liên thông Cơ sở dữ liệu về dược; phụ thuộc hl7.fhir.vn.core.base
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.patient-access	Gói truy cập của người dân	Sổ sức khoẻ điện tử trên VNeID, khám sức khoẻ định kỳ và chứng nhận sức khoẻ; phụ thuộc hl7.fhir.vn.core.base và hl7.fhir.vn.pharmacy
hl7.fhir.vn.legal	Gói hành lang pháp lý	Danh mục văn bản pháp lý (VNLegalDocumentRefCS) và trạng thái hiệu lực máy-đọc; nền tảng trích dẫn cho mọi gói khác
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	10 bộ mã theo QĐ 2552/QĐ-BYT và QĐ 3080/QĐ-BYT
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

Quy mô tài nguyên ở phiên bản 0.10.0

Gói	Số lượng tài nguyên
hl7.fhir.vn.core.base	817
hl7.fhir.vn.pharmacy	36
hl7.fhir.vn.bhyt.submission	77
hl7.fhir.vn.patient-access	169
hl7.fhir.vn.legal	9 — sổ đăng ký pháp lý: VNLegalDocumentRefCS + trạng thái hiệu lực + mã ngoại lệ căn cứ + bộ mã VAI TRÒ văn bản (issuing/governing/foundational/historical) và extension gắn vai trò; trục phát hành riêng theo nhịp pháp luật (ADR-0022)
hl7.fhir.vn.terminology.clinical	26
hl7.fhir.vn.terminology.traditional-medicine	22
hl7.fhir.vn.device	3
hl7.fhir.vn.core	1162

Từ 0.10.0, mọi gói npm KHÔNG chứa fixture âm/test-only (các resource cố ý sai phục vụ oracle validator ở lại fsh-generated và trang IG); tổng của gói tổng hợp vì vậy nhỏ hơn tổng số instance của IG website.

Chuỗi phụ thuộc: core.base ← pharmacy ← patient-access; bhyt.submission ← core.base. CapabilityStatement/vn-core-server chỉ nằm trong gói tổng hợp vì nó khai năng lực của toàn bộ IG — đặt trong core.base sẽ tạo phụ thuộc ngược sang pharmacy.

---

Ranh giới nội dung

hl7.fhir.vn.core.base

Giữ lại:

• Hồ sơ, phần mở rộng, hệ định danh, tham số tìm kiếm và CapabilityStatement mức cơ sở;
• Bộ mã nền tảng dùng xuyên nhiều hồ sơ như định danh, dân tộc, tôn giáo, nghề nghiệp, tỉnh/xã/huyện lịch sử, loại hình cơ sở, hạng, cấp, tuyến kỹ thuật lịch sử, chức danh, chuyên khoa, trình độ, đồng ý xử lý dữ liệu;
• Các ví dụ và tài liệu phục vụ triển khai FHIR-native;
• Ngữ nghĩa đủ dùng cho EMR/HSSK, ứng dụng công dân, chia sẻ dữ liệu dùng chung và hướng dẫn theo từng vai trò ở lớp lõi.

Không đưa vào:

• Logical model và operation chuyên cho lớp liên thông hồ sơ thanh toán BHYT;
• Các bộ thuật ngữ lâm sàng quy mô lớn;
• Các bộ thuật ngữ Y học cổ truyền;
• Logic gateway, facade và orchestration tích hợp theo từng cổng cụ thể.

hl7.fhir.vn.pharmacy

Giữ lại:

• Profile đơn thuốc ngoại trú và đơn thuốc cổ truyền (VNCoreOutpatientPrescription, VNCoreYHCTOutpatientPrescription);
• Cấp phát và bán thuốc theo đơn (VNCoreMedicationDispense, VNCoreMedicationAdministration);
• Bốn logical model liên thông Cơ sở dữ liệu về dược (danh mục thuốc, nhập kho, xuất kho, kiểm kê);
• NamingSystem số đăng ký lưu hành và giấy chứng nhận đủ điều kiện kinh doanh dược;
• Ví dụ thuộc trục dược.

Không kéo ngược vào gói lõi:

• Ràng buộc định dạng mã đơn thuốc quốc gia theo TT 26/2025/TT-BYT;
• Quy tắc thời hạn lĩnh thuốc và luồng báo cáo về Hệ thống đơn thuốc quốc gia.

Giữ ở lõi có chủ ý: VNCoreMedication, VNCoreMedicationRequest, VNCoreMedicationStatement là Medication floor — mọi hồ sơ lâm sàng đều cần, và các extension dược mà VNCoreClaim/VNCoreExplanationOfBenefit tham chiếu cũng phải ở lõi để không đảo chiều phụ thuộc.

hl7.fhir.vn.patient-access

Giữ lại:

• Sổ sức khoẻ điện tử trên VNeID: logical model nội dung, envelope liên thông, tự khai của người dân;
• Khám sức khoẻ định kỳ: VNCoreCompositionHealthCheckup, bộ mẫu phiếu, toàn bộ bộ mã vn-ksk-* và vn-health-checkup-*;
• Chứng nhận sức khoẻ (VNCoreHealthCredentialBundle) và VNCoreCompositionHealthRecordSummary;
• CapabilityStatement/vn-citizen-app-client;
• Ví dụ thuộc trục người dân.

Phụ thuộc hl7.fhir.vn.pharmacy vì Sổ sức khoẻ điện tử tổng hợp tham chiếu VNCoreMedicationDispense.

hl7.fhir.vn.bhyt.submission

Giữ lại:

• VNCoreBHYTSubmissionBundle;
• Logical model Check-in + XML 1-15;
• Operation validate, gửi, thu hồi;
• Bộ mã gắn chặt với lớp gửi nhận hồ sơ và thanh toán như loại thẻ BHYT, mã đối tượng đến KCB, kết quả điều trị, tình trạng ra viện, nhóm chi phí, lý do bất khả kháng, loại tai nạn.

Không kéo ngược vào gói lõi:

• Định dạng xuất cổng;
• Quy tắc MA_LK, SO_CCCD, yyyyMMddHHmm;
• Capability theo vai trò gateway;
• Logic tái sử dụng dữ liệu hoặc LGSP/API facade không gắn riêng với quy trình nghiệp vụ của bên thanh toán.

Lớp hướng dẫn không tách thành gói riêng

Ở thời điểm 0.3.0 đến v0.5.0, repo không tạo package riêng cho LGSP/API facade. Lý do:

• Đây là lớp hướng dẫn triển khai, ma trận vai trò và ranh giới tích hợp, không phải tập tài nguyên tiêu thụ độc lập như thuật ngữ hay luồng gửi hồ sơ cho bên thanh toán;
• Phần này nên nằm trong trang diễn giải, CapabilityStatement, OperationDefinition, tập lệnh kiểm tra hợp lệ và tài liệu quản trị;
• Việc mở thêm gói chỉ nên cân nhắc khi có bên sử dụng rõ ràng và nhịp phát hành độc lập.

hl7.fhir.vn.terminology.clinical

Giữ lại:

• ICD-10 VN;
• ICD-9-CM;
• SNOMED CT VN subset;
• CLS;
• LOINC;
• ConceptMap lâm sàng liên quan.

Trong gói này, các bộ mã quy mô lớn có thể được công bố dưới dạng tài nguyên FHIR JSON sinh sẵn thay vì FSH nếu đó là cách ổn định hơn để bảo toàn dữ liệu nguồn và giảm độ rung khi biên dịch.

hl7.fhir.vn.terminology.traditional-medicine

Giữ lại:

• 11 CodeSystem thuộc các đợt QĐ 2552/QĐ-BYT, QĐ 3080/QĐ-BYT và QĐ 2738/QĐ-BYT;
• Các ValueSet tương ứng;
• Provenance pháp lý theo từng quyết định hiện hành.

Ở trạng thái hiện tại, 10 CodeSystem thuộc phạm vi QĐ 2552/QĐ-BYT và QĐ 3080/QĐ-BYT được công bố bằng tài nguyên FHIR JSON sinh sẵn từ dữ liệu nguồn có căn cứ pháp lý rõ ràng; ba hệ mã YHCT khác nằm ngoài ranh giới gói này theo phân loại artifact hiện hành.

hl7.fhir.vn.device

Giữ lại:

• VNMedicalDeviceNomenclatureCS tổng hợp QĐ-3107/QĐ-BYT-2024 và QĐ-847/QĐ-BYT-2025;
• VNMedicalDeviceNomenclatureVS và VNDeviceTypeVS cho binding preferred trong package .device;
• Các profile/gói tương lai cho DeviceDefinition, luồng quản lý pháp quy, hướng dẫn UDI, kiểm định, tài sản, mua sắm và vòng đời thiết bị khi có ca sử dụng triển khai.

Không kéo ngược vào Core:

• Ràng buộc mức required VNCoreDevice.type vào danh pháp thiết bị;
• Catalog, số lưu hành, hồ sơ lưu hành, kiểm định, bảo trì, định mức, mua sắm và mã tài sản;
• Ánh xạ SNOMED CT/GMDN/EMDN nếu chưa có license/provenance và ConceptMap được rà soát.

---

Ma trận phụ thuộc

Gói	Phụ thuộc tối thiểu
hl7.fhir.vn.core	Tám gói mô-đun bên dưới + hl7.fhir.r4.core, hl7.terminology.r4, DICOM, IPS, SDC và R4 extensions
hl7.fhir.vn.core.base	hl7.fhir.r4.core, hl7.terminology.r4, clinical terminology, traditional-medicine terminology, legal, DICOM, IPS, SDC và R4 extensions
hl7.fhir.vn.bhyt.submission	hl7.fhir.r4.core, core.base, pharmacy và R4 extensions
hl7.fhir.vn.pharmacy	hl7.fhir.r4.core, core.base và IPS
hl7.fhir.vn.patient-access	hl7.fhir.r4.core, core.base, pharmacy, IPS và R4 extensions
hl7.fhir.vn.terminology.clinical	hl7.fhir.r4.core, hl7.terminology.r4, legal và traditional-medicine terminology
hl7.fhir.vn.terminology.traditional-medicine	hl7.fhir.r4.core, hl7.terminology.r4 và legal
hl7.fhir.vn.device	hl7.fhir.r4.core, core.base
hl7.fhir.vn.legal	hl7.fhir.r4.core

---

Hướng dẫn dùng gói trong giai đoạn thử nghiệm

Kiểm tra cục bộ

Ưu tiên dùng:

• hl7.fhir.vn.core nếu cần cài trọn bộ;
• Hoặc truyền đồng thời nhiều -ig nếu cần kiểm tra theo từng gói mô-đun.

Trạng thái công bố hiện tại

Ở thời điểm hiện tại:

• Cả 9 gói (ADR-0020 + ADR-0022) đã được công bố công khai ở mức thử nghiệm trên website và canonical của VN Core/VN Device;
• hl7.fhir.vn.core là gói tổng hợp và là điểm vào mặc định cho đa số đơn vị triển khai;
• 8 gói mô-đun đều có package-list.json, history.html, và trang đích công bố riêng dưới đúng đường dẫn canonical của từng gói;
• Các gói hiện vẫn dùng chung một website hướng dẫn triển khai tổng hợp, chưa tách thành các Implementation Guide độc lập theo gói;
• Hồ sơ mirror lên packages.fhir.org đã được chuẩn bị như một bước đăng ký riêng, nhưng vẫn chờ tiếp nhận ngoài repo;
• Trước khi mirror đó hoàn tất, kiểm tra cục bộ vẫn nên ưu tiên gói tổng hợp hoặc truyền tường minh nhiều -ig.

Triển khai EMR và liên thông nội bộ

Ưu tiên:

• hl7.fhir.vn.core.base;
• Cộng các gói thuật ngữ khi môi trường validator hoặc máy chủ FHIR chưa tự kéo được phụ thuộc từ file .tgz cục bộ.

Triển khai gateway BHYT

Ưu tiên:

• hl7.fhir.vn.core.base;
• hl7.fhir.vn.bhyt.submission;
• Cộng các gói thuật ngữ khi cần kiểm tra cục bộ hoặc build độc lập.

---

Quản trị tối thiểu

Mỗi gói phải có:

• Phạm vi rõ;
• Phụ thuộc rõ;
• Ghi chú phát hành;
• Căn cứ pháp lý/dấu vết nguồn gốc;
• Tiêu chí hiện hành, lịch sử, ngừng dùng;
• Kiểm tra chất lượng trước khi phát hành.

Đối với một bản phát hành đủ điều kiện công bố công khai, bộ build nội bộ phải chứng minh tối thiểu:

• governance/qa-classification.json được sinh từ đúng builtAt và sourceFingerprint của bản dựng;
• Nhóm lỗi nội dung (content) bằng 0; mọi expected-fail, renderer-limitation, tooling-artifact và inconclusive có lý do máy-đọc được, không bị diễn giải thành “sạch”;
• Link hỏng chỉ được loại khỏi nhóm nội dung khi là anchor sâu của StructureDefinition và Element.id tồn tại thật trong snapshot của chính resource đó;
• Nếu dựng offline (txMode=na), số phép kiểm terminology chưa chạy phải xuất hiện trong evidence với cờ terminologyValidationPending và release note phải công bố giới hạn này;
• Mọi cảnh báo bị bỏ qua có giải trình rõ trong input/ignoreWarnings.txt hoặc allowlist quản trị tương ứng.

Hợp đồng chi tiết và ngoại lệ hẹp nằm trong governance/release-policy.md; không dùng tổng số raw error/warning của Publisher làm đại diện cho số lỗi nội dung.

Nguồn sự thật quản trị cho việc phân loại tài nguyên hiện nằm tại:

• governance/packages/package-artifact-classification.json
• governance/packages/README.md

---

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

Nếu cần	Nên đọc tiếp
Vai trò triển khai và CapabilityStatement	Tuân thủ theo vai trò triển khai
Quy trình phát hành các gói	Phát hành và quản trị
Chiến lược ổn định và maturity	Ổn định và tuân thủ
Quyết định thiết kế gói	Quyết định thiết kế

---

English Summary

This page explains the VN Core package boundary. VN Core publishes nine packages: an aggregate, a stable base, BHYT Submission, Pharmacy, Patient Access, two terminology packages, a device package, and a legal-registry package on its own cadence. The aggregate stays self-contained; split packages are experimental projections installed by URL. Choose by scope; keep gateway, payer and device-catalog logic out of VN Core Base.