# Ổn định & Conformance - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Ổn định & Conformance

# Ổn định và tuân thủ — Stability and Conformance

Chiến lược ổn định hóa VN Core bao gồm mô hình mức độ trưởng thành cho tài nguyên, ranh giới giữa `VN Core Base`, lớp liên thông hồ sơ thanh toán BHYT (`BHYT Submission`), các terminology packages và package thiết bị y tế, cùng các yêu cầu tuân thủ mức cơ sở theo từng vai trò triển khai.

Từ phiên bản `0.3.0`, dự án ưu tiên **ổn định lõi trước khi mở rộng phạm vi**. Điều này giúp giảm thay đổi phá vỡ tương thích, thuận lợi hơn cho giai đoạn thí điểm của HIS/EMR, và giữ được nhịp cập nhật pháp lý nhanh của lớp BHYT mà không làm rung toàn bộ lõi.

**Ưu tiên trước thí điểm**: Trước giai đoạn thí điểm, VN Core ưu tiên quản trị dữ liệu, định danh theo CCCD, EMR/HSSK, Đồng bộ BHYT, lớp ứng dụng người dân và tích hợp, LGSP/API facade và nền tảng an toàn trước khi mở rộng thêm phạm vi tài nguyên.

-------

## Nguyên tắc ổn định

1. `VN Core Base`, lớp`BHYT Submission`và các gói thuật ngữ phải được tách logic rõ ràng.
1. Ưu tiên tái sử dụng FHIR base và các extension chuẩn của HL7 trước khi tạo extension cục bộ mới.
1. Chỉ coi một tài nguyên là “ổn định” khi có ví dụ, kiểm tra tự động và ca sử dụng triển khai rõ ràng.
1. Mọi thay đổi phá vỡ tương thích trên lõi phải đi kèm ghi chú chuyển đổi và thời gian ngừng dùng hợp lý.
1. Ưu tiên gia cố hướng dẫn theo từng vai trò, dữ liệu dùng chung và mức bảo mật cơ sở trước khi mở rộng sang khai thác dữ liệu thứ cấp, telehealth hoặc Bulk Data.

-------

## Ranh giới package

| | | | |
| :--- | :--- | :--- | :--- |
| `VN Core Base` | Liên thông nội bộ FHIR-native cho EMR, HIE, hồ sơ công dân | `Patient`,`RelatedPerson`,`Encounter`,`Coverage`,`DocumentReference`,`Consent`,`AuditEvent`,`Provenance`, thuật ngữ nền tảng | Chậm hơn, ưu tiên ổn định |
| `BHYT Submission` | Lớp liên thông hồ sơ thanh toán BHYT ở tầng ánh xạ/cổng | `VNCoreBHYTSubmissionBundle`, logical models Check-in + Bảng 1-12,`$validate-bhyt-claim`,`$submit-bhyt-claim`,`MA_LK` | Nhanh hơn, theo quy định BHXH/BYT |
| `Terminology Clinical` | Quản trị thuật ngữ lâm sàng quy mô lớn | ICD-10 VN, ICD-9-CM, tập con SNOMED CT VN, CLS, LOINC, ConceptMap | Theo từng đợt cập nhật thuật ngữ |
| `Terminology Traditional Medicine` | Quản trị thuật ngữ Y học cổ truyền | 10 CodeSystem + 10 ValueSet Y học cổ truyền | Theo từng đợt cập nhật chuyên môn |
| `Device` | Quản trị danh pháp và package mở rộng thiết bị y tế | `VNMedicalDeviceNomenclatureCS`,`VNMedicalDeviceNomenclatureVS`,`VNDeviceTypeVS`, profile thiết bị mở rộng sau này | Theo văn bản danh pháp/regulatory và pilot thiết bị |

**Hệ quả thiết kế**:

* `Patient`, `Coverage`, `Claim` vẫn là tài nguyên FHIR-native.
* Các trường xuất như `SO_CCCD`, `MA_LK`, `yyyyMMddHHmm` được gia cố ở lớp liên thông hồ sơ thanh toán BHYT và các script kiểm tra tuân thủ.
* Khi pháp lý BHYT thay đổi, ưu tiên đổi ở lớp `BHYT Submission` trước; chỉ đổi `Base` nếu thực sự ảnh hưởng semantic cốt lõi.
* Hướng dẫn cho `LGSP/API facade`, `data reuse` và ma trận vai trò/bộ dữ liệu nằm ở `narrative/conformance layer`, không đẩy thẳng vào cardinality của tài nguyên lõi nếu chưa có căn cứ ngữ nghĩa đủ mạnh.

