Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.5.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

Hành vi tìm kiếm tối thiểu cho VN Core, bao gồm kỳ vọng theo từng kiểu token, string, date, reference và số lượng custom SearchParameter được giữ ở mức vừa đủ để tránh việc mỗi HIS/FHIR server tự diễn giải khác nhau.

Đọc cùng Tìm kiếm chuỗi và Unicode, Danh mục định danh và Hồ sơ khi cần chốt tối thiểu theo từng vai trò triển khai.

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.

---

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.

---

Hành vi theo kiểu tham số

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.

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.

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ả.

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.

---

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

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-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ơ
vn-sp-claim-response-xml1-id	token	Tìm kiếm chính xác theo XML1_ID hoặc mã phản hồi gateway BHYT

Artifact lịch sử còn giữ để tương thích

Artifact lịch sử: vn-sp-patient-vneid được giữ lại như artifact lịch sử (retired) để ghi nhận quyết định thiết kế cũ. Artifact này không thuộc nhóm search expectation tối thiểu của core capability hiện hành; chỉ xem xét khi một hệ thống phải tương thích với lớp ứng dụng người dân và tích hợp VNeID.

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

---

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

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.

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.

---

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

Nếu cần	Nên đọc tiếp
Nắm quy tắc Unicode và dấu tiếng Việt cho tìm kiếm chuỗi	Tìm kiếm chuỗi và Unicode
Tra danh mục định danh dùng cho token search	Danh mục định danh
Xem ánh xạ URI/OID và cầu nối dữ liệu lịch sử	Ánh xạ URI/OID
Hiểu kỳ vọng về tuân thủ và mức trưởng thành của search	Ổn định và tuân thủ

---

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.