Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide
0.10.0 - Draft for Community Review
Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.10.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Claim/ExplanationOfBenefitClaim, nhiều insuranceClaimResponse, không phải ExplanationOfBenefit
Trang này dành cho hệ thống đang chạy trên v0.7.0 và cần chuyển sang v0.10.0. Nó liệt kê những gì phải sửa trong dữ liệu và mã nguồn, kèm lý do — không phải toàn bộ thay đổi của hai chu kỳ.
Mỗi mục nêu: cái gì đổi, vì sao, và chuyển đổi thế nào.
Claim/ExplanationOfBenefitĐổi gì. Hai profile VNCoreItemizedHealthcareCostClaim và VNCoreItemizedHealthcareCostExplanationOfBenefit đã bị gỡ. Bảng kê chi phí khám bệnh, chữa bệnh theo QĐ 697/QĐ-BYT nay dựng trên Invoice: VNCoreCostStatementInvoice.
Vì sao. Bảng kê là chứng từ cơ sở khám bệnh, chữa bệnh phát hành cho người bệnh, không phải hồ sơ đề nghị cơ quan bảo hiểm thanh toán. Đặt nó trên Claim kéo theo một hệ quả không vá được: FHIR R4 quy định Claim.insurance là 1..*, nên ca người không có thẻ bảo hiểm y tế — Phần Hai của chính mẫu — buộc phải khai một Coverage không tồn tại. Chi tiết ở ADR-0021 — Ranh giới vòng đời tài chính BHYT (hồ sơ quyết định trong wiki quản trị của dự án, wiki/decisions/adr-0021-financial-lifecycle-boundaries.md).
Chuyển đổi.
| v0.7.0 | v0.10.0 |
|---|---|
Claim.item (bảng kê) |
Invoice.lineItem |
| (chưa có) | Invoice.account 1..1 → VNCoreAccount — mắt xích MỚI, bắt buộc |
| (chưa có) | ChargeItem.account 1..1 → VNCoreAccount — mắt xích MỚI, bắt buộc |
Claim.item.net |
Invoice.lineItem.priceComponent[type=base].amount |
extension[coverageBenefitStage] trên Claim |
extension[segment] trên Invoice |
extension[itemBenefitStageSequence] trên Claim.item |
extension[line].extension[segmentSequence] |
Claim.total |
Invoice.totalNet |
Claim.identifier[MALK] |
Invoice.identifier[MALK] — cùng hệ định danh |
Hai extension cũ chuyển sang trạng thái nghỉ (#retired) và mang hướng dẫn thay thế trong ^definition; chúng còn resolve được nhưng không nên dùng cho dữ liệu mới.
Đổi gì. Lát insuranceCostInfo đã bị gỡ khỏi VNCoreMedicationRequest, VNCoreMedicationDispense, VNCoreMedicationAdministration và VNCoreProcedure. ^context của extension thu từ 9 vị trí xuống 5: Claim.item, Claim.item.detail, ExplanationOfBenefit.item, ExplanationOfBenefit.item.detail, Invoice.lineItem.
Vì sao. Cùng một con số tồn tại ở hai nơi mà không ràng buộc nào bắt chúng khớp; khi lệch, không có quy tắc nào nói bên nào đúng. Chính ánh xạ của bộ hướng dẫn cũng đã bỏ vị trí lâm sàng: PHAM_VI, TYLE_TT, MUC_HUONG chỉ map vào Claim.item.extension[insuranceCostInfo].
Chuyển đổi. Chuyển thẳng sang dòng chi phí tương ứng trên Claim.item hoặc Invoice.lineItem. Gỡ một nhịp, không qua giai đoạn deprecated — giữ trạng thái hai nguồn sự thật thêm một chu kỳ chỉ kéo dài rủi ro.
Claim, nhiều insuranceĐổi gì. Khi người bệnh được cấp thẻ mới giữa đợt điều trị, hoặc có đồng thời nhiều thẻ/quyền lợi trong cùng đợt, ghi một Claim với nhiều insurance và đúng một focal = true. Claim.related giữ cardinality tuỳ chọn theo FHIR nhưng không còn Must Support hay nghĩa vụ gửi, nhận, lưu hoặc bảo toàn ở mức tối thiểu quốc gia. Không dùng hướng dẫn này để chia một đợt KCB hoặc sinh MA_LK mới. Hồ sơ điều chỉnh/bổ sung giữ neo XML1_ID, MA_LK và dòng dữ liệu gốc theo TT 12/2026/TT-BTC; VN Core 0.10.0 chưa quy định mô hình FHIR cho luồng đó. Instance hợp lệ trước thay đổi này vẫn hợp lệ vì cardinality không đổi.
Vì sao. QĐ 130/QĐ-BYT được sửa đổi, bổ sung bởi QĐ 4750/QĐ-BYT và QĐ 3176/QĐ-BYT, đọc hợp nhất, quy định cả bốn trường XML1 MA_THE_BHYT, MA_DKBD, GT_THE_TU, GT_THE_DEN: khi người bệnh được cấp thẻ mới trong thời gian điều trị thì “ghi tiếp” giá trị của thẻ mới, các giá trị cách nhau bằng dấu chấm phẩy — tức vẫn là một dòng XML1. NĐ 188/2025/NĐ-CP Điều 21 khoản 2 quy định mức hưởng mới được tính từ thời điểm thẻ mới có giá trị sử dụng và cơ sở khám bệnh, chữa bệnh phải kiểm tra quyền lợi, mức hưởng trước khi kết thúc lượt khám bệnh, chữa bệnh, ra viện.
Lưu ý phạm vi. Sắp insurance.sequence theo thứ tự các mã được ghi trong MA_THE_BHYT. Việc chọn thẻ còn giá trị khi kết thúc đợt — thẻ cơ sở kiểm tra trước khi ra viện — làm focal là quy ước minh hoạ của VN Core, không phải quy định trực tiếp của văn bản. Phân đoạn chi phí theo ngày dịch vụ và mức hưởng áp dụng trên từng dòng; xem ExampleClaimReissuedCard. Không dùng mô hình này để gộp các đợt khác nhau.
ClaimResponse, không phải ExplanationOfBenefitĐổi gì. ClaimResponse là nơi nhận kết quả giám định của cơ quan bảo hiểm xã hội. ExplanationOfBenefit lùi về vai trò tuỳ chọn, hướng người bệnh. Extension costSummary đã bị gỡ khỏi ExplanationOfBenefit, vẫn giữ trên Claim.
Vì sao. Cơ quan bảo hiểm xã hội trả kết quả giám định chứ không phát hành ExplanationOfBenefit. Về costSummary: đối chiếu trên ví dụ ExampleExplanationOfBenefitBHYT cho thấy cả bảy giá trị của extension trùng khít bảy total tương ứng — nó chỉ nhân đôi số liệu.
Chuyển đổi. Biểu diễn các tổng bằng phần tử total lặp theo category trên ClaimResponse và ExplanationOfBenefit; profile không khai các slice total có tên. category dùng binding extensible tới vn-bhyt-adjudication-category-vs.
ConceptMap vn-cm-bhyt-financial-field-to-adjudication ánh xạ mười mã nguồn: T_TONGCHI và T_TONGCHI_BV → submitted; T_TONGCHI_BH → eligible (quan hệ wider, không tương đương tuyệt đối); T_BHTT → benefit; T_BNCCT → copay; T_BNTT → patient-self-pay; T_NGUONKHAC → other-fund; T_NGOAIDS → non-covered; T_THUOC → medication-subtotal; T_VTYT → supplies-subtotal. Không suy ánh xạ ngược duy nhất từ category.
T_BHTT_GDV thuộc chuỗi XML hiện hành nhưng chưa có ánh xạ trong ConceptMap này; giữ trong Claim.extension[costSummary]. T_NGOAIDS là trường legacy của QĐ 4210/QĐ-BYT, chỉ dùng để đọc/bridge dữ liệu lịch sử, không tự đổi thành T_BHTT_GDV. Giữ costSummary trên Claim vì Claim.total gốc chỉ là một Money đơn.
ClaimResponse.error — BREAKINGĐổi gì. Ở 0.9.0, từ chối nghiệp vụ của cơ quan bảo hiểm xã hội được ghi ở ClaimResponse.error
với error.code bind vào vn-bhyt-review-issue-vs. Từ 0.10.0 cách đó không còn hợp lệ:
Ở 0.9.0 |
Ở 0.10.0 |
|---|---|
error.code = mã lý do từ chối |
adjudication.category = denied (từ chối trước thanh toán) hoặc recovered (thu hồi sau thanh toán) |
| lý do nằm trong chính mã lỗi | adjudication.reason mang lý do; adjudication.amount mang số tiền |
| không có chỗ ghi căn cứ pháp lý | bắt buộc ít nhất một VNCoreExtAdjudicationLegalEvidence |
ClaimResponse.error từ 0.10.0 chỉ dành cho lỗi xử lý hồ sơ — sai định dạng, thiếu trường,
không đọc được — chứ không phải quyết định nghiệp vụ.
Vì sao. Từ chối thanh toán là một QUYẾT ĐỊNH có tiền, có lý do và có căn cứ pháp lý; lỗi xử lý
hồ sơ thì không có thứ nào trong ba thứ đó. Gộp hai việc vào một trường làm cơ sở khám bệnh, chữa
bệnh không phân biệt được "hồ sơ gửi sai, gửi lại đi" với "đã giám định và từ chối chi trả khoản
này, đây là căn cứ" — hai tình huống dẫn tới hai hành động hoàn toàn khác nhau. Invariant
vn-claim-response-denied-complete cưỡng chế đủ ba thành phần, nên một khoản bị từ chối mà thiếu
số tiền, thiếu lý do hoặc thiếu căn cứ sẽ không qua được validate.
Chuyển đổi. Với mỗi error mang mã lý do nghiệp vụ: chuyển thành một adjudication ở đúng cấp
(toàn hồ sơ, item, item.detail hoặc addItem), đặt category = denied/recovered, đưa mã lý
do cũ vào reason, điền amount bằng số tiền bị từ chối, và gắn căn cứ pháp lý. Các error còn lại
— nếu thật sự là lỗi xử lý — giữ nguyên.
Đổi gì. Invariant mới vn-patient-mrn-issuer-scoped: mã bệnh nhân ghi dưới URI dùng tạm cấp quốc gia http://fhir.hl7.org.vn/core/sid/mrn phải kèm assigner.
Vì sao. Khoá duy nhất của identifier là system + value. Nếu mọi cơ sở cùng ghi dưới một URI quốc gia thì hai người bệnh khác nhau ở hai bệnh viện có thể mang đúng một cặp system + value.
Chuyển đổi. Cách đúng hơn cả là mỗi cơ sở công bố URI riêng cho namespace mã bệnh nhân của mình (ví dụ http://cho-ray.benhvien.example.vn/sid/mrn); khi đó không cần assigner. Nếu tạm thời vẫn dùng URI quốc gia thì bắt buộc điền assigner.
Đổi gì. vn-claim-response-money-vnd và vn-cost-statement-money-vnd chặn mọi khoản tiền không phải VND.
Vì sao. Trước đây quy ước chỉ nằm ở phần mô tả — một lời nhắc, không phải ràng buộc; hồ sơ ghi USD hoặc bỏ trống currency vẫn hợp lệ.
Quy ước ghi số. Đồng Việt Nam không có đơn vị nhỏ hơn đồng đang lưu hành, nên Money.value ghi thẳng số đồng: 200000 nghĩa là hai trăm nghìn đồng. Không nhân hay chia 100 theo thói quen của các hệ tiền tệ có xu, không ghi phần thập phân.
Đổi gì. identifier[CCCD] hạ từ 1..1 xuống 0..1, thay bằng invariant vn-patient-identifier-minimum.
Vì sao. Bản trước buộc người nước ngoài, trẻ sơ sinh chưa cấp số định danh và người bệnh cấp cứu chưa rõ nhân thân đều phải mang một identifier rỗng chỉ để thoả cardinality — tạo định danh giả.
Chuyển đổi. Phải có ít nhất một trong: số định danh cá nhân, hộ chiếu, hoặc giấy khai sinh. Nếu không có định danh quốc gia nào thì phải có mã bệnh nhân của cơ sở kèm extension vn-ext-force-majeure-reason. Riêng data-absent-reason trên CCCD không đủ để miễn — nó cho biết "không có giá trị", không cho biết vì sao được phép không có.
Đổi gì. Coding ICD-10 trong VN Core chuyển từ http://hl7.org/fhir/sid/icd-10 sang http://fhir.hl7.org.vn/core/CodeSystem/vn-icd10-cs. Trên VNCoreConditionDiagnosis, slice icd10vn nay cố định hệ Việt Nam; mã WHO gốc chuyển sang slice mới icd10who (tuỳ chọn) dành cho liên thông quốc tế.
Vì sao. Danh mục Việt Nam là một edition quốc gia, không phải tập con của bảng WHO: nó mang mã mở rộng riêng không tồn tại trong ICD-10 quốc tế — B18.00/09/10/19 (viêm gan B mạn theo giai đoạn miễn dịch), I70.00–I70.91 (xơ vữa động mạch), J96.00–J96.99 (suy hô hấp). Phát chúng dưới URI của WHO là khai sai định danh: hệ thống quốc tế có quyền hiểu URI đó là bảng của WHO và coi mã lạ là mã không hợp lệ. Đây cũng là khuôn chung của mọi national edition — Đức dùng icd10gm, Mỹ dùng sid/icd-10-cm, đều tách khỏi URI WHO dù đa số mã trùng nhau.
Lưu ý con số: trong 3.355 mã cấp 5 của danh mục, chỉ 23 mã là mở rộng riêng Việt Nam. Phần còn lại (chương XIII M, chương XIX S/T) là supplementary subdivision do chính WHO định nghĩa nên vẫn thuộc hệ WHO.
Chuyển đổi. Đổi Coding.system sang vn-icd10-cs. Mã giữ nguyên chuỗi cho phần lớn danh mục, TRỪ 918 mã mang ký hiệu kép: từ 0.10.0 chúng ở dạng ASCII trơn (E11.3 thay cho E11.3†, H36.0 thay cho H36.0*), và vai trò dagger/asterisk chuyển sang property dagger-asterisk của CodeSystem. Lý do: ký hiệu †/* là quy ước IN ẤN đánh dấu cặp nguyên nhân–biểu hiện, không phải một phần của mã theo WHO; để trong giá trị mã thì hệ thống lưu mã theo trường MA_BENH của QĐ 3176/QĐ-BYT không khớp được mã nào. Hệ thống nào đã lưu chuỗi có ký hiệu chỉ cần cắt bỏ †/* — phép rút là song ánh, không mã nào va chạm. vn-icd10-cs hiện là edition 2026 (business version 2026-07-01, 16.052 concept — 15.844 hiện hành + 208 mã huỷ giữ inactive; giảm so với bản trước vì 94 dòng Phụ lục 4 hoá ra là cùng một mã in hai kiểu, nay gộp làm một), đối soát ba chiều với bảng ký TT 06/2026/TT-BYT và PL4/PL5 QĐ 1849/QĐ-BYT; dữ liệu lập trước 01/07/2026 resolve qua bản wrapper TIỀN-CHUYỂN-ĐỔI đóng băng byte-for-byte tại version 2020-legacy (nội dung 2020 cộng 3.928 mã PL5 đã nạp sớm và J13 inactive — KHÔNG phải edition 2020 thuần). Với 15.821 mã hiện hành có tên WHO 2019 tương ứng, vn-cm-icd10vn-to-icd10who cho ánh xạ một-đối-một (sourceVersion=2026-07-01, targetVersion=2019; 23 mã mở rộng VN và 208 mã huỷ không map) để sinh coding thứ hai khi cần gửi ra quốc tế. Truy vấn không phải sửa: SearchParameter vn-icd10 phủ cả hai hệ.
| Danh mục | v0.7.0 | v0.10.0 |
|---|---|---|
Huyệt châm cứu vn-yhct-acupoint-cs |
466 mã | 1.630 mã — bổ sung biến thể theo bên (bên trái, bên phải, hai bên), mỗi biến thể một mã dùng chung riêng do Bộ Y tế cấp |
ICD-10 vn-icd10-vs |
chỉ include http://hl7.org/fhir/sid/icd-10 |
include cả hai hệ; hệ chính khi coding là vn-icd10-cs (xem mục 8) — hiện là edition 2026 (2026-07-01, 16.052 concept, mã ASCII trơn, đối soát xong với bảng ký TT 06/2026/TT-BYT + PL4/PL5 QĐ 1849/QĐ-BYT); dữ liệu lịch sử resolve qua bản wrapper tiền-chuyển-đổi 2020-legacy (2020 + phần PL5 nạp sớm, không phải edition 2020 thuần) |
vn-body-site-vs |
chỉ SNOMED anatomy | thêm mã huyệt, để châm cứu mã hoá được bằng danh mục Bộ Y tế |
| Bộ mã hành chính | Các canonical và biểu diễn mã huyện cũ | Một canonical mỗi cấp; mã huyện nhà nước ba chữ số, history/current ValueSet riêng — xem phần hành chính bên dưới |
Hệ thống đang gửi mã huyệt biến thể theo bên (6536003 Trung Phủ bên trái) trước đây không validate được, nay hợp lệ.
VNCoreObservationYHCT từ 0.10.0 dùng pattern A (quyết định governance 12/08/2026 —
analysis/99 mục 6): code là THUỘC TÍNH được khám từ vn-yhct-observation-attribute-vs
(pulse-type, tongue-body, tongue-coating, inquiry-symptom…), finding (mạch trầm,
chất lưỡi nhợt…) là valueCodeableConcept theo bộ mã dùng chung QĐ 2552/3080/QĐ-BYT.
component.code, lặp trong valueString): mỗi component cũ
trở thành MỘT Observation atomic mới — component.code cũ chuyển xuống
valueCodeableConcept, phần chữ của valueString chuyển vào value.text/note.valueString không còn hợp lệ (invariant vn-yhct-no-string-result); panel tứ chẩn
dùng mã panel-* + hasMember, không mang value (invariant vn-yhct-panel-shape);
mạch theo bộ vị dùng component.code = pulse-{left|right}-{cun|guan|chi}.combo-value-concept
(server SHALL hỗ trợ theo CapabilityStatement).vn-ext-practice-license-exemption (trên Practitioner) ngừng authoring từ 0.10.0:
miễn trừ GPHN là quyền CÓ GIỚI HẠN theo cơ-sở/thời-gian/phạm-vi (Luật 15/2023/QH15
Điều 19 khoản 2 điểm a), không phải thuộc tính vô hạn của con người. Bản ghi mới dùng
vn-ext-practice-license-exemption-role trên PractitionerRole:
organization + period hữu hạn (invariant vn-role-exemption-bounded);supervisor (invariant
vn-role-exemption-trainee-supervised);evidence 1..*: Reference(DocumentReference) khi văn bản đã số hoá hoặc
Identifier số quyết định khi thực địa chỉ có bản giấy.Dữ liệu cũ trên Practitioner vẫn đọc được (extension cũ giữ định nghĩa, gỡ ở 0.11); KHÔNG tự động migrate — bản ghi cũ thiếu cơ sở/thời hạn/người giám sát phải được bổ sung thủ công khi chuyển.
Chạy validator trên dữ liệu mẫu của hệ thống với gói [email protected]. Các lỗi hay gặp nhất khi chuyển từ v0.7.0:
Claim mang extension bảng kê → chuyển sang Invoice;Money thiếu currency hoặc ghi khác VND;assigner;MedicationRequest/Procedure còn mang insuranceCostInfo.| Nếu cần | Nên đọc tiếp |
|---|---|
Hiểu vì sao bảng kê chuyển sang Invoice |
ADR-0021 — Ranh giới vòng đời tài chính (wiki quản trị dự án, wiki/decisions/adr-0021-financial-lifecycle-boundaries.md) |
| Nắm chính sách phân loại thay đổi và ngưỡng phát hành | Phát hành và quản trị |
| Xem mức độ ổn định của từng tài nguyên | Ổn định và tuân thủ |
| Bắt đầu tích hợp từ đầu | Bắt đầu |
Năm ValueSet vn-province-vs, vn-province-history-vs, vn-district-vs, vn-ward-vs, vn-ward-history-vs dùng expansion kèm theo làm định nghĩa thành viên đã thẩm định, không có compose. Bên tích hợp cần nạp và dùng expansion này, giữ ba tham số date, historyScope, used-codesystem; tham số cuối dùng valueUri dạng canonical CodeSystem|version để xác định edition nguồn. Máy chủ chỉ tái tính từ compose sẽ trả tập rỗng, nên phải hỗ trợ expansion tường minh trước khi chọn mã/kiểm thành viên; không diễn giải tập rỗng đó là mã nguồn không hợp lệ. Tập current được chốt theo trạng thái có bằng chứng tại ngày snapshot; membership trong tập history không chứng minh hiệu lực lịch sử.
Ba CodeSystem vn-province-cs, vn-district-cs, vn-ward-cs dùng mã nhà nước dài 2/3/5 chữ số. Ngoại lệ không tương thích đã được chủ dự án duyệt riêng cho 0.10.0: rút hai cặp CS/VS province-legacy, district-legacy và hai ConceptMap vn-cm-district-rename, vn-cm-province-legacy-to-new. Package cũ không bị sửa; nguồn và registry chuyển mã cũ được lưu để tái lập.
Giữ text, mã và ngày hồ sơ nguồn. Với mã tỉnh/xã nhà nước, dùng canonical của cấp đó và history ValueSet; không tự chuyển hồ sơ lịch sử sang tỉnh/xã hiện hành. Tập chọn mới có 34 tỉnh và 3.321 xã tại 20/09/2026. Danh mục history rộng hơn: 64/716/11.180 mã quan sát; không phải tất cả có giai đoạn đã xác minh. Tra cứu theo ngày chỉ được trả tên và tỉnh quản lý khi có bằng chứng. Thiếu ngày hay ngoài khoảng trả không đủ căn cứ; Coding.version là edition dữ liệu, không phải ngày hồ sơ.
Bộ mã xã của VN Core v0.7.0, v0.8.0 và bản 0.9.0 tại commit 49151c7c đã chép nhầm 06978 cho Xã Ba Chẽ, tỉnh Quảng Ninh (22). Công báo QĐ 19/2025/QĐ-TTg, trang 46, ghi đúng 06970. Bản 0.10.0 sửa lỗi chép bảng này; đây không phải sự kiện hành chính đổi mã.
Chỉ sửa 06978 thành 06970 khi dấu vết dữ liệu chứng minh nguồn là đúng bảng VN Core cũ nêu trên, đúng Xã Ba Chẽ và đúng tỉnh 22. Trong hồ sơ chuyển đổi, giữ lại mã, tên, phiên bản và nguồn ban đầu cùng giá trị đã đính chính. Không thay 06978 hàng loạt và không dùng bảng chuyển mã huyện cho trường hợp này.
Cùng lớp đính chính transcript, mã 00745 giữ nguyên nhưng tên được sửa từ Xã Phó Bảng thành Xã Phố Bảng theo Công báo QĐ 19/2025/QĐ-TTg. Ngược lại, mười xã Đồng Nai chuyển thành phường là các delta theo ngày hiệu lực riêng: áp dụng theo ngày hồ sơ và không gộp chúng với hai đính chính bảng trên.
Canonical trong bảng có tiền tố chung http://fhir.hl7.org.vn/core/CodeSystem/. Phiên bản gói và CodeSystem.version là hai giá trị khác nhau; source_edition là ngữ cảnh tra bảng chuyển, không được chép vào Coding.version đích.
| Phiên bản gói / bản nguồn | Canonical (sau tiền tố) | CodeSystem.version |
Dạng mã | source_scheme |
source_edition |
|---|---|---|---|---|---|
| 0.7.0 | vn-district-cs |
0.7.0 |
TMS, ví dụ 10101 |
tms |
tms-before-2026-09-09 |
| 0.8.0 | vn-district-cs |
0.7.0 |
TMS, ví dụ 10101 |
tms |
tms-before-2026-09-09 |
| 0.9.0 | vn-district-cs |
0.9.0 |
TMS, ví dụ 10101 |
tms |
tms-before-2026-09-09 |
| 0.9.0 | vn-district-legacy-cs |
0.9.0 |
TMS, ví dụ 10101 |
tms |
tms-before-2026-09-09 |
0.10.0 nháp trước tích hợp, commit f44ef7f3 |
vn-district-cs |
0.10.0 |
Ghép tỉnh+huyện, ví dụ 01001 |
province-district |
0.10.0 |
0.10.0 nháp trước tích hợp, commit f44ef7f3 |
vn-district-legacy-cs |
20250630 |
Ghép tỉnh+huyện, ví dụ 01001 |
province-district |
20250630 |
| 0.10.0 nháp sau tích hợp | vn-district-cs |
20260920 |
Mã nhà nước 3 chữ số, ví dụ 001 |
Không áp dụng bảng chuyển 5 chữ số | Không áp dụng |
Đối chiếu nguồn Git tại tag v0.7.0, v0.8.0 và commit 49151c7c (main / feat/release-0.9.0) cho thấy mỗi bộ huyện trên có đúng tập 696 mã TMS của bảng chuyển. Không có tag v0.9.0 trong checkout đã kiểm; hàng 0.9.0 dựa trên commit nguồn này, chưa phải phép đối chiếu byte gói .tgz đã phân phối. Hai bản 0.7.0/0.8.0 không có canonical vn-district-legacy-cs. Hai FSH mã ghép tại f44ef7f3 khớp nguyên byte với bản lưu trước tích hợp và phủ đúng 696 mã ghép trong registry.
tms-before-2026-09-09 chỉ là nhãn snapshot chuyển mã đã pin, không phải FHIR business version hoặc ngày hiệu lực hành chính. Các giá trị 0.7.0, 0.8.0, 0.9.0 không phải edition hợp lệ của scheme tms. Chỉ chọn nhãn snapshot sau khi xác định dữ liệu thuộc đúng bộ nguồn trong bảng. Bản tuỳ biến, bản 0.10.0 nháp không xác định được nguồn, canonical/edition khác, hoặc mã ngoài bảng: không hỗ trợ tự động, vì chưa có ánh xạ được kiểm cho ngữ cảnh đó; giữ dữ liệu gốc và xử lý riêng.
Tải vn-district-code-migration.json từ site IG (đường dẫn /core/vn-district-code-migration.json trên fhir.hl7.org.vn; cũng có tại gốc site). Đây là JSON tra bảng gồm 696 dòng, không phải artifact FHIR và không cần Python hay bộ nguồn của người bảo trì.
a3941e2d5f3b6412d615a9eb019b7b5dbc5ad2b47189f9924ae6f0456458b064.sourceRegistry.sha256: 4c94a909bb0adb675e5c97747749bedc130eb7843bebc63ae1fea479b2740096.Sau khi tải, kiểm bằng shasum -a 256 vn-district-code-migration.json và đối chiếu checksum tệp ở trên. Lưu checksum cùng hồ sơ chuyển đổi. Metadata trong JSON chứa rowCount, sourceSchemes (edition, loại edition, cột mã) và giới hạn sử dụng.
source_scheme và source_edition theo bảng; kiểm edition thuộc sourceSchemes[source_scheme].editions. Không đoán hệ từ độ dài hay giá trị mã.tmsCode nếu scheme là tms, hoặc combinedCode nếu là province-district; chỉ nhận khi có đúng một dòng. Thiếu ngữ cảnh hoặc không tìm thấy dòng thì trả không đủ căn cứ, không tự đệm, cắt chuỗi hoặc thử sang hệ còn lại.targetCode nguyên chuỗi 3 chữ số và targetSystem trong metadata. Ví dụ TMS 10101 và mã ghép 01001 cùng cho 001; riêng 11101 thuộc TMS cho 347, còn hệ ghép cho 101. Lưu mã/hệ/edition nguồn, ngày hồ sơ, checksum và dòng đã dùng làm dấu vết chuyển đổi.Chỉ đổi biểu diễn mã, không chứng nhận địa giới/pháp nhân; không tự chuyển hồ sơ lịch sử sang đơn vị hiện hành. unitName lấy nguyên từ sourceNameFromMigration của registry để nhận biết dòng; không phải tên đã xác minh tại ngày hồ sơ. Có 64 nhãn khác display của các FSH nguồn, nên không dùng tên trong bảng để ghi đè display/text gốc. Việc chuyển biểu diễn cũng không chứng minh hiệu lực hoặc tỉnh quản lý tại ngày hồ sơ. Address.district vẫn lưu tên dạng text.
API load_district_migrations(...).migrate_district(code, source_scheme, source_edition) là công cụ của người bảo trì repo: nó tái kiểm hash các nguồn cục bộ, gồm tệp bị gitignore. Người bảo trì phải cấp đúng bộ nguồn theo wiki/workflows/administrative-source-provisioning.md trước khi dùng API; clone công khai đơn thuần không đủ. Bộ sinh scripts/generate-district-code-migration.py chỉ đọc registry đã pin để xuất tệp tải xuống; thay registry cần kiểm nguồn và thẩm định lại trước khi cập nhật pin/checksum.
Hai extension tỉnh/xã vẫn tuỳ chọn 0..1 MS; địa chỉ chỉ có text hợp lệ cả khi country=VN. ConceptMap chuyển trạng thái chỉ có các cạnh đã thẩm định và không thay crosswalk đầy đủ lịch sử. Trạng thái dữ liệu hiện tại là content=fragment; không được diễn giải thiếu giai đoạn là đơn vị chưa từng tồn tại.
Trong 0.10.0, vn-bhyt-card-type-vs gồm đúng 59 mã của Phụ lục I CV 1804/BHXH-QLT.
CodeSystem đi kèm có 71 mã, gồm thêm 12 mã tương thích; binding là extensible.
Không tự đọc hai ký tự đầu thẻ 15 ký tự bằng nghĩa của danh mục hiện hành. DN cũ là lao động
trong doanh nghiệp nói chung, trong khi DN mới giới hạn doanh nghiệp nhà nước; HX, NN, NO,
CT và nhiều mã khác cũng có thay đổi phạm vi.
Khi đã xác minh dữ liệu theo bảng Phụ lục C QĐ 3680/QĐ-BHXH, dùng
vn-bhyt-card-type-legacy-cs, gồm 49 mã.
Bản này không bao quát mọi danh mục trước 2025 hay toàn bộ 53 mã biên tập ở VN Core 0.8.0.
Khi thiếu nguồn, giữ identifier, nội dung gốc và provenance; có thể ghi CodeableConcept.text
như ví dụ thẻ cũ. Tra cứu lại cơ quan BHXH trước
khi chọn mã hiện hành. Không chạy thay system/code hàng loạt theo ký hiệu.
ConceptMap đối chiếu chỉ chứa
relatedto, giữ experimental=true; không phải lệnh tự chuyển mã. Package lịch sử đã
phát hành được giữ nguyên. Mã thẻ, mã đối tượng, nhóm đóng và quyền lợi thanh toán là các dữ
liệu khác nhau. Property group và historical-benefit-level đã được bỏ khỏi CodeSystem
hiện hành; ứng dụng phải dùng quyền lợi do BHXH cung cấp theo thời điểm dịch vụ. Cập nhật
quyền lợi từ 01/01/2026 áp dụng CN và người từ đủ 75 tuổi trở lên thuộc LH, không phải mọi LH.
Bộ mã tiền giường giữ canonical và hai mã ví dụ cũ, mở rộng thành 284 mã theo Phụ lục 3–4 QĐ 2010/QĐ-BYT. Không suy thêm mã từ ô trống.
Bản nháp KSK trước sửa đã đưa 22 trường CKDT_* vào Observation.code. Bản này bỏ các mã chữ ký khỏi bộ mã Observation (còn 160 mã); giữ nguyên 26 linkId/text trong hai Questionnaire và dùng definition vn-core-provenance#Provenance.signature.data. Mã PHAN_LOAI_SK của 0.8.0 không đổi. Hệ thống đã thử bản nháp cần kiểm các CKDT đang lưu dạng Observation và đối chiếu lại nguồn, không đổi mù sang kết quả lâm sàng hay chữ ký.
Trong ví dụ XML QĐ 2062/QĐ-BYT có CKDT mang chuỗi “Bình thường”, khác ý nghĩa chữ ký của bảng mô tả. Giữ nguyên chuỗi nhận được trong QuestionnaireResponse; chỉ sinh Provenance.signature khi có dữ liệu chữ ký, người ký, thời điểm và định dạng phù hợp. Signature.data của FHIR R4 dùng base64Binary; việc mã hoá một chuỗi bất kỳ không làm chuỗi đó thành chữ ký hợp lệ. Definition của Questionnaire không tự thực hiện chuyển đổi hoặc xác minh mật mã.
vn-department-cs giữ đủ 67 mã liệt kê của QĐ 1804/QĐ-BYT Phụ lục 02 nhưng khai fragment vì nguồn còn cho phép mã ghép/chuyên khoa sâu/đơn nguyên, ví dụ K02.D35. Binding Organization.type[deptClass] chuyển từ required sang extensible: vẫn phải dùng mã ValueSet khi phù hợp; ngoài tập chỉ dùng mã suy dẫn đã kiểm căn cứ và khoa gốc tại cơ sở. Giữ Coding.system canonical cho MA_KHOA; mã HIS thuần nội bộ tiếp tục dùng identifier. Không tự suy một mã hợp lệ chỉ vì khớp dạng chữ K và số. count=67 là số concept liệt kê, không phải số biểu thức mã suy dẫn có thể tạo.
This page lists what implementers running v0.7.0 must change for v0.10.0. The cost statement moves from Claim/ExplanationOfBenefit to Invoice (ADR-0021) because FHIR R4 requires Claim.insurance 1..*, making the uninsured case unrepresentable. insuranceCostInfo is removed from four clinical profiles in a single step. A card reissued during one episode is represented by one Claim with multiple ordered insurance entries and exactly one focal entry. Claim.related remains optional with its FHIR semantics, but it is no longer Must Support and carries no national minimum send, receive, persistence, or preservation obligation. Do not split an episode or generate a new MA_LK from this guide; VN Core 0.10.0 does not define the FHIR model for adjustment or supplementation flows. Previously valid instances remain valid because the cardinality is unchanged. Adjudication results belong on ClaimResponse; costSummary is removed from ExplanationOfBenefit (it stays on Claim) because, in ExampleExplanationOfBenefitBHYT, its seven values exactly duplicated the corresponding total elements; totals repeat by category, with no named total slices. New invariants enforce issuer-scoped medical record numbers and VND currency. National ID is no longer mandatory on every Patient. The acupuncture point code system grows from 466 to 1,630 codes.
Ward-table corrections are provenance-sensitive. VN Core v0.7.0, v0.8.0 and the 0.9.0 source at commit 49151c7c mistakenly recorded 06978 for Xã Ba Chẽ in Quảng Ninh (22); page 46 of the Official Gazette publication of QĐ 19/2025/QĐ-TTg records 06970. Version 0.10.0 corrects a table transcription error, not an administrative code-change event. Replace the old value only when the source is that VN Core table and both the commune and province match; retain the original code, name, version and source in the migration trail. Never replace 06978 globally or use the district-code migration table for this case. Code 00745 keeps its code while its name is corrected from “Xã Phó Bảng” to “Xã Phố Bảng”. The ten Đồng Nai communes reclassified as wards are date-effective deltas and must remain separate from these corrections.