HL7 Vietnam VN Core FHIR Implementation Guide

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.8.0 - Draft for Community Review Viet Nam cờ

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.8.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Phát hành & Governance

Phát hành và quản trị — Release and Governance

Khung quản trị tối thiểu cho VN Core trong giai đoạn trial-use: phân loại thay đổi, siết chất lượng phát hành và giúp cộng đồng đọc mức độ ổn định của từng tài nguyên.

Trạng thái hiện hành: VN Core đang ở dải phát hành Bản nháp để cộng đồng rà soát; khung quản trị hiện tại ưu tiên minh bạch, ổn định và phản hồi từ triển khai thực tế.

Nguyên tắc quản trị hiện tại

  1. Ưu tiên ổn định VN Core Base trước khi mở rộng phạm vi.
  2. Chỉ đưa vào bản phát hành công khai những gì đã có ví dụ, hướng dẫn và kiểm tra tối thiểu.
  3. Tách lớp liên thông hồ sơ thanh toán BHYT (BHYT Submission) và các gói thuật ngữ lớn để giảm độ rung của core.
  4. Mọi thay đổi có thể ảnh hưởng đến bên triển khai phải có phần diễn giải hoặc ghi chú chuyển đổi tương ứng.

Phân loại thay đổi

Loại thay đổi Áp dụng điển hình Kỳ vọng tài liệu đi kèm
Bản vá / ổn định hóa sửa ví dụ, sửa tài liệu, sửa liên kết hỏng, sửa câu chữ, giảm nhiễu QA, gia cố tập lệnh ghi chú thay đổi ngắn, không đổi ngữ nghĩa cốt lõi
Bổ sung thêm profile, extension, search parameter, ví dụ, operation, mã mới đang hiệu lực ghi chú thay đổi + hướng dẫn + ví dụ
Phá vỡ tương thích đổi URL tài nguyên, đổi cardinality, đổi binding theo cách làm dữ liệu cũ không còn hợp lệ, đổi hợp đồng tìm kiếm ghi chú chuyển đổi bắt buộc + cảnh báo phát hành

Cách áp dụng trong giai đoạn 0.x

Do VN Core chưa ở 1.0.0, thay đổi bổ sung vẫn có thể đi nhanh hơn một bản phát hành trưởng thành. Tuy nhiên:

  • Nhóm duy trì SHOULD không gộp thay đổi phá vỡ ngữ nghĩa vào bản vá.
  • Nhóm duy trì SHOULD hạn chế mở rộng phạm vi quá lớn trong những ngày cuối trước khi gắn thẻ công bố.
  • Mọi thay đổi làm bên triển khai phải sửa dữ liệu hoặc logic tích hợp SHALL được ghi rõ trong changelog.

Trạng thái quản trị của v0.8.0 (hiện hành)

v0.8.0 là bản nháp để cộng đồng rà soát hiện hành, dạng minor có thay đổi phá vỡ tương thích công bố đúng SemVer. Chủ đề chính: tái cấu trúc dữ liệu khám sức khỏe (KSK) theo QĐ 2062/QĐ-BYT — 17 mẫu phiếu theo QĐ 1551/QĐ-BYT chuyển retired, thay bằng 3 mẫu theo nhóm tuổi và mẫu sức khỏe tâm thần TT 25/2026/TT-BYT — cùng đợt rà soát văn bản pháp lý 07/2026 và đợt gia cố theo kiểm toán độc lập (Codex GPT-5.6). Không đổi canonical URL hoặc package id.

v0.7.0 được đóng băng nguyên trạng và đánh dấu thay thế (superseded) từ 16/07/2026: không sửa nội dung đã gắn thẻ, không bổ sung assets phát hành. Đây là mức nhẹ hơn "rút lại (withdrawn)" của v0.6.1 — bản 0.7.0 vẫn là mốc lịch sử hợp lệ, nhưng người triển khai dùng v0.8.0.

  • Tập căn cứ pháp lý: VNLegalDocumentRefCS đạt 172 concept, danh mục công khai phản chiếu đủ 172 mục có nguồn đối chiếu;
  • Số liệu phát hành chi tiết chốt tại governance/release-metrics/0.8.0.json tại thời điểm gắn thẻ công bố.

