# Lịch sử thay đổi - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Lịch sử thay đổi

# Lịch sử thay đổi — Changelog

Lịch sử thay đổi theo từng phiên bản.

-------

## Cách dùng changelog

* Nếu bạn đang nâng phiên bản, hãy đọc từ phiên bản mới nhất trở xuống và tập trung vào các thay đổi có khả năng ảnh hưởng đến ánh xạ dữ liệu, validation, package dependency và hành vi tìm kiếm.
* Nếu bạn là reviewer hoặc thành viên cộng đồng, hãy dùng changelog để theo dõi hướng trưởng thành của IG, không dùng nó thay cho tài liệu hướng dẫn triển khai.
* Nếu bạn cần quyết định có nên nâng phiên bản ngay hay chưa, hãy đọc thêm [Ổn định và tuân thủ](stability-and-conformance.md) và [Phát hành và quản trị](release-governance.md).

## Phiên bản 0.5.0 — Draft for Community Review (2026-05-01)

**Trạng thái**: Bản công bố hiện hành — structured legal references, device/BHYT hardening và pilot readiness

### Ảnh chụp phát hành

* **52 hồ sơ**, **44 phần mở rộng cục bộ + 3 chuẩn HL7**, **70 CodeSystems**, **75 ValueSets**, **5 ConceptMaps**
* **19 SearchParameters**, **22 NamingSystems**, **13 logical models**, **3 OperationDefinitions**, **5 CapabilityStatements**
* **152 tệp ví dụ / 154 thực thể ví dụ**, **294 total instances**, **476 exported JSON artifacts**
* `VNLegalDocumentRefCS` công bố **101 văn bản pháp lý structured** theo 18 miền public, kèm trạng thái hiệu lực và quan hệ thay thế

### Structured legal references

* Thêm [VNLegalDocumentRefCS](CodeSystem-vn-legal-document-ref-cs.md) và [VNLegalDocumentRefVS](ValueSet-vn-legal-document-ref-vs.md) làm registry pháp lý máy đọc được.
* Thêm [VNCoreExtLegalBasis](StructureDefinition-vn-ext-legal-basis.md) để gắn căn cứ pháp lý ở mức artifact hoặc element.
* Thêm audit tooling cho citation: kiểm tra `future-effective`, văn bản đã bị thay thế, inline-only citation và coverage theo artifact.
* Mở rộng legal corpus lên 101 văn bản, bao gồm nhóm pháp lý 2026 như VBHN 04/06/08, TT 12/2026/BTC, NĐ 233/2025 và các luật/văn bản mới liên quan dữ liệu, an ninh mạng, phòng bệnh và y tế cơ sở.

### Profiles mới hoặc được public surface trong v0.5

* [VNCorePaymentReconciliation](StructureDefinition-vn-core-payment-reconciliation.md) — quyết toán/thanh toán BHYT theo chu kỳ và biên bản 06/BH, dùng `claimAuditStatus` để biểu diễn vòng đời giám định nội địa.
* [VNCoreEndpointBHYT](StructureDefinition-vn-core-endpoint-bhyt.md) — endpoint cổng `gdbhyt` cho lớp gateway/facade BHYT.
* [VNCoreHealthcareService](StructureDefinition-vn-core-healthcare-service.md) — dịch vụ y tế, đặc biệt cho TYT cấp xã/phường/đặc khu sau mô hình chính quyền 2 cấp.
* [VNCoreCompositionBreachNotification](StructureDefinition-vn-core-composition-breach-notification.md) — Composition structured cho Mẫu 08 NĐ 356/2025 về thông báo vi phạm DLCN.

### Device cluster hardening

* Thêm [VNCoreExtDeviceRegistrationNumber](StructureDefinition-vn-ext-device-registration-number.md) và [VNMedicalDeviceRegistrationNumberNS](NamingSystem-vn-medical-device-registration-number-ns.md) cho số lưu hành TBYT.
* Gia cố `VNCoreImplantableDevice`: risk class, số lưu hành, UDI carrier và lifecycle được nâng mức kỳ vọng cho thiết bị cấy ghép C/D.
* Bổ sung ví dụ thiết bị class A/B/C: `ExampleDeviceVTYTN03Syringe`, `ExampleDeviceVTYTClassBThermometer`, `ExampleDeviceImplantDentalClassC`.
* Giữ danh pháp thiết bị trong package `.device`; Core không hard-bind `Device.type` vào một danh mục duy nhất khi governance danh pháp chưa ổn định.

### BHYT, consent và audit

* Thêm [VNCoreExtClaimAuditStatus](StructureDefinition-vn-ext-claim-audit-status.md) và [VNCoreExtPaymentReconciliationForm](StructureDefinition-vn-ext-payment-reconciliation-form.md) cho quyết toán BHYT.
* Thêm [VNCoreExtCoverageCumulativeCopay](StructureDefinition-vn-ext-coverage-cumulative-copay.md), [VNCoreExtPaymentSource](StructureDefinition-vn-ext-payment-source.md), [VNCoreExtTenderInfo](StructureDefinition-vn-ext-tender-info.md), [VNCoreExtTraditionalProcessingMethod](StructureDefinition-vn-ext-traditional-processing-method.md) và [VNCoreExtRecurrentWoundBenefit](StructureDefinition-vn-ext-recurrent-wound-benefit.md) để làm rõ carrier thanh toán/gateway theo QĐ 3176 và QĐ 697.
* Thêm [VNCoreExtConsentMethod](StructureDefinition-vn-ext-consent-method.md) và [VNCoreExtAuditRetention](StructureDefinition-vn-ext-audit-retention.md) cho baseline Luật 91/2025 và NĐ 356/2025.

