HL7 Vietnam VN Core FHIR Implementation Guide

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

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

Quyết định thiết kế

Quyết định thiết kế — Design Decisions

Mỗi quyết định thiết kế ghi rõ nội dung quyết định, lý do và hệ quả triển khai.

DD-01: CCCD là primary citizen identifier, VNeID chỉ ở lớp ứng dụng

Quyết định: CCCD (Căn cước công dân 12 số) là định danh cá nhân lõi duy nhất trong VNCorePatient. VNeID được giữ ở lớp ứng dụng người dân và tích hợp, không phải patient identifier song song.

Lý do:

  • Số định danh cá nhân trên CCCD là trục chính theo TT 17/2024/TT-BCA và chiến lược chuyển đổi số QĐ 3516/QĐ-BYT.
  • VNeID là tài khoản định danh điện tử (app-layer), không phải mã bệnh nhân. Nếu coi VNeID ngang hàng CCCD sẽ tạo nhập nhằng khi liên thông giữa HIS, EMR và cổng BHXH.
  • NamingSystem cho VNeID ở trạng thái retired trong phiên bản hiện hành; SearchParameter tương ứng cũng retired.

Hệ quả: Mọi hệ thống muốn trao đổi dữ liệu bệnh nhân qua VN Core phải hỗ trợ identifier[CCCD]. Hệ thống dùng VNeID để xác thực vẫn hoạt động bình thường nhưng không ghi VNeID vào patient identifier lõi.

DD-02: Tách VN Core Base khỏi BHYT Submission

Quyết định: hl7.fhir.vn.core.base và hl7.fhir.vn.bhyt.submission là hai package riêng biệt. Logic chi trả, format gateway và rule đặc thù payer không được kéo ngược vào lõi.

Lý do:

  • Semantic lõi FHIR (Patient, Encounter, Condition, Observation) phải ổn định cho EMR, HIE, hồ sơ công dân — không chỉ cho mục đích gửi hồ sơ BHXH.
  • Format dữ liệu đầu ra BHXH thay đổi theo QĐ 130 → QĐ 4750 → QĐ 3176 → QĐ 697, nhịp nhanh hơn lõi FHIR.
  • Nếu trộn, mỗi thay đổi payer-facing sẽ tạo breaking change cho toàn bộ IG.

Hệ quả: Hệ thống EMR/HIS nội bộ chỉ cần core.base. Hệ thống gửi hồ sơ BHXH cần thêm bhyt.submission. Gateway/facade phải hiểu ranh giới này để không mở rộng semantic lõi một cách vô ý.

DD-03: Tách terminology packages khỏi lõi

Quyết định: Thuật ngữ lâm sàng quy mô lớn (ICD-10 VN, CLS, SNOMED CT VN) và thuật ngữ Y học cổ truyền được tách thành hl7.fhir.vn.terminology.clinical và hl7.fhir.vn.terminology.traditional-medicine.

Lý do:

  • Bộ mã lớn (CLS: 2.964 chỉ số, ICD-10 VN: hàng nghìn mã) thay đổi theo quyết định BYT, không theo nhịp phát hành của core profiles.
  • Build time và package size tăng đáng kể khi terminology nằm trong lõi.
  • Cho phép đơn vị triển khai chỉ kéo terminology cần dùng.

Hệ quả: Validator và FHIR server cần kéo thêm terminology packages nếu cần kiểm tra binding. Build cục bộ nên dùng gói tổng hợp hl7.fhir.vn.core hoặc truyền nhiều -ig.

DD-04: Địa chỉ 2 cấp theo NQ 202/2025, giữ backward-compatible huyện

Quyết định: VNCoreAddress dùng mô hình tỉnh + xã/phường theo NQ 202/2025 (34 tỉnh/thành). Cấp huyện không còn là cấp chính quyền chính thức nhưng vẫn được hỗ trợ qua address.district cho dữ liệu lịch sử.

Lý do:

  • NQ 202/2025/QH15 chuyển sang mô hình 2 cấp (tỉnh + xã) từ 01/07/2025.
  • Dữ liệu bệnh viện, CSYT và hồ sơ bệnh nhân cũ vẫn gắn với huyện. Nếu xóa trường huyện, dữ liệu lịch sử không thể biểu diễn.
  • FHIR Address không có trường ward/commune chuẩn → cần extension vn-ext-ward.

Hệ quả: address.state là tỉnh/TP (34 đơn vị mới, VNProvinceCS với 34 active + 29 deprecated). address.district vẫn dùng được nhưng không bắt buộc cho hồ sơ mới. Ward/commune dùng extension riêng.

Quyết định: VN Core coi VNCoreConsent, VNCoreAuditEvent, VNCoreProvenance là phần của conformance baseline, không phải tài nguyên tùy chọn.

