# Hành vi tìm kiếm - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## 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](string-search-guidance.md), [Danh mục định danh](identifier-registry.md) và [Hồ sơ](profiles.md) 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](string-search-guidance.md) 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

| | | |
| :--- | :--- | :--- |
| `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ắ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](string-search-guidance.md) |
| Tra danh mục định danh dùng cho token search | [Danh mục định danh](identifier-registry.md) |
| Xem ánh xạ URI/OID và cầu nối dữ liệu lịch sử | [Ánh xạ URI/OID](identifier-registry.md#ánh-xạ-uri-và-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ủ](stability-and-conformance.md) |

-------

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

