Định danh người bệnh
Bắt đầu với VNCorePatient, NamingSystem CCCD/BHYT/BHXH, SearchParameter patient-cccd và các extension dân tộc/địa chỉ. Mã số BHYT có 2 định dạng: 10 chữ số hiện hành hoặc 15 ký tự legacy.
VN Core Deep Dive
Bản đồ artifact VN Core v0.9.0: đọc gì trước khi vào IG
Trong phạm vi package trial-use VN Core, IG là nguồn kỹ thuật có thẩm quyền để validate dữ liệu; đây chưa phải tiêu chuẩn quốc gia được cơ quan có thẩm quyền công nhận. Trang này là bản đồ đọc: giúp CIO, lập trình viên và đội nghiệp vụ hiểu mỗi loại artifact dùng để làm gì, đọc theo thứ tự nào, và khi nào cần đi sâu vào trang IG tương ứng.
Tóm tắt nhanh
- Không đọc IG theo alphabet. Hãy đọc theo workflow: định danh, EMR, BHYT, terminology, server capability, rồi mới đến từng profile chi tiết.
- Profile nói dữ liệu phải có hình dạng gì; CodeSystem/ValueSet nói mã nào được dùng; CapabilityStatement nói server phải hỗ trợ gì.
- Example và Bundle là cầu nối quan trọng giữa constraint và dữ liệu thật; đọc example trước khi viết bộ chuyển đổi giúp tránh hiểu sai slicing hoặc binding.
- Knowledge Hub giải thích cách đọc; IG là nguồn normative trong phạm vi package trial-use cho StructureDefinition, snapshot/differential và validation, không phải tuyên bố công nhận chuẩn quốc gia.
1. VN Core không chỉ là tập profile
Khi mới mở IG, người đọc thường nhìn thấy danh sách dài artifact và tưởng rằng VN Core là một thư viện profile. Cách đọc đó dễ bỏ sót ý đồ thiết kế. Một profile như VNCorePatient chỉ có nghĩa đầy đủ khi đi cùng NamingSystem cho CCCD/BHYT/BHXH, CodeSystem dân tộc, ValueSet địa chỉ, SearchParameter tìm theo định danh, example Patient Việt Nam, và CapabilityStatement mô tả server phải hỗ trợ search nào.
Vì vậy cần đọc VN Core như một hệ thống gồm ba lớp. Lớp conformance trả lời "dữ liệu hợp lệ là gì". Lớp terminology trả lời "mã này có nghĩa gì và lấy từ đâu". Lớp implementation trả lời "server/client phải hỗ trợ API nào, validate ra sao, gói dữ liệu đi như thế nào". IG là nơi chứa tất cả; Knowledge Hub là lớp giúp định hướng trước khi đọc sâu.
2. Bảng artifact và vai trò
| Artifact | Số lượng | Đọc để hiểu gì | FHIR type |
|---|---|---|---|
| Profiles | 86 | Ràng buộc Resource FHIR cho Việt Nam: Patient, Coverage, Claim, EMR, KSK, IPS, thiết bị, dữ liệu lâm sàng. | StructureDefinition |
| Extensions | 56 | Các trường FHIR base chưa có: dân tộc, mã xã/phường, BHYT, dữ liệu đặc thù Việt Nam. | StructureDefinition |
| CodeSystems | 165 | Bộ mã gốc: dân tộc, pháp lý, BHYT, hành chính, ICD-10 VN, thuật ngữ dùng chung. | CodeSystem |
| ValueSets | 168 | Tập mã bind vào element cụ thể, quyết định mã nào được phép dùng trong từng ngữ cảnh. | ValueSet |
| ConceptMaps | 17 | Ánh xạ có hướng giữa các mã hoặc khái niệm thuộc những hệ mã hoặc tập giá trị xác định. | ConceptMap |
| NamingSystems | 36 | Đăng ký URI cho định danh: CCCD, BHYT, BHXH, mã cơ sở KCB, MRN. | NamingSystem |
| SearchParameters | 19 | API contract để tìm kiếm theo CCCD, BHYT, MA_LK, MA_CSKCB và các identifier Việt Nam. | SearchParameter |
| CapabilityStatements | 5 | Tuyên bố năng lực tối thiểu cho server, EMR, gateway BHYT, citizen app. | CapabilityStatement |
| OperationDefinitions | 4 | Các operation có hợp đồng rõ: validate/submit/reverse BHYT, generate IPS summary. | OperationDefinition |
| LogicalModels | 27 | Mô hình trung gian cho XML BHYT, KSK, dataset pháp lý hoặc biểu mẫu trước khi map sang FHIR. | StructureDefinition |
3. Đọc theo workflow Việt Nam
BHYT và dữ liệu đầu ra KCB
Đọc Coverage, Claim, ClaimResponse, EOB, Invoice, 16 logical models (Check-in + XML1–XML15) và 3 operations validate/submit/reverse. Các annotation ^mapping ở logical models hướng dẫn adapter; package chưa phát hành artifact ConceptMap bao phủ và kiểm chứng đầu-cuối toàn bộ XML1–XML15 ↔ Claim/EOB.
Bệnh án điện tử và hồ sơ sức khỏe
Đọc Composition, DocumentReference, DiagnosticReport, Observation, Provenance và Bundle document cho EMR/IPS/VNeID.
Terminology và pháp lý
Đọc CodeSystem/ValueSet trước khi đọc constraint: nhiều lỗi FHIR không nằm ở JSON shape mà nằm ở mã dùng sai hệ thống.
4. Thứ tự đọc khuyến nghị
- Đọc page narrative trước. Trang chủ IG, Profiles, Terminology và Package Architecture cho biết ranh giới release và module.
- Đọc example trước profile. Ví dụ thật cho thấy profile được dùng trong workflow nào, các reference nối với nhau ra sao.
- Đọc differential để biết VN Core thêm gì. Snapshot rất dài vì gồm toàn bộ base FHIR; differential mới cho thấy phần Việt Nam thực sự ràng buộc.
- Kiểm tra terminology sau khi đọc profile. Lỗi production thường đến từ dùng đúng element nhưng sai system/code/version.
- Cuối cùng chạy validator. Không coi một payload hợp lệ chỉ vì app đọc được JSON; phải validate với package VN Core cùng version release.
5. Đi sâu trong IG
Chuỗi đọc VN Core Deep Dive
Đi từ overview sang IG theo đúng thứ tự.
Bốn bài này là lớp định hướng trước khi mở IG kỹ thuật trial-use: nắm bản đồ artifact, đọc Profile, kiểm soát terminology, rồi validate Bundle/workflow.
Bản đồ artifact
Đang đọcProfile, terminology, capability, operation, example và package boundary.
Cách đọc Profile
Differential, snapshot, Must Support, slicing, binding và extension.
Terminology
CodeSystem, ValueSet, ConceptMap, NamingSystem và Coding.display.
Bundle và Validation
Bundle, example, CapabilityStatement, OperationDefinition và go-live checks.