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 - Draft for Community Review (v0.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Mỗi quyết định thiết kế ghi rõ nội dung quyết định, lý do và hệ quả triển khai.
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:
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.
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:
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ô ý.
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:
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.
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:
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:
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.
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:
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.
Quyết định: VNCorePatient dùng patient-religion, patient-citizenship, patient-birthPlace chuẩn HL7 thay vì tạo extension riêng.
Lý do:
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).
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. |
| 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ư |
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.