HL7 Vietnam VN Core FHIR Implementation Guide

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.5.0 - Draft for Community Review

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## Kiến trúc gói phát hành

# Kiến trúc gói phát hành — Package Architecture

VN Core tách thành 6 gói phát hành với ranh giới rõ ràng giữa lõi, lớp nghiệp vụ, terminology và thiết bị y tế.

Package boundary là rule quản trị của bản phát hành, không phải tiện ích đóng gói. Nếu một quyết định làm đổi semantic lõi, đổi lớp nghiệp vụ hoặc đổi nhịp phát hành, nó phải được phản ánh ở boundary này.

Nếu đang tìm điểm vào theo vai trò triển khai thay vì theo package, xem thêm Tuân thủ theo vai trò triển khai.

## Quy tắc package boundary

- Không dồn toàn bộ artifact vào một gói đơn khối.
- Không trộn `VN Core Base`, `BHYT Submission` và các terminology packages vào cùng một lớp ngữ nghĩa.
- Không kéo logic gateway, facade hoặc payer submission ngược trở lại `VN Core Base` nếu đó không phải semantic lõi.

## Package boundary đang giữ những gì

Kiến trúc gói phát hành hiện hành được dùng để:

1. Giữ `VN Core Base` ổn định nhất có thể cho liên thông FHIR-native.
2. Tách `BHYT Submission` khỏi lõi để logic payer-facing không làm lệch semantic dùng chung.
3. Tách các `terminology packages` lớn khỏi lõi để giảm độ rung khi phát hành.
4. Tách package `hl7.fhir.vn.device` cho danh pháp thiết bị, catalog/regulatory workflow và các lớp asset/procurement khi có use case.
5. Giữ lớp `gateway / API facade / LGSP` ở narrative guidance, `CapabilityStatement` và script kiểm tra thay vì tạo package khi chưa có nhịp phát hành độc lập.
6. Duy trì một `gói tổng hợp` để kiểm tra cục bộ, đào tạo và cài đặt nhanh trong giai đoạn đầu.

## Các gói phát hành

Gói | Vai trò | Dùng khi nào
--- | --- | ---
`hl7.fhir.vn.core` | Gói tổng hợp | Kiểm tra cục bộ, đào tạo, thử nghiệm nhanh và cài đặt trọn bộ
`hl7.fhir.vn.core.base` | Gói lõi ổn định | EMR, HIE, hồ sơ công dân, dữ liệu dùng chung và liên thông FHIR-native
`hl7.fhir.vn.bhyt.submission` | Gói liên thông hồ sơ thanh toán BHYT | Gateway, adapter, kiểm tra và ánh xạ hồ sơ thanh toán; phụ thuộc `hl7.fhir.vn.core.base`
`hl7.fhir.vn.terminology.clinical` | Gói thuật ngữ lâm sàng | ICD-10 VN, ICD-9-CM, SNOMED CT VN subset, CLS, LOINC, ConceptMap lâm sàng
`hl7.fhir.vn.terminology.traditional-medicine` | Gói thuật ngữ Y học cổ truyền | Toàn bộ bộ mã Y học cổ truyền hiện hành
`hl7.fhir.vn.device` | Gói thiết bị y tế | Danh pháp thiết bị, `DeviceDefinition`, regulatory workflow, UDI guidance, kiểm định, asset và procurement khi có use case

### Quy mô tài nguyên ở phiên bản `0.5.0`

Gói | Số lượng tài nguyên
--- | ---
`hl7.fhir.vn.core.base` | 387
`hl7.fhir.vn.bhyt.submission` | 51
`hl7.fhir.vn.terminology.clinical` | 12
`hl7.fhir.vn.terminology.traditional-medicine` | 20
`hl7.fhir.vn.device` | 3
`hl7.fhir.vn.core` | 474

## Ranh giới nội dung

### `hl7.fhir.vn.core.base`

Giữ lại:

- Hồ sơ, phần mở rộng, hệ định danh, tham số tìm kiếm và `CapabilityStatement` mức cơ sở;
- Bộ mã nền tảng dùng xuyên nhiều hồ sơ như định danh, dân tộc, tôn giáo, nghề nghiệp, tỉnh/xã/huyện lịch sử, loại hình cơ sở, hạng, cấp, tuyến kỹ thuật lịch sử, chức danh, chuyên khoa, trình độ, đồng ý xử lý dữ liệu;
- Các ví dụ và tài liệu phục vụ triển khai FHIR-native;
- Ngữ nghĩa đủ dùng cho `EMR/HSSK`, ứng dụng công dân, chia sẻ dữ liệu dùng chung và hướng dẫn theo từng vai trò ở lớp lõi.