### Phát hành theo gói mô-đun

Từ `0.3.0`, repo vẫn được biên soạn bằng **một dự án SUSHI dạng monorepo**, nhưng pipeline phát hành đã có thể sinh **5 gói mô-đun và 1 gói tổng hợp**:

| | | |
| :--- | :--- | :--- |
| `hl7.fhir.vn.core` | Gói tổng hợp cho kiểm tra cục bộ và cài đặt trọn bộ | `python3 scripts/build-split-packages.py` |
| `hl7.fhir.vn.core.base` | Gói ổn định cho interoperability FHIR-native | `python3 scripts/build-split-packages.py` |
| `hl7.fhir.vn.bhyt.submission` | Gói bundle/logical model/operation cho liên thông hồ sơ BHYT, phụ thuộc`hl7.fhir.vn.core.base` | `python3 scripts/build-split-packages.py` |
| `hl7.fhir.vn.terminology.clinical` | Gói thuật ngữ lâm sàng quy mô lớn | `python3 scripts/build-split-packages.py` |
| `hl7.fhir.vn.terminology.traditional-medicine` | Gói thuật ngữ Y học cổ truyền | `python3 scripts/build-split-packages.py` |
| `hl7.fhir.vn.device` | Gói mở rộng thiết bị y tế, trước mắt chứa danh pháp QĐ-3107 + QĐ-847 | `python3 scripts/build-split-packages.py` |

Điểm này cho phép tách nhịp phát hành ở mức **gói tiêu thụ** mà không phải nhân đôi nguồn biên soạn. Ở trạng thái hiện tại, cả `6` gói đã được công bố công khai; trước khi kênh mirror bên ngoài hoàn tất, kiểm tra cục bộ vẫn nên ưu tiên `hl7.fhir.vn.core` hoặc truyền đồng thời nhiều `-ig`.

-------

## Mô hình mức độ trưởng thành

| | | |
| :--- | :--- | :--- |
| **Ứng viên ổn định** | Có profile rõ, ví dụ tốt, tìm kiếm/định danh phù hợp, kiểm tra validation/Tier 2 đã có | `VNCorePatient`,`VNCoreRelatedPerson`,`VNCoreAddress`,`VNCoreOrganization`,`VNCoreEncounter`,`VNCoreCoverage`,`VNCoreClaim`,`VNCoreConsent`,`VNCoreAuditEvent`,`VNCoreProvenance` |
| **Thử nghiệm áp dụng** | Đã dùng được nhưng còn phụ thuộc phản hồi và thí điểm | `VNCoreComposition`,`VNCoreDocumentReference`,`VNCoreClaimResponse`,`VNCoreExplanationOfBenefit`,`VNCoreDevice`,`VNCoreImplantableDevice`,`VNCoreDeviceUseStatement`,`VNCoreOrganizationDepartment`,`VNCoreMedicationDispense`,`VNCoreImagingStudy`,`VNCoreDiagnosticReportLab`,`VNCoreDiagnosticReportImaging`,`VNCoreDiagnosticReportPathology`, các logical model BHYT |
| **Thực nghiệm** | Chưa nên coi là mức cơ sở quốc gia, còn chờ ca sử dụng rộng hơn | luồng ePrescription, Bulk Data, nhắn tin nâng cao, ánh xạ trao đổi dữ liệu xuyên biên giới |

### Cập nhật maturity v0.4-v0.5

