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

Quy ước biên tập và thuật ngữ

Quy ước biên tập và thuật ngữ — Editorial Conventions

Trang này là nguồn sự thật ở mức narrative cho cách viết, cách dùng thuật ngữ và cách tổ chức nội dung trên website VN Core FHIR IG.

Mục tiêu là giúp các trang công khai giữ được 3 yêu cầu cùng lúc:

  • Tiếng Việt chuẩn mực, rõ nghĩa và thống nhất;
  • Đủ chiều sâu kỹ thuật cho người triển khai;
  • Không lẫn lộn giữa thuật ngữ nghiệp vụ, thuật ngữ FHIR và thuật ngữ pháp lý.

Trang này dành cho ai?

  • Nhóm duy trì nội dung, biên tập viên và reviewer cộng đồng đang viết hoặc rà narrative.
  • Nhóm kiến trúc, QA và quản trị cần một chuẩn chung để đánh giá chất lượng nội dung.
  • Đơn vị triển khai muốn hiểu vì sao VN Core dùng một số cách gọi nhất định cho vai trò triển khai, gói, profile, Bundle và lớp liên thông.

Khi nào nên đọc trang này?

  • Khi bắt đầu viết một trang narrative mới.
  • Khi rà soát một trang cũ để chuẩn hóa lại văn phong, thuật ngữ hoặc cấu trúc.
  • Khi có tranh luận về cách gọi tên artifact, vai trò triển khai hoặc cách dịch một thuật ngữ kỹ thuật sang tiếng Việt.

Sau khi đọc, bạn nên chốt được gì?

  • Thuật ngữ nào phải giữ nguyên tiếng Anh, thuật ngữ nào nên Việt hóa.
  • Cách gọi chuẩn cho các lớp VN Core Base, BHYT Submission, terminology, quản trị và conformance.
  • Khung tối thiểu mà một trang narrative nên có trước khi công bố.
  • Cách tách rõ yêu cầu pháp lý hiện hành, hướng dẫn triển khai và hỗ trợ dữ liệu lịch sử.

1. Nguyên tắc biên tập chung

  1. Viết cho người triển khai thật, không viết như changelog hay danh mục artifact khô cứng.
  2. Ưu tiên tiếng Việt rõ nghĩa; chỉ giữ tiếng Anh khi đó là tên chuẩn, tên artifact hoặc thuật ngữ khó Việt hóa mà giữ nguyên sẽ chính xác hơn.
  3. Lấy baseline quốc tế trước, rồi mới Việt hóa ở những chỗ thật sự có khác biệt về pháp lý, vận hành hoặc ngữ nghĩa quốc gia.
  4. Không trộn lẫn 3 lớp nội dung: căn cứ pháp lý hiện hành, hướng dẫn triển khai của VN Core, và hỗ trợ dữ liệu lịch sử/chuyển đổi.
  5. Không để một trang vừa nói về resource lõi, vừa kéo theo logic gateway cục bộ nếu logic đó chỉ đúng cho một vai trò triển khai hay một package riêng.

2. Ma trận thuật ngữ chuẩn