Không đưa vào:

- Logical model và operation chuyên cho lớp liên thông hồ sơ thanh toán BHYT;
- Các bộ thuật ngữ lâm sàng quy mô lớn;
- Các bộ thuật ngữ Y học cổ truyền;
- Logic gateway, facade và orchestration tích hợp theo từng cổng cụ thể.

### `hl7.fhir.vn.bhyt.submission`

Giữ lại:

- `VNCoreBHYTSubmissionBundle`;
- Logical model Check-in + XML 1-12;
- Operation validate, gửi, thu hồi;
- Bộ mã gắn chặt với lớp gửi nhận hồ sơ và thanh toán như loại thẻ BHYT, mã đối tượng đến KCB, kết quả điều trị, tình trạng ra viện, nhóm chi phí, lý do bất khả kháng, loại tai nạn.

Không kéo ngược vào gói lõi:

- Định dạng xuất cổng;
- Quy tắc `MA_LK`, `SO_CCCD`, `yyyyMMddHHmm`;
- Capability theo vai trò gateway;
- Logic tái sử dụng dữ liệu hoặc `LGSP/API facade` không gắn riêng với quy trình nghiệp vụ của bên thanh toán.

### Lớp hướng dẫn không tách thành gói riêng

Ở thời điểm `0.3.0` đến `v0.5.0`, repo không tạo package riêng cho LGSP/API facade. Lý do:

- Đây là lớp hướng dẫn triển khai, ma trận vai trò và ranh giới tích hợp, không phải tập tài nguyên tiêu thụ độc lập như terminology hay payer submission;
- Phần này nên nằm trong narrative pages, `CapabilityStatement`, `OperationDefinition`, validation scripts và tài liệu quản trị;
- Việc mở thêm gói chỉ nên cân nhắc khi có bên sử dụng rõ ràng và nhịp phát hành độc lập.

### `hl7.fhir.vn.terminology.clinical`

Giữ lại:

- `ICD-10 VN`;
- `ICD-9-CM`;
- `SNOMED CT VN subset`;
- `CLS`;
- `LOINC`;
- `ConceptMap` lâm sàng liên quan.

Trong gói này, các bộ mã quy mô lớn có thể được công bố dưới dạng tài nguyên FHIR JSON sinh sẵn thay vì FSH nếu đó là cách ổn định hơn để bảo toàn dữ liệu nguồn và giảm độ rung khi biên dịch.

### `hl7.fhir.vn.terminology.traditional-medicine`

Giữ lại:

- Toàn bộ 10 `CodeSystem` Y học cổ truyền;
- Các `ValueSet` tương ứng;
- Provenance pháp lý theo từng quyết định hiện hành.

Ở trạng thái hiện tại, toàn bộ 10 `CodeSystem` Y học cổ truyền đều được công bố bằng tài nguyên FHIR JSON sinh sẵn từ dữ liệu nguồn có căn cứ pháp lý rõ ràng; các `ValueSet` và narrative tiếp tục được duy trì riêng để thuận tiện cho biên tập chuyên môn và mô tả song ngữ.

### `hl7.fhir.vn.device`

Giữ lại:

- `VNMedicalDeviceNomenclatureCS` tổng hợp QĐ-3107/QĐ-BYT-2024 và QĐ-847/QĐ-BYT-2025;
- `VNMedicalDeviceNomenclatureVS` và `VNDeviceTypeVS` cho binding `preferred` trong package `.device`;
- Các profile/package tương lai cho `DeviceDefinition`, regulatory workflow, UDI guidance, kiểm định, asset, procurement và lifecycle thiết bị khi có use case triển khai.

Không kéo ngược vào Core:

- Required binding `VNCoreDevice.type` vào danh pháp thiết bị;
- Catalog, số lưu hành, hồ sơ lưu hành, kiểm định, bảo trì, định mức, mua sắm và mã tài sản;
- Mapping SNOMED CT/GMDN/EMDN nếu chưa có license/provenance và ConceptMap được review.

## Ma trận phụ thuộc

