Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.5.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 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.
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, telehealth hoặc Bulk Data.

Ranh giới package

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:

Đ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

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ó 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ị. 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 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. 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:

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

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.