Khái niệm Cách gọi chuẩn Tránh dùng khi không cần Ghi chú
Package gói package trong câu tiếng Việt thông thường Giữ nguyên package id khi cần nêu tên kỹ thuật như hl7.fhir.vn.core.base
Vai trò triển khai vai trò triển khai actor trong câu tiếng Việt thông thường Dùng cho các trang tuân thủ, checklist, CapabilityStatement
Profile artifact profile dịch máy móc mọi chỗ thành hồ sơ Trong tiêu đề công khai có thể dùng Hồ sơ, nhưng khi nói chính xác artifact FHIR nên ưu tiên profile
Resource resource hồ sơ nếu đang nói tài nguyên FHIR cụ thể Patient, Encounter, Observation là resource, không gọi chung là hồ sơ nếu câu cần chính xác kỹ thuật
Bundle Bundle gói dữ liệu nếu đang nói đúng artifact FHIR Giữ nguyên tên chuẩn FHIR
CapabilityStatement CapabilityStatement tuyên bố năng lực nếu gây tối nghĩa Có thể thêm mô tả tiếng Việt sau dấu gạch ngang hoặc trong câu giải thích
SearchParameter SearchParameter tham số tìm kiếm khi đang gọi đúng artifact Trong narrative phổ thông có thể nói tham số tìm kiếm; khi nêu artifact nên giữ tên chuẩn
NamingSystem NamingSystem hệ thống đặt tên Giữ nguyên vì đây là tài nguyên FHIR cụ thể
CodeSystem / ValueSet CodeSystem, ValueSet dịch không nhất quán thành nhiều biến thể Trong câu phổ thông có thể dùng bộ mã, tập giá trị để giải thích
OperationDefinition OperationDefinition định nghĩa thao tác nếu đang gọi đúng artifact Khi nói hành vi có thể dùng operation
Must Support Must Support dịch hoàn toàn thành phải hỗ trợ nếu đang nói đúng nhãn FHIR Có thể diễn giải nghĩa bằng tiếng Việt ở câu tiếp theo
VN Core Base lõi FHIR-native, VN Core Base core đứng một mình nếu dễ mơ hồ Dùng khi nói ranh giới package hoặc lớp ngữ nghĩa lõi
BHYT Submission lớp liên thông hồ sơ BHYT hoặc lớp liên thông hồ sơ thanh toán BHYT giao nộp BHYT, submission/gateway trong câu tiếng Việt Giữ BHYT Submission khi nhắc đúng tên package/layer
gateway layer gateway layer lớp cổng, tầng cổng Chỉ dùng khi đang nói lớp kiến trúc kỹ thuật; không dùng để thay tên chính thức của Cổng giám định BHXH
Checklist checklist danh sách kiểm tra nếu làm câu dài và nặng Dùng cho các trang tự rà soát, tiêu chí sẵn sàng và biểu mẫu ngắn
Sẵn sàng thí điểm sẵn sàng thí điểm pilot-ready trong câu tiếng Việt Chỉ giữ pilot-ready trong English Summary hoặc khi trích đúng nhãn tiếng Anh
Bộ dữ liệu kiểm thử bộ dữ liệu kiểm thử fixture, fixtures trong câu tiếng Việt Có thể giữ fixture trong tên script, tên file hoặc English Summary
validator validator khi nói tool hoặc thành phần kỹ thuật trình kiểm tra Khi nói hoạt động, ưu tiên kiểm tra hợp lệ, xác thực hoặc validate theo ngữ cảnh
Vai trò phía gửi BHYT client gửi hồ sơ thanh toán BHYT client giao nộp, bên nộp Dùng trong narrative, checklist và CapabilityStatement
Vai trò phía nhận BHYT server tiếp nhận hồ sơ thanh toán BHYT server giao nộp, server submission Dùng cho facade, adapter, gateway tiếp nhận
Artifact BHYT chính Bundle hồ sơ thanh toán BHYT bundle giao nộp, bundle submission trong câu tiếng Việt Giữ đúng tên VNCoreBHYTSubmissionBundle khi nhắc artifact
Trạng thái vòng đời hiện hành, lịch sử, ngừng dùng lẫn lộn legacy, deprecated, cũ trong cùng một cột mô tả deprecated chỉ nên giữ khi nói đúng metadata FHIR hoặc property code

3. Khi nào giữ tiếng Anh?

Giữ nguyên tiếng Anh trong 5 nhóm tình huống:

  1. Tên chuẩn FHIR hoặc HL7 như Patient, Coverage, Bundle, CodeSystem, ValueSet, NamingSystem, CapabilityStatement.
  2. Tên package, canonical, system URI, mã code, operation id, search parameter id.
  3. Thuật ngữ chuẩn quốc tế đã được dùng ổn định và khó Việt hóa mà không mất nghĩa, như FHIR-native, IPS, SMART on FHIR, OAuth.
  4. Thuật ngữ kiến trúc hoặc tooling đã được đội triển khai dùng ổn định, như gateway layer, mapping layer, search layer, validator, adapter, middleware, round-trip mapper, indexing pipeline.
  5. English Summary ở cuối trang.

Không nên giữ tiếng Anh khi đã có cách gọi tiếng Việt ngắn, rõ và đủ chính xác, như:

  • governance trong câu mô tả phổ thông nếu có thể viết quản trị;
  • deployment scope nếu có thể viết phạm vi triển khai;
  • technical debt nếu có thể viết nợ kỹ thuật;
  • pilot-ready nếu có thể viết sẵn sàng thí điểm;
  • fixture nếu có thể viết bộ dữ liệu kiểm thử;
  • actor nếu câu chỉ đang nói vai trò triển khai, không cần nhấn mạnh thuật ngữ HL7.

Không nên dịch máy móc các cụm ở nhóm 4 thành lớp cổng, trình kiểm tra, tầng tìm kiếm hoặc các biến thể tương tự nếu bản dịch làm câu gượng hoặc lệch nghĩa kiến trúc.

4. Quy tắc viết hoa, viết thường và cách gọi tên