### Tác động nâng cấp

* Bản `0.5.0` là additive/hardening release: không đổi canonical URL, không đổi package id, không thay thế semantics lõi của `Patient`, `Encounter`, `Condition`, `Observation`.
* Bên triển khai đang dùng `0.4.0` nên ưu tiên rà lại device identifiers, legal citation, BHYT reconciliation/gateway boundary và privacy incident/audit policy trước khi pilot.

## Phiên bản 0.4.0 — Wave 2 (2026-04-14)

**Trạng thái**: Draft for Community Review — bổ sung lớp CĐHA, Dược, Thiết bị và Khoa phòng

### Ảnh chụp phát hành

* **48 hồ sơ** (thêm 7), **34 phần mở rộng cục bộ + 3 chuẩn HL7**, **64 CodeSystems**, **69 ValueSets**, **4 ConceptMaps**
* **145 tệp ví dụ / 146 thực thể ví dụ**, **274 total instances** trong release metrics; `sushi .` import 274 FSH instances

### Profiles mới (7)

* [`VNCoreOrganizationDepartment`](StructureDefinition-vn-core-organization-department.md) — Khoa/Phòng theo QĐ 2010/QĐ-BYT (19/6/2025) Phụ lục 6; identifier slicing `departmentCode` (K01-K53, K99) + `localCode`; type fixed `dept`; `partOf` bắt buộc tham chiếu CSYT chủ quản
* [`VNCoreMedicationDispense`](StructureDefinition-vn-core-medication-dispense.md) — Cấp phát thuốc, liên thông BHYT chain qua `authorizingPrescription` → `VNCoreMedicationRequest`
* [`VNCoreImagingStudy`](StructureDefinition-vn-core-imaging-study.md) — Nghiên cứu CĐHA (DICOM StudyInstanceUID); procedureCode/reasonCode/bodySite bindings cho ICD-10 VN + SNOMED CT VN Body Structure
* [`VNCoreDiagnosticReportLab`](StructureDefinition-vn-core-diagnostic-report-lab.md), [`VNCoreDiagnosticReportImaging`](StructureDefinition-vn-core-diagnostic-report-imaging.md), [`VNCoreDiagnosticReportPathology`](StructureDefinition-vn-core-diagnostic-report-pathology.md) — 3 sub-profiles kế thừa `VNCoreDiagnosticReport` theo pattern parent-child kiểu JP Core; category slice theo `coding.code` (LAB/RAD/PAT) + nhóm chi phí BHYT (QĐ 697 nhóm 3/4)
* [`VNCoreImplantableDevice`](StructureDefinition-vn-core-implantable-device.md) — Thiết bị cấy ghép patient-bound theo pattern US Core; `patient/type/status 1..1`, UDI/lifecycle/safety MS, không hard mandate UDI toàn Core

### Refactor trọng tâm

* **VNCoreDevice**: nâng từ **2 MS → 12+ MS** với identifier slicing (`medicalDeviceItemCode`, `serialNumber`), UDI carrier theo FHIR base, full lifecycle (manufactureDate/expirationDate/lotNumber/serialNumber/modelNumber), extension `VNCoreExtDeviceGroup` fallback và `VNCoreExtDeviceRiskClass` optional; dữ liệu thanh toán TBYT ưu tiên ở `Claim.item`; `type` được relax về `0..1 MS` để không reject dữ liệu legacy/BHYT thiếu danh pháp chuẩn
* **VNCoreProcedure**: bổ sung `focalDevice` Must Support cho thủ thuật đặt/tháo/thay/điều chỉnh thiết bị; example PCI đặt stent và tháo lưới lọc tĩnh mạch chủ dùng `Procedure.focalDevice`, còn theo dõi đang sử dụng dùng `DeviceUseStatement`
* **VNCoreDiagnosticReport**: trở thành parent profile với `category` slicing open on `coding.code`; `result` relax xuống `Observation` base để children re-tighten
* **ExampleDeviceImplant** đổi sang `VNCoreImplantableDevice` cho Stent mạch vành (SCT 360046005) + deviceGroup N06.00.000, có patient/lifecycle/UDI HRF; bổ sung `ExampleDeviceImplantIVCFilter` và `ExampleProcedureIVCFilterRemoval` cho ca explant hợp lý về mặt lâm sàng

### Extensions mới (2)

* [`VNCoreExtDeviceGroup`](StructureDefinition-vn-ext-device-group.md) — Nhóm thiết bị y tế theo danh mục BHYT (N01-N09); Context: `Claim.item` ưu tiên và `Device` legacy/fallback; binding extensible [VNDeviceGroupVS](ValueSet-vn-device-group-vs.md)
* [`VNCoreExtDeviceRiskClass`](StructureDefinition-vn-ext-device-risk-class.md) — Phân loại rủi ro A/B/C/D theo NĐ 98/2021/NĐ-CP Điều 4 và TT 05/2022/TT-BYT; optional trên `Device`, không thay nhóm BHYT hoặc `Device.type`

