HL7 Vietnam VN Core FHIR Implementation Guide

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.3.0 - STU1 Draft Viet Nam cờ

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

Tuân thủ theo vai trò triển khai

Tuân thủ theo vai trò triển khai — Conformance by Actor

Trang này gom các yêu cầu tuân thủ tối thiểu theo từng nhóm triển khai để người đọc không phải tự ráp lại từ nhiều trang khác nhau. Mục tiêu là giúp mỗi bên biết rõ mình là ai, đang tiêu thụ gói nào, cần đọc gì trước, phải hỗ trợ gì ở mức tối thiểu và khi nào có thể coi là sẵn sàng cho giai đoạn thí điểm.

Trang này dành cho ai?

  • Kiến trúc sư giải pháp, maintainer package và nhóm điều phối tiêu chuẩn cần chốt ranh giới triển khai.
  • Nhóm HIS, EMR, FHIR server, gateway và ứng dụng người dân cần biết đúng tập yêu cầu của vai trò mình.
  • Nhóm QA, reviewer cộng đồng và nhóm quản trị dữ liệu chủ cần một ma trận conformance có thể đối chiếu được.

Dùng trang này như thế nào?

  • Bắt đầu bằng bảng điều hướng nhanh để xác định vai trò triển khai chính.
  • Chỉ đọc sâu vào các mục tương ứng với vai trò mà hệ thống thực sự đảm nhận.
  • Nếu một hệ thống đóng nhiều vai trò, áp dụng hợp của các yêu cầu thay vì chọn một vai trò duy nhất.

Kết quả mong đợi sau khi đọc

  • Biết vai trò triển khai nào tương ứng với hệ thống của mình.
  • Biết gói, trang guidance, CapabilityStatement và ví dụ nào là bắt buộc phải tiêu thụ.
  • Có một checklist tối thiểu để quyết định hệ thống đã sẵn sàng cho giai đoạn thí điểm hay chưa.

Nếu cần chuyển ngay sang lớp tự kiểm tra ngắn, xem Checklist sẵn sàng thí điểm theo vai trò.

Nguyên tắc chung

  • Profile không đủ để chứng minh tuân thủ nếu thiếu CapabilityStatement, examples, search behavior và kiểm tra thực thi được.
  • VN Core Base, lớp liên thông hồ sơ BHYT (BHYT Submission), terminology và governance phải được tiêu thụ theo đúng ranh giới package, không trộn tuỳ tiện.
  • Một vai trò triển khai chỉ nên cam kết những gì đúng với phạm vi của mình; không phải mọi hệ thống đều phải hỗ trợ toàn bộ IG.

1. Điều hướng nhanh theo vai trò triển khai

Vai trò triển khai Họ thường đang cần gì? Nên bắt đầu từ Gói/CapabilityStatement nên xem trước
Kiến trúc tiêu chuẩn, quản trị dữ liệu, điều phối triển khai Chốt phạm vi, package boundary, policy current/legacy/deprecated, readiness của release Kiến trúc gói phát hành hl7.fhir.vn.core, Ổn định và tuân thủ
HIS/EMR/FHIR server nội bộ Ánh xạ dữ liệu nghiệp vụ sang FHIR-native, hỗ trợ search và validation Bắt đầu nhanh hl7.fhir.vn.core.base, VNCoreServer, VNCoreEMRServer
Client gửi hồ sơ thanh toán BHYT Tạo bundle, ánh xạ hồ sơ xuất, gọi operation và kiểm tra dữ liệu trước khi gửi Liên thông hồ sơ BHYT hl7.fhir.vn.bhyt.submission, VNBHYTGatewayClient
Server tiếp nhận hồ sơ thanh toán BHYT hoặc facade tích hợp Tiếp nhận, kiểm tra, phản hồi và quản trị lớp liên thông hồ sơ BHYT Liên thông hồ sơ BHYT hl7.fhir.vn.bhyt.submission, VNBHYTGatewayServer
Ứng dụng người dân, cổng bệnh nhân, tích hợp VNeID Truy cập dữ liệu tối thiểu, đồng ý xử lý dữ liệu, bảo mật và công bố rõ phạm vi dữ liệu Bảo mật và quyền riêng tư hl7.fhir.vn.core.base, VNCitizenAppClient
Nhóm terminology, định danh và dữ liệu chủ Chốt NamingSystem, CodeSystem, ValueSet, provenance và vòng đời mã Danh mục định danh hl7.fhir.vn.core.base, Hướng dẫn thuật ngữ
QA, reviewer cộng đồng, nhóm ballot/thí điểm Đối chiếu maturity, test, examples, release note và implementation report Ổn định và tuân thủ Toàn bộ CapabilityStatement và bộ script kiểm tra

