# Quyết định thiết kế - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Quyết định thiết kế

# Quyết định thiết kế — Design Decisions

Mỗi quyết định thiết kế ghi rõ nội dung quyết định, lý do và hệ quả triển khai.

-------

## DD-01: CCCD là primary citizen identifier, VNeID chỉ ở lớp ứng dụng

**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**:

* Số định danh cá nhân trên CCCD là trục chính theo TT 17/2024/TT-BCA và chiến lược chuyển đổi số QĐ 3516/QĐ-BYT.
* VNeID là tài khoản định danh điện tử (app-layer), không phải mã bệnh nhân. Nếu coi VNeID ngang hàng CCCD sẽ tạo nhập nhằng khi liên thông giữa HIS, EMR và cổng BHXH.
* `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.

-------

## DD-02: Tách VN Core Base khỏi BHYT Submission

**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ù payer không được kéo ngược vào lõi.

**Lý do**:

* Semantic lõi FHIR (Patient, Encounter, Condition, Observation) phải ổn định cho EMR, HIE, hồ sơ công dân — không chỉ cho mục đích gửi hồ sơ BHXH.
* Format dữ liệu đầu ra BHXH thay đổi theo QĐ 130 → QĐ 4750 → QĐ 3176 → QĐ 697, nhịp nhanh hơn lõi FHIR.
* Nếu trộn, mỗi thay đổi payer-facing sẽ tạo breaking change cho toàn bộ IG.

**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 semantic lõi một cách vô ý.

-------

## DD-03: Tách terminology packages khỏi lõi

**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**:

* Bộ mã lớn (CLS: 2.964 chỉ số, ICD-10 VN: hàng nghìn mã) thay đổi theo quyết định BYT, không theo nhịp phát hành của core profiles.
* Build time và package size tăng đáng kể khi terminology nằm trong lõi.
* Cho phép đơn vị triển khai chỉ kéo terminology cần dùng.

**Hệ quả**: Validator và FHIR server cần kéo thêm terminology packages 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`.

-------

## DD-04: Địa chỉ 2 cấp theo NQ 202/2025, giữ backward-compatible huyện