| | | |
| :--- | :--- | :--- |
| [VNCorePaymentReconciliation](StructureDefinition-vn-core-payment-reconciliation.md) | Trial Use v0.5 | Profile mới cho biên bản quyết toán/thanh toán BHYT 06/BH; giữ`PaymentReconciliation.outcome`chuẩn FHIR và dùng`claimAuditStatus`cho vòng đời giám định nội địa |
| [VNCoreEndpointBHYT](StructureDefinition-vn-core-endpoint-bhyt.md) | Trial Use v0.5 | Profile endpoint cổng`gdbhyt`cho submit/tra cứu hồ sơ BHYT; dùng ở gateway/facade, không kéo vào core clinical semantics |
| [VNCoreHealthcareService](StructureDefinition-vn-core-healthcare-service.md) | Trial Use v0.5 | Profile dịch vụ y tế, nhất là TYT cấp xã/phường/đặc khu;`type`extensible với`VNHealthcareServiceTypeVS` |
| [VNCoreCompositionBreachNotification](StructureDefinition-vn-core-composition-breach-notification.md) | Trial Use v0.5 | Composition structured cho Mẫu 08 NĐ 356/2025; có section bắt buộc và attester legal warning |
| [VNCoreExtLegalBasis](StructureDefinition-vn-ext-legal-basis.md) | Trial Use v0.5 | Extension căn cứ pháp lý structured cho artifact/element, dùng`VNLegalDocumentRefCS`để giảm drift citation |
| [VNCoreExtDeviceRegistrationNumber](StructureDefinition-vn-ext-device-registration-number.md) | Trial Use v0.5 | Số lưu hành thiết bị y tế; Must Support trong implantable device C/D ở mức warning để không chặn dữ liệu legacy |
| [VNCoreExtClaimAuditStatus](StructureDefinition-vn-ext-claim-audit-status.md) | Trial Use v0.5 | Trạng thái giám định BHYT cho`PaymentReconciliation`,`Task`,`ClaimResponse` |
| [VNCoreOrganizationDepartment](StructureDefinition-vn-core-organization-department.md) | Trial Use v0.4 | Profile mới cho khoa/phòng,`partOf`bắt buộc và identifier`departmentCode` |
| [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) | Trial Use v0.4 | Profile mới cho cấp phát thuốc, nối chuỗi MedicationRequest → MedicationDispense → Claim/EOB |
| [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) | Trial Use v0.4 | Profile mới cho DICOM/RIS/PACS metadata và CĐHA |
| [VNCoreDiagnosticReportLab](StructureDefinition-vn-core-diagnostic-report-lab.md) | Trial Use v0.4 | Sub-profile lab từ parent DiagnosticReport |
| [VNCoreDiagnosticReportImaging](StructureDefinition-vn-core-diagnostic-report-imaging.md) | Trial Use v0.4 | Sub-profile CĐHA, có`imagingStudy`reference và nhóm chi phí 4 |
| [VNCoreDiagnosticReportPathology](StructureDefinition-vn-core-diagnostic-report-pathology.md) | Trial Use v0.4 | Sub-profile GPB,`specimen`bắt buộc và`conclusionCode`extensible |
| [VNCoreDevice](StructureDefinition-vn-core-device.md) | Trial Use v0.4 (re-classified) | Update major: mở rộng Must Support từ 2 MS lên 12+ MS, thêm identifier slicing, UDI và lifecycle;`deviceGroup`chỉ fallback vì dữ liệu thanh toán TBYT ưu tiên ở`Claim.item`;`type`được relax về`0..1 MS`để tránh reject dữ liệu legacy/BHYT |
| [VNCoreImplantableDevice](StructureDefinition-vn-core-implantable-device.md) | Trial Use v0.4 | Profile con patient-bound cho thiết bị cấy ghép;`patient/type/status 1..1`, UDI/lifecycle/safety MS, không hard mandate UDI toàn Core |
| [VNCoreExtDeviceGroup](StructureDefinition-vn-ext-device-group.md) | Trial Use v0.4 | Extension cho nhóm TBYT BHYT N01-N09;`Claim.item`preferred,`Device`fallback |

### Điều kiện để nâng từ Thử nghiệm áp dụng lên Ứng viên ổn định

* Có ít nhất 2 example chất lượng cao
* Có test pass trong `scripts/validate.sh` hoặc `scripts/validate-tier2.sh`
* Không phụ thuộc vào extension/local code trùng nghĩa với FHIR base
* Có ít nhất 1 ca sử dụng thí điểm hoặc ma trận ánh xạ rõ ràng

-------

## Chính sách phát hành

Chi tiết quản trị công bố công khai, phân loại thay đổi và ngưỡng phát hành tối thiểu đã được tách sang trang [Phát hành và quản trị](release-governance.md). Phần dưới đây giữ vai trò tóm tắt ở mức tuân thủ.

| | | |
| :--- | :--- | :--- |
| **Breaking** | Minor/major release có ghi chú chuyển đổi bắt buộc | Đổi URL tài nguyên, đổi cardinality bắt buộc, đổi binding làm dữ liệu cũ không còn hợp lệ |
| **Additive** | Minor release | Thêm profile, search parameter, ví dụ, operation, mã mới đang hiệu lực |
| **Patch/Stabilization** | Patch release | Sửa ví dụ, script validation, tài liệu, CapabilityStatement theo từng vai trò triển khai |

