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

Phát hành & Governance

Phát hành và quản trị — Release and Governance

Trang này mô tả khung quản trị tối thiểu cho VN Core trong giai đoạn trial-use.

Mục tiêu là:

  • Công bố rõ cách phân loại thay đổi
  • Siết chất lượng phát hành mà không tự làm quy trình quá nặng
  • Giúp cộng đồng hiểu cách góp ý, cách theo dõi thay đổi và cách đọc mức độ ổn định của từng tài nguyên

Trang này dành cho ai?

  • Nhóm duy trì IG, reviewer cộng đồng và những người chuẩn bị đề xuất thay đổi.
  • Đơn vị triển khai muốn hiểu mức cam kết ổn định của từng đợt phát hành.
  • Nhóm QA và quản trị sản phẩm cần biết ngưỡng tối thiểu trước khi gắn thẻ công bố.

VN Core 0.3.x vẫn là bản dự thảo thử nghiệm do cộng đồng duy trì. Đây chưa phải chuẩn bắt buộc hoặc chuẩn do cơ quan nhà nước ban hành. Vì vậy, khung quản trị hiện tại ưu tiên minh bạch, ổn định và phản hồi từ triển khai thực tế hơn là quy trình hành chính nặng.

1. Nguyên tắc quản trị hiện tại

  1. Ưu tiên ổn định VN Core Base trước khi mở rộng phạm vi.
  2. Chỉ đưa vào bản phát hành công khai những gì đã có ví dụ, hướng dẫn và kiểm tra tối thiểu.
  3. Tách lớp liên thông hồ sơ thanh toán BHYT (BHYT Submission) và các gói thuật ngữ lớn để giảm độ rung của core.
  4. Mọi thay đổi có thể ảnh hưởng đến bên triển khai phải có phần diễn giải hoặc ghi chú chuyển đổi tương ứng.

2. Phân loại thay đổi

Loại thay đổi Áp dụng điển hình Kỳ vọng tài liệu đi kèm
Patch / stabilization sửa ví dụ, sửa tài liệu, sửa liên kết hỏng, sửa câu chữ, giảm nhiễu QA, gia cố script changelog ngắn, không đổi ngữ nghĩa cốt lõi
Additive thêm profile, extension, search parameter, ví dụ, operation, mã mới đang hiệu lực changelog + hướng dẫn + ví dụ
Breaking đổi URL tài nguyên, đổi cardinality, đổi binding theo cách làm dữ liệu cũ không còn hợp lệ, đổi hợp đồng tìm kiếm ghi chú chuyển đổi bắt buộc + cảnh báo phát hành

2.1. Cách áp dụng trong giai đoạn 0.x

Do VN Core chưa ở 1.0.0, thay đổi bổ sung vẫn có thể đi nhanh hơn một bản phát hành trưởng thành. Tuy nhiên:

  • Nhóm duy trì SHOULD không gộp thay đổi phá vỡ ngữ nghĩa vào bản vá.
  • Nhóm duy trì SHOULD hạn chế mở rộng phạm vi quá lớn trong những ngày cuối trước khi gắn thẻ công bố.
  • Mọi thay đổi làm bên triển khai phải sửa dữ liệu hoặc logic tích hợp SHALL được ghi rõ trong changelog.

3. Ngưỡng phát hành tối thiểu trước khi công bố

Trước khi công bố một bản trial-use, nhóm duy trì nên bảo đảm tối thiểu:

  • ./scripts/validate.sh --quick pass.
  • ./scripts/validate-tier2.sh pass nếu thay đổi chạm đến data rules quốc gia.
  • bash _genonce.sh pass.
  • output/qa.html không còn errors, warnings, broken links.
  • Câu chữ của trang chủ, trang tải xuống, README và changelog đồng bộ.
  • Ghi chú công bố gói phát hành khớp trạng thái thực tế.

Nếu release chạm lớp BHYT Submission, nên chạy thêm:

  • ./scripts/validate-bhyt-submission.sh
  • ./scripts/validate-bhyt-roundtrip.sh

Nếu release chạm security/governance, nên chạy thêm:

  • ./scripts/validate-security-baseline.sh

4. Quy tắc ngừng dùng

  • Không xóa mã cũ hoặc identifier cũ ngay nếu còn cần cho dữ liệu lịch sử.
  • Ưu tiên deprecated hoặc legacy trước khi loại bỏ hoàn toàn.
  • Không đổi canonical URL chỉ vì đổi wording hoặc đổi cách diễn giải narrative.
  • Nếu chuyển từ extension cục bộ sang extension chuẩn HL7, phải có thời gian chuyển tiếp và ví dụ cập nhật kèm theo.

5. Vai trò của cộng đồng góp ý

Ở giai đoạn hiện tại, cộng đồng có thể tham gia qua:

  • GitHub issue cho lỗi, điểm mơ hồ, câu chữ pháp lý, hành vi tìm kiếm, thuật ngữ.
  • Pull request cho tài liệu, ví dụ, câu chữ và các chỉnh sửa nhỏ.
  • Implementation report cho phản hồi triển khai thật.

Nội dung góp ý có giá trị cao nhất là:

  • Lỗi tái tạo được.
  • Profile và ví dụ không khớp nhau.
  • Điểm mơ hồ gây hiểu sai ở nhà cung cấp.
  • Thiếu hướng dẫn khiến triển khai thực tế bị vướng.
  • Khác biệt giữa tài nguyên và quy định hiện hành.

6. Điều gì chưa cần làm quá nặng ở giai đoạn này

VN Core chưa cần ngay:

  • Quy trình ballot nội bộ nhiều vòng như một affiliate trưởng thành.
  • Hệ thống phê duyệt đa tầng cho mọi bản vá tài liệu.
  • FMM chính thức cho từng tài nguyên.
  • Mở rộng nhịp phát hành gói quá dày khi chưa có mức độ tiếp nhận đủ rộng.

Điều cần lúc này là:

  • Tính trung thực của bản phát hành.
  • Hướng dẫn đủ rõ.
  • Đầu mối tiếp nhận vấn đề minh bạch.
  • Danh sách việc cần sửa bám theo phản hồi thật.

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

English Summary

This page defines the minimum release and governance framework for VN Core during the trial-use phase. The project prioritizes a truthful public release, clear change classification, lightweight but real quality gates, and transparent community feedback over heavyweight formal governance. Breaking changes must be documented clearly, patch releases should remain stabilization-focused, and public releases should only occur when validation, QA, and publication wording are aligned.