Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.9.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

SMART on FHIR — nghĩa vụ và scope

SMART on FHIR — nghĩa vụ theo vai trò và ma trận scope

Các CapabilityStatement của VN Core công bố SMART-on-FHIR làm dịch vụ bảo mật tối thiểu. Trang này mô tả nghĩa vụ của từng vai trò khi triển khai theo khai báo đó, và cách gắn phạm vi truy cập (scope) với nghĩa vụ pháp lý Việt Nam.

Ranh giới của trang này

VN Core không vận hành máy chủ ủy quyền, không cấp phát scope, không định nghĩa scope mới, và không chứng nhận một triển khai nào là tuân thủ SMART. Khai báo rest.security.service = SMART-on-FHIR trong CapabilityStatement là yêu cầu đặt ra cho bên triển khai, không phải tuyên bố rằng có một máy chủ sẵn sàng.

Mọi triển khai phải tự công bố authorization server metadata, danh sách scope thực tế, audience, launch context và quy tắc truy cập theo từng use case. Tuân thủ SMART không tự chứng minh tuân thủ Luật 91/2025/QH15 — hai việc kiểm tra khác nhau, xem Bảo mật và quyền riêng tư.

Bốn vai trò trong một luồng SMART

Vai trò	Ai đảm nhận trong bối cảnh Việt Nam	Nghĩa vụ cốt lõi
Resource server	Máy chủ FHIR của cơ sở khám bệnh, chữa bệnh (VNCoreEMRServer), cổng dữ liệu bảo hiểm y tế (VNBHYTGatewayServer)	Từ chối yêu cầu vượt scope; ghi AuditEvent cho mọi truy cập hồ sơ; không dựa vào ứng dụng để tự giới hạn phạm vi
Authorization server	Hệ thống định danh của cơ sở, hoặc nhà cung cấp định danh dùng chung	Cấp token đúng phạm vi đã đồng ý; gắn được token với chủ thể dữ liệu và với căn cứ xử lý; thu hồi được token
Ứng dụng khách	Phần mềm lâm sàng nội bộ, ứng dụng người dân, connector VNeID (VNCitizenAppClient), phần mềm cơ sở gửi hồ sơ (VNBHYTGatewayClient)	Chỉ xin scope cần cho chức năng đang chạy; không lưu dữ liệu vượt mục đích đã khai; xử lý được trường hợp bị từ chối scope
Người dùng cuối	Người hành nghề, người bệnh, người đại diện	Ngoài phạm vi kỹ thuật của IG; nghĩa vụ thuộc chính sách nội bộ của cơ sở

Điểm hay bị bỏ sót: scope không phải là căn cứ xử lý dữ liệu. Một token hợp lệ chứng minh ứng dụng được phép gọi API, không chứng minh việc xử lý dữ liệu có căn cứ theo Luật 91/2025/QH15 Điều 19. Hai lớp này phải tồn tại song song — xem VNProcessingLegalBasisCS và VNCoreAuditEventLegalBasisDecision.

Ma trận scope theo use case

Bảng dưới là điểm khởi đầu để thu hẹp, không phải danh sách để sao chép nguyên. Nguyên tắc: mỗi chức năng xin scope hẹp nhất chạy được, không xin * cho tiện.