### Terminology mới và cập nhật

* [`VNDeviceGroupCS`](CodeSystem-vn-device-group-cs.md) + [`VNDeviceGroupVS`](ValueSet-vn-device-group-vs.md) — 9 codes `N01.00.000..N09.00.000` theo TT 04/2017/TT-BYT Phụ lục 01 + TT 24/2025/TT-BYT (đổi thuật ngữ VTYT → TBYT) + VBHN 14/VBHN-BYT
* [`VNDeviceRiskClassCS`](CodeSystem-vn-device-risk-class-cs.md) + [`VNDeviceRiskClassVS`](ValueSet-vn-device-risk-class-vs.md) — 4 codes `A..D` theo NĐ 98/2021/NĐ-CP Điều 4; dùng cho risk class optional, không dùng làm danh pháp thiết bị
* `VNMedicalDeviceNomenclatureCS` + `VNMedicalDeviceNomenclatureVS` + `VNDeviceTypeVS` — 956 concept danh pháp thiết bị trong package `hl7.fhir.vn.device`, tổng hợp QĐ-3107/QĐ-BYT-2024 và QĐ-847/QĐ-BYT-2025 theo provenance concept-level; Core không required-bind `Device.type`
* [`VNExaminationCodeCS`](CodeSystem-vn-examination-code-cs.md) — fragment 2 mã khám bệnh dùng cho positive seed XML3, có provenance từ Phụ lục 2 QĐ 2010/QĐ-BYT; hiện cover `02.05` cho `Nội tiêu hóa` và `10.22` cho `Ngoại tiêu hóa`, còn 2 row consultation/care chưa đủ sạch vẫn giữ ở catalog ví dụ cục bộ riêng.
* [`VNBedDayCodeCS`](CodeSystem-vn-bed-day-code-cs.md) — fragment 2 mã ngày giường dùng cho positive seed XML3, có provenance từ Phụ lục 3 QĐ 2010/QĐ-BYT; hiện cover `K22.NG1` và `K48.HSTC`, trong khi 2 row consultation/care chưa đủ sạch vẫn giữ ở catalog ví dụ cục bộ riêng.
* [`VNBHYTFinancialFieldCS`](CodeSystem-vn-bhyt-financial-field-cs.md) + [`VNBHYTFinancialFieldVS`](ValueSet-vn-bhyt-financial-field-vs.md) — 14 trường tổng tiền BHYT (`T_TONGCHI`, `T_BHTT`, `T_BNCCT`, `T_BNTT`, `T_NGUONKHAC*`, `T_NGOAIDS`, `T_THUOC`, `T_VTYT`) làm source traceability cho cost summary/adjudication.
* [`VNBHYTAdjudicationCategoryCS`](CodeSystem-vn-bhyt-adjudication-category-cs.md) + [`VNBHYTAdjudicationCategoryVS`](ValueSet-vn-bhyt-adjudication-category-vs.md) — 5 category cục bộ (`patient-self-pay`, `other-fund`, `non-covered`, `medication-subtotal`, `supplies-subtotal`) để bổ sung HL7 `adjudication` ở `ClaimResponse.total`/`EOB.total`.
* [`ConceptMap/vn-cm-bhyt-financial-field-to-adjudication`](ConceptMap-vn-cm-bhyt-financial-field-to-adjudication.md) — ánh xạ trường tổng tiền BHYT sang HL7 adjudication và category cục bộ; không encode công thức quyền lợi hoặc catalog lý do từ chối của payer.
* [`VNMorphologyVS`](ValueSet-vn-morphology-vs.md) — Subset SNOMED CT filter `concept is-a #49755003` (Morphologically abnormal structure) theo QĐ 2493/QĐ-BYT (08/2025) ~5.155 codes; dùng cho `VNCoreDiagnosticReportPathology.conclusionCode` extensible binding
* [`VNDepartmentCS`](CodeSystem-vn-department-cs.md): 51 → **54 codes** (thêm K51 Đột quỵ, K52 Phẫu thuật tạo hình thẩm mỹ, K53 Nam học) per QĐ 2010/QĐ-BYT Phụ lục 6 (tiền nhiệm QĐ 5937/QĐ-BYT bị bãi bỏ phần Phụ lục 5)

### Cơ sở pháp lý bổ sung

