Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide
0.10.0 - Draft for Community Review
Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.10.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 tuyên bố tuân thủ VNCorePatient phải hỗ trợ slice identifier[CCCD]; khi chưa có giá trị thực, dùng data-absent-reason và định danh thay thế theo guidance. Đây là quy tắc tuân thủ của dự án để giữ khoá định danh lõi ổn định, không phải nguyên văn cardinality của TT 13/2025/TT-BYT. Điều 1 khoản 3 của Thông tư yêu cầu kết nối thông tin bệnh án điện tử với số định danh cá nhân của công dân Việt Nam và người nước ngoài đã được cấp tài khoản định danh điện tử. Hệ thống dùng VNeID để xác thực không ghi định danh ứng dụng VNeID vào patient identifier lõi nếu hợp đồng tích hợp không định nghĩa một identifier system tương ứng.
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ả (amendment 0.10.0): address.state giữ tên dạng text; extension tỉnh/xã giữ Coding tuỳ chọn với history binding. Mỗi cấp dùng một canonical ổn định, tên và cha gắn vào khoảng có bằng chứng; tập chọn hiện hành tách khỏi tập mã lịch sử. Address.district giữ text cũ và không Must Support; xã dùng extension riêng. Mã có trong history ValueSet không tự chứng minh hiệu lực tại ngày hồ sơ. Ngoại lệ chuyển đổi một lần chỉ áp dụng cho họ hành chính đã chốt trong hợp đồng, không thay quy tắc identity của miền khác.
Quyết định: VN Core công bố VNCoreConsent, VNCoreAuditEvent, VNCoreProvenance để các actor/use case có thể đưa chúng vào hợp đồng conformance. Việc Resource nào bắt buộc phải do CapabilityStatement, workflow và chính sách triển khai cụ thể xác định; không có blanket cardinality áp dụng cho mọi actor.
Lý do:
Hệ quả: Mỗi actor phải công bố phạm vi event, provenance và consent mà mình hỗ trợ; ma trận kiểm soát được dẫn xuất từ legal basis, threat model, DPIA/chính sách và integration contract. Không suy ra rằng FHIR server tự phát sinh AuditEvent/Provenance, hay Consent là căn cứ duy nhất cho mọi trao đổi.
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à 10 ActorDefinition làm đích actor: hai vai chung vn-core-actor-sender / vn-core-actor-receiver, cùng tám vai chuyên biệt vn-actor-emr-repository, vn-actor-citizen-app, vn-actor-bhyt-submitter, vn-actor-bhyt-adjudicator, vn-actor-document-source, vn-actor-data-requester, vn-actor-data-responder, vn-actor-eservice-gateway.
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 ở 0.10.0: sáu lát nghĩa vụ theo hướng luồng — CoreData (15 profile), EMR (44), Citizen App (16), BHYT Submission (7), BHYT Response (3), EService (3). Lát nền vẫn là Sender → SHALL:populate-if-known; Receiver → SHALL:no-error + SHALL:persist; các lát chuyên biệt gắn vào tám actor riêng (xem Hướng dẫn Must Support và Tuân thủ theo vai trò triển khai).
Quyết định (ADR-0024 §6, 21/08/2026): FHIR R4 cho phép biểu diễn cùng một sự việc bằng nhiều đường. VN Core không cấm các đường thay thế, nhưng công bố thứ tự ưu tiên để hai hệ thống không ghi cùng một dữ liệu theo hai kiểu rồi không đọc được của nhau.
| Nhóm | Ưu tiên | Ghi chú |
|---|---|---|
| Ký / xác nhận | Composition.attester — xác nhận nội dung tài liệu |
Người ký/xác nhận điện tử theo TT 13/2025/TT-BYT Điều 3 |
Provenance.signature — bằng chứng ký (chữ ký số) |
Chữ ký số theo NĐ 137/2024/NĐ-CP; attester KHÔNG chứa và không thay thế chữ ký |
|
Bundle.signature — toàn vẹn gói |
Áp cho cả gói khi truyền, không cho từng tài liệu | |
| Đơn vị và nơi | Organization — đơn vị chịu trách nhiệm |
Khoa/phòng trực thuộc dùng Organization con, không nhét tên khoa vào display của reference trỏ bệnh viện |
Location — nơi thực hiện |
Phòng, giường, cơ sở vật lý | |
| Xét nghiệm | song mã LOINC + VN CLS chỉ khi quan hệ ánh xạ là equivalent |
QĐ 1227/QĐ-BYT ban hành ánh xạ, nhưng chỉ 1.404/2.964 cặp là equivalent; 1.560 cặp wider KHÔNG được tự sinh coding LOINC (ghi rộng hơn thực tế) — xem Hướng dẫn thuật ngữ |
Lý do: ba nhóm này là chỗ bộ rà 97a đo được rằng cùng một dữ liệu có nhiều cách ghi đều hợp lệ (CORE-P2-96). Cấm bớt đường sẽ chặn dữ liệu có thật; để nguyên thì truy vấn không hội tụ. Công bố thứ tự ưu tiên giữ được cả hai.
Hệ quả: bên gửi chọn carrier ưu tiên khi có đủ dữ liệu; bên nhận PHẢI đọc được mọi carrier trong bảng. Ràng buộc cứng chỉ áp ở profile chuyên biệt của từng luồng, không áp toàn cục.
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.10.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 |
|---|---|---|
ADR-0021 — Ranh giới vòng đời tài chính (wiki/decisions/adr-0021-financial-lifecycle-boundaries.md) |
Bảng kê chi phí khám bệnh, chữa bệnh chuyển từ Claim.item sang VNCoreCostStatementInvoice.lineItem; VNCoreExtCoverageBenefitStage ngừng dùng, thay bằng VNCoreExtCostStatementSegment trên Invoice. |
Bảng kê là chứng từ chi phí của một đợt điều trị, còn Claim là hồ sơ đề nghị thanh toán gửi cơ quan bảo hiểm. Gộp hai việc vào một resource làm không phân biệt được chi phí phát sinh với số tiền đề nghị chi trả — đây là thay đổi phá vỡ tương thích lớn nhất của 0.10.0. |
ADR-0022 — Sở hữu canonical và gói pháp lý (wiki/decisions/adr-0022-canonical-ownership-legal-track.md) |
Tách hl7.fhir.vn.legal thành gói mô-đun thứ tám (tổng 9 gói kể cả gói tổng hợp); mỗi canonical có đúng một gói chủ; gói tổng hợp khai quan hệ phụ thuộc dạng DAG. |
Corpus pháp lý được nhiều miền dùng chung nên không thuộc riêng miền nào; để nó nằm trong core.base tạo vòng phụ thuộc mà package.json khai một chiều nên không lộ ra. |
| v0.5 Căn cứ pháp lý có cấu trúc (VNLegalDocumentRefCS, VNLegalDocumentRefVS, VNCoreExtLegalBasis) | Chuẩn hoá 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 hoá 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.