2. Vai trò 1: Kiến trúc tiêu chuẩn, quản trị dữ liệu và điều phối triển khai

Vai trò này là ai?

  • Nhóm thiết kế kiến trúc cấp chương trình hoặc cấp nền tảng.
  • Nhóm điều phối nhiều hệ thống cùng tiêu thụ VN Core.
  • Nhóm phải chốt chính sách phát hành, canonical, vòng đời artifact và ranh giới package.

Họ cần gì?

  • Biết phần nào là lõi FHIR-native, phần nào là lớp liên thông hồ sơ BHYT.
  • Biết artifact nào đang current, artifact nào chỉ giữ cho dữ liệu lịch sử.
  • Biết ngưỡng tối thiểu để cho phép một gói hoặc một vai trò triển khai đi vào giai đoạn thí điểm.

Nên đọc theo thứ tự nào?

  1. Trang chủ
  2. Kiến trúc gói phát hành
  3. Ổn định và tuân thủ
  4. Phát hành và quản trị
  5. Danh mục định danh
  6. Hướng dẫn thuật ngữ

Artifact và quyết định phải chốt

Chủ đề Cần chốt gì?
Package boundary Hệ thống nào tiêu thụ core.base, hệ thống nào cần thêm bhyt.submission, hệ thống nào chỉ cần terminology
Canonical discipline system URI, canonical URL, chính sách đổi phiên bản và ngừng dùng
Identifier governance Tách rõ định danh công dân, định danh payer, định danh tổ chức và định danh cục bộ
Terminology governance Bộ mã nào dùng quốc tế, bộ mã nào là local extension, provenance ở đâu
Conformance Vai trò triển khai nào phải công bố CapabilityStatement, vai trò nào chỉ cần tuân thủ như client

Khi nào vai trò này được xem là sẵn sàng?

  • Đã chốt rõ ma trận vai trò triển khai cho hệ thống trong phạm vi triển khai.
  • Đã xác định package tiêu thụ cho từng vai trò triển khai.
  • Đã có quy trình công bố current / legacy / deprecated cho định danh và thuật ngữ.
  • Đã thống nhất ngưỡng phát hành tối thiểu theo Phát hành và quản trị.

3. Vai trò 2: HIS, EMR và FHIR server nội bộ

Vai trò này là ai?

  • Hệ thống nguồn hoặc hệ thống đích trao đổi dữ liệu FHIR-native trong bệnh viện hoặc mạng lưới chăm sóc.
  • Máy chủ FHIR dùng cho EMR, kho dữ liệu lâm sàng nội bộ, HIE hoặc các API dùng chung.

Họ cần gì?

  • Biết profile nào thực sự cần cho lộ trình triển khai trước mắt.
  • Biết cách diễn giải Must Support, định danh, địa chỉ, search và validation.
  • Biết tối thiểu phải công bố hoặc hỗ trợ gì để được coi là tương thích với VN Core Base.

Nên đọc theo thứ tự nào?

  1. Bắt đầu nhanh
  2. Hướng dẫn chung
  3. Hướng dẫn Must Support
  4. Hành vi tìm kiếm
  5. Hướng dẫn kiểm tra hợp lệ
  6. Hồ sơ

Gói và CapabilityStatement

Nội dung Mức tối thiểu
Gói hl7.fhir.vn.core.base
CapabilityStatement tham chiếu VNCoreServer hoặc VNCoreEMRServer tùy vai trò hệ thống
Resource cần ưu tiên Patient, RelatedPerson, Practitioner, Organization, Location, Encounter, Coverage, Condition, Observation, MedicationRequest, DocumentReference, Composition, Consent, AuditEvent, Provenance