4.1. Viết hoa

  • Tên tài nguyên FHIR và tên artifact giữ đúng cách viết chuẩn: Patient, Observation, CapabilityStatement.
  • Tên văn bản pháp lý viết theo tên chính thức khi dẫn chiếu lần đầu.
  • Tiêu đề trang tiếng Việt dùng kiểu viết hoa tự nhiên của tiếng Việt, không viết hoa theo lối tiếng Anh.

4.2. Viết tắt

  • Lần đầu xuất hiện, nên viết đầy đủ rồi mới viết tắt nếu trang chưa đủ ngữ cảnh.
  • Với các viết tắt quá quen trong ngành và xuất hiện dày đặc như BHYT, BHXH, CCCD, EMR, HIS, FHIR, có thể dùng trực tiếp nếu câu vẫn rõ nghĩa.

4.3. Ngày tháng và mốc thời gian

  • Ưu tiên mốc thời gian tuyệt đối thay vì hiện nay, mới đây, sắp tới nếu nội dung dễ thay đổi theo thời gian.
  • Khi một quyết định phụ thuộc hiệu lực pháp lý, nên ghi rõ ngày hoặc số hiệu văn bản.

5. Quy tắc tách 3 lớp nội dung

Lớp nội dung Mục đích Dấu hiệu trong câu
Căn cứ pháp lý hiện hành Xác định ràng buộc đang có hiệu lực theo, căn cứ, hiệu lực, phải, được quy định tại
Hướng dẫn triển khai của VN Core Đưa ra quyết định thiết kế hoặc cách làm khuyến nghị VN Core chọn, khuyến nghị, nên, ưu tiên, không nên
Hỗ trợ dữ liệu lịch sử / chuyển đổi Giữ tương thích dữ liệu cũ nhưng không coi là hướng thiết kế mới dữ liệu lịch sử, cầu nối, chuyển đổi, legacy, ngừng dùng

Không nên viết một câu gộp cả 3 lớp theo kiểu:

  • Văn bản cũ vẫn còn đó nên profile hiện hành phải giữ nguyên mô hình cũ;
  • Hệ thống nguồn đang quen dùng XML nên resource lõi phải bẻ theo XML;
  • Package lõi phải gánh luôn logic chỉ đúng cho gateway hay facade.

6. Khung chuẩn cho một trang narrative

Một trang narrative chuẩn của VN Core nên có tối thiểu các phần sau:

Phần Mục đích
Mở đầu 1-2 câu Nói rõ trang này bao quát điều gì
Trang này dành cho ai? Xác định đúng nhóm người đọc
Khi nào nên đọc trang này? Chỉ ra thời điểm hoặc tình huống đọc
Sau khi đọc, bạn nên chốt được gì? Biến trang từ mô tả sang công cụ ra quyết định
Nội dung chính Trình bày theo nguyên tắc, ma trận, tình huống, hệ quả triển khai
Liên hệ với các trang khác hoặc mục tương đương Chỉ đường sang các trang chuyên sâu liên quan
English Summary Giữ lớp tóm tắt tiếng Anh ngắn và đúng vocabulary chuẩn

Tùy loại trang, có thể thêm:

  • Ma trận pháp lý cho trang pháp lý;
  • CapabilityStatement hoặc Checklist cho trang conformance;
  • Quy tắc bắt buộc tối thiểu cho trang triển khai.

7. Checklist rà soát trước khi phát hành nội dung

  • Trang đã nói rõ người đọc là ai và họ cần quyết định gì.
  • Thuật ngữ dùng đúng theo ma trận trên, nhất là với profile, resource, Bundle, BHYT Submission, current/legacy/deprecated.
  • Không còn cụm Vietlish không cần thiết khi tiếng Việt đã đủ rõ.
  • Các câu về pháp lý, guidance và dữ liệu lịch sử không bị trộn nghĩa.
  • Các vai trò triển khai và package được gọi nhất quán với conformance-by-actor, package-architecture, stability-and-conformance.
  • English Summary không mâu thuẫn với narrative tiếng Việt và không dùng vocabulary khác hẳn.
  • Liên kết sang các trang liên quan đã có và không làm người đọc bị rơi vào ngõ cụt.

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

English Summary

This page defines the editorial and terminology conventions for VN Core narrative content. It standardizes when Vietnamese terms should be preferred, when English FHIR artifact names should be retained, how actor/package/layer names should be written consistently, and how legal requirements, implementation guidance, and historical compatibility notes should be separated. It also defines the minimum structure expected for a mature VN Core narrative page.