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

Ổn định & Conformance

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

Trang này mô tả chiến lược ổn định hóa VN Core, 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) và các gói thuật ngữ, cùng các yêu cầu tuân thủ mức cơ sở theo từng vai trò triển khai.

Trang này dành cho ai?

• Nhóm kiến trúc và quản trị tiêu chuẩn cần biết lõi nào đủ ổn định để đưa vào giai đoạn thí điểm hoặc mở rộng tích hợp.
• Nhóm implementer cần hiểu package nào thay đổi chậm, package nào thay đổi nhanh hơn.
• Nhóm QA và reviewer cộng đồng cần tiêu chí maturity rõ ràng để đánh giá tài nguyên.

Những gì dự án hiện tại cố ý làm chặt hơn

Repo hiện tại đặt mục tiêu trưởng thành rõ rệt ở lớp conformance:

• Không dồn tất cả vào một đặc tả đơn khối;
• Không coi profile là đủ nếu thiếu hướng dẫn theo vai trò triển khai, CapabilityStatement, ví dụ và bộ kiểm thử;
• Không để canonical discipline, current/legacy/deprecated policy và package governance bị xem nhẹ;
• Không để terminology và legal provenance đứng ngoài chiến lược ổn định hóa.

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.

Sau khi định hướng lại theo hướng lấy dữ liệu làm trung tâm, nhánh ổn định tiếp theo không chỉ là “ổn định kỹ thuật”, mà còn là gia cố theo trục quản trị dữ liệu, VNeID, EMR/HSSK, LGSP/API facade và ưu tiên bảo mật.

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

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

2.1. 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 4 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ả 5 gói đã được công bố công khai trên website và canonical của VN Core; hồ sơ đăng ký cho packages.fhir.org đã được chuẩn bị nhưng vẫn phụ thuộc bước tiếp nhận ngoài repo. Trước khi kênh mirror đó 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.

3. Mô hình mức độ trưởng thành

Đ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

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

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

6. Tự động hóa kiểm tra tuân thủ

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

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

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

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

6.5. 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-7 qua DiagnosticReport + Composition, xml8-9 qua newborn/maternity documents, xml10 qua death certificate, xml11 qua HIV treatment record, và xml12 qua supporting documents
• 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

6.6. 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ữ

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

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

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

English Summary

VN Core is moving to a stabilization-first strategy. After alignment with the Ministry of Health's digital strategy and architecture decisions, this stabilization phase now explicitly includes data governance, VNeID-aligned identity semantics, EMR/HSSK interoperability, LGSP/API facade guidance, and security-first pilot readiness. The guide distinguishes VN Core Base from the faster-moving BHYT Submission layer, introduces an artifact maturity model, defines a release/deprecation policy, and publishes role-specific CapabilityStatements for EMR servers, BHYT gateway clients/servers, and citizen-facing apps. Conformance is no longer documentation-only: repository scripts now cover baseline validation, BHYT submission checks, and executable Tier 2 rules such as CCCD gender/year consistency, ward-to-province hierarchy, MA_LK, SO_CCCD with force-majeure exception handling, and export datetime formatting.