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

Hành vi tìm kiếm

Hành vi tìm kiếm — Search Behavior

Trang này mô tả hành vi tìm kiếm tối thiểu mà bên triển khai cần nắm khi triển khai VN Core FHIR IG.

Mục tiêu là:

  • Giữ số lượng custom SearchParameter ở mức vừa đủ
  • Làm rõ kỳ vọng theo từng kiểu token, string, date, reference
  • Tránh việc mỗi HIS/FHIR server tự diễn giải khác nhau

Trang này dành cho ai?

  • Nhóm triển khai FHIR server hoặc API facade phải công bố hành vi search rõ ràng.
  • Nhóm HIS/EMR tích hợp cần biết truy vấn nào có thể kỳ vọng là tương thích liên hệ thống.
  • Nhóm QA và reviewer cần một mặt bằng chung để viết test case search.

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

  • Khi cần công bố hành vi tìm kiếm cho một điểm cuối API, một vai trò triển khai hoặc một CapabilityStatement.
  • Khi phải chốt search nào là tìm kiếm nghiệp vụ chính xác và search nào chỉ là hành vi tăng cường cục bộ.
  • Khi đang viết test case tìm kiếm cho CCCD, BHYT, BHXH, MA_LK, MA_LUOT_KCB hoặc các chuỗi tiếng Việt có dấu.

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

  • Search parameter nào là bắt buộc tối thiểu cho liên thông.
  • Hành vi nào là chuẩn FHIR, hành vi nào là mở rộng cục bộ phải công bố rõ.
  • Khi nào cần đọc thêm trang Unicode/string search, identifier registry hoặc profile cụ thể.

Dùng trang này cùng với gì?

Search là một phần của conformance, không phải ghi chú phụ

Một hạn chế dễ gặp ở các bộ profile đời đầu là có profile nhưng không nói rõ hệ thống phải search như thế nào. VN Core hiện tại cố ý tách hẳn search semantics ra thành guidance riêng để trưởng thành hơn:

  • Search được gắn với hướng dẫn theo vai trò triển khai và CapabilityStatement, không chỉ ghi rải rác trong profile;
  • Search theo định danh quốc gia được xem là hành vi conformance cốt lõi, không phải tối ưu tùy hứng;
  • Hành vi tăng cường như accent-insensitive hay fuzzy search phải được công bố rõ, thay vì để mỗi hệ thống tự hiểu.

1. Nguyên tắc chung

  • Hệ thống SHALL tuân thủ semantics chuẩn của FHIR cho các SearchParameter mà mình công bố hỗ trợ.
  • VN Core chỉ thêm custom SearchParameter khi bài toán pháp lý hoặc nghiệp vụ Việt Nam không thể dựa hoàn toàn vào search parameter chuẩn.
  • Những điểm không được chuẩn hóa bằng SearchParameter riêng nên được mô tả ở phần hướng dẫn và công bố trong CapabilityStatement hoặc báo cáo triển khai.

2. Hành vi theo kiểu tham số

2.1. token

token là kiểu ưu tiên cho các định danh và mã nghiệp vụ Việt Nam.

Áp dụng chính:

  • CCCD
  • BHYT
  • BHXH
  • GPHN
  • CCHN
  • CSKCB
  • MA_LK
  • MA_LUOT_KCB
  • Mã ICD-10

Quy tắc:

  • Server SHALL hỗ trợ exact match theo logic của FHIR token search.
  • Server SHALL NOT biến token search thành fuzzy text search.
  • Nếu hệ thống có normalize tối thiểu như bỏ khoảng trắng, bỏ dấu gạch nối hoặc upper-case hóa một số định danh, hệ thống SHOULD công bố rõ.
  • Với định danh có system rõ, bên triển khai SHOULD ưu tiên tra cứu theo cặp system + value.

2.2. string

string áp dụng cho:

  • Patient.name
  • Practitioner.name
  • Organization.name
  • Location.name

Quy tắc:

  • Server SHALL hỗ trợ string search theo semantics chuẩn của FHIR.
  • Accent-insensitive search, ASCII folding, hoặc fuzzy search là hành vi tăng cường cục bộ.
  • Nếu hệ thống hỗ trợ tìm kiếm không dấu cho tên tiếng Việt, cần xem thêm Tìm kiếm chuỗi và Unicode và nên công bố rõ trong CapabilityStatement hoặc implementation report.