### Quy tắc ngừng dùng

* Không xóa mã cũ ngay nếu còn dùng cho dữ liệu lịch sử; đánh dấu `deprecated` trước.
* Không thay URL extension/profile chỉ vì đổi câu chữ.
* Nếu một extension cục bộ bị thay bằng extension chuẩn của HL7, phải cập nhật ví dụ và tài liệu trước khi coi extension cũ là ngừng dùng.

-------

## CapabilityStatement theo từng vai trò triển khai

Ma trận đọc theo vai trò triển khai, gói tiêu thụ, checklist sẵn sàng thí điểm và tiêu chí tối thiểu cho từng vai trò đã được tách sang [Tuân thủ theo vai trò triển khai](conformance-by-actor.md). Phần dưới đây chỉ giữ vai trò tóm tắt các `CapabilityStatement` đang được công bố.

VN Core hiện công bố 5 `CapabilityStatement`:

| | | |
| :--- | :--- | :--- |
| `VNCoreServer` | Mức cơ sở chung | Tổng quan tối thiểu cho một máy chủ FHIR tuân thủ VN Core |
| `VNCoreEMRServer` | EMR/EHR nội bộ | Bệnh viện, HIS/EMR, kho dữ liệu lâm sàng nội bộ |
| `VNBHYTGatewayClient` | Client gửi hồ sơ thanh toán BHYT | Middleware/HIS gửi hồ sơ thanh toán BHYT |
| `VNBHYTGatewayServer` | Server tiếp nhận hồ sơ thanh toán BHYT | Facade/adapter tiếp nhận hồ sơ thanh toán BHYT |
| `VNCitizenAppClient` | Ứng dụng người dân/kết nối VNeID | Cổng bệnh nhân, ứng dụng di động, cổng công dân |

### Lý do cần tách theo từng vai trò triển khai

* Tránh một `CapabilityStatement` quá rộng và mơ hồ.
* Giúp bên triển khai biết chính xác vai trò của mình phải hỗ trợ gì.
* Cho phép package `Base` ổn định hơn, trong khi lớp `BHYT Submission` vẫn thay đổi theo quy định.

-------

## Tự động hóa kiểm tra tuân thủ

### Tier 1

```
./scripts/validate.sh

```

Kiểm tra:

* Compile SUSHI
* Ưu tiên runtime `Node 22` để khớp với CI; wrapper local sẽ tự chọn `node@22` nếu có
* StructureDefinitions
* Examples cơ bản

### Liên thông hồ sơ BHYT

```
./scripts/validate-bhyt-submission.sh

```

Kiểm tra:

* Bundle/profile/operations cho BHYT
* 6 positive bundles
* Bộ dữ liệu kiểm thử âm tính cho `MA_LK`, `SO_CCCD`, `exportDateTime`

### Kiểm tra thực thi được ở Tầng 2

```
./scripts/validate-tier2.sh

```

Kiểm tra:

* CCCD khớp giới tính và năm sinh
* Prefix 3 số đầu CCCD hợp lệ theo `vn-citizen-id-birthplace-prefix-cs`
* Xã/phường thuộc đúng tỉnh theo `vn-ward-cs`
* `Coverage.identifier[BHYT]` dạng CCCD khớp CCCD của beneficiary
* `subscriberId` khớp `identifier[BHYT]`
* Thiếu `SO_CCCD` chỉ hợp lệ khi có force majeure reason
* `MA_LK` tồn tại và nhất quán trong bundle BHYT
* `exportDateTime` tuân thủ `yyyyMMddHHmm`

### Mức bảo mật cơ sở

```
./scripts/validate-security-baseline.sh

```

Kiểm tra:

* 5 CapabilityStatement đều khai báo `SMART-on-FHIR`
* Trang `security.md` có đủ phần ma trận scope, `break-glass`, bộ dữ liệu lưu giữ tối thiểu và chính sách chữ ký
* Các tài nguyên quản trị `Consent`, `AuditEvent`, `Provenance` và các ví dụ cốt lõi tồn tại

### Chuyển đổi khứ hồi BHYT XML/JSON

```
./scripts/validate-bhyt-roundtrip.sh

```

Kiểm tra:

