Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Local Development build (v0.9.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Hướng dẫn chung

Hướng dẫn chung — General Guidance

Các quy tắc nền dưới đây áp dụng chung cho VN Core: cách biểu diễn tên, địa chỉ, định danh, pattern datatype và ranh giới giữa guidance chung với các trang chuyên đề.

Baseline quốc tế trước, Việt hóa sau

VN Core hiện tại đi theo nguyên tắc: dùng baseline quốc tế trước, rồi chỉ Việt hóa ở nơi thật sự cần.

• Với resource và datatype, ưu tiên FHIR R4, IPS và extension chuẩn của HL7 nếu đã diễn đạt đúng ngữ nghĩa.
• Chỉ localize khi Việt Nam có khác biệt thật về pháp lý, luồng công việc, định danh, địa chỉ hành chính hoặc bộ mã vận hành.
• Nếu một khác biệt chỉ là cách hiển thị, cách search hoặc cách ánh xạ gateway, nên giải quyết ở tài liệu hướng dẫn hoặc lớp triển khai trước khi tạo thêm profile/extension.

Pattern dùng lại xuyên suốt nhiều hồ sơ

Không để mỗi profile tự định nghĩa lại một pattern cho cùng một datatype. Các pattern dùng lại được giữ ở trang diễn giải và quản trị thay vì lặp lại trong từng profile:

Must Support (MS)

Chi tiết cách diễn giải và cẩm nang HIS -> FHIR đã được tách sang trang riêng: Hướng dẫn Must Support.

Định nghĩa

Trong VN Core IG, khi một element được đánh dấu Must Support (MS), nghĩa là:

• Hệ thống gửi (Sender): Nếu có dữ liệu cho element đó, PHẢI gửi kèm trong resource
• Hệ thống nhận (Receiver): PHẢI có khả năng xử lý và lưu trữ dữ liệu của element đó mà không gây lỗi

Must Support KHÔNG có nghĩa là element đó bắt buộc phải có giá trị (required). Một element có thể vừa MS vừa 0..1 — nghĩa là không bắt buộc có, nhưng nếu có thì phải hỗ trợ.

Ví dụ — Must Support

Xử lý khi thiếu dữ liệu

Khi element MS không có giá trị, hệ thống cần phân biệt cardinality:

• Với element có cardinality tối thiểu lớn hơn 0, vẫn phải khai phần tử và dùng Data Absent Reason extension (http://hl7.org/fhir/StructureDefinition/data-absent-reason) khi profile cho phép.
• Với element tùy chọn (0..x), có thể bỏ phần tử; không tạo element rỗng chỉ để biểu thị thiếu dữ liệu.

Tên tiếng Việt trong FHIR

Cấu trúc HumanName

Tên tiếng Việt có cấu trúc: Họ + Tên đệm + Tên gọi. Ánh xạ sang FHIR:

Quy tắc

1. text nên được điền khi nguồn có họ tên đầy đủ chính thức; VN Core đánh dấu name.text là 0..1 MS, không phải phần tử bắt buộc.
2. Ánh xạ family và given theo cấu trúc tên do nguồn có thẩm quyền cung cấp; không suy ra máy móc chỉ từ vị trí từ đầu tiên.
3. Giữ nguyên thứ tự các thành phần trong given; dùng text để bảo toàn cách viết chính thức.
4. Dấu tiếng Việt: PHẢI giữ nguyên dấu Unicode (UTF-8). Không bỏ dấu, không chuyển ASCII
5. use = official cho tên chính thức trên CCCD/giấy tờ

Ví dụ — Tên

{
  "name": [{
    "use": "official",
    "text": "Nguyễn Văn An",
    "family": "Nguyễn",
    "given": ["Văn", "An"]
  }]
}

Trường hợp đặc biệt

• Tên 2 chữ (không có đệm): given chỉ có 1 phần tử. Ví dụ: Bảo Đại → family: "Bảo", given: ["Đại"]
• Họ kép: family chứa toàn bộ họ kép. Ví dụ: "Tôn Thất" → family: "Tôn Thất"
• Người nước ngoài: Dùng tên theo hộ chiếu, use: "official"

Địa chỉ Việt Nam

Cấu trúc VNCoreAddress

Địa chỉ Việt Nam sau NQ 202/2025/QH15 có 2 cấp chính (tỉnh + xã), nhưng VN Core vẫn hỗ trợ tương thích ngược:

Tương thích ngược

• Hệ thống CŨ (trước 01/7/2025) có thể vẫn gửi mã huyện theo danh mục 63 tỉnh
• Hệ thống NHẬN nên chấp nhận cả mã cũ và mới
• VNDistrictLegacyCS giữ 696 mã huyện cũ với property concept status = deprecated để hỗ trợ dữ liệu lịch sử; CodeSystem này ở trạng thái retired theo tiền lệ Province/KSK legacy và chỉ dùng để resolve, validate hoặc di trú dữ liệu cũ. Canonical cũ VNDistrictCS cũng ở trạng thái retired nhưng giữ đủ mã để resolve dữ liệu đã công bố.

Hệ thống định danh (Identifier)

Để tra cứu tập trung các NamingSystem, xem thêm Danh mục định danh. Để bắc cầu với OID hoặc hệ thống cũ, xem Ánh xạ URI/OID.

Thứ tự ưu tiên

CCCD: CCCD là định danh cá nhân lõi cho công dân Việt Nam trong VN Core.
VNeID: VNeID là tài khoản định danh điện tử và kênh truy cập của ứng dụng người dân; chỉ nên dùng ở lớp ứng dụng người dân, xác thực hoặc tích hợp, không dùng song song với CCCD như một định danh người bệnh chính.

Khi chưa có CCCD

VN Core vẫn giữ identifier[CCCD] là lát cắt định danh chính. Tuy nhiên, khi chưa có giá trị CCCD thực tế, cần tách ba tình huống:

Không nên dùng forceMajeureReason để mô tả người bệnh có định danh thay thế hợp lệ như hộ chiếu hoặc giấy khai sinh.

Cấu trúc CCCD

Số CCCD 12 chữ số mã hóa thông tin:

• Vị trí 1-3: Mã prefix nơi đăng ký khai sinh theo danh mục BCA
• Vị trí 4: Giới tính + thế kỷ sinh (0=Nam/19xx, 1=Nữ/19xx, 2=Nam/20xx, 3=Nữ/20xx)
• Vị trí 5-6: 2 chữ số cuối năm sinh
• Vị trí 7-12: Số ngẫu nhiên

Mã prefix BCA này là terminology hỗ trợ validation cho CCCD đã cấp và không thay thế cho VNProvinceCS dùng trong địa chỉ hành chính hiện hành.

Chi tiết kiểm tra hợp lệ: xem Hướng dẫn kiểm tra hợp lệ

Tìm kiếm và so khớp định danh

• Với CCCD, BHYT, BHXH, GPHN, CCHN, MA_LK, MA_LUOT_KCB và mã phản hồi gateway BHYT, nên coi tìm kiếm là truy vấn nghiệp vụ chính xác theo kiểu token khi hệ thống công bố search tương ứng.
• Không nên biến tìm kiếm theo định danh thành tìm kiếm mờ theo văn bản tự do.
• Các hành vi normalize như bỏ khoảng trắng hoặc chuẩn hóa dấu gạch nối chỉ nên là hành vi nội bộ và cần công bố rõ nếu có.

Chi tiết xem Hành vi tìm kiếm.

Organization và Location

Không trộn 4 khái niệm khác nhau

Khi triển khai Organization và Location, VN Core tách riêng:

vn-ext-org-level chỉ biểu diễn cấp quản lý hành chính y tế hiện hành, không thay cho tuyến kỹ thuật cũ.

Khuyến nghị điền dữ liệu

• Bệnh viện/phòng khám: ưu tiên organizationType, organizationLevel, facilityCareLevel; chỉ điền organizationRank khi có căn cứ pháp lý rõ.
• Trạm y tế: thường không có hạng pháp lý, nên dùng organizationRankStatus = not-applicable nếu cần diễn đạt rõ.
• CDC/đơn vị dự phòng/kiểm nghiệm: dùng healthUnitRank, không dùng organizationRank.
• Location không mang hạng pháp lý; chỉ nên mang facilityCareLevel khi địa điểm được quản trị như một phân hệ chuyên môn riêng.

Chi tiết: xem Quản trị Organization và Location.

Mức độ ràng buộc (Binding Strength)

VN Core IG sử dụng các mức binding theo FHIR:

Quy ước URL

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

English Summary

This page defines the general reusable rules for VN Core. It covers Vietnamese names, address modeling, identifier precedence, Organization/Location separation, and binding basics that apply across multiple profiles. Historical district data uses VNDistrictLegacyCS; the former VNDistrictCS canonical is retired but remains fully resolvable. Detailed Must Support interpretation is documented on its own page.