Use case	Kiểu launch	Scope khởi điểm	Ghi chú thu hẹp
Bác sĩ mở hồ sơ trong lượt khám đang xử lý	user + launch (có launch/patient, launch/encounter)	openid, fhirUser, user/Patient.read, user/Encounter.read, user/Condition.read, user/Observation.read, user/MedicationRequest.read	Ràng buộc thêm theo lượt khám ở tầng policy: token cấp user/*.read vẫn phải bị resource server chặn nếu người bệnh không thuộc phạm vi điều trị
Kê đơn thuốc điện tử	user + launch	thêm user/MedicationRequest.write, user/Medication.read	Không kèm user/Patient.write: kê đơn không sửa hồ sơ nhân khẩu
Điều phối chuyển tuyến và cấp phát thuốc	user hoặc system	user/ServiceRequest.read, user/Task.read, user/Task.write	Bên nhận chuyển tuyến chỉ cần Task và ServiceRequest, không cần toàn bộ hồ sơ trước khi tiếp nhận
Đặt lịch khám qua cổng công khai	không cần token người bệnh cho bước tra cứu	Slot.read, Schedule.read ở mức ẩn danh	Slot không chứa dữ liệu người bệnh nên tra cứu lịch trống không cần token cá nhân. Bước đặt lịch mới cần patient/Appointment.write
Ứng dụng người dân xem hồ sơ của mình	patient	openid, fhirUser, launch/patient, patient/Patient.read, patient/Condition.read, patient/Observation.read, patient/DocumentReference.read, patient/Coverage.read, patient/AuditEvent.read	patient/AuditEvent.read phục vụ quyền được biết ai đã truy cập dữ liệu của mình — nên có, không nên bỏ
Người đại diện, người giám hộ xem hồ sơ	patient	như trên, cộng patient/RelatedPerson.read	Quan hệ đại diện phải được kiểm ở tầng policy, không suy ra từ scope. Dữ liệu thuộc nhóm #special-protection cần chặn riêng kể cả với đại diện
Người bệnh cấp và rút đồng ý	patient	patient/Consent.read, patient/Consent.write	Rút đồng ý phải khả dụng ngang với cấp đồng ý; không thiết kế luồng chỉ cho phép cấp
Cơ sở gửi hồ sơ bảo hiểm y tế	system (client credentials)	system/Bundle.create, system/Claim.create, system/Claim.read, system/Coverage.read	Không cấp system/Patient.* rộng: cổng giám định xử lý theo hồ sơ, không duyệt toàn bộ danh sách người bệnh
Kho dữ liệu rút trích theo lô	system	xem Bulk Data	Rút trích lô có nghĩa vụ riêng, nặng hơn truy cập lẻ

Launch context cần trong bối cảnh Việt Nam

Ngoài launch/patient và launch/encounter chuẩn của SMART, triển khai tại Việt Nam thường cần thêm ngữ cảnh cơ sở khám bệnh, chữa bệnh để phân biệt quyền của cùng một người hành nghề khi làm việc tại nhiều cơ sở. FHIR không chuẩn hóa ngữ cảnh này; nếu dùng, hãy khai trong tài liệu triển khai và giữ nhất quán giữa các ứng dụng của cùng một cơ sở, đừng phát minh biến thể riêng cho từng ứng dụng.

Gắn scope với nghĩa vụ pháp lý

Nghĩa vụ	Điều khoản	Hệ quả với thiết kế scope
Xử lý đúng mục đích đã thông báo	Luật 91/2025/QH15 Điều 9, Điều 19	Một ứng dụng nhiều chức năng nên xin scope theo từng chức năng, không xin gộp một lần cho mọi tình huống
Quyền được biết ai đã truy cập	Luật 91/2025/QH15 Chương II	Cấp patient/AuditEvent.read cho ứng dụng người dân, và ghi AuditEvent đủ chi tiết để trả lời
Dữ liệu sức khỏe là dữ liệu cá nhân nhạy cảm	Luật 91/2025/QH15; NĐ 356/2025/NĐ-CP	Scope rộng dạng user/*.* với dữ liệu lâm sàng cần lý do vận hành rõ ràng, ghi trong hồ sơ xử lý
Bảo mật thông tin trong hồ sơ bệnh án	Luật 15/2023/QH15 Điều 69	Truy cập của người hành nghề phải gắn với quan hệ điều trị, kiểm ở tầng policy chứ không chỉ ở scope
Truy cập khẩn cấp vượt quyền	Luật 91/2025/QH15 Điều 19 khoản 1 điểm a	Break-glass là quyết định policy có AuditEvent riêng, không phải một scope đặc biệt — xem Bảo mật

Kiểm tra trước khi công bố một triển khai

1. Đã công bố authorization server metadata tại .well-known/smart-configuration chưa?
2. Danh sách scope thực tế có khớp với chức năng đang chạy, hay còn scope thừa từ giai đoạn phát triển?
3. Resource server có tự kiểm phạm vi, hay đang tin vào ứng dụng khách?
4. Có ghi AuditEvent cho truy cập đọc, không chỉ cho ghi và sửa?
5. Người bệnh rút đồng ý thì token đang phát hành có bị thu hồi không, hay chỉ chặn ở lần cấp sau?

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

Nếu cần	Nên đọc tiếp
Căn cứ xử lý, consent, kiểm toán truy cập, break-glass	Bảo mật và quyền riêng tư
Nghĩa vụ theo vai trò triển khai	Tuân thủ theo vai trò triển khai
Rút trích dữ liệu theo lô	Rút trích dữ liệu theo lô
Mức xử lý dữ liệu và nhãn phân loại	Khử định danh và dữ liệu dùng cho AI

English Summary

VN Core CapabilityStatements declare SMART-on-FHIR as the minimum security service. That is an obligation placed on implementers, not a claim that a server exists — this IG operates no authorization server and mints no scopes. The page maps four SMART roles to Vietnamese deployment actors, gives a starting scope matrix per use case (to be narrowed, never copied wholesale), and ties scopes to duties under Law 91/2025/QH15 and Law 15/2023/QH15. Key point: a valid token proves API authorization, never a lawful basis for processing — those are two independent layers.