Gói | Phụ thuộc tối thiểu
--- | ---
`hl7.fhir.vn.core` | `hl7.fhir.r4.core`, `hl7.terminology.r4`
`hl7.fhir.vn.core.base` | `hl7.fhir.r4.core`, `hl7.terminology.r4`, `hl7.fhir.vn.terminology.clinical`, `hl7.fhir.vn.terminology.traditional-medicine`
`hl7.fhir.vn.bhyt.submission` | `hl7.fhir.r4.core`, `hl7.fhir.vn.core.base`
`hl7.fhir.vn.terminology.clinical` | `hl7.fhir.r4.core`, `hl7.terminology.r4`
`hl7.fhir.vn.terminology.traditional-medicine` | `hl7.fhir.r4.core`, `hl7.terminology.r4`
`hl7.fhir.vn.device` | `hl7.fhir.r4.core`, `hl7.fhir.vn.core.base`

## Hướng dẫn dùng gói trong giai đoạn thử nghiệm

### Kiểm tra cục bộ

Ưu tiên dùng:

- `hl7.fhir.vn.core` nếu cần cài trọn bộ;
- Hoặc truyền đồng thời nhiều `-ig` nếu cần kiểm tra theo từng gói mô-đun.

### Trạng thái công bố hiện tại

Ở thời điểm hiện tại:

- Cả `6` gói đã được công bố công khai ở mức thử nghiệm trên website và canonical của VN Core/VN Device;
- `hl7.fhir.vn.core` là gói tổng hợp và là điểm vào mặc định cho đa số đơn vị triển khai;
- 5 gói mô-đun đều có `package-list.json`, `history.html`, và trang đích công bố riêng dưới đúng đường dẫn canonical của từng gói;
- Các gói hiện vẫn dùng chung một website hướng dẫn triển khai tổng hợp, chưa tách thành 5 Implementation Guide độc lập;
- Hồ sơ mirror lên `packages.fhir.org` đã được chuẩn bị như một bước đăng ký riêng, nhưng vẫn chờ tiếp nhận ngoài repo;
- Trước khi mirror đó hoàn tất, kiểm tra cục bộ vẫn nên ưu tiên gói tổng hợp hoặc truyền tường minh nhiều `-ig`.

### Triển khai EMR và liên thông nội bộ

Ưu tiên:

- `hl7.fhir.vn.core.base`;
- Cộng các gói thuật ngữ khi môi trường validator hoặc máy chủ FHIR chưa tự kéo được phụ thuộc từ file `.tgz` cục bộ.

### Triển khai gateway BHYT

Ưu tiên:

- `hl7.fhir.vn.core.base`;
- `hl7.fhir.vn.bhyt.submission`;
- Cộng các gói thuật ngữ khi cần kiểm tra cục bộ hoặc build độc lập.

## Governance tối thiểu

Mỗi gói phải có:

- Phạm vi rõ;
- Phụ thuộc rõ;
- Release note;
- Căn cứ pháp lý/provenance;
- Tiêu chí `hiện hành`, `lịch sử`, `ngừng dùng`;
- Kiểm tra chất lượng trước khi phát hành.

Đối với một bản phát hành đủ điều kiện công bố công khai, bộ build nội bộ phải chứng minh tối thiểu:

- `0 lỗi` trong `output/qa.html` hoặc `output/qa.json`;
- `0 cảnh báo` trong `output/qa.html` hoặc `output/qa.json`;
- `0 liên kết hỏng` trong `output/qa.html`;
- Mọi suppressed message đều có giải trình rõ trong `input/ignoreWarnings.txt`.

Lưu ý: số lượng liên kết hỏng có thể được IG Publisher báo riêng với số lượng lỗi/cảnh báo, nên ngưỡng phát hành phải kiểm tra tường minh phần này thay vì chỉ nhìn tổng số lỗi.

Nguồn sự thật quản trị cho việc phân loại tài nguyên hiện nằm tại:

- `governance/packages/package-artifact-classification.json`
- `governance/packages/README.md`

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

Nếu cần | Nên đọc tiếp
--- | ---
Vai trò triển khai và CapabilityStatement | Conformance by Actor
Quy trình phát hành các gói | Release Governance
Chiến lược ổn định và maturity | Stability and Conformance
Quyết định thiết kế gói | Design Decisions

## English Summary

This page explains the VN Core package boundary. VN Core publishes one aggregate package, one stable base package, one payer-facing `BHYT Submission` package, two terminology packages, and one medical-device package. Implementers should choose packages by scope and avoid pulling gateway, payer-specific, or device regulatory/catalog logic back into `VN Core Base`.