* **Thiết bị y tế**: TT 04/2017/TT-BYT Phụ lục 01, TT 24/2025/TT-BYT (30/6/2025, HL 01/9/2025), VBHN 14/VBHN-BYT
* **Khoa/Phòng**: QĐ 2010/QĐ-BYT (19/6/2025) Phụ lục 6, QĐ 3176/QĐ-BYT (MA_KHOA trong XML đầu ra KCB)
* **Dược**: Luật 105/2016/QH13 Điều 74 (sửa đổi bởi Luật 44/2024/QH15 Điều 1 khoản 36), NĐ 163/2025/NĐ-CP (29/6/2025, thay NĐ 54/2017 từ 01/7/2025), TT 26/2025/TT-BYT (Điều 5/10/12 — đơn điện tử, liên thông Hệ thống đơn thuốc QG), TT 27/2025/TT-BYT (thuốc YHCT BHYT)
* **Danh mục kỹ thuật và CĐHA/GPB**: QĐ 1227/QĐ-BYT (11/4/2025) — 2.964 mã CLS 5 nhóm (HH-TM 1.022, Hóa sinh 447, Vi sinh 174, GPB 81, Điện quang 1.240); TT 23/2024/TT-BYT (thay TT 43/2013 từ 18/10/2024); TT 38/2024/TT-BYT — Hệ thống thông tin KCB; QĐ 697/QĐ-BYT (19/3/2026) — 12 nhóm chi phí; QĐ 2427/QĐ-BYT + QĐ 2493/QĐ-BYT — SNOMED CT VN Body Structure + Morphology; QĐ 3148/QĐ-BYT (2017) — liên thông công nhận KQXN

### Văn bản đánh dấu legacy / hết hiệu lực

* NĐ 54/2017/NĐ-CP — hết hiệu lực 01/7/2025 (thay bởi NĐ 163/2025/NĐ-CP Điều 129)
* TT 43/2013/TT-BYT — hết hiệu lực 18/10/2024 (thay bởi TT 23/2024/TT-BYT); chapter mapping chính xác cho backward audit: Ch. XVIII = CĐHA, Ch. XXI = TDCN, Ch. XXIV = Vi sinh, Ch. XXV = GPB

### Quản trị thiết kế (Design Decisions v0.4)

* `DD-v04-05` — DiagnosticReport sub-profiles (pattern parent-child)
* `DD-v04-06` — Device refactor (identifier slicing + UDI + deviceGroup)
* `DD-v04-07` — Missing Profiles (OrgDept + MedDispense + ImagingStudy)
* `ADR-0005` — `VNCoreDevice.type 0..1 MS`, chưa required binding danh pháp thiết bị
* `ADR-0007` — thêm `VNCoreImplantableDevice` patient-bound
* `wave2-legal-consolidated` — tổng hợp 3 Codex legal cross-reviews (nguồn: governance/v0.4-decisions/)

-------

## Phiên bản 0.3.0 — Bản ổn định trước thí điểm (03/2026)

**Trạng thái**: Draft for Community Review — bản lịch sử trước Wave 2

### Ảnh chụp phát hành

* **32 hồ sơ**, **27 phần mở rộng cục bộ + 3 phần mở rộng Patient chuẩn HL7**, **52 CodeSystems**, **54 ValueSets**
* **14 SearchParameters**, **19 NamingSystems**, **13 logical models**, **3 OperationDefinitions**
* **122 tệp ví dụ / 123 thực thể ví dụ**
* **232 thực thể / 345 tài nguyên JSON xuất ra** sau `sushi .`

### Tài nguyên mới hoặc bổ sung trọng tâm

