HL7 Vietnam VN Core FHIR Implementation Guide

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

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

## DD-05: Consent, AuditEvent, Provenance là baseline, không phải phụ lục

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 trail through v0.5.0

Các quyết định thiết kế được ghi trong `governance/` và `wiki/decisions/` để giữ audit trail tách khỏi narrative IG. Trang này tóm tắt các quyết định còn tác động trực tiếp đến bản `v0.5.0`; các mục `v0.4` vẫn được giữ như lịch sử thiết kế của Wave 2, không phải trạng thái hiện hành mới nhất.

Document | Summary | Rationale
--- | --- | ---
v0.5 Structured Legal References (VNLegalDocumentRefCS, VNLegalDocumentRefVS, VNCoreExtLegalBasis) | Chuẩn hóa căn cứ pháp lý thành terminology có thuộc tính ngày ban hành, hiệu lực, trạng thái, quan hệ thay thế và cơ quan ban hành. | Tránh legal citation rải rác trong mô tả text; cho phép audit tự động, đánh dấu `future-effective` và kiểm soát văn bản hết hiệu lực.
v0.5 Device Regulatory Hardening (VNCoreExtDeviceRegistrationNumber, VNMedicalDeviceRegistrationNumberNS) | Thêm số lưu hành thiết bị y tế, ví dụ class A/B/C, hardening risk class/UDI cho thiết bị cấy ghép và giữ danh pháp thiết bị trong package `.device`. | `Device.type` không nên bị required-bind vào một danh mục chưa đủ governance, nhưng thiết bị cấy ghép C/D cần dấu vết số lưu hành và lifecycle rõ hơn.
v0.5 BHYT Reconciliation and Gateway Endpoint (VNCorePaymentReconciliation, VNCoreEndpointBHYT) | Bổ sung lớp quyết toán/thanh toán BHYT theo biên bản 06/BH và endpoint cổng `gdbhyt` cho CSKCB ký hợp đồng BHXH. | Claim/EOB mô tả hồ sơ và quyền lợi; quyết toán chu kỳ và endpoint submit là workflow/gateway semantics riêng, cần tách khỏi hồ sơ lâm sàng lõi.
v0.5 Privacy Incident and Audit Baseline (VNCoreCompositionBreachNotification, VNCoreExtAuditRetention, VNCoreExtConsentMethod) | Mô hình hóa Mẫu 08 thông báo vi phạm DLCN, phương thức thể hiện đồng ý và thời hạn lưu trữ audit. | Luật 91/2025 và NĐ 356/2025 tạo nghĩa vụ vận hành cụ thể; cần biểu diễn được incident record, consent evidence và audit retention thay vì chỉ guidance text.
v0.5 Commune-level Service Modeling (VNCoreHealthcareService) | Thêm profile HealthcareService cho dịch vụ y tế, đặc biệt dịch vụ TYT cấp xã/phường/đặc khu trong mô hình chính quyền 2 cấp. | `Organization` và `Location` không đủ để mô tả danh mục dịch vụ đang cung cấp; service catalog cần resource riêng để liên thông EMR/HSSK và citizen-facing discovery.
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 `medicalDeviceItemCode`, `serialNumber`, mở rộng UDI/lifecycle/MS theo FHIR base và thêm VNCoreExtDeviceGroup ở mức fallback; thanh toán TBYT ưu tiên ở `Claim.item`. | Profile Device cũ quá mềm cho VTYT/TBYT BHYT; cần đủ dữ liệu định danh, hạn dùng, lot/serial và manufacturer, nhưng không biến nhóm/phạm vi/tỷ lệ thanh toán BHYT thành thuộc tính nội tại của thiết bị.
ADR-0005 — Device.type cardinality và binding (`wiki/decisions/adr-0005-device-type-cardinality-binding.md`) | VNCoreDevice relax `type` về `0..1 MS`; chưa required binding vào QĐ 847/QĐ 3107/GMDN/SNOMED; profile con implantable siết riêng. | National Core phải nhận dữ liệu legacy/BHYT thiếu danh pháp chuẩn; nguồn terminology thiết bị còn chờ governance.
ADR-0007 — VNCoreImplantableDevice (`wiki/decisions/adr-0007-implantable-device-profile.md`) | Thêm VNCoreImplantableDevice, patient-bound với `patient/type/status 1..1`, UDI/lifecycle/safety MS. | Theo pattern US Core Implantable Device, siết đúng context cấy ghép mà không làm profile Device nền quá chặt.
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 VN Core design decisions, rationale, and implementation consequences. It covers CCCD identifiers, Core versus BHYT boundaries, terminology packaging, two-level addresses, consent/audit/provenance, no separate LGSP package, HL7 Patient extension reuse, and v0.5.0 updates for legal references, devices, BHYT reconciliation, breach notification, and HealthcareService modeling.