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
Tìm kiếm chuỗi & Unicode
Tìm kiếm chuỗi và Unicode — String Search and Unicode Guidance
Trang này 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 FHIR IG.
Mục tiêu là giảm khác biệt giữa các HIS/EMR/FHIR server khi xử lý:
- Họ tên tiếng Việt có dấu.
- Tên người nước ngoài theo hộ chiếu.
- Tên cơ sở y tế.
- Text tự do trong địa chỉ, tài liệu và mô tả nghiệp vụ.
Trang này dành cho ai?
- Nhóm phát triển FHIR server, search layer hoặc indexing pipeline.
- Nhóm HIS/EMR cần biết dữ liệu nào phải giữ nguyên khi lưu trữ và hiển thị.
- Nhóm QA cần kiểm thử tên tiếng Việt có dấu, tên hộ chiếu và địa chỉ thực tế.
Trang này giúp chốt điều gì?
- Giá trị gốc nào phải được bảo toàn tuyệt đối.
- Những chuẩn hóa nào chỉ nên diễn ra trong lớp lập chỉ mục nội bộ.
- Khi nào nên kết hợp trang này với Hành vi tìm kiếm để định nghĩa chính sách search hoàn chỉnh.
1. Nguyên tắc nền
1.1. 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.
1.2. 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.
1.3. 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.
2. Quy tắc cho dữ liệu tiếng Việt
2.1. 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.
2.2. Đị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.
2.3. 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.
3. 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. |
3.1. 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
3.2. 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õ.
4. Ví dụ triển khai
4.1. Ví dụ tên tiếng Việt
Nguồn HIS:
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.
4.2. Ví dụ tên hộ chiếu
Nguồn hộ chiếu:
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ộ.
5. Liên hệ với các trang khác
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, especially for official Vietnamese names and passport-based foreign names. Unicode normalization such as NFC is recommended for internal indexing, but not as a replacement for the stored canonical value. Accent-insensitive or fuzzy search is considered a local enhancement rather than a baseline conformance requirement, and should be disclosed explicitly if supported.