* **Profiles**: `VNCoreBundle`, `VNCoreBHYTSubmissionBundle`, `VNCoreConsent`, `VNCoreComposition`, `VNCoreAuditEvent`, `VNCoreProvenance`, `VNCoreRelatedPerson`
* **Gia cố lớp hành chính**: thêm `VNCoreLocation` để tách khoa/phòng/địa điểm cung cấp dịch vụ khỏi `Organization`
* **Gia cố quy trình xét nghiệm**: thêm `VNCoreSpecimen`, nối chuỗi `ServiceRequest -> Specimen -> ObservationLab -> DiagnosticReport`, bổ sung ví dụ mẫu huyết thanh, máu toàn phần, nước tiểu và tình huống xét nghiệm đầu-cuối
* **Hướng dẫn Must Support**: thêm trang `must-support-guidance.md`, chốt cách diễn giải Must Support, bảng xử lý thiếu dữ liệu và cẩm nang HIS -> FHIR cho bệnh nhân, lượt khám, tài liệu, BHYT và hồ sơ thanh toán
* **Ma trận pháp lý theo miền**: thêm mục **Ma trận pháp lý theo hồ sơ** trong `legal-basis.md`, tách lớp căn cứ hiện hành / lịch sử / quyết định thiết kế cho 4 nhóm hồ sơ chính: Patient/RelatedPerson, Practitioner/Organization/Location, tài liệu lâm sàng và lớp liên thông hồ sơ BHYT (`BHYT Submission`)
* **Kiến trúc gói phát hành**: thêm trang `package-architecture.md`, chốt mô hình `4` gói mô-đun (`core.base`, `bhyt.submission`, `terminology.clinical`, `terminology.traditional-medicine`) và `1` gói tổng hợp
* **Tách gói phát hành**: mở rộng cơ chế build để sinh `hl7.fhir.vn.core`, `hl7.fhir.vn.core.base`, `hl7.fhir.vn.bhyt.submission`, `hl7.fhir.vn.terminology.clinical` và `hl7.fhir.vn.terminology.traditional-medicine` từ cùng một kho mã nguồn biên soạn
* **Hồ sơ công bố mô-đun**: bổ sung `package-list.json`, `history.html`, và trang đích công bố tối thiểu cho từng gói mô-đun ngay trong cùng website `fhir.hl7.org.vn/core`
* **Gia cố template phát hành**: chuyển nền HTML build từ `fhir.base.template` sang `fhir2.base.template` theo thông báo bảo mật ngày 17/03/2026 của FHIR Foundation, loại bỏ phụ thuộc vào template cũ đã ngừng hỗ trợ
* **Chuẩn hóa Patient**: `VNCorePatient` chuyển sang dùng các extension chuẩn `patient-religion`, `patient-citizenship`, `patient-birthPlace`; thêm các lát cắt `BHXH`, `GKS`, `HC` và `contact` cho luồng người giám hộ
* **Chuẩn hóa Coverage**: thêm `subscriber`, `relationship`, invariant kiểm tra `subscriberId` khớp `identifier[BHYT]`, và đưa `Coverage.type` về ngữ nghĩa chuẩn FHIR `medical` thay vì dùng cho `NGUON_CTRA`
* **Liên thông tôn giáo**: thêm `ConceptMap` `vn-cm-religion-to-v3-religious-affiliation` và ví dụ mã kép cho `patient-religion` ở các trường hợp có ánh xạ 1-1
* **Gia cố Consent**: thêm invariant yêu cầu `provision.period.end` khi đã khai báo consent có thời hạn
* **SearchParameters**: `vn-ma-lk`, `vn-ma-luot-kcb`, `vn-ma-dkbd`, `vn-bhxh`, `vn-gks`, `vn-gphn`, cùng artifact lịch sử `vn-vneid` ở trạng thái `retired`
* **NamingSystems**: thêm `VNeID` (integration-only / `retired`), `GKS`, `GPHN`, `VNMaLuotKCB`, mã phản hồi gateway BHYT, cùng các hệ CMND/BHXH/Hộ chiếu/Mã vật tư
* **Gia cố định danh Encounter**: `vn-ext-encounter-code` chuyển từ `string` sang `Identifier`, gắn `system` riêng cho `MA_LUOT_KCB` và đổi `vn-sp-encounter-ma-luot-kcb` sang `token` để tìm kiếm nhất quán hơn trong `gateway` và `validator`
* **Ví dụ bệnh nhân nước ngoài dùng hộ chiếu**: thêm `ExamplePatientForeignPassport` để minh họa bệnh nhân người nước ngoài dùng `identifier[HC]`, giữ lát cắt `CCCD` với `data-absent-reason`, và không lạm dụng `forceMajeureReason`
* **Artifact `gateway layer`**: Check-in + các logical model BHYT XML 1-12, `$validate-bhyt-claim`, `$submit-bhyt-claim`, `$reverse-bhyt-claim`
* **Gia cố ánh xạ BHYT**: thêm chú thích `mapping` nội tuyến cho toàn bộ logical model Check-in + XML1-12, chốt nguồn FHIR cho từng trường và tách rõ trường gốc với trường suy ra để xuất dữ liệu
* **Làm dày XML2 thuốc BHYT**: thêm `VNCoreExtPaymentSource` cho `NGUON_CTRA`, sửa đúng semantics `VNPaymentSourceCS` theo QĐ 130/QĐ 3176 (`1` BHYT, `2` dự án/viện trợ, `3` chương trình mục tiêu quốc gia, `4` nguồn khác), và kéo thêm `SO_DANG_KY`/`NGAY_YL` vào round-trip/report từ carrier thuốc thực tế
* **Tự động hóa quản trị**: thêm script kiểm tra mức bảo mật cơ sở, ảnh chụp/diff thuật ngữ và chuyển đổi khứ hồi BHYT JSON/XML
* **Hỗ trợ kiểm tra số định danh cá nhân**: thêm `VNCitizenIdBirthplacePrefixCS/VS`, đóng gói bộ thuật ngữ hỗ trợ kiểm tra 3 số đầu CCCD và đưa `TT 17/2024/TT-BCA` vào tài liệu tham chiếu pháp lý
* **Báo cáo chuyển đổi khứ hồi**: sinh thêm `output/bhyt-roundtrip/README.md` và `output/bhyt-roundtrip/index.html` để rà soát độ bao phủ theo bundle/bảng XML
* **Độ bao phủ bộ dữ liệu kiểm thử BHYT**: bổ sung bundle dương tính `HIV/AIDS` và `tử vong`, làm giàu bundle `nội trú` và `trẻ sơ sinh` để round-trip mapper phủ thực tế `xml4-12`
* **Báo cáo triển khai**: thêm trang `implementation-reports.md` để chuẩn hóa báo cáo thí điểm/ballot
* **Organization/Location legal alignment**: tách riêng `organizationRank`, `healthUnitRank`, `organizationRankStatus`, `facilityCareLevel`, và `legacyTechnicalLine`; bổ sung trang `organization-location-governance.md`
* **YHCT terminology semantics**: chuẩn hóa `CodeSystem.property.uri` cho toàn bộ 10 CodeSystem YHCT, giữ nguyên mã pháp lý nhưng làm rõ ngữ nghĩa property trong hệ sinh thái terminology và loại bỏ toàn bộ thông báo QA kiểu “property has only a code and not a URI”
* **Chiến lược biên soạn bộ mã lớn**: chuyển các `CodeSystem` quy mô lớn như `VNCLSCS`, `VNWardCS`, `VNOCCS` và toàn bộ 10 `CodeSystem` Y học cổ truyền sang tài nguyên FHIR JSON sinh sẵn từ dữ liệu nguồn máy đọc được hoặc phụ lục pháp lý, giúp SUSHI ổn định và giữ nguyên provenance pháp lý
* **Tái cấu trúc định danh người hành nghề**: chuyển `VNCorePractitioner` sang mô hình `GPHN` hiện hành / `CCHN` lịch sử, thêm NamingSystem `VNGPHN` và `vn-sp-practitioner-gphn`, đồng thời hạ `CCHN` xuống lớp tương tác liên thông dữ liệu lịch sử

