Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.5.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 6 gói phát hành với ranh giới rõ ràng giữa lõi, lớp nghiệp vụ, terminology và thiết bị y tế.

Package boundary là rule 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 semantic lõi, đổi lớp nghiệp vụ hoặc đổi nhịp phát hành, nó phải được phản ánh ở boundary này.

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

Quy tắc package boundary

• 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 terminology packages vào cùng một lớp ngữ nghĩa.
• Không kéo logic gateway, facade hoặc payer submission ngược trở lại VN Core Base nếu đó không phải semantic lõi.

---

Package boundary đ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 payer-facing không làm lệch semantic dùng chung.
3. Tách các terminology packages lớn khỏi lõi để giảm độ rung khi phát hành.
4. Tách package hl7.fhir.vn.device cho danh pháp thiết bị, catalog/regulatory workflow và các lớp asset/procurement khi có use case.
5. Giữ lớp gateway / API facade / LGSP ở narrative guidance, CapabilityStatement và script kiểm tra thay vì tạo package 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.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

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

Gói	Số lượng tài nguyên
hl7.fhir.vn.core.base	387
hl7.fhir.vn.bhyt.submission	51
hl7.fhir.vn.terminology.clinical	12
hl7.fhir.vn.terminology.traditional-medicine	20
hl7.fhir.vn.device	3
hl7.fhir.vn.core	474

---

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.bhyt.submission

Giữ lại:

• VNCoreBHYTSubmissionBundle;
• Logical model Check-in + XML 1-12;
• 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ư terminology hay payer submission;
• Phần này nên nằm trong narrative pages, CapabilityStatement, OperationDefinition, validation scripts 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:

• Toàn bộ 10 CodeSystem Y học cổ truyền;
• 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, toàn bộ 10 CodeSystem Y học cổ truyền đều đượ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; các ValueSet và narrative tiếp tục được duy trì riêng để thuận tiện cho biên tập chuyên môn và mô tả song ngữ.

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/package tương lai cho DeviceDefinition, regulatory workflow, UDI guidance, kiểm định, asset, procurement và lifecycle thiết bị khi có use case triển khai.

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

• Required binding 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;
• Mapping SNOMED CT/GMDN/EMDN nếu chưa có license/provenance và ConceptMap được review.

---

Ma trận phụ thuộc

Gói	Phụ thuộc tối thiểu
hl7.fhir.vn.core	hl7.fhir.r4.core, hl7.terminology.r4
hl7.fhir.vn.core.base	hl7.fhir.r4.core, hl7.terminology.r4, hl7.fhir.vn.terminology.clinical, hl7.fhir.vn.terminology.traditional-medicine
hl7.fhir.vn.bhyt.submission	hl7.fhir.r4.core, hl7.fhir.vn.core.base
hl7.fhir.vn.terminology.clinical	hl7.fhir.r4.core, hl7.terminology.r4
hl7.fhir.vn.terminology.traditional-medicine	hl7.fhir.r4.core, hl7.terminology.r4
hl7.fhir.vn.device	hl7.fhir.r4.core, hl7.fhir.vn.core.base

---

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ả 6 gói đã đượ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;
• 5 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 5 Implementation Guide độc lập;
• 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.

---

Governance tối thiểu

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

• Phạm vi rõ;
• Phụ thuộc rõ;
• Release note;
• Căn cứ pháp lý/provenance;
• 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:

• 0 lỗi trong output/qa.html hoặc output/qa.json;
• 0 cảnh báo trong output/qa.html hoặc output/qa.json;
• 0 liên kết hỏng trong output/qa.html;
• Mọi suppressed message đều có giải trình rõ trong input/ignoreWarnings.txt.

Lưu ý: số lượng liên kết hỏng có thể được IG Publisher báo riêng với số lượng lỗi/cảnh báo, nên ngưỡng phát hành phải kiểm tra tường minh phần này thay vì chỉ nhìn tổng số lỗi.

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	Conformance by Actor
Quy trình phát hành các gói	Release Governance
Chiến lược ổn định và maturity	Stability and Conformance
Quyết định thiết kế gói	Design Decisions

---

English Summary

This page explains the VN Core package boundary. VN Core publishes one aggregate package, one stable base package, one payer-facing BHYT Submission package, two terminology packages, and one medical-device package. Implementers should choose packages by scope and avoid pulling gateway, payer-specific, or device regulatory/catalog logic back into VN Core Base.