Tối thiểu phải hỗ trợ gì?

  • Đọc và ghi đúng các profile lõi thuộc use case đã cam kết.
  • Hỗ trợ tìm kiếm token, string, date, reference theo đúng Hành vi tìm kiếm.
  • Xử lý đúng Identifier theo system URI, không thay bằng chuỗi hiển thị cục bộ.
  • Tôn trọng các quy tắc Must Support, Data Absent Reason và validation mức cơ sở.

Khi nào vai trò này được xem là sẵn sàng?

  • Ví dụ đại diện của chính hệ thống đã pass ./scripts/validate.sh.
  • Những quy tắc rủi ro cao đã pass ./scripts/validate-tier2.sh hoặc kiểm tra tương đương.
  • Search behavior đã được công bố rõ cho các truy vấn nghiệp vụ chính.
  • Ít nhất một CapabilityStatement nội bộ đã được đối chiếu với VNCoreServer hoặc VNCoreEMRServer.

4. Vai trò 3: Client gửi hồ sơ thanh toán BHYT

Vai trò này là ai?

  • HIS, middleware hoặc adapter chịu trách nhiệm tạo và gửi hồ sơ thanh toán BHYT.
  • Hệ thống không nhất thiết phải là máy chủ FHIR tổng quát, nhưng phải tạo được dữ liệu submission đúng ngữ nghĩa.

Họ cần gì?

  • Biết đâu là ngữ nghĩa lõi FHIR và đâu là ràng buộc xuất dữ liệu cho lớp liên thông hồ sơ BHYT.
  • Biết bundle nào, operation nào và tập kiểm tra nào là bắt buộc.
  • Biết cách ánh xạ MA_LK, MA_LUOT_KCB, SO_CCCD, subscriberId, identifier[BHYT] và các bảng xuất.

Nên đọc theo thứ tự nào?

  1. Liên thông hồ sơ BHYT
  2. Danh mục định danh
  3. Ánh xạ URI/OID
  4. Hướng dẫn kiểm tra hợp lệ
  5. Ổn định và tuân thủ

Gói và CapabilityStatement

Nội dung Mức tối thiểu
Gói hl7.fhir.vn.core.base + hl7.fhir.vn.bhyt.submission
CapabilityStatement tham chiếu VNBHYTGatewayClient
Operation cần biết $validate-bhyt-claim, $submit-bhyt-claim, $reverse-bhyt-claim

Tối thiểu phải hỗ trợ gì?

  • Sinh đúng VNCoreBHYTSubmissionBundle và các resource lõi liên quan.
  • Bảo đảm nhất quán giữa Coverage, Claim, Encounter, Patient và các logical model xuất.
  • Kiểm soát chặt các trường định danh và thời gian theo quy tắc của lớp liên thông hồ sơ BHYT, không đẩy ngược logic đó vào profile lõi khi không cần.

Khi nào vai trò này được xem là sẵn sàng?

  • Pass ./scripts/validate-bhyt-submission.sh.
  • Pass ./scripts/validate-bhyt-roundtrip.sh với các gói hồ sơ mà hệ thống đã cam kết hỗ trợ.
  • Có bộ ví dụ dương tính và âm tính đại diện cho ca sử dụng thực của đơn vị.
  • Đã công bố rõ lỗi nào được chặn ở phía client trước khi gửi gateway.

5. Vai trò 4: Server tiếp nhận hồ sơ thanh toán BHYT hoặc facade tích hợp

Vai trò này là ai?

  • Hệ thống tiếp nhận bundle hồ sơ thanh toán BHYT, thực hiện kiểm tra, chuẩn hóa, phản hồi hoặc bắc cầu sang cổng nghiệp vụ phía sau.
  • Lớp này thường mang vai trò gateway, facade hoặc adapter, không nên bị đồng nhất với core.base.

Họ cần gì?

  • Biết ranh giới giữa semantic cốt lõi và logic của lớp liên thông hồ sơ BHYT.
  • Biết mức kiểm tra nào phải thực hiện ở phía server.
  • Biết cách công bố hành vi lỗi, validation và phản hồi theo operation.

Nên đọc theo thứ tự nào?

  1. Liên thông hồ sơ BHYT
  2. Kiến trúc gói phát hành
  3. Ổn định và tuân thủ
  4. Bảo mật và quyền riêng tư

Gói và CapabilityStatement