### Điều chỉnh sau rà soát lâm sàng

* **CCCD bắt buộc**: `identifier[CCCD]` 0..1 → 1..1 per TT 13/2025
* **security.md**: Cập nhật reference VNCoreConsent (thay thế interim guidance)
* **VNProvinceCS**: Ghi rõ ^count = 63 (34 active + 29 deprecated)
* **Ví dụ Coverage**: Dùng type có mã hóa thay vì chỉ dùng văn bản
* **Guardian modeling**: thêm `VNCoreRelatedPerson` + example mẹ của bệnh nhi; tách riêng example quyền lợi BHYT cấp trực tiếp cho trẻ và example coverage liên kết người đại diện
* **Consent trẻ em**: bổ sung thuật ngữ `parental-proxy`/`guardian-consent` và ví dụ `ExampleConsentParentalProxy` dùng `RelatedPerson` làm người thực hiện đồng ý

### Hạ tầng

* Cloudflare Worker: ghi đè đường dẫn URL (không chuyển hướng) cho canonical FHIR URL
* Định tuyến theo mẫu: tự nhận diện tất cả resource type
* Bộ xử lý `/core/*`: `package-list.json`, `qa.html` được phục vụ đúng qua `/core/`
* CI: Node.js 22 + runtime Node.js 24 bật theo lựa chọn
* FHIR auto-ig-builder GitHub App cài đặt

-------

## Phiên bản 0.1.0 — Bản dự thảo đầu tiên (03/2026)

**Trạng thái**: Draft

### Profiles (23)

* **VNCorePatient** — Bệnh nhân Việt Nam (CCCD, tên tiếng Việt, dân tộc, tôn giáo, nghề nghiệp, địa chỉ 2 cấp)
* **VNCorePractitioner** — Nhân viên y tế (CCHN, học vị)
* **VNCorePractitionerRole** — Vai trò nhân viên y tế (chức danh V.08, chuyên khoa)
* **VNCoreOrganization** — Cơ sở KCB (hạng BV, tuyến, loại hình)
* **VNCoreAddress** — Địa chỉ Việt Nam (tỉnh + xã, backward-compatible huyện)
* **VNCoreEncounter** — Lượt khám/điều trị (loại KCB BHYT, kết quả điều trị)
* **VNCoreCondition** — Chẩn đoán (ICD-10 VN + YHCT)
* **VNCoreObservationLab** — Kết quả xét nghiệm (LOINC VN)
* **VNCoreObservationVitalSigns** — Sinh hiệu
* **VNCoreObservationYHCT** — Quan sát YHCT (lưỡi, mạch, triệu chứng)
* **VNCoreAllergyIntolerance** — Dị ứng (SNOMED CT VN)
* **VNCoreProcedure** — Thủ thuật/phẫu thuật (ICD-9-CM)
* **VNCoreMedicationRequest** — Đơn thuốc điện tử (ePrescription, TT 13/2025, Luật Dược 2016, QĐ 3176)
* **VNCoreMedication** — Thuốc (ATC, SNOMED CT)
* **VNCoreServiceRequest** — Yêu cầu DVKT/cận lâm sàng (TT 20/2014, TT 39/2018, QĐ 3176)
* **VNCoreCoverage** — Thẻ BHYT (3 format: CCCD/BHXH/cũ)
* **VNCoreClaim** — Yêu cầu thanh toán KCB BHYT (QĐ 3176 → QĐ 697, 14 nhóm chi phí)
* **VNCoreClaimResponse** — Phản hồi thanh toán BHYT
* **VNCoreExplanationOfBenefit** — Giải trình quyền lợi BHYT
* **VNCoreDocumentReference** — Tài liệu y tế (bệnh án điện tử per TT 13/2025)
* **VNCoreDiagnosticReport** — Kết quả CLS (XN, CĐHA, GPB)
* **VNCoreDevice** — Trang thiết bị y tế
* **VNCoreDeviceUseStatement** — Sử dụng TBYT cho bệnh nhân

### Extensions (20)