Lý do:

  • Luật 91/2025 và NĐ 356/2025 coi dữ liệu y tế là DLCN nhạy cảm. Quyền đồng ý, truy vết và kiểm toán là nghĩa vụ pháp lý, không phải best practice.
  • Nếu không thiết kế từ đầu, việc bổ sung consent/audit muộn sẽ phá vỡ kiến trúc dữ liệu đã triển khai.

Hệ quả: Mọi actor triển khai phải có cơ chế ghi nhận consent, audit và provenance — dù chưa nhất thiết phải dùng FHIR resource trao đổi, nhưng phải có cơ chế tương đương có thể truy xuất.

DD-06: Không tạo package riêng cho LGSP/API facade

Quyết định: Lớp LGSP/API facade được giữ ở mức narrative guidance, CapabilityStatement và validation scripts — không tách thành package riêng.

Lý do:

  • Đây là lớp hướng dẫn triển khai, không phải tập tài nguyên tiêu thụ độc lập.
  • Chi phí quản trị package tăng nhanh hơn giá trị thực tế khi chưa có bên sử dụng rõ ràng và nhịp phát hành độc lập.

Hệ quả: Guidance cho LGSP/API facade nằm trong narrative pages và CapabilityStatement. Có thể mở package khi có nhu cầu rõ ràng từ pilot.

DD-07: Dùng HL7 standard extensions cho Patient thay vì tạo mới

Quyết định: VNCorePatient dùng patient-religion, patient-citizenship, patient-birthPlace chuẩn HL7 thay vì tạo extension riêng.

Lý do:

  • Giảm số lượng extension cục bộ.
  • Tăng khả năng tương hợp với các IG quốc gia khác.
  • Extension chuẩn HL7 đã có lifecycle và governance rõ ràng.

Hệ quả: Chỉ tạo extension cục bộ khi FHIR base thật sự không có (dân tộc 54 dân tộc VN, ward/commune, BHYT coverage details).

Governance documents for v0.4 Wave 2

Các quyết định Wave 2 được ghi trong thư mục governance để giữ audit trail tách khỏi narrative IG. Trang này chỉ tóm tắt ngắn các quyết định có tác động trực tiếp đến artifact v0.4.

Document Summary Rationale
DD-v04-05 — DiagnosticReport Sub-profiles (governance/v0.4-decisions/DD-v04-05-diagnosticreport-subprofiles.md) Tạo VNCoreDiagnosticReportLab, VNCoreDiagnosticReportImaging, VNCoreDiagnosticReportPathology theo parent-child pattern từ VNCoreDiagnosticReport. Một profile DiagnosticReport chung không đủ validation safety cho Lab, CĐHA và GPB; các nhóm này có category, specimen/imagingStudy và căn cứ thanh toán khác nhau.
DD-v04-06 — Device Refactor (governance/v0.4-decisions/DD-v04-06-device-refactor.md) Refactor VNCoreDevice với identifier slicing maVTYT, serialNumber, udiDI, mở rộng UDI/lifecycle/MS và thêm VNCoreExtDeviceGroup. Profile Device cũ quá mềm cho VTYT/TBYT BHYT; cần đủ dữ liệu định danh, hạn dùng, lot/serial, manufacturer và nhóm TBYT để đối soát thanh toán và quản lý thiết bị.
DD-v04-07 — Missing Profiles (governance/v0.4-decisions/DD-v04-07-missing-profiles.md) Bổ sung VNCoreOrganizationDepartment, VNCoreMedicationDispense, VNCoreImagingStudy. Ba profile này chặn các workflow thực tế: MA_KHOA, cấp phát thuốc sau kê đơn, và metadata DICOM/RIS/PACS cho CĐHA.
wave2-legal-consolidated (governance/v0.4-decisions/wave2-legal-consolidated.md) Tổng hợp 3 legal cross-reviews của Codex ngày 14/04/2026 cho DD-v04-05, DD-v04-06 và DD-v04-07. Chốt corrections pháp lý trước khi code: QĐ 2010 mã khoa 54 codes, TT 24/2025 cho TBYT, TT 26/2025 và NĐ 163/2025 cho đơn thuốc/cấp phát, QĐ 2493 morphology binding extensible.

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

Nếu cần Nên đọc tiếp
Hiểu package boundary chi tiết Kiến trúc gói phát hành
Xem nghĩa vụ theo actor Tuân thủ theo vai trò triển khai
Tra căn cứ pháp lý cụ thể Cơ sở pháp lý
Xem security/privacy baseline Bảo mật và quyền riêng tư

English Summary

This page consolidates the key design decisions of VN Core into a single reference. Each entry states the decision, rationale, and implementation consequences. Topics covered include: CCCD as primary identifier (DD-01), separation of Core Base from BHYT Submission (DD-02), terminology package split (DD-03), two-level address model (DD-04), consent/audit/provenance as baseline (DD-05), no separate LGSP package (DD-06), and reuse of HL7 standard Patient extensions (DD-07).