HL7 Vietnam VN Core FHIR Implementation Guide

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.5.0 - Draft for Community Review

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## Tìm kiếm chuỗi & Unicode

# Tìm kiếm chuỗi và Unicode — String Search and Unicode Guidance

Chuẩn hóa cách xử lý chuỗi tiếng Việt và hành vi tìm kiếm liên quan đến Unicode trong VN Core — giảm khác biệt giữa các HIS/EMR/FHIR server khi xử lý họ tên có dấu, tên người nước ngoài, tên cơ sở y tế và text tự do.

Ba điểm chính: giá trị gốc nào phải được bảo toàn, chuẩn hóa nào chỉ được phép diễn ra trong lớp lập chỉ mục nội bộ, và khi nào cần đọc cùng Hành vi tìm kiếm để công bố chính sách search hoàn chỉnh.

## Nguyên tắc nền

### Bảo toàn giá trị gốc

- Hệ thống gửi SHALL giữ nguyên giá trị Unicode gốc theo hồ sơ nguồn nếu đó là tên chính thức hoặc dữ liệu có giá trị pháp lý.
- Hệ thống nhận SHALL lưu giữ được giá trị gốc mà không làm mất dấu, đổi thứ tự ký tự hoặc ép về ASCII.
- Hệ thống SHALL NOT thay tên chính thức có dấu bằng phiên bản không dấu trong resource FHIR lưu trữ.

Ví dụ:

- `Nguyễn Văn An` phải được giữ nguyên dưới dạng có dấu nếu đó là giá trị nguồn.
- `TRẦN THỊ BÍCH NGỌC` không được tự động đổi thành `Tran Thi Bich Ngoc` trong dữ liệu đã lưu.

### Chuẩn hóa để lập chỉ mục là việc nội bộ

- FHIR resource được trao đổi là nguồn sự thật cho giá trị gốc.
- Việc normalize Unicode để so khớp, lập chỉ mục hoặc tối ưu tìm kiếm là hành vi nội bộ của server.
- Server SHOULD dùng một dạng Unicode nhất quán khi lập chỉ mục, khuyến nghị `NFC`.
- Server MAY áp dụng thêm lowercasing, collapsing whitespace hoặc accent folding cho chỉ mục nội bộ nếu có kiểm soát.

### Tìm kiếm không phân biệt dấu không phải mặc định bắt buộc

- FHIR string search cơ bản vẫn theo semantics chuẩn của FHIR.
- Hỗ trợ tìm kiếm không dấu là mở rộng cục bộ, không phải nghĩa vụ mặc định của mọi bên triển khai.
- Nếu một hệ thống hỗ trợ tìm kiếm không dấu hoặc fuzzy search cho tiếng Việt, hệ thống đó SHOULD công bố rõ trong CapabilityStatement, tài liệu triển khai hoặc implementation report.

## Quy tắc cho dữ liệu tiếng Việt

### Họ tên người Việt

- `HumanName.text` SHOULD giữ nguyên cách viết chính thức theo hồ sơ nguồn.
- `HumanName.family` và `HumanName.given` SHOULD phản ánh đúng cấu trúc tên tiếng Việt, không đổi sang thứ tự phương Tây nếu không có lý do nghiệp vụ rõ ràng.
- Tìm kiếm theo `name` SHOULD ưu tiên so khớp trên dữ liệu đã chuẩn hóa nhưng SHALL trả về resource chứa giá trị gốc.

### Địa chỉ và tên cơ sở

- `Address.text`, `Address.line`, `Organization.name`, `Location.name` phải giữ nguyên dấu tiếng Việt nếu nguồn có.
- Không nên coi phiên bản không dấu là canonical form.
- Nếu hệ thống cho phép tìm `Benh vien Cho Ray` và vẫn trả về `Bệnh viện Chợ Rẫy`, cần coi đó là hành vi mở rộng tìm kiếm, không phải chuyển đổi dữ liệu nguồn.

### Tên người nước ngoài và hộ chiếu

- Dữ liệu theo hộ chiếu SHALL giữ nguyên đúng cách viết trong hộ chiếu.
- Không được tự ý thêm dấu tiếng Việt vào tên hộ chiếu không dấu.
- Với tên có dấu Latin ngoài tiếng Việt hoặc có ký tự ghép, hệ thống SHOULD bảo toàn nguyên trạng và chỉ normalize cho chỉ mục nội bộ nếu cần.

## Quy tắc triển khai cho server

Chủ thể | Quy tắc
--- | ---
Sender | SHALL gửi giá trị text gốc nếu có; SHALL NOT bỏ dấu chỉ để “dễ tìm hơn”.
Receiver | SHALL chấp nhận và bảo toàn chuỗi Unicode hợp lệ.
Server | SHOULD normalize nội bộ về `NFC` khi lập chỉ mục; MAY hỗ trợ accent-insensitive search nếu công bố rõ.
Client | SHALL NOT giả định rằng mọi server đều hỗ trợ tìm kiếm không dấu hoặc fuzzy search.

### Chuẩn hóa tối thiểu nên hỗ trợ

Để giảm sai lệch giữa các hệ thống, server SHOULD cân nhắc các chuẩn hóa tối thiểu sau cho chỉ mục nội bộ:

- Đưa về Unicode `NFC`
- Trim khoảng trắng đầu/cuối
- Gộp nhiều khoảng trắng liên tiếp thành một khoảng trắng
- Với một số định danh text-like như hộ chiếu, có thể bỏ khoảng trắng hoặc dấu gạch nối nếu chính sách local yêu cầu

### Những gì không nên làm

- Không ghi đè dữ liệu gốc bằng giá trị đã normalize.
- Không sinh thêm trường text không dấu vào resource chuẩn chỉ để phục vụ search.
- Không coi accent-insensitive search là điều kiện tuân thủ mặc định của VN Core nếu chưa công bố rõ.

## Ví dụ triển khai

### Ví dụ tên tiếng Việt

Nguồn HIS:

- `Nguyễn Văn An`

Khuyến nghị:

- Lưu `HumanName.text = Nguyễn Văn An`.
- Cho phép server lập chỉ mục nội bộ theo cả `nguyễn văn an` và `nguyen van an` nếu muốn.
- Vẫn trả về resource chứa `Nguyễn Văn An`.

### Ví dụ tên hộ chiếu

Nguồn hộ chiếu:

- `NGUYEN / ANH-MINH`.

Khuyến nghị:

- Giữ đúng text theo hộ chiếu trong bản ghi chính thức
- Không tự thêm dấu
- Nếu tìm kiếm có bỏ dấu hoặc bỏ gạch nối thì phải coi là mở rộng tìm kiếm cục bộ.

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

Nếu cần | Nên đọc tiếp
--- | ---
Hiểu hành vi cụ thể theo từng loại search parameter | Hành vi tìm kiếm
Nắm quy tắc tên tiếng Việt và định danh | Hướng dẫn chung
Diễn giải Must Support và xử lý thiếu dữ liệu | Hướng dẫn Must Support

## English Summary

This page defines how VN Core expects implementers to handle Unicode strings and string search behavior. Systems must preserve the original source value, normalize only in internal indexing layers, and disclose any accent-insensitive or fuzzy search behavior as a local enhancement rather than a baseline conformance requirement.