* `vn-ext-ethnicity` — Dân tộc (54 dân tộc, 121/TCTK-PPCĐ)
* `vn-ext-religion` — Tôn giáo (16 tôn giáo, CV 6955/BNV-TGCP)
* `vn-ext-occupation` — Nghề nghiệp (VSCO 2020, 1.516 mã, QĐ 34/2020/QĐ-TTg)
* `vn-ext-province` — Tỉnh/TP (34 đơn vị, NQ 202/2025)
* `vn-ext-ward` — Xã/Phường (~3.321 đơn vị, NQ 202/2025)
* `vn-ext-bhyt-card-type` — Loại đối tượng BHYT (53 mã, NĐ 146/2018)
* `vn-ext-primary-care-facility` — Nơi ĐKKCB ban đầu (Luật BHYT)
* `vn-ext-insurance-visit-type` — Loại KCB BHYT (MALYDO, QĐ 3176)
* `vn-ext-treatment-outcome` — Kết quả điều trị (KET_QUA_DTRI, 8 mã, QĐ 3176)
* `vn-ext-org-rank` — Hạng bệnh viện (4 hạng, TT 06/2024/TT-BYT)
* `vn-ext-org-level` — Tuyến KCB
* `vn-ext-org-type` — Loại hình CSKCB (8 loại, Luật KCB 2023)
* `vn-ext-claim-cost-summary` — Tổng hợp chi phí Claim (QĐ 697)
* `vn-ext-claim-item-department` — Khoa chỉ định dịch vụ
* `vn-ext-claim-payment-period` — Thời gian thanh toán BHYT
* `vn-ext-insurance-cost-info` — Thông tin chi phí BHYT
* `vn-ext-payment-method` — Phương thức thanh toán
* `vn-ext-order-date` — Ngày y lệnh
* `vn-ext-med-registration-number` — Số đăng ký thuốc
* `vn-ext-device-insurance-scope` — Phạm vi BH trang thiết bị y tế

### CodeSystems (42) và ValueSets (43)

* 17 CodeSystem quốc gia (dân tộc, tôn giáo, ĐVHC, BHYT 53 mã, KCB, chi phí 14 mã, kết quả điều trị 8 mã, ra viện 5 mã, mã đối tượng KCB 27 mã per QĐ 3276, loại dịch vụ y tế 8 mã per TT 20/2014 + TT 39/2018, trình độ chuyên môn, v.v.)
* 2 CodeSystem nhân viên y tế: 
* Chức danh nghề nghiệp V.08 (32 mã — TT 41/2025, TT 02/2025)
* Chuyên khoa y tế (47 mã, 8 nhóm — TT 43/2013 DMKT 28 chuyên khoa, TT 21/2017, TT 32/2023 Điều 11 Phụ lục V–XVII)
 
* 5 CodeSystem quốc tế bản địa hóa (ICD-10 VN 15.026, ICD-9-CM 3.882, SNOMED CT VN 77.393, LOINC VN 66.077, CLS VN 2.964)
* 10 CodeSystem Y học cổ truyền (QĐ 2552 + QĐ 3080) — bao gồm VNYHCTDiseaseCS 228 mã (38 bệnh danh + 190 thể lâm sàng)
* 7 CodeSystem bảo hiểm/thanh toán (chi phí, phương thức TT, phạm vi BH TBYT, loại CLS, per QĐ 697/QĐ-BYT)
* 1 CodeSystem nghề nghiệp VSCO (1.516 mã, 5 cấp, ISCO-08 compatible — QĐ 34/2020/QĐ-TTg)

### SearchParameters (11)

* `vn-sp-patient-cccd` — Tìm Patient theo CCCD (Luật Căn cước 2023)
* `vn-sp-patient-bhyt` — Tìm Patient theo BHYT (Luật BHYT)
* `vn-sp-organization-cskcb` — Tìm Organization theo mã CSKCB (QĐ 3176)
* `vn-sp-practitioner-cchn` — Tìm Practitioner theo CCHN (Luật KCB 2023, Điều 19-26)
* `vn-sp-coverage-bhyt` — Tìm Coverage theo số thẻ BHYT (NĐ 188/2025)
* `vn-sp-encounter-malydo` — Tìm Encounter theo MALYDO (QĐ 3176/QĐ-BYT)
* `vn-sp-condition-icd10` — Tìm Condition theo ICD-10 (QĐ 4469/QĐ-BYT, QĐ 98/QĐ-BYT)

### ConceptMaps (2)

* `vn-cm-cls-to-loinc` — Ánh xạ CLS VN → LOINC (2.964 chỉ số, 100% coverage, QĐ 1227/QĐ-BYT)
* `vn-cm-religion-to-v3-religious-affiliation` — Ánh xạ một phần danh mục tôn giáo Việt Nam sang `v3-ReligiousAffiliation` cho các trường hợp tương đương rõ về ngữ nghĩa

### CapabilityStatement (5)

* **VNCoreServer** — CapabilityStatement mức cơ sở cho máy chủ FHIR tuân thủ VN Core
* **VNCoreEMRServer** — CapabilityStatement mức cơ sở cho EMR/EHR nội bộ
* **VNBHYTGatewayClient** — CapabilityStatement mức cơ sở cho client gửi hồ sơ thanh toán BHYT
* **VNBHYTGatewayServer** — CapabilityStatement mức cơ sở cho server/facade tiếp nhận hồ sơ thanh toán BHYT
* **VNCitizenAppClient** — CapabilityStatement mức cơ sở cho ứng dụng người dân/VNeID connector

### NamingSystems (5)

* CCCD, BHYT, CCHN, CSKCB, MRN

### Examples (33)

