Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.6.0 - Draft for Community Review
Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.6.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ù bên thanh toán 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 ngữ nghĩa 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 các gói thuật ngữ 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/QH15 (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 hướng dẫn diễn giải, CapabilityStatement và tập lệnh kiểm tra hợp lệ — không tách thành package riêng.
Lý do:
Hệ quả: Guidance cho LGSP/API facade nằm trong trang diễn giải và CapabilityStatement. Có thể mở package khi có nhu cầu rõ ràng từ thí điểm.
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).
Quyết định: VN Core dùng obligation extension từ hl7.fhir.uv.extensions.r4#5.3.0 (R4-native, fhirVersion 4.0.1) để mã hoá nghĩa vụ Must Support theo vai trò, và 2 ActorDefinition (vn-core-actor-sender, vn-core-actor-receiver) làm đích actor.
Lý do:
obligation extension được HL7 phát hành bản R4 chính thức nên tương thích FHIR R4 (4.0.1).Lưu ý cross-version (rủi ro đã cân nhắc): ActorDefinition là resource bổ sung ở R5, KHÔNG thuộc R4 core. SUSHI sinh artifact sạch (0 lỗi) và IG Publisher hiện hành render được trong IG R4, nhưng đây là artifact mang tính tham chiếu (informative), không phải resource conformance R4 chuẩn. KHÔNG trỏ ActorDefinition qua CapabilityStatement.instantiates/imports (các trường này dành cho CapabilityStatement). Cần xác nhận lại ở lần build IG Publisher đầy đủ trước khi nâng lên normative; nếu tooling từ chối, phương án dự phòng là chuyển sang obligation documentation-based (không actor canonical).
Phạm vi pilot (0.6.0): VNCorePatient + VNCoreCoverage. Sender → SHALL:populate-if-known; Receiver → SHALL:no-error + SHALL:persist. Mở rộng dần sang lâm sàng/tài chính ở các bản sau (xem Hướng dẫn Must Support).
Các quyết định thiết kế được ghi trong governance/ và wiki/decisions/ để giữ dấu vết kiểm toán tách khỏi phần diễn giải của 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.6.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.
| Tài liệu | Tóm tắt | Lý do |
|---|---|---|
| v0.5 Căn cứ pháp lý có cấu trúc (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 citation pháp lý rải rác trong mô tả text; cho phép kiểm toán tự động, đánh dấu future-effective và kiểm soát văn bản hết hiệu lực. |
| v0.5 Gia cố quản lý pháp quy thiết bị (VNCoreExtDeviceRegistrationNumber, VNMedicalDeviceRegistrationNumberNS) | Thêm số lưu hành thiết bị y tế, ví dụ class A/B/C, gia cố nhóm rủi ro/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 đủ quản trị, nhưng thiết bị cấy ghép C/D cần dấu vết số lưu hành và vòng đời 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 gửi là luồng công việc/gateway ngữ nghĩa 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/QH15 và NĐ 356/2025/NĐ-CP 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/vòng đời/MS theo FHIR base và thêm VNCoreExtDeviceGroup ở mức phương án dự phòng; 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 ràng buộc mức required vào QĐ 847/QĐ-BYT/QĐ 3107/QĐ-BYT/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ờ quản trị. |
ADR-0007 — VNCoreImplantableDevice (wiki/decisions/adr-0007-implantable-device-profile.md) |
Thêm VNCoreImplantableDevice, patient-bound với patient/type/status 1..1, UDI/vòng đời/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 luồng công việc thực tế: MA_KHOA, cấp phát thuốc sau kê đơn, và siêu dữ liệu DICOM/RIS/PACS cho CĐHA. |
wave2-legal-consolidated (governance/v0.4-decisions/wave2-legal-consolidated.md) |
Tổng hợp 3 legal rà soát chéo 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/QĐ-BYT mã khoa 54 codes, TT 24/2025/TT-BYT cho TBYT, TT 26/2025/TT-BYT và NĐ 163/2025/NĐ-CP cho đơn thuốc/cấp phát, QĐ 2493/QĐ-BYT morphology binding extensible. |
| Nếu cần | Nên đọc tiếp |
|---|---|
| Hiểu ranh giới gói 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.