2.3. date

date áp dụng cho:

  • Patient.birthDate
  • Thời gian encounter
  • Thời gian hiệu lực bảo hiểm

Quy tắc:

  • Với birthDate, search SHOULD được hiểu theo ngày lịch, không gắn timezone.
  • Với dateTime hoặc tìm kiếm ràng buộc theo khoảng thời gian, hệ thống SHOULD dùng chuẩn FHIR cho tiền tố như ge, gt, le, lt.
  • Khi nguồn chỉ biết một phần độ chi tiết, bên triển khai không nên tự sinh timezone hoặc thời điểm giả.

2.4. reference

reference áp dụng cho quan hệ:

  • Bệnh nhân của một hồ sơ
  • Practitioner/practitionerRole
  • Organization/service provider
  • Encounter-subject
  • Coverage-beneficiary

Quy tắc:

  • Server SHALL hỗ trợ reference search theo semantics chuẩn của FHIR cho các reference search parameter đã công bố.
  • Relative reference và absolute reference hợp lệ đều nên được xử lý nhất quán.
  • Identifier-based reference resolution chỉ nên coi là hỗ trợ mở rộng nếu được công bố rõ, không mặc định giả định.

3. Kỳ vọng tối thiểu cho search của VN Core

3.1. Các custom search parameter quốc gia cần được hiểu như tìm kiếm chính xác

SearchParameter Kiểu Kỳ vọng triển khai
vn-sp-patient-cccd token Exact business identifier search; không fuzzy
vn-sp-patient-bhyt token Tìm kiếm chính xác cho 3 format BHYT được hỗ trợ
vn-sp-patient-bhxh token Tìm kiếm chính xác theo mã số BHXH
vn-sp-patient-gks token Tìm kiếm chính xác theo số giấy khai sinh khi có
vn-sp-patient-vneid token Tìm kiếm chính xác theo tài khoản định danh điện tử nếu hệ thống triển khai
vn-sp-practitioner-gphn token Tìm kiếm chính xác theo giấy phép hành nghề hiện hành
vn-sp-practitioner-cchn token Tìm kiếm chính xác theo định danh lịch sử
vn-sp-organization-cskcb token Tìm kiếm chính xác theo mã CSKCB
vn-sp-encounter-malydo token Tìm kiếm chính xác theo mã lý do/loại KCB BHYT
vn-sp-encounter-ma-luot-kcb token Tìm kiếm chính xác theo mã lượt khám
vn-sp-coverage-bhyt token Tìm kiếm chính xác theo thẻ BHYT
vn-sp-coverage-ma-dkbd token Tìm kiếm chính xác theo mã nơi đăng ký KCB ban đầu
vn-sp-condition-icd10 token Tìm kiếm chính xác theo mã ICD-10 VN
vn-sp-claim-ma-lk token Tìm kiếm chính xác theo mã liên kết hồ sơ

3.2. Các hành vi tăng cường nên công bố rõ

Nếu hệ thống triển khai các hành vi sau, cần công bố rõ:

  • Tìm kiếm không dấu cho tên tiếng Việt
  • Normalize dấu gạch nối hoặc khoảng trắng trong hộ chiếu
  • Search by chained reference phức tạp
  • Search dùng identifier thay cho reference trực tiếp
  • Search có ranking hoặc fuzzy score

4. Hướng triển khai cho đơn vị cung cấp

4.1. Nên làm

  • Ưu tiên exact token indexing cho các định danh pháp lý/nghiệp vụ.
  • Viết rõ cam kết hành vi tìm kiếm cho từng endpoint trong tài liệu triển khai nội bộ.
  • Ghi vào implementation report các search parameter nào thực sự đã test.

4.2. Không nên làm

  • Không tạo custom SearchParameter mới chỉ để mô tả một hành vi normalization nội bộ.
  • Không biến token search thành string contains search.
  • Không quảng bá support search rộng hơn thực tế đã test.

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

English Summary

This page defines the minimum expected search behavior for VN Core. Custom search parameters are intentionally limited and focused on Vietnamese business identifiers such as CCCD, BHYT, BHXH, GPHN, CSKCB, MA_LK, and MA_LUOT_KCB, all of which should behave as exact token searches rather than fuzzy text searches. Accent-insensitive name search and other advanced string matching remain local enhancements and should be disclosed explicitly if supported.