Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.3.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

Trang này mô tả cách phân chia gói phát hành của VN Core trong giai đoạn thử nghiệm và chuẩn bị triển khai quy mô lớn.

Sau khi tái khẳng định hướng phát triển lấy dữ liệu làm trung tâm, kiến trúc gói phát hành không chỉ phục vụ công bố, mà còn phải giữ rõ ranh giới giữa dữ liệu lõi FHIR-native, gateway / API facade / LGSP, liên thông hồ sơ thanh toán BHYT và thuật ngữ quy mô lớn.

Trang này dành cho ai?

• Kiến trúc sư hệ thống cần quyết định cài gói nào cho từng bài toán triển khai.
• Maintainer package và nhóm vận hành publication cần hiểu ranh giới từng gói.
• Reviewer maturity cần kiểm tra xem việc tách gói đã phản ánh đúng phạm vi nghiệp vụ và mức ổn định hay chưa.

Sau khi đọc, bạn nên chốt được gì?

• Gói nào là điểm vào mặc định cho từng nhóm triển khai.
• Gói nào có thể nâng phiên bản độc lập và gói nào phải đi cùng nhau.
• Vì sao lớp liên thông hồ sơ thanh toán BHYT (BHYT Submission) và các thuật ngữ lớn không nên bị trộn trở lại vào lõi.
• Khi nào nên đánh giá conformance theo vai trò triển khai trước khi chốt package tiêu thụ.

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.

Từ tài liệu đơn khối sang publication có ranh giới

Repo hiện tại giữ một nguyên tắc rất rõ: terminology và identifier không phải phần phụ. Từ đó, publication được triển khai theo hướng trưởng thành hơn:

• Không dồn mọi thứ vào một tài liệu hoặc một gói đơn khối;
• Không để terminology, NamingSystem và legal provenance đứng ngoài chiến lược package/governance;
• Không coi profile là đủ nếu chưa có guidance, conformance và test tương ứng.

Vì vậy, kiến trúc gói hiện tại tách riêng VN Core Base, lớp liên thông hồ sơ thanh toán BHYT (BHYT Submission) và các package thuật ngữ lớn, trong khi narrative giữ vai trò giải thích ranh giới, thay vì nhồi toàn bộ semantics vào artifact.

---

1. Mục tiêu

Kiến trúc gói phát hành được thiết kế để đạt đồng thời 5 mục tiêu:

1. Giữ lõi quốc gia ổn định nhất có thể;
2. Tách lớp liên thông hồ sơ thanh toán BHYT ra khỏi các ca sử dụng FHIR nội bộ;
3. Tách các bộ thuật ngữ lớn ra khỏi gói lõi để giảm độ rung;
4. Giữ rõ ranh giới giữa FHIR-native exchange và lớp gateway / API facade / LGSP ở mức hướng dẫn và năng lực hệ thống;
5. Vẫn có 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.

---

2. 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	Điểm vào mặc định để 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
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 liên quan
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

2.1. Quy mô tài nguyên ở phiên bản 0.3.0

Gói	Số lượng tài nguyên
hl7.fhir.vn.core.base	264
hl7.fhir.vn.bhyt.submission	48
hl7.fhir.vn.terminology.clinical	12
hl7.fhir.vn.terminology.traditional-medicine	20
hl7.fhir.vn.core	345

---

3. Ranh giới nội dung

3.1. 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ể.

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

3.5. 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.4.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.

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

3.4. 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ữ.

---

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

---

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

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

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

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

• Cả 5 gói đã được công bố công khai ở mức thử nghiệm trên website và canonical của VN Core;
• 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;
• 4 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 4 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.

5.2. 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ộ.

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

---

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

---

English Summary

VN Core now uses a five-package publication model: one aggregate package (hl7.fhir.vn.core), one stable base package (hl7.fhir.vn.core.base), one payer-facing submission package (hl7.fhir.vn.bhyt.submission), and two terminology packages (hl7.fhir.vn.terminology.clinical and hl7.fhir.vn.terminology.traditional-medicine). After alignment with the Ministry of Health digital-transformation strategy and digital-architecture decisions, the package model is also used to preserve a clear boundary between FHIR-native core exchange, payer submission, large terminology payloads, and implementation guidance for LGSP/API facade patterns. All five packages are publicly published as trial-use packages on the VN Core canonical site. A registry-submission package set for packages.fhir.org has been prepared, but final mirroring still depends on external registry intake. Until that mirror is live, local validation should still prefer either the aggregate package or an explicit multi-package -ig invocation.