* Sinh chuyển đổi khứ hồi JSON/XML từ các bundle BHYT dương tính
* Tạo đủ envelope `checkIn`, `xml1` đến `xml12`
* Đảm bảo `MA_LK` đồng nhất giữa các bảng đã sinh
* Kiểm tra các trường bắt buộc của bảng được điền từ bộ dữ liệu ví dụ hiện tại
* Phủ `xml4` qua `DiagnosticReport`, `xml5`, `xml7`, `xml8` qua `Composition`, `xml6` qua hồ sơ HIV/AIDS có security gate, `xml9` qua giấy chứng sinh, `xml10` qua giấy nghỉ dưỡng thai; `xml11` và `xml12` chỉ sinh khi có fixture nghỉ việc hưởng BHXH hoặc giám định y khoa tương ứng
* Sinh thêm báo cáo độ bao phủ dễ đọc tại `output/bhyt-roundtrip/README.md` và `output/bhyt-roundtrip/index.html`
* Dùng các chú thích `mapping` ngay trong 13 logical model như nguồn sự thật ở mức tài nguyên cho lớp xuất dữ liệu

### Quản trị thuật ngữ

```
./scripts/validate-terminology-governance.sh

```

Kiểm tra:

* Sinh ảnh chụp thuật ngữ hiện tại
* So sánh với ảnh chụp mốc chuẩn `0.3.0`
* Xuất báo cáo khác biệt để rà soát trước khi thay đổi thuật ngữ

### Phần tiếp tục mở rộng

* Quy tắc check-digit/phân bổ mã ngoài phạm vi terminology hiện có trong IG
* Mở rộng bộ chuyển đổi khứ hồi cho các bảng có nhiều dòng chi tiết hơn khi bundle tương lai bổ sung `MedicationAdministration`, `Specimen`, `ImagingStudy`, `CarePlan` hoặc hồ sơ chứng từ chuyên khoa sâu hơn
* ConceptMap quốc tế cho `facilityCareLevel`/`organizationRank` chỉ được phát hành khi có target terminology đủ ổn định và equivalence có thể bảo vệ được về mặt ngữ nghĩa

### Chính sách cảnh báo

Mục tiêu QA của VN Core là:

* `0 errors`
* `0 warning` do chính tài nguyên của VN Core gây ra nếu có thể sửa bằng nội dung hoặc cấu hình
* Cảnh báo còn lại chỉ thuộc 1 trong 2 nhóm: 
* Cảnh báo từ các tài nguyên HL7 chính thức ngoài phạm vi kiểm soát trực tiếp
* Cảnh báo có chủ đích do dùng `URN` nội bộ cho danh mục pháp lý/chính sách
 

Vì vậy:

* Cảnh báo về `concept.definition`, phiên bản mở rộng SNOMED CT, mô tả tài nguyên và cấu hình build phải được sửa tận gốc
* Cảnh báo từ extension `patient-citizenship` chính thức tới `http://hl7.org/fhir/ValueSet/country` được coi là phát sinh từ nguồn ngoài
* Cảnh báo từ `urn:vn-law:*` và `urn:vn-authority:*` được coi là định danh chính sách có chủ đích và được ẩn kèm giải trình

-------

## Bảo mật mức cơ sở cho lõi ổn định

* Dùng `Consent` thay vì custom cục bộ cho đồng ý xử lý dữ liệu
* Dùng `AuditEvent` cho truy cập/chia sẻ
* Dùng `Provenance.signature` cho xác nhận tài liệu/hồ sơ số
* Tách tài khoản dịch vụ của cổng BHYT khỏi tài khoản lâm sàng nội bộ
* Áp dụng `break-glass` qua chính sách cục bộ + audit, không mã hóa thành trường tùy biến riêng nếu FHIR base đã đủ
* Xem mức bảo mật cơ sở là điều kiện vào thí điểm cho `EMR/HSSK`, cổng công dân và các luồng chia sẻ dữ liệu dùng chung

-------

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

| | |
| :--- | :--- |
| Kiến trúc gói phát hành | [Package Architecture](package-architecture.md) |
| Quy trình phát hành | [Release Governance](release-governance.md) |
| Vai trò triển khai | [Conformance by Actor](conformance-by-actor.md) |
| Quyết định thiết kế | [Design Decisions](design-decisions.md) |

-------

## English Summary

This page defines the stabilization and conformance model for VN Core. It explains the maturity tiers, the separation between `VN Core Base`, `BHYT Submission`, and terminology packages, the release and retirement rules, and the minimum automated checks used before pilot expansion.