Nội dung Mức tối thiểu
Gói hl7.fhir.vn.bhyt.submission
CapabilityStatement tham chiếu VNBHYTGatewayServer
Vùng trách nhiệm Operation, kiểm tra bundle, kiểm toán, tách quyền dịch vụ và logging

Tối thiểu phải hỗ trợ gì?

  • Kiểm tra bundle và logical model theo chính sách của lớp liên thông hồ sơ BHYT.
  • Phân biệt lỗi cú pháp, lỗi ngữ nghĩa và lỗi nghiệp vụ cổng.
  • Ghi nhận AuditEvent và Provenance ở mức phù hợp với vai trò gateway.
  • Không tự ý mở rộng semantic của profile lõi chỉ để giải quyết yêu cầu orchestration cục bộ.

Khi nào vai trò này được xem là sẵn sàng?

  • Các operation đã có mô tả đầu vào, đầu ra và mã lỗi ở mức có thể kiểm thử.
  • Có kiểm tra bảo mật tối thiểu theo Bảo mật và quyền riêng tư.
  • Có nhật ký kiểm toán đủ để truy vết ca gửi, kiểm tra, trả kết quả và thu hồi.
  • Có giới hạn trách nhiệm rõ giữa gateway và hệ thống nguồn.

6. Vai trò 5: Ứng dụng người dân, cổng bệnh nhân và tích hợp VNeID

Vai trò này là ai?

  • Ứng dụng di động, cổng bệnh nhân, cổng công dân hoặc lớp tích hợp phục vụ truy cập dữ liệu cho cá nhân.
  • Hệ thống chủ yếu đọc dữ liệu và công bố rõ phạm vi truy cập, đồng ý xử lý dữ liệu và kiểm toán.

Họ cần gì?

  • Biết resource nào nên mở cho người dân ở giai đoạn đầu.
  • Biết cách giới hạn phạm vi dữ liệu theo mục đích sử dụng.
  • Biết cách diễn giải Consent, AuditEvent, Provenance và bảo mật mức cơ sở.

Nên đọc theo thứ tự nào?

  1. Bảo mật và quyền riêng tư
  2. Hướng dẫn chung
  3. Hồ sơ
  4. Ổn định và tuân thủ

Gói và CapabilityStatement

Nội dung Mức tối thiểu
Gói hl7.fhir.vn.core.base
CapabilityStatement tham chiếu VNCitizenAppClient
Resource cần ưu tiên Patient, RelatedPerson, Coverage, DocumentReference, Composition, Consent, AuditEvent, Provenance

Tối thiểu phải hỗ trợ gì?

  • Chỉ truy cập đúng tập dữ liệu đã công bố và có căn cứ chia sẻ rõ.
  • Tách quyền người dùng cuối, tài khoản dịch vụ và cơ chế break-glass.
  • Công bố rõ search và phạm vi đọc, tránh suy diễn rằng ứng dụng người dân có quyền như hệ thống lâm sàng nội bộ.

Khi nào vai trò này được xem là sẵn sàng?

  • Có ma trận quyền truy cập và lưu giữ tối thiểu.
  • Có ví dụ hoặc luồng kiểm thử chứng minh Consent, AuditEvent và Provenance hoạt động đúng.
  • Có chính sách giảm thiểu dữ liệu và giải thích rõ cho người dùng cuối phạm vi dữ liệu đang hiển thị.

7. Vai trò 6: Terminology, định danh và dữ liệu chủ

Vai trò này là ai?

  • Nhóm quản trị NamingSystem, CodeSystem, ValueSet, mapping và các danh mục dùng chung.
  • Nhóm chịu trách nhiệm chốt system URI, nguồn pháp lý, provenance và quy tắc current/legacy/deprecated.

Họ cần gì?

  • Biết danh mục nào là hạ tầng dùng chung, không phải chi tiết phụ của từng profile.
  • Biết nguyên tắc kết hợp thuật ngữ quốc tế với danh mục Việt Nam.
  • Biết quy trình thay đổi mã, thay đổi binding và ảnh hưởng lên triển khai.

Nên đọc theo thứ tự nào?

  1. Danh mục định danh
  2. Ánh xạ URI/OID
  3. Hướng dẫn thuật ngữ
  4. Thuật ngữ
  5. Phát hành và quản trị

