1. 什麼是實施指南？
實施指南（IG） 是規則、設定檔、擴充、值集、特定用例範例的集合。越南 IG 將定義如何根據越南標準表示醫療數據。
| IG成分 | 描述 | 例如越南 |
|---|---|---|
| 型材 | 基礎資源綁定 | VN-核心-患者（需要 CCCD） |
| 擴充 | 新增數據元素 | 健康保險號碼，越南裔 |
| 值集 | 啟用的代碼集 | 越南民族列表，ICD-10 越南 |
| 代碼系統 | 代碼系統 | 省/市代碼、醫療機構代碼 |
| 範例 | 範例範例 | 具有 CCCD 和健康保險的樣本患者 |
| 能力聲明 | 伺服器要求 | 需要什麼最低支援？ |
2. FSH——FHIR 簡寫
卵泡刺激素 是一種特定於領域的語言，有助於編寫比 JSON/XML 簡潔許多倍的 FHIR 設定檔。
# Cài đặt SUSHI (FSH compiler)
npm install -g fsh-sushi
# Tạo IG project mới
sushi init
專案結構
vn-core-ig/
├── sushi-config.yaml
├── input/
│ ├── fsh/
│ │ ├── profiles/
│ │ │ ├── VNCorePatient.fsh
│ │ │ ├── VNCoreOrganization.fsh
│ │ │ └── VNCoreEncounter.fsh
│ │ ├── extensions/
│ │ │ ├── BHYTExtension.fsh
│ │ │ └── EthnicityExtension.fsh
│ │ ├── valuesets/
│ │ │ ├── VNEthnicityVS.fsh
│ │ │ └── VNProvinceVS.fsh
│ │ ├── codesystems/
│ │ │ ├── VNEthnicityCS.fsh
│ │ │ └── VNProvinceCS.fsh
│ │ └── examples/
│ │ └── PatientExample.fsh
│ └── pagecontent/
│ └── index.md
└── ig.ini
sushi-config.yaml
id: vn.core
canonical: http://fhir.vn/ImplementationGuide/vn-core
name: VNCoreIG
title: Vietnam Core Implementation Guide
status: draft
version: 0.1.0
fhirVersion: 5.0.0
copyrightYear: 2025+
releaseLabel: ci-build
publisher:
name: Vietnam FHIR Community
url: https://fhir.vn
jurisdiction: urn:iso:std:iso:3166#VN "Vietnam"
dependencies:
hl7.fhir.r5.core: 5.0.0
3. VN-核心-病患資料
// input/fsh/profiles/VNCorePatient.fsh
Profile: VNCorePatient
Parent: Patient
Id: vn-core-patient
Title: "VN Core Patient"
Description: "Profile Patient cho hệ thống y tế Việt Nam"
// Bắt buộc có ít nhất 1 identifier (CCCD hoặc BHYT)
* identifier 1..* MS
* identifier ^slicing.discriminator.type = #pattern
* identifier ^slicing.discriminator.path = "system"
* identifier ^slicing.rules = #open
// Slice: CCCD
* identifier contains cccd 0..1 MS
* identifier[cccd].system = "http://fhir.vn/sid/cccd" (exactly)
* identifier[cccd].value 1..1
* identifier[cccd].value ^short = "Số Căn cước Công dân (12 số)"
// Slice: BHYT
* identifier contains bhyt 0..1 MS
* identifier[bhyt].system = "http://fhir.vn/sid/bhyt" (exactly)
* identifier[bhyt].value 1..1
* identifier[bhyt].value ^short = "Số thẻ Bảo hiểm Y tế"
// Họ tên bắt buộc
* name 1..* MS
* name.family 1..1 MS
* name.given 1..* MS
* name.text 1..1 MS
// Giới tính, ngày sinh bắt buộc
* gender 1..1 MS
* birthDate 1..1 MS
// Địa chỉ
* address MS
* address.city MS
* address.district MS
* address.state MS
* address.line MS
// Extensions
* extension contains
VNEthnicityExtension named ethnicity 0..1 MS and
VNBHYTExtension named bhytInfo 0..1 MS
4. 越南延期
延伸：健康保險訊息
// input/fsh/extensions/BHYTExtension.fsh
Extension: VNBHYTExtension
Id: vn-bhyt-extension
Title: "VN BHYT Extension"
Description: "Thông tin bảo hiểm y tế Việt Nam"
Context: Patient
* extension contains
soThe 1..1 MS and
noiDangKy 1..1 MS and
ngayHieuLuc 1..1 MS and
ngayHetHan 0..1 MS and
mucHuong 1..1 MS
* extension[soThe].value[x] only string
* extension[soThe] ^short = "Số thẻ BHYT (15 ký tự)"
* extension[noiDangKy].value[x] only Reference(Organization)
* extension[noiDangKy] ^short = "Nơi đăng ký KCB ban đầu"
* extension[ngayHieuLuc].value[x] only date
* extension[ngayHieuLuc] ^short = "Ngày bắt đầu hiệu lực"
* extension[ngayHetHan].value[x] only date
* extension[ngayHetHan] ^short = "Ngày hết hạn"
* extension[mucHuong].value[x] only integer
* extension[mucHuong] ^short = "Mức hưởng BHYT (%)"
延伸：種族
// input/fsh/extensions/EthnicityExtension.fsh
Extension: VNEthnicityExtension
Id: vn-ethnicity-extension
Title: "VN Ethnicity Extension"
Description: "Dân tộc theo danh mục 54 dân tộc Việt Nam"
Context: Patient
* value[x] only CodeableConcept
* valueCodeableConcept from VNEthnicityVS (required)
5. 代碼系統和值集
// input/fsh/codesystems/VNEthnicityCS.fsh
CodeSystem: VNEthnicityCS
Id: vn-ethnicity-cs
Title: "VN Ethnicity CodeSystem"
Description: "Danh mục 54 dân tộc Việt Nam (theo TCTK)"
* ^caseSensitive = true
* #01 "Kinh"
* #02 "Tày"
* #03 "Thái"
* #04 "Mường"
* #05 "Khmer"
* #06 "Hoa"
* #07 "Nùng"
* #08 "Hmông"
* #09 "Dao"
* #10 "Gia Rai"
// ... thêm 44 dân tộc còn lại
// input/fsh/valuesets/VNEthnicityVS.fsh
ValueSet: VNEthnicityVS
Id: vn-ethnicity-vs
Title: "VN Ethnicity ValueSet"
Description: "ValueSet cho 54 dân tộc Việt Nam"
* include codes from system VNEthnicityCS
// input/fsh/codesystems/VNProvinceCS.fsh
CodeSystem: VNProvinceCS
Id: vn-province-cs
Title: "VN Province CodeSystem"
Description: "63 tỉnh/thành phố Việt Nam"
* ^caseSensitive = true
* #01 "Hà Nội"
* #79 "TP. Hồ Chí Minh"
* #48 "Đà Nẵng"
* #31 "Hải Phòng"
* #92 "Cần Thơ"
// ... thêm các tỉnh/thành còn lại
6. 例子
// input/fsh/examples/PatientExample.fsh
Instance: VNPatientExample01
InstanceOf: VNCorePatient
Title: "Ví dụ: Bệnh nhân Nguyễn Văn A"
Description: "Ví dụ Patient tuân thủ VN-Core-Patient profile"
Usage: #example
* identifier[cccd].system = "http://fhir.vn/sid/cccd"
* identifier[cccd].value = "001234567890"
* identifier[bhyt].system = "http://fhir.vn/sid/bhyt"
* identifier[bhyt].value = "DN4012345678901"
* name[0].family = "Nguyễn"
* name[0].given[0] = "Văn"
* name[0].given[1] = "A"
* name[0].text = "Nguyễn Văn A"
* gender = #male
* birthDate = "1990-05-15"
* address[0].line[0] = "123 Nguyễn Huệ, Phường Bến Nghé"
* address[0].district = "Quận 1"
* address[0].city = "TP. Hồ Chí Minh"
* address[0].state = "79"
* address[0].country = "VN"
* extension[ethnicity].valueCodeableConcept = VNEthnicityCS#01 "Kinh"
* extension[bhytInfo].extension[soThe].valueString = "DN4012345678901"
* extension[bhytInfo].extension[noiDangKy].valueReference = Reference(Organization/org-bvdk-001)
* extension[bhytInfo].extension[ngayHieuLuc].valueDate = "2025-01-01"
* extension[bhytInfo].extension[ngayHetHan].valueDate = "2025-12-31"
* extension[bhytInfo].extension[mucHuong].valueInteger = 80
7. 建置並發布 IG
# Compile FSH → FHIR JSON
sushi .
# Output:
# fsh-generated/
# resources/
# StructureDefinition-vn-core-patient.json
# StructureDefinition-vn-bhyt-extension.json
# CodeSystem-vn-ethnicity-cs.json
# ValueSet-vn-ethnicity-vs.json
# Patient-VNPatientExample01.json
# Chạy IG Publisher (cần Java 17+)
./_genonce.sh
# Hoặc dùng Docker
docker run --rm -v $(pwd):/ig \
hl7fhir/ig-publisher-base:latest \
java -jar /app/publisher.jar \
-ig /ig/ig.ini
與 IG 驗證資源
# Validate một resource
java -jar validator_cli.jar \
patient-example.json \
-ig vn-core-ig/output \
-profile http://fhir.vn/StructureDefinition/vn-core-patient
# Kết quả:
# Information: All OK (0 errors, 0 warnings)
8. 高階 IG——不變量和約束
// Thêm invariant cho CCCD (12 số)
Invariant: vn-cccd-format
Description: "Số CCCD phải có đúng 12 chữ số"
Expression: "value.matches('^[0-9]{12}$')"
Severity: #error
* identifier[cccd].value obeys vn-cccd-format
// Thêm invariant cho BHYT (15 ký tự)
Invariant: vn-bhyt-format
Description: "Số thẻ BHYT phải có đúng 15 ký tự"
Expression: "value.matches('^[A-Z]{2}[0-9]{13}$')"
Severity: #error
* identifier[bhyt].value obeys vn-bhyt-format
9. 總結
實施指南 — 針對特定用例的一組規則、設定檔、擴充
FSH（FHIR 簡寫） — 簡介書寫語言簡潔易讀
VN-核心-患者 — 資料 患者需要身分證、健康保險、全名、性別、出生日期
擴充 — 健康保險資訊（卡號、註冊地點、福利等級）、越南裔
代碼系統/值集 — 54個民族、63個省/市、醫療機構代碼
SUSHI + IG 出版商 — 從 FSH → JSON → HTML IG 建立管道