Trạng thái quản trị của v0.7.0 (đã thay thế — superseded)

v0.7.0 là bản nháp để cộng đồng rà soát của chu kỳ trước, nay đóng băng nguyên trạng và được thay thế bởi v0.8.0 (xem mục trên). Đây là bản gia cố sau kiểm toán hậu phát hành của dòng 0.6.x: v0.6.1 được đánh dấu rút lại (withdrawn) sau kiểm toán độc lập 12–13/07/2026 thay vì sửa âm thầm nội dung đã công bố. v0.7.0 sửa nhóm lỗi ánh xạ tài chính BHYT (T_NGUONKHAC theo dòng, TYLE_TT_DV, MA_TTDV người ký giấy), khai đúng scope operations, gán đủ gói bhyt.submission, rollover trạng thái pháp lý chạm mốc 01/07/2026 (corpus 145 văn bản) và công bố đúng SemVer 3 breaking change tồn đọng kèm hướng dẫn migration (Encounter.serviceProvider 1..1; MedicationRequest.requester loại Organization; vn-ext-encounter-code retired — dùng Encounter.identifier[maLuotKcb]), không đổi canonical URL hoặc package id:

  • Logical model BHYT: thêm BHYTXML13ReferralLM, BHYTXML14FollowUpAppointmentLM, BHYTXML15TuberculosisLM và mở rộng BHYTCheckInLM, phủ 100% chỉ tiêu XML1–XML15;
  • Terminology & extension tài chính: thêm VNAnesthesiaMethodCS, VNDocumentFormCS, VNCareTransferReasonCS, VNGenderCS (kèm ConceptMap giới tính → AdministrativeGender) cùng các extension VNCoreExtOtherFundBreakdown, VNCoreExtGestationalAge, VNCoreExtAnesthesiaMethod;
  • Kiểm chứng công thức: 3 invariant công thức tài chính BHYT và các adapter rule round-trip cho XML13/14/15;
  • Tập căn cứ pháp lý: VNLegalDocumentRefCS đạt 145 concept tại thời điểm phát hành (chu kỳ v0.8.0 nâng lên 172 — xem mục trên);
  • Số liệu phát hành: profiles 73 (không đổi), extensions 51→52, CodeSystems 143→145, ValueSets 148→150; bề mặt công bố dùng download root 0.7.0.

Trạng thái quản trị của v0.6.0 (bản liền trước)

v0.6.0 là bản phát hành phụ liền trước, làm nền cho v0.6.1. Đây là bản bổ sung ba trục lớn trên nền v0.5.3, không đổi canonical URL, package id hoặc ngữ nghĩa lõi của Patient/Encounter/Condition/Observation:

  • Quản lý chăm sóc: VNCoreCarePlan/CareTeam/Goal/EpisodeOfCare/ClinicalImpression + VNCoreMedicationStatement/MedicationAdministration; thang phân loại ưu tiên cấp cứu VNCoreObservationTriageAcuity (thang đề xuất nội bộ tham chiếu ATS — xem ADR-0014);
  • KSK liên thông (HL7 SDC): VNCoreQuestionnaire/QuestionnaireResponse + 17 mẫu phiếu VNKSKQuestionnaire01–17 theo QĐ 1551/QĐ-BYT Phụ lục 01, kèm VNCoreFamilyMemberHistory (xem ADR-0015);
  • Tương tác quốc tế (IPS): VNCoreCompositionIPS kế thừa Composition-uv-ips + operation $summary, dependency hl7.fhir.uv.ips#2.0.1, cầu thuật ngữ SNOMED CT (xem ADR-0016);
  • Tập căn cứ pháp lý: thêm QĐ 2919/QĐ-BYT (chuẩn dữ liệu Giấy chứng sinh) → VNLegalDocumentRefCS 132 concept, công khai registry mirror đủ 132 mục có nguồn đối chiếu; độ phủ trích dẫn pháp lý có tác động kỹ thuật 83/83 (100%);
  • Profiles 52→73, CodeSystems 75→139, ValueSets 81→144, ConceptMaps 5→6; bề mặt công bố dùng download root 0.6.0.