Tối thiểu phải hỗ trợ gì?

  • Quản trị vòng đời current / legacy / deprecated cho từng hệ định danh và bộ mã.
  • Duy trì provenance, căn cứ pháp lý và ghi chú chuyển đổi khi có thay đổi đáng kể.
  • Công bố rõ bộ mã nào là bắt buộc, bộ mã nào chỉ là guidance hoặc bridge.

Khi nào vai trò này được xem là sẵn sàng?

  • Có registry nhất quán cho NamingSystem, CodeSystem, ValueSet.
  • Có snapshot hoặc báo cáo khác biệt trước mỗi thay đổi thuật ngữ.
  • Có nguyên tắc rõ về dùng LOINC, SNOMED CT, ICD trước khi bổ sung danh mục Việt Nam.

8. Vai trò 7: QA, reviewer cộng đồng và nhóm đánh giá maturity

Vai trò này là ai?

  • Nhóm rà soát chất lượng phát hành, tổ chức thí điểm, chuẩn bị ballot hoặc đánh giá khả năng tiêu thụ.
  • Nhóm này không nhất thiết vận hành hệ thống, nhưng phải quyết định một release đã đủ chín chưa.

Họ cần gì?

  • Một ma trận kiểm tra lặp lại được.
  • Bộ tiêu chí rõ để đánh giá maturity, examples, scripts và release note.
  • Một cấu trúc implementation report có thể dùng chung cho nhiều đơn vị.

Nên đọc theo thứ tự nào?

  1. Ổn định và tuân thủ
  2. Hướng dẫn kiểm tra hợp lệ
  3. Báo cáo triển khai
  4. Phát hành và quản trị

Tối thiểu phải hỗ trợ gì?

  • Đối chiếu vai trò triển khai với CapabilityStatement, ví dụ và script kiểm tra tương ứng.
  • Phân biệt lỗi do nội dung, lỗi do package, lỗi do thiếu implementation guidance và lỗi do môi trường cài đặt.
  • Theo dõi rõ phần nào đã có test tự động và phần nào vẫn cần review thủ công.

Khi nào vai trò này được xem là sẵn sàng?

  • Có checklist lặp lại được cho từng vai trò triển khai chính.
  • Các script kiểm tra mức cơ sở đều xanh trên bản phát hành mục tiêu.
  • Có ít nhất một implementation report hoặc báo cáo thử nghiệm cho vai trò triển khai đang đánh giá.

9. Nếu một hệ thống đóng nhiều vai trò

Rất nhiều hệ thống ở Việt Nam vừa là EMR server, vừa là client gửi hồ sơ thanh toán BHYT, đôi khi còn kiêm cổng bệnh nhân. Trong trường hợp đó:

  • Không dùng một CapabilityStatement duy nhất để đại diện cho mọi vai trò;
  • Không trộn các ràng buộc của lớp liên thông hồ sơ BHYT trở lại vào profile lõi nếu chúng chỉ đúng cho một luồng cụ thể;
  • Không coi việc pass một bộ test của vai trò này là đã đủ cho vai trò khác.

Khuyến nghị thực tế là tách đánh giá theo vai trò trước, sau đó mới lập ma trận tích hợp tổng thể của hệ thống.

10. Kết nối với các trang khác

Nếu bạn cần Nên đọc tiếp
Biết vai trò triển khai nào đang ở mức ổn định cao hơn Ổn định và tuân thủ
Tự kiểm tra nhanh mức sẵn sàng thí điểm của từng vai trò triển khai Checklist sẵn sàng thí điểm theo vai trò
Biết package nào tương ứng với từng vai trò triển khai Kiến trúc gói phát hành
Biết cách diễn giải nghĩa vụ đọc/ghi ở cấp element Hướng dẫn Must Support
Biết cách kiểm tra hệ thống trước giai đoạn thí điểm Hướng dẫn kiểm tra hợp lệ
Biết cách báo cáo một ca triển khai thật Báo cáo triển khai

English Summary

This page reorganizes VN Core conformance guidance by implementation actor. Instead of asking implementers to infer obligations from profiles alone, it explains what each actor needs, which packages and CapabilityStatements apply, what the minimum support expectations are, and when an actor can be considered pilot-ready. The page covers governance/architecture teams, EMR/FHIR servers, BHYT submission clients, gateway/facade servers, citizen-facing apps, terminology and identifier governance teams, and QA/review groups.