VN Core FHIR Implementation Guide
Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam — Vietnamese Core FHIR Implementation Guide
Package: hl7.fhir.vn.core |
Canonical: http://fhir.hl7.org.vn/core |
Category: National Base
| Version | Date | Status | Sequence | FHIR | Description |
|---|---|---|---|---|---|
| 0.9.0 (current) | 2026-07-27 | Trial Use | Community Review Draft | 4.0.1 | v0.9.0 là bản minor có breaking change, tập trung vào trục thanh toán BHYT và độ chính xác của chính bộ artifact. Trục thanh toán: profile bảng kê chi phí chi tiết nhiều giai đoạn hưởng theo QĐ 697/QĐ-BYT (VNCoreItemizedHealthcareCostClaim / VNCoreItemizedHealthcareCostExplanationOfBenefit); logical model biên bản quyết toán quý Mẫu số 06/BH theo TT 12/2026/TT-BTC kèm VNQuarterlySettlementIndicatorCS (55 chỉ tiêu) và validator ngoài kiểm 23 công thức nội tại + 6 quy tắc liên kỳ. Trục an toàn dữ liệu: VNCoreAuditEventLegalBasisDecision theo mô hình IHE BALP, VNAuditEventSubtypeCS, chuyển carrier căn cứ xử lý dữ liệu từ Consent sang AuditEvent (ADR-0019). Trục pháp lý: bổ sung ba văn bản hợp nhất luật nền — VBHN 40/VBHN-VPQH (Luật BHYT), VBHN 26/VBHN-VPQH (Luật KCB), VBHN 76/VBHN-VPQH (Luật Dược) — đưa kho pháp lý lên 206 văn bản, và ghi nhận Điều 44 Luật 114/2025/QH15 đưa khám sức khỏe định kỳ, khám sàng lọc, khám chữa bệnh từ xa và khám chữa bệnh tại nhà vào phạm vi hưởng BHYT với mức 100% cho lượt khám sức khỏe định kỳ hoặc khám sàng lọc miễn phí. Trục chất lượng: ba cổng kiểm ngữ nghĩa mới — đích ánh xạ của logical model, mốc thời gian ví dụ phải nằm trong Encounter.period, và số học tài chính của Claim/ClaimResponse/ExplanationOfBenefit. BREAKING: extension vn-ext-encounter-code bị gỡ hẳn sau khi giữ trạng thái retired trọn v0.8.0 — dữ liệu chuyển sang Encounter.identifier[maLuotKcb]; mã VNInsuranceVisitTypeCS#5 (không có trong QĐ 4210/QĐ-BYT) chuyển deprecated và mọi ví dụ đã chuyển sang mã 1 (đúng tuyến). v0.8.0 đóng băng nguyên trạng theo chính sách phát hành. |
| 0.8.0 | 2026-07-17 | Trial Use | Community Review Draft | 4.0.1 | v0.8.0 là bản minor có breaking change, chủ đề chính: tái cấu trúc toàn diện dữ liệu khám sức khỏe định kỳ (KSK) theo QĐ 2062/QĐ-BYT (07/07/2026) — văn bản thay Phụ lục 01/02/03 của QĐ 1551/QĐ-BYT — cùng đợt gia cố sửa lỗi hậu kiểm toán độc lập (Codex GPT-5.6). v0.7.0 được ĐÓNG BĂNG nguyên trạng (không sửa nội dung đã tag, đúng RELEASE-POLICY). (1) KSK BREAKING: 17 mẫu phiếu VNKSKQuestionnaire01–17 (QĐ 1551/QĐ-BYT) chuyển status retired; thay bằng 3 mẫu theo nhóm tuổi VNKSKQuestionnaireU06 (<6 tuổi, 109 trường), VNKSKQuestionnaire06to18, VNKSKQuestionnaire18Plus (QĐ 2062/QĐ-BYT Phụ lục 01) + mẫu khám sức khỏe tâm thần VNKSKQuestionnaireMental (TT 25/2026/TT-BYT Mẫu 04); VNHealthCheckupFormTypeCS +4 mã (#18–21); answer terminology hình thức hóa answerValueSet + VNKSKApneaCS/VS mới. (2) DOI_TUONG: VNHealthCheckupSubjectCS 14→16 mã — mã 14 đổi nghĩa 'Các đối tượng khác'→'Người lao động không chính thức', thêm 15 'Người chưa có BHYT' + 16 'Các đối tượng khác', nhiều mã cách nhau ';'. (3) Transport envelope theo QĐ 2062/QĐ-BYT: VNHealthCheckupG12EnvelopeLM tái dựng sang resource-sync (Phụ lục 03 — POST /api/platform/resource-sync/push, OAuth2 Bearer, service-type=100, txn_type=sync_ehr, RSASHA256); VNHealthCheckupDataSyncEnvelopeLM sửa Phụ lục 02 (sync_checkup, msg_id sender_id+YY+MM+DD+UUIDv4, RSASHA256, data_type chỉ xml/json base64). (4) Migrate căn cứ pháp lý KSK QĐ 1551/QĐ-BYT → QĐ 2062/QĐ-BYT trên 9 terminology + LogicalModel + 2 profile + CapabilityStatement. (5) Sửa hậu Codex review: ConceptMap CMVNCommunicableDiseaseToICD10 thêm target.comment cho 3 mapping #narrower (B40/B41/C14) đúng invariant cmd-1; VNEncounterTypeCS legal-basis telemedicine TT-30-2024→TT-30-2023; QuestionnaireResponse 18+ điền đủ 17 trường required; metadata TT 25/2026/TT-BYT sửa 3→4 Thông tư (+TT 42/2025/TT-BYT) và đa mốc hiệu lực (chung 15/08/2026, Điều 2+3 KSK 01/07/2026); 6 văn bản tiền nhiệm danh mục bệnh truyền nhiễm (QĐ 1988/2369/740/3896/3044/3644) đưa vào context-only hết phantom citation; rollover TT 18/2026/TT-BYT → in-force. Corpus VNLegalDocumentRefCS 172 văn bản. Phạm vi: 74 profiles, 153 CodeSystems, 156 ValueSets, 12 ConceptMaps (10 FSH + 2 JSON sinh từ dữ liệu nguồn), 19 SearchParameters, 32 NamingSystems. Không đổi canonical URL/package id. ĐỢT REMEDIATION HẬU KIỂM TOÁN (16-17/07/2026) bổ sung BREAKING: Consent restructure theo R4 (rule ở provision.provision, root không type; tách VNProcessingLegalBasisCS cho Điều 19; xóa invariant period-end); xóa sub-extension restrictedSensitivity (deny theo lớp qua securityLabel); Patient identifier slicing theo Identifier.type (MRN per-facility); sid/bhyt chỉ 2 format (CCCD ra khỏi namespace); tách giai đoạn hiệu lực vn-health-checkup-subject-legacy + vn-province-legacy (CM 63/63 từ NQ 202/2025/QH15); rename vn-qd3176-cost-group→vn-bhyt-claim-cost-group (ADR-0017). Viện dẫn Luật 91/NĐ 356/2025/NĐ-CP theo bản BAN HÀNH + ma trận điều khoản 47 claims + 2 gate CI mới + oracle negative-fixtures. Số liệu sau remediation: 74 profiles, 53 extensions, 153 CodeSystems, 156 ValueSets, 12 ConceptMaps, corpus 172 văn bản. |
| 0.7.0 | 2026-07-13 | Trial Use | Community Review Draft | 4.0.1 | [SUPERSEDED 16/07/2026 — đóng băng nguyên trạng sau kiểm toán độc lập Codex; thay bằng v0.8.0] v0.7.0 là bản gia cố phát hành sau kiểm toán độc lập hậu v0.6.1; v0.6.1 được đánh dấu withdrawn (failed release candidate) thay vì sửa âm thầm nội dung đã public. (1) Tài chính BHYT: exporter round-trip xuất đủ T_NGUONKHAC_NSNN/VTNN/VTTN/CL + T_NGUONKHAC theo từng dòng XML2/XML3 từ extension vn-ext-other-fund-breakdown và áp quy tắc giảm trừ tuần tự T_BNTT → T_BNCCT → T_BHTT theo QĐ 3176/QĐ-BYT; rule phân bổ quỹ theo dòng (BHYT-EXPORT-032) cộng T_NGUONKHAC nên hồ sơ hợp lệ 60+10+10+20=100 không còn bị từ chối; TYLE_TT_DV vắng mặt xuất 100 thay vì lấy nhầm TYLE_TT_BH; THANH_TIEN_BH dùng công thức đầy đủ Bảng 3 khi có DON_GIA_BH; thêm rule cảnh báo BHYT-EXPORT-035 khi MA_THE_BHYT mang định danh thay thế (CCCD 12 số/mã BHXH 10 số). (2) XML13/XML14: MA_TTDV đọc từ người ký giấy (DocumentReference.author qua context.related, hoặc performer Practitioner với giấy hẹn) — không còn fallback về bác sĩ chỉ định; fixture chuyển tuyến bổ sung giấy chuyển tuyến có chữ ký Giám đốc TTYT. (3) Conformance: invariant vn-gestational-age-range dùng $this trên valueInteger (giá trị hợp lệ 1–42 tuần validate được); 4 operation chuyển từ system-level rest.operation về đúng resource (Bundle/$validate-bhyt-claim, Bundle/$submit-bhyt-claim, Claim/$reverse-bhyt-claim, Patient/[id]/$summary) trên cả 3 CapabilityStatement. (4) Gói modular: hl7.fhir.vn.bhyt.submission nhận đủ delta 0.6.x (3 LM XML13–15, 6 bundle ví dụ, eligibility profiles + examples, bộ mã GIOI_TINH/MA_LYDO_CT/MAU_SO + ConceptMap giới tính, 2 bộ mã điều trị lao mới); các extension chứa bởi VNCoreClaim giữ ở core.base có chủ ý để đúng chiều dependency. (5) Terminology mới: VNTBTreatmentTypeCS (LOAI_DTRI_LAO 0–3) + VNTBRegimenCS (PHACDO_DTRI_LAO 1–27, Bảng 15) — ví dụ lao hết coding thiếu system. (6) Pháp lý: property status của VNLegalDocumentRefCS chuyển type Coding (hệ VNLegalDocumentStatusCS) đúng FHIR R4; rollover trạng thái ngày 13/07/2026 cho 8 văn bản chạm mốc hiệu lực 01/07/2026; corpus thêm TT 56/2017/TT-BYT, TT 18/2022/TT-BYT, TT 30/2020/TT-BYT và 8 văn bản đợt hiệu lực 01/07/2026 — TT 13/2026/TT-BYT (tiêm chủng), NĐ 165/2026/NĐ-CP (hướng dẫn Luật Phòng bệnh), TT 12/2026/TT-BYT (sàng lọc trước sinh/sơ sinh), NĐ 168/2026/NĐ-CP (hướng dẫn Luật Dân số), TT 16/2026/TT-BYT (hỗ trợ thuốc miễn phí), NĐ 161/2026/NĐ-CP (lương cơ sở), NQ 21/2026/NQ-CP (phân cấp GPHN), Luật 148/2025/QH15 (Chuyển đổi số) — tổng 145 văn bản, hết phantom citation; sửa 5 file full-text gán nhầm nội dung (Luật 116/2025/QH15 ⟂ QĐ 3090, QĐ 387/QĐ-BYT ⇄ QĐ 11/2026/QĐ-TTg, TT 55/2025/TT-BYT ⇄ TT 56/2025/TT-BYT) ở cả tầng PDF nguồn. (7) Versioning & policy: 186 file artifact bump ^version theo last-changed policy (0.7.0), 3 bump khống được hoàn tác, VNGenerateIPSSummary khai version tường minh; 3 breaking change tồn đọng của 0.6.x được công bố đúng SemVer kèm hướng dẫn migration: Encounter.serviceProvider 0..1→1..1, MedicationRequest.requester loại Organization, vn-ext-encounter-code khôi phục ở trạng thái retired (dữ liệu mới dùng Encounter.identifier[maLuotKcb]) và sẽ gỡ ở v0.8.0. (8) Nền build: hl7.terminology.r4 7.2.0, hl7.fhir.uv.ips 2.0.1; auto-oid-root 2.25.x ghi nhận suppress có hồ sơ. Không đổi canonical URL, package id. |
| 0.6.1 | 2026-07-10 | Trial Use | Community Review Draft | 4.0.1 | [WITHDRAWN 13/07/2026 — rút lại sau kiểm toán hậu phát hành; thay bằng v0.7.0] v0.6.1 patch additive hậu-v0.6.0, chủ đề duy nhất: hoàn thiện chuẩn hóa dữ liệu đầu ra BHYT theo QĐ 3176/QĐ-BYT trên toàn bộ 16 bảng phụ lục (~479 chỉ tiêu, đối chiếu nguyên văn bản .docx kèm phụ lục — persist tại analysis/qd3176-appendix). (1) Logical model: 3 LM mới BHYTXML13ReferralLM (giấy chuyển tuyến, 37 chỉ tiêu), BHYTXML14FollowUpAppointmentLM (giấy hẹn khám lại, 22), BHYTXML15TuberculosisLM (quản lý điều trị lao, 20); BHYTCheckInLM mở rộng 7→26 field; vá 39 field thiếu + 84 mapping vn-fhir cho XML1–XML12 — mỗi bảng phủ 100% chỉ tiêu spec; sửa mô tả sai maPtttQt (ICD-9-CM, không phải phương thức thanh toán). (2) Terminology: VNAnesthesiaMethodCS/VS (PP_VO_CAM), VNDocumentFormCS/VS (MAU_SO CT07), VNCareTransferReasonCS/VS (MA_LYDO_CT), VNGenderCS/VS + ConceptMap CMVNGenderToAdministrativeGender (GIOI_TINH 1/2/3 ↔ administrative-gender). (3) Carrier: VNCoreExtOtherFundBreakdown (T_NGUONKHAC_* per-line), paymentCeiling (T_TRANTT, NĐ 188/2025/NĐ-CP) vào InsuranceCostInfo, totalInsuranceFeeForService (T_BHTT_GDV) vào ClaimCostSummary, VNCoreExtGestationalAge (TUOI_THAI 1–42 tuần), VNCoreExtAnesthesiaMethod. (4) Validation: 3 invariant công thức tài chính (T_BHTT, SO_NGAY_DTRI, SO_NGAY) + sửa 2 adapter rule EXPORT-005/006 thiếu thừa số tỷ lệ + 4 rule mới EXPORT-031..034 (định danh phân bổ quỹ per-line và cấp hồ sơ). (5) Round-trip: exporter xuất GIOI_TINH/GIOI_TINH_CON theo mã 1/2/3 (trước đây rò rỉ enum FHIR male/female), bổ sung seed + adapter rules XML13/14/15, per-line T_BNTT/T_BNCCT/T_BHTT, T_TONGCHI_BH cấp hồ sơ. Không đổi canonical URL, package id hoặc semantic lõi. |
| 0.6.0 | 2026-06-04 | Trial Use | Community Review Draft | 4.0.1 | v0.6.0 minor release, bổ sung ba trục lớn trên nền v0.5.3. (1) Quản lý chăm sóc: VNCoreCarePlan/CareTeam/Goal/EpisodeOfCare/ClinicalImpression + VNCoreMedicationStatement/MedicationAdministration, khép bộ ba CarePlan→Goal→CareTeam và chuỗi kê đơn→cấp phát→sử dụng; thang phân loại ưu tiên cấp cứu VNCoreObservationTriageAcuity (thang đề xuất nội bộ tham chiếu ATS, QĐ 01/2008/QĐ-BYT làm căn cứ nguyên tắc ưu tiên — xem ADR-0014). (2) KSK liên thông theo HL7 SDC: VNCoreQuestionnaire/QuestionnaireResponse + 17 mẫu phiếu VNKSKQuestionnaire01–17 theo QĐ 1551/QĐ-BYT Phụ lục 01 (linkId = mã trường), kèm VNCoreFamilyMemberHistory (xem ADR-0015). (3) Tương tác quốc tế: VNCoreCompositionIPS kế thừa Composition-uv-ips + OperationDefinition $summary (projection Sổ SKĐT nội địa → IPS Bundle), dependency hl7.fhir.uv.ips#2.0.0, cầu thuật ngữ SNOMED CT qua VNSNOMEDSubsetCS (xem ADR-0016). Legal corpus VNLegalDocumentRefCS thêm QĐ 2919/QĐ-BYT (chuẩn dữ liệu Giấy chứng sinh) → 134 concepts; public registry mirror đủ 134 mục có nguồn đối chiếu; actionable legal citation coverage 83/83 (100%). Profiles 52→73, CodeSystems 75→139, ValueSets 81→144, ConceptMaps 5→6, extensions 48 (gồm 45 cục bộ + 3 HL7). Không đổi canonical URL, package id hoặc semantic lõi. v0.6.0 nâng độ chín 3 trục theo review độc lập: (SDC) VNCoreQuestionnaire/QuestionnaireResponse DẪN XUẤT hl7.fhir.uv.sdc#4.0.0, formal-hoá toàn bộ 5.523 answer code (285 hệ ad-hoc → 56 CodeSystem chính thức căn cứ QĐ 1551/QĐ-BYT) + answerValueSet + required + artifact-versionAlgorithm semver; (IPS) thêm VNCoreBundleIPS (kế thừa Bundle-uv-ips) + ví dụ document Bundle hợp lệ + ràng $summary; (SNOMED) ConceptMap ICD-10 VN → SNOMED CT. Phần lớn mức tăng CodeSystems/ValueSets đến từ bước formal-hoá answer terminology. |
| 0.5.3 | 2026-05-30 | Trial Use | Community Review Draft | 4.0.1 | Patch additive hậu-v0.5.2, các đóng góp core-bound cho IG phái sinh CHC: thêm VNBasicHealthServiceCS/VS (74 concept) theo TT 30/2024/TT-BYT (gói dịch vụ y tế cơ bản TYT xã), trục bối cảnh cung cấp dịch vụ VNServiceDeliverySettingCS/VS (6 mã), và vòng đời mã cơ sở trên VNCoreOrganization (extension VNCoreExtOrgLifecycleRelation + identifier.period, VNOrgLifecycleRelationCS 4 mã + VNOrgCarryOverItemCS 5 mã) cho sáp nhập/chia tách cơ sở y tế theo NQ 202/2025/QH15. VNLegalDocumentRefCS lên 117 concepts (thêm TT 30/2024/TT-BYT); actionable legal citation coverage 74/74 (100%); registry public giai đoạn v0.5 có 101 mục nguồn TVPL exact. Trạng thái public hiện hành của v0.6.0 là 134 nguồn. |
| 0.5.2 | 2026-05-29 | Trial Use | Community Review Draft | 4.0.1 | Patch additive hậu-v0.5.1: mở rộng VNLegalDocumentRefCS lên 116 concepts (thêm Luật Dân số 113/2025/QH15 future-effective 01/07/2026, TT 11/2026/TT-BYT, nhóm QĐ triển khai EMR/SKĐT — QĐ 31/QĐ-BYT/QĐ 586/QĐ-BYT/QĐ 965/QĐ-BYT, cặp thay thế QĐ 582/QĐ-BYT↔QĐ 32/QĐ-BYT và QĐ 966/QĐ-BYT↔QĐ 658/QĐ-BYT, QĐ 486/QĐ-BYT YHCT, QĐ 622/QĐ-BYT điện quang, các VBHN hợp nhất); thêm ValueSet VNFetalSexDisclosureDiseaseVS (137 dòng STT / 136 mã ICD-10 unique) gắn căn cứ pháp lý qua vn-ext-legal-basis. Giữ actionable legal citation coverage 73/73 (100%); registry public giai đoạn v0.5 có 101 mục nguồn TVPL exact. Trạng thái public hiện hành của v0.6.0 là 134 nguồn. |
| 0.5.1 | 2026-05-10 | Trial Use | Community Review Draft | 4.0.1 | Patch hậu-v0.5.0 release: fix 17 audit findings consistency; thêm governance/roadmap.json + release-manifest.json là single source of truth; migrate 26 P2 orphan documents (60% → 100% actionable); thêm 4 examples (PaymentReconciliation, EndpointBHYT, HealthcareService TYTXa, BreachNotification); SEO + housekeeping. |
| 0.5.0 | 2026-05-01 | Trial Use | Community Review Draft | 4.0.1 | Community Review Draft — v0.5: structured legal reference framework (VNLegalDocumentRefCS 101 docs), device cluster hardening, future-effective marker, audit tooling. 52 profiles, 70 CodeSystems, 75 ValueSets, 5 ConceptMaps. |
| 0.4.0 | 2026-04-24 | Trial Use | Community Review Draft | 4.0.1 | Community Review Draft — Wave 2: imaging, pharmacy, devices, departments. 48 profiles, 65 CodeSystems, 70 ValueSets, 4 ConceptMaps. |
| 0.3.0 | 2026-03-25 | Trial Use | Community Review Draft | 4.0.1 | Community Review Draft — Wave 1: first public release. Demographics, BHYT submission, baseline terminology, outpatient workflows. 32 profiles, 52 CodeSystems, 54 ValueSets, 2 ConceptMaps. |
| current | 2026-05-30 | CI Build | 4.0.1 | Continuous Integration Build (latest in version control) |
Được sinh tự động từ metadata phát hành của gói. Xem package-list.json để biết thêm chi tiết.