* Ít nhất 1 ví dụ cho mỗi profile
* 2 ví dụ Patient (đầy đủ + tối thiểu)
* 2 ví dụ Practitioner (BSCKII + tối thiểu) + 1 PractitionerRole
* 2 ví dụ Organization (BV tuyến TW + Trạm y tế)
* 2 ví dụ Coverage (BHYT mới + legacy)
* 2 ví dụ Encounter (ngoại trú + nội trú)
* 4 ví dụ Condition (Tây y + YHCT)
* 1 ví dụ MedicationRequest + 1 Medication
* 2 ví dụ ServiceRequest (xét nghiệm đường huyết + chụp X-quang ngực)
* 1 ví dụ Claim + 1 ClaimResponse + 1 ExplanationOfBenefit
* 1 ví dụ DocumentReference + 1 DiagnosticReport
* 1 ví dụ Device + 1 DeviceUseStatement
* Các ví dụ Observation (Lab, VitalSigns, YHCT), AllergyIntolerance, Procedure, Address

### Cải tiến đáng chú ý

* **VNYHCTDiseaseCS — REBUILD HOÀN TOÀN** từ Excel nguồn QĐ 2552/QĐ-BYT (sheet "DM ngay 2752025"): 
* Sửa lỗi nghiêm trọng: U50.101 trước đó ghi sai bệnh danh ("Hiếp thống" → đúng: **"Hoàng đản"**)
* Sửa format sub-code: từ `.0, .1, .8, .9` (sai) → **`.01, .02, .03...`** (đúng QĐ 2552)
* Tăng từ 135 codes (sai, thiếu) → **228 codes** (38 bệnh danh + 190 thể lâm sàng)
* Bổ sung 12 bệnh danh thiếu: Hoàng đản, Si ngốc, Si chứng, Thất ngôn, Tọa cốt phong, Tọa điến phong, Kiên tý, Khái thấu, Chứng cam, Phong chẩn, Tầm ma chẩn, Hạ trĩ
* **228/228 display duy nhất** — không còn trùng lặp (trước đó 25 nhóm display giống hệt)
* Display bệnh danh: `"{YHCT} — {YHHĐ} [{ICD-10}]"` (VD: "Yêu thống — Đau cột sống thắt lưng [M54.5]")
* Display thể lâm sàng: `"{YHCT}: {tên thể} [{ICD-10}]"` (VD: "Yêu thống: Thể hàn thấp [M54.5]")
* `hierarchyMeaning` sửa từ `#grouped-by` → **`#is-a`** (chuẩn FHIR)
* Properties mới: `icd10` (mã ICD-10), `yhhd-name` (tên bệnh YHHĐ), `ma-dung-chung` (mã dùng chung BYT)
* English designations đầy đủ cho 228 codes (thuật ngữ TCM chuẩn quốc tế)
 
* **VNCoreServiceRequest — Bổ sung 3 elements**: 
* `identifier` (0..* MS) — Mã phiếu chỉ định / Số yêu cầu
* `requisition` (0..1) — Mã nhóm yêu cầu (gộp nhiều XN/DVKT cùng phiếu)
* `performerType` (0..1) — Loại chuyên khoa thực hiện, bind VNSpecialtyVS
* Cập nhật `code` description: ghi rõ LOINC cho XN (QĐ 1227), ICD-9-CM cho PT/TT (QĐ 387), SNOMED CT cho CĐHA
 
* **ExampleConditionYHCTYeuThong** — Cập nhật dùng mã thể lâm sàng cụ thể `U62.392.5.01` (Thể hàn thấp) thay vì base code `U62.392.5`

### Trang nội dung (16)

* Trang chủ, Giới thiệu (Omi HealthTech & OmiGroup), Bắt đầu nhanh
* Cơ sở pháp lý, Hướng dẫn chung, Hướng dẫn thuật ngữ
* Tình huống lâm sàng (khám ngoại trú + BHYT)
* Profiles, Extensions, Thuật ngữ, Bảo mật
* Validation, Ổn định & Conformance, SNOMED CT VN Đính chính
* Tải xuống, Lịch sử thay đổi

### Khung pháp lý tham chiếu

* 28+ văn bản pháp lý và chiến lược liên quan (NQ 202/2025, TT 13/2025, Luật 91/2025, NĐ 356/2025, QĐ 3516/QĐ-BYT, v.v.)
* Tuân thủ mô hình ĐVHC 2 cấp mới (34 tỉnh + xã)
* Tuân thủ Luật BVDLCN (dữ liệu y tế = DLCN nhạy cảm)

-------

## Liên hệ với các trang khác

| | |
| :--- | :--- |
| Tìm hiểu quy trình phát hành và governance của IG | [Release & Governance](release-governance.md) |
| Hiểu chiến lược ổn định và cam kết backward-compatibility | [Stability & Conformance](stability-and-conformance.md) |
| Tải xuống phiên bản hiện hành và các artifact liên quan | [Downloads](downloads.md) |

## English Summary

This changelog records the release-to-release delta of VN Core. The `0.5.0` entry is the current Draft for Community Review and should be read first when assessing upgrade impact, validation changes, package changes, mapping changes, or new artifact expectations. Older `0.4.0` and `0.3.0` entries are retained as historical release notes.