**Quyết định**: `VNCoreAddress` dùng mô hình tỉnh + xã/phường theo NQ 202/2025 (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**:

* NQ 202/2025/QH15 chuyển sang mô hình 2 cấp (tỉnh + xã) từ 01/07/2025.
* Dữ liệu bệnh viện, CSYT và hồ sơ bệnh nhân cũ vẫn gắn với huyện. Nếu xóa trường huyện, dữ liệu lịch sử không thể biểu diễn.
* FHIR `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.

-------

## DD-05: Consent, AuditEvent, Provenance là baseline, không phải phụ lục

**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**:

* Luật 91/2025 và NĐ 356/2025 coi dữ liệu y tế là DLCN nhạy cảm. Quyền đồng ý, truy vết và kiểm toán là nghĩa vụ pháp lý, không phải best practice.
* Nếu không thiết kế từ đầu, việc bổ sung consent/audit muộn sẽ phá vỡ kiến trúc dữ liệu đã triển khai.

**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.

-------

## DD-06: Không tạo package riêng cho LGSP/API facade

**Quyết định**: Lớp LGSP/API facade được giữ ở mức narrative guidance, `CapabilityStatement` và validation scripts — không tách thành package riêng.

**Lý do**:

* Đây là lớp hướng dẫn triển khai, không phải tập tài nguyên tiêu thụ độc lập.
* Chi phí quản trị package tăng nhanh hơn giá trị thực tế khi chưa có bên sử dụng rõ ràng và nhịp phát hành độc lập.

**Hệ quả**: Guidance cho LGSP/API facade nằm trong narrative pages và `CapabilityStatement`. Có thể mở package khi có nhu cầu rõ ràng từ pilot.

-------

## DD-07: Dùng HL7 standard extensions cho Patient thay vì tạo mới

**Quyết định**: `VNCorePatient` dùng `patient-religion`, `patient-citizenship`, `patient-birthPlace` chuẩn HL7 thay vì tạo extension riêng.

**Lý do**:

* Giảm số lượng extension cục bộ.
* Tăng khả năng tương hợp với các IG quốc gia khác.
* Extension chuẩn HL7 đã có lifecycle và governance rõ ràng.

**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).

-------

## Governance trail through v0.5.0

Các quyết định thiết kế được ghi trong `governance/` và `wiki/decisions/` để giữ audit trail tách khỏi narrative 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.5.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.

| | | |
| :--- | :--- | :--- |
| **v0.5 Structured Legal References**([VNLegalDocumentRefCS](CodeSystem-vn-legal-document-ref-cs.md),[VNLegalDocumentRefVS](ValueSet-vn-legal-document-ref-vs.md),[VNCoreExtLegalBasis](StructureDefinition-vn-ext-legal-basis.md)) | 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 legal citation rải rác trong mô tả text; cho phép audit tự động, đánh dấu`future-effective`và kiểm soát văn bản hết hiệu lực. |
| **v0.5 Device Regulatory Hardening**([VNCoreExtDeviceRegistrationNumber](StructureDefinition-vn-ext-device-registration-number.md),[VNMedicalDeviceRegistrationNumberNS](NamingSystem-vn-medical-device-registration-number-ns.md)) | Thêm số lưu hành thiết bị y tế, ví dụ class A/B/C, hardening risk class/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 đủ governance, nhưng thiết bị cấy ghép C/D cần dấu vết số lưu hành và lifecycle rõ hơn. |
| **v0.5 BHYT Reconciliation and Gateway Endpoint**([VNCorePaymentReconciliation](StructureDefinition-vn-core-payment-reconciliation.md),[VNCoreEndpointBHYT](StructureDefinition-vn-core-endpoint-bhyt.md)) | 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 submit là workflow/gateway semantics riêng, cần tách khỏi hồ sơ lâm sàng lõi. |
| **v0.5 Privacy Incident and Audit Baseline**([VNCoreCompositionBreachNotification](StructureDefinition-vn-core-composition-breach-notification.md),[VNCoreExtAuditRetention](StructureDefinition-vn-ext-audit-retention.md),[VNCoreExtConsentMethod](StructureDefinition-vn-ext-consent-method.md)) | 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 và NĐ 356/2025 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](StructureDefinition-vn-core-healthcare-service.md)) | 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](StructureDefinition-vn-core-diagnostic-report-lab.md),[VNCoreDiagnosticReportImaging](StructureDefinition-vn-core-diagnostic-report-imaging.md),[VNCoreDiagnosticReportPathology](StructureDefinition-vn-core-diagnostic-report-pathology.md)theo parent-child pattern từ[VNCoreDiagnosticReport](StructureDefinition-vn-core-diagnostic-report.md). | 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](StructureDefinition-vn-core-device.md)với identifier slicing`medicalDeviceItemCode`,`serialNumber`, mở rộng UDI/lifecycle/MS theo FHIR base và thêm[VNCoreExtDeviceGroup](StructureDefinition-vn-ext-device-group.md)ở mức fallback; 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](StructureDefinition-vn-core-device.md)relax`type`về`0..1 MS`; chưa required binding vào QĐ 847/QĐ 3107/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ờ governance. |
| **ADR-0007 — VNCoreImplantableDevice**(`wiki/decisions/adr-0007-implantable-device-profile.md`) | Thêm[VNCoreImplantableDevice](StructureDefinition-vn-core-implantable-device.md), patient-bound với`patient/type/status 1..1`, UDI/lifecycle/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](StructureDefinition-vn-core-organization-department.md),[VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md),[VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md). | Ba profile này chặn các workflow thực tế:`MA_KHOA`, cấp phát thuốc sau kê đơn, và metadata DICOM/RIS/PACS cho CĐHA. |
| **wave2-legal-consolidated**(`governance/v0.4-decisions/wave2-legal-consolidated.md`) | Tổng hợp 3 legal cross-reviews 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 mã khoa 54 codes, TT 24/2025 cho TBYT, TT 26/2025 và NĐ 163/2025 cho đơn thuốc/cấp phát, QĐ 2493 morphology binding extensible. |

-------

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

| | |
| :--- | :--- |
| Hiểu package boundary chi tiết | [Kiến trúc gói phát hành](package-architecture.md) |
| Xem nghĩa vụ theo actor | [Tuân thủ theo vai trò triển khai](conformance-by-actor.md) |
| Tra căn cứ pháp lý cụ thể | [Cơ sở pháp lý](legal-basis.md) |
| Xem security/privacy baseline | [Bảo mật và quyền riêng tư](security.md) |

## English Summary

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.

