Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.10.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Ổn định & Conformance

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

Chiến lược ổn định hoá 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 gói thuật ngữ và gói 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 khi mở rộng triển khai, VN Core ưu tiên kiểm thử 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.

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.
2. Ư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.
3. 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.
4. 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ý.
5. Ư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, khám từ xa hoặc Bulk Data.

Ranh giới gói

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 tập lệnh 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 ngữ nghĩa cốt lõi.
• Hướng dẫn cho LGSP/API facade, tái sử dụng dữ liệu và ma trận vai trò/bộ dữ liệu nằm ở lớp diễn giải/tuân thủ, 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 8 gói mô-đun và 1 gói tổng hợp:

Đ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ả 9 gói (8 mô-đun + gói tổng hợp) đã được dựng; 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

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

Đ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ó kiểm thử đạt 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ị. Phần dưới đây giữ vai trò tóm tắt ở mức tuân thủ.

Quy tắc ngừng dùng

• Không xoá 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. 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ố 10 CapabilityStatement. Năm bản chính:

Năm bản chuyên biệt còn lại: VNCoreDataResponder và VNCoreDataRequester (trao đổi đọc giữa hai cơ sở), VNFormsDocumentSource và VNFormsDocumentConsumer (trao đổi bảng kê và biểu mẫu đã ký), VNEServiceGateway (cổng dịch vụ công).

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.

Hợp đồng ghi/đọc — bổ sung từ 0.10.0

Trước 0.10.0, các CapabilityStatement chỉ khai interaction và searchParam. Điều đó đủ để nói làm được gì, nhưng không nói ghi và đọc lại theo luật nào. Hệ quả đo được: hai máy chủ cùng tuyên bố conform một profile vẫn có thể không tương thích khi ghi — không thống nhất chống lost update, không thống nhất cách chống trùng khi gửi lại, và không rõ có đọc lại được phiên bản cũ hay không.

Từ 0.10.0, mọi CapabilityStatement mô tả máy chủ khai thêm hợp đồng ấy ở dạng máy đọc được. Khuôn được chọn theo đúng tương tác mà mục resource ấy khai — một cờ nói về tương tác không tồn tại thì bên đọc không biết tin phần nào:

referencePolicy chỉ khai literal. Cố ý không khai resolves (nghĩa hẹp: máy chủ cố chuyển logical sang literal, thất bại vẫn có thể nhận) và không khai enforced ở khuôn dùng chung — enforced là cam kết toàn vẹn tham chiếu, đúng với kho hồ sơ lâm sàng nhưng thường không đúng với cổng hay proxy. Cơ sở bảo đảm được toàn vẹn thì khai enforced trong CapabilityStatement triển khai của mình.

VNCoreServer và VNCoreEMRServer khai thêm transaction và batch ở cấp REST, kèm ghi chú phân biệt: transaction PHẢI nguyên tử, batch thì không. Máy chủ không bảo đảm được tính nguyên tử thì không khai transaction, và bên gửi phải có hợp đồng bù trừ riêng.

Ba điều hợp đồng này chưa phủ, bên triển khai phải tự chốt trong hợp đồng API: giới hạn kích thước payload và tệp đính kèm, quy tắc phân trang ổn định khi dữ liệu thay đổi giữa hai lần gọi, và chính sách lưu trữ/huỷ dữ liệu theo thời hạn.

Các CapabilityStatement mô tả client (VNCoreDataRequester, VNBHYTGatewayClient, VNCitizenAppClient) cố ý không mang nhóm cờ này: client không quyết định chính sách lưu trữ của máy chủ.

Tự động hoá 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:

• VNCoreBHYTSubmissionBundle, 16 logical models (Check-in + XML1–XML15) và 3 operations validate/submit/reverse cho BHYT
• 9 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] chỉ nhận mã số BHYT 10 chữ số hiện hành hoặc số thẻ 15 ký tự lịch sử; CCCD của beneficiary được kiểm tra riêng qua Patient.identifier[CCCD]
• subscriberId khớp identifier[BHYT]
• Thiếu SO_CCCD chỉ hợp lệ khi có lý do bất khả kháng hoặc giấy tờ thay thế được profile cho phép (hộ chiếu/giấy khai sinh)
• 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:

• 9 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 xml15
• Đả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; xml13 (chuyển tuyến), xml14 (hẹn khám lại) và xml15 (quản lý điều trị lao) chỉ sinh khi có fixture 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 ánh xạ ngay trong 16 logical models (Check-in + XML1–XML15) như nguồn sự thật ở mức tài nguyên cho lớp xuất dữ liệu

Các chú thích ^mapping này là đặc tả ánh xạ ở mức element để xây dựng và kiểm thử adapter. Chúng không phải một ConceptMap hoàn chỉnh, đã kiểm chứng đầu-cuối cho toàn bộ XML1–XML15 ↔ Claim/ExplanationOfBenefit; không được suy diễn phạm vi đó từ số lượng ConceptMap của package.

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ộ + kiểm toán, không mã hoá thành trường tuỳ 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

English Summary

This page defines VN Core stability, package boundaries, conformance checks, and release rules. The BHYT layer contains 16 logical models (Check-in plus XML1–XML15) and three operations: validate, submit, and reverse. Element-level ^mapping annotations guide adapters; no end-to-end ConceptMap spanning every table and Claim/ExplanationOfBenefit is published. BHYT identifiers support current 10-digit and legacy 15-character values.