Trạng thái quản trị của các bản trước

v0.5.3 là bản vá bổ sung gồm các đóng góp thuộc phạm vi lõi cho IG phái sinh Chăm sóc sức khỏe cộng đồng (CHC), không đổi canonical URL, package id hoặc ngữ nghĩa lõi:

  • thêm VNBasicHealthServiceCS/VNBasicHealthServiceVS (danh mục, nội dung gói dịch vụ y tế cơ bản do Trạm Y tế xã thực hiện) theo TT 30/2024/TT-BYT;
  • thêm trục bối cảnh cung cấp dịch vụ VNServiceDeliverySettingCS/VNServiceDeliverySettingVS;
  • thêm vòng đời mã cơ sở trên VNCoreOrganization (VNCoreExtOrgLifecycleRelation + identifier.period, VNOrgLifecycleRelationCS + VNOrgCarryOverItemCS) cho sáp nhập/chia tách/đổi mã cơ sở theo NQ 202/2025/QH15;
  • mở rộng VNLegalDocumentRefCS lên 117 concept (thêm TT 30/2024/TT-BYT), nâng độ phủ trích dẫn pháp lý có tác động kỹ thuật lên 74/74 (100%); danh mục công khai giai đoạn v0.5 có 101 mục nguồn TVPL khớp chính xác, còn trạng thái công khai hiện hành của v0.6.0 là 132 nguồn;
  • bề mặt công bố dùng download root 0.5.3 và package split 0.5.3.

v0.5.2 là bản vá tập căn cứ pháp lý ngay trước đó: mở rộng VNLegalDocumentRefCS lên 116 concept (Luật Dân số 113/2025, nhóm QĐ EMR/SKĐT, VBHN hợp nhất) và thêm VNFetalSexDisclosureDiseaseVS, giữ độ phủ trích dẫn pháp lý có tác động kỹ thuật 73/73 (100%).

v0.5.1 là bản vá đồng bộ/quản trị trước đó: đồng bộ siêu dữ liệu phát hành, bề mặt gói, roadmap/news/wiki và đưa độ phủ trích dẫn pháp lý có tác động kỹ thuật lên 100%, với release-manifest và roadmap làm nguồn chuẩn.

v0.5.0 là bản phát hành bổ sung/gia cố trước đó nữa, mở rộng bề mặt triển khai ở các điểm sau:

  • căn cứ pháp lý có cấu trúc: VNLegalDocumentRefCS, VNLegalDocumentRefVS, VNCoreExtLegalBasis;
  • gia cố thí điểm BHYT: VNCorePaymentReconciliation, VNCoreEndpointBHYT, claimAuditStatus, paymentReconciliationForm;
  • nền tảng quyền riêng tư/kiểm toán: VNCoreCompositionBreachNotification, VNCoreExtConsentMethod, VNCoreExtAuditRetention;
  • gia cố quản lý pháp quy thiết bị: số lưu hành thiết bị y tế, nhóm rủi ro, cờ IVD và ví dụ class A/B/C;
  • phát hiện dịch vụ: VNCoreHealthcareService cho dịch vụ y tế, đặc biệt tuyến xã/phường/đặc khu.

Các nội dung này cần được thí điểm trước khi nâng mức trưởng thành: dữ liệu thực, lỗi validator, phản hồi từ nhà cung cấp và chênh lệch quy trình địa phương sẽ quyết định phần nào được siết thành ràng buộc mạnh hơn trong bản kế nhiệm.

Ngưỡng phát hành tối thiểu trước khi công bố

Trước khi công bố một bản trial-use, nhóm duy trì nên bảo đảm tối thiểu:

  • ./scripts/validate.sh --quick chạy thành công.
  • ./scripts/validate-tier2.sh chạy thành công nếu thay đổi chạm đến quy tắc dữ liệu quốc gia.
  • bash _genonce.sh chạy thành công.
  • output/qa.html không còn errors, warnings, broken links.
  • Câu chữ của trang chủ, trang tải xuống, README và changelog đồng bộ.
  • Ghi chú công bố gói phát hành khớp trạng thái thực tế.

Nếu bản phát hành chạm lớp BHYT Submission, nên chạy thêm:

  • ./scripts/validate-bhyt-submission.sh
  • ./scripts/validate-bhyt-roundtrip.sh

Nếu bản phát hành chạm bảo mật/quản trị, nên chạy thêm:

  • ./scripts/validate-security-baseline.sh

Quy tắc ngừng dùng

  • Không xóa mã cũ hoặc identifier cũ ngay nếu còn cần cho dữ liệu lịch sử.
  • Ưu tiên deprecated hoặc legacy trước khi loại bỏ hoàn toàn.
  • Không đổi canonical URL chỉ vì đổi wording hoặc đổi cách diễn giải narrative.
  • Nếu chuyển từ extension cục bộ sang extension chuẩn HL7, phải có thời gian chuyển tiếp và ví dụ cập nhật kèm theo.

Vai trò của cộng đồng góp ý

Ở giai đoạn hiện tại, cộng đồng có thể tham gia qua:

  • Email hoặc kênh thí điểm được chỉ định cho lỗi, điểm mơ hồ, câu chữ pháp lý, hành vi tìm kiếm, thuật ngữ.
  • Repo công khai, issue và pull request sẽ được công bố sau khi quản trị và quy trình đóng góp được chốt.
  • Implementation report cho phản hồi triển khai thật.

Nội dung góp ý có giá trị cao nhất là:

  • Lỗi tái tạo được.
  • Profile và ví dụ không khớp nhau.
  • Điểm mơ hồ gây hiểu sai ở nhà cung cấp.
  • Thiếu hướng dẫn khiến triển khai thực tế bị vướng.
  • Khác biệt giữa tài nguyên và quy định hiện hành.

Điều gì chưa cần làm quá nặng ở giai đoạn này

VN Core chưa cần ngay:

  • Quy trình ballot nội bộ nhiều vòng như một affiliate trưởng thành.
  • Hệ thống phê duyệt đa tầng cho mọi bản vá tài liệu.
  • FMM chính thức cho từng tài nguyên.
  • Mở rộng nhịp phát hành gói quá dày khi chưa có mức độ tiếp nhận đủ rộng.

Điều cần lúc này là:

  • Tính trung thực của bản phát hành.
  • Hướng dẫn đủ rõ.
  • Đầu mối tiếp nhận vấn đề minh bạch.
  • Danh sách việc cần sửa bám theo phản hồi thật.

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

Nếu cần Nên đọc tiếp
Nắm chính sách ổn định và mức độ trưởng thành của artifact Ổn định và tuân thủ
Hiểu cách các gói phát hành được tổ chức và phụ thuộc lẫn nhau Kiến trúc gói phát hành

English Summary

This page defines VN Core release governance: change rules, quality gates, and the current v0.8.0 scope. v0.8.0 (breaking) restructures health-checkup data per Decision 2062/QĐ-BYT — 17 forms retired for three age-group forms plus a mental-health form, DOI_TUONG grows to 16 codes, Appendix 02/03 transport — and hardens the guide after the independent Codex audit; the previous v0.7.0 line is frozen.