# Tuân thủ theo vai trò triển khai - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Tuân thủ theo vai trò triển khai

# Tuân thủ theo vai trò triển khai — Conformance by Actor

Mỗi vai trò triển khai có package tối thiểu, CapabilityStatement, ngưỡng kỹ thuật và dấu hiệu sẵn sàng riêng.

Nếu cần lớp tự kiểm tra ngắn hơn, xem [Checklist sẵn sàng thí điểm theo vai trò](pilot-readiness-checklists.md).

## Quy tắc đọc trang này

* `Profile` không đủ để chứng minh tuân thủ nếu thiếu `CapabilityStatement`, examples, search behavior và kiểm tra thực thi được.
* Một actor chỉ nên cam kết những gì đúng với phạm vi của mình; không phải mọi hệ thống đều phải hỗ trợ toàn bộ IG.

## Ma trận actor ở mức tóm tắt

| | | | |
| :--- | :--- | :--- | :--- |
| Kiến trúc tiêu chuẩn, quản trị dữ liệu | `hl7.fhir.vn.core` | [Kiến trúc gói phát hành](package-architecture.md),[Ổn định và tuân thủ](stability-and-conformance.md) | Boundary, vòng đời artifact, release governance |
| HIS, EMR, FHIR server nội bộ | `hl7.fhir.vn.core.base` | `VNCoreServer`,`VNCoreEMRServer` | FHIR-native exchange, search, validation, Must Support |
| Client gửi hồ sơ thanh toán BHYT | `hl7.fhir.vn.core.base`+`hl7.fhir.vn.bhyt.submission` | `VNBHYTGatewayClient` | Bundle, operation, mapping hồ sơ thanh toán |
| Server tiếp nhận hồ sơ BHYT / facade tích hợp | `hl7.fhir.vn.bhyt.submission` | `VNBHYTGatewayServer` | Kiểm tra bundle, phản hồi lỗi, audit và logging |
| Ứng dụng người dân / cổng bệnh nhân | `hl7.fhir.vn.core.base` | `VNCitizenAppClient` | Minimal read scope, consent, audit, provenance |
| LIS / hệ thống xét nghiệm | `hl7.fhir.vn.core.base` | Local LIS capability profile | Specimen, DiagnosticReportLab, ObservationLab |
| RIS/PACS / hệ thống CĐHA | `hl7.fhir.vn.core.base` | Local RIS capability profile | ImagingStudy, DiagnosticReportImaging, DICOM metadata |
| Terminology, định danh, dữ liệu chủ | `hl7.fhir.vn.core.base` | [Danh mục định danh](identifier-registry.md),[Hướng dẫn thuật ngữ](terminology-guidance.md) | `NamingSystem`,`CodeSystem`,`ValueSet`, provenance |
| QA, reviewer cộng đồng, nhóm maturity | Toàn bộ release trong phạm vi đánh giá | Validation scripts, implementation reports | Repeatable checks, release quality, pilot readiness |

## Actor 1: Kiến trúc tiêu chuẩn, quản trị dữ liệu

### Kiến trúc — Tài liệu

| | | | | | |
| :--- | :--- | :--- | :--- | :--- | :--- |
| [Trang chủ](index.md) | [Kiến trúc gói phát hành](package-architecture.md) | [Ổn định và tuân thủ](stability-and-conformance.md) | [Phát hành và quản trị](release-governance.md) | [Danh mục định danh](identifier-registry.md) | [Hướng dẫn thuật ngữ](terminology-guidance.md) |

### Kiến trúc — Ngưỡng tối thiểu

* Chốt rõ actor nào tiêu thụ package nào; không để logic payer-facing quay lại thay đổi semantic lõi FHIR.
* Có policy `hiện hành / lịch sử / ngừng dùng` cho định danh và thuật ngữ.
* Xác định release nào đủ điều kiện pilot và release nào chỉ review nội bộ.

### Kiến trúc — Bằng chứng sẵn sàng

* Ma trận actor/package cho hệ thống triển khai, policy canonical URL/versioning, và release threshold theo [Phát hành và quản trị](release-governance.md).

## Actor 2: HIS, EMR và FHIR server nội bộ

### HIS/EMR — Tài liệu

| | | | | | | |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| `hl7.fhir.vn.core.base` | `VNCoreServer`/`VNCoreEMRServer` | [Bắt đầu nhanh](getting-started.md) | [Hướng dẫn chung](general-guidance.md) | [Must Support](must-support-guidance.md) | [Tìm kiếm](search-behavior.md) | [Validation](validation-guidance.md) |

### HIS/EMR — Ngưỡng tối thiểu

* Đọc/ghi đúng các profile lõi; hỗ trợ `token`, `string`, `date`, `reference` search.
* Xử lý `Identifier` theo `system URI`; tôn trọng `Must Support` và `Data Absent Reason`.
* SHOULD SUPPORT [VNCoreOrganizationDepartment](StructureDefinition-vn-core-organization-department.md) khi hệ thống quản lý khoa/phòng, chuyển khoa hoặc phân bổ chi phí theo `MA_KHOA`.
* SHALL hỗ trợ [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) nếu EMR ghi nhận cấp phát thuốc nội trú/ngoại trú.
* SHOULD hỗ trợ [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) nếu có tích hợp RIS/PACS.
* SHALL dùng các sub-profile [VNCoreDiagnosticReportLab](StructureDefinition-vn-core-diagnostic-report-lab.md), [VNCoreDiagnosticReportImaging](StructureDefinition-vn-core-diagnostic-report-imaging.md), [VNCoreDiagnosticReportPathology](StructureDefinition-vn-core-diagnostic-report-pathology.md) cho báo cáo theo lĩnh vực, thay vì chỉ trao đổi [VNCoreDiagnosticReport](StructureDefinition-vn-core-diagnostic-report.md) chung.

### HIS/EMR — Bằng chứng sẵn sàng

* Examples pass `./scripts/validate.sh` và `validate-tier2.sh`; có `CapabilityStatement` nội bộ đối chiếu với `VNCoreServer`/`VNCoreEMRServer`.

## Actor 3: Client gửi hồ sơ thanh toán BHYT

### Client BHYT — Tài liệu

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| `hl7.fhir.vn.core.base`+`hl7.fhir.vn.bhyt.submission` | `VNBHYTGatewayClient` | [Liên thông BHYT](bhyt-submission.md) | [Danh mục định danh](identifier-registry.md) | [Validation](validation-guidance.md) |

### Client BHYT — Ngưỡng tối thiểu

* Sinh đúng `VNCoreBHYTSubmissionBundle`; nhất quán giữa `Coverage`, `Claim`, `Encounter`, `Patient`.
* Không đẩy ngược logic export/gateway vào profile lõi.
* SHALL hỗ trợ [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) khi hồ sơ có dữ liệu cấp phát thuốc phục vụ mapping `MA_THUOC`, `SO_DANG_KY`, `NGAY_CAP` trong chuỗi XML thuốc/DVKT.
* MAY gửi/nhận [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) khi cần bổ sung metadata CĐHA cho XML4 hoặc đối soát chi phí nhóm CĐHA.

### Client BHYT — Bằng chứng sẵn sàng

* Pass `validate-bhyt-submission.sh` và `validate-bhyt-roundtrip.sh`; có bộ positive/negative fixtures.

## Actor 4: Server tiếp nhận hồ sơ BHYT / facade tích hợp

### Server BHYT — Tài liệu

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| `hl7.fhir.vn.bhyt.submission` | `VNBHYTGatewayServer` | [Liên thông BHYT](bhyt-submission.md) | [Kiến trúc gói](package-architecture.md) | [Bảo mật](security.md) |

### Server BHYT — Ngưỡng tối thiểu

* Kiểm tra bundle theo policy submission; phân biệt lỗi cú pháp / ngữ nghĩa / nghiệp vụ.
* Ghi `AuditEvent` và `Provenance` phù hợp vai trò gateway.
* SHALL chấp nhận và validate [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) khi bundle khai báo dữ liệu cấp phát thuốc.
* MAY chấp nhận [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) nếu gateway hoặc facade hỗ trợ đối soát CĐHA giàu metadata hơn `DiagnosticReport` đơn lẻ.

### Server BHYT — Bằng chứng sẵn sàng

* Operation có đầu vào/đầu ra/mã lỗi kiểm thử được; có logging, audit, tracing đủ truy vết; có giới hạn trách nhiệm rõ giữa gateway và hệ thống nguồn.

## Actor 5: LIS / hệ thống xét nghiệm

### LIS — Tài liệu

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| `hl7.fhir.vn.core.base` | [VNCoreSpecimen](StructureDefinition-vn-core-specimen.md) | [VNCoreObservationLab](StructureDefinition-vn-core-observation-lab.md) | [VNCoreDiagnosticReportLab](StructureDefinition-vn-core-diagnostic-report-lab.md) | [Validation](validation-guidance.md) |

### LIS — Ngưỡng tối thiểu

* SHALL hỗ trợ [VNCoreSpecimen](StructureDefinition-vn-core-specimen.md) cho mẫu bệnh phẩm và accession/lifecycle mẫu.
* SHALL hỗ trợ [VNCoreDiagnosticReportLab](StructureDefinition-vn-core-diagnostic-report-lab.md) cho báo cáo xét nghiệm tổng hợp.
* SHOULD liên kết kết quả chi tiết qua [VNCoreObservationLab](StructureDefinition-vn-core-observation-lab.md) thay vì chỉ gửi kết luận text.

### LIS — Bằng chứng sẵn sàng

* Có fixtures order/result đi qua `ServiceRequest` → `Specimen` → `ObservationLab` → `DiagnosticReportLab`, pass validation và giữ được mã xét nghiệm LOINC/CLS theo policy terminology.

## Actor 6: RIS/PACS / hệ thống CĐHA

### RIS/PACS — Tài liệu

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| `hl7.fhir.vn.core.base` | [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) | [VNCoreDiagnosticReportImaging](StructureDefinition-vn-core-diagnostic-report-imaging.md) | [Clinical Scenarios](clinical-scenarios.md) | [Validation](validation-guidance.md) |

### RIS/PACS — Ngưỡng tối thiểu

* SHALL hỗ trợ [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) cho DICOM `StudyInstanceUID`, accession, modality và thông tin thực hiện chụp.
* SHALL hỗ trợ [VNCoreDiagnosticReportImaging](StructureDefinition-vn-core-diagnostic-report-imaging.md) cho báo cáo đọc phim, `resultsInterpreter`, `imagingStudy` reference và `presentedForm`.

### RIS/PACS — Bằng chứng sẵn sàng

* Có fixtures CĐHA chứng minh `ServiceRequest` → `ImagingStudy` → `DiagnosticReportImaging`, bao gồm ít nhất một modality `CT` hoặc `US` và PDF kết quả.

## Actor 7: Ứng dụng người dân, cổng bệnh nhân, tích hợp VNeID

### Citizen App — Tài liệu

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| `hl7.fhir.vn.core.base` | `VNCitizenAppClient` | [Bảo mật](security.md) | [Hướng dẫn chung](general-guidance.md) | [Hồ sơ](profiles.md) |

### Citizen App — Ngưỡng tối thiểu

* Chỉ truy cập đúng tập dữ liệu đã công bố; tách quyền người dùng cuối / tài khoản dịch vụ / `break-glass`.
* Không mô tả `VNeID` như patient identifier lõi song song với `CCCD`.

### Citizen App — Bằng chứng sẵn sàng

* Ma trận quyền truy cập tối thiểu; luồng chứng minh `Consent`, `AuditEvent`, `Provenance` hoạt động đúng.

## Actor 8: Terminology, định danh và dữ liệu chủ

### Terminology — Tài liệu

| | | | |
| :--- | :--- | :--- | :--- |
| [Danh mục định danh](identifier-registry.md) | [Hướng dẫn thuật ngữ](terminology-guidance.md) | [Thuật ngữ](terminology.md) | [Phát hành và quản trị](release-governance.md) |

### Terminology — Ngưỡng tối thiểu

* Duy trì trạng thái `hiện hành / lịch sử / ngừng dùng` nhất quán; ghi rõ provenance và căn cứ pháp lý khi thay đổi.
* Ưu tiên `LOINC`, `SNOMED CT`, `ICD` trước khi tạo mã địa phương mới.

### Terminology — Bằng chứng sẵn sàng

* Registry nhất quán cho `NamingSystem`/`CodeSystem`/`ValueSet`; có snapshot khác biệt trước mỗi đợt cập nhật.

## Actor 9: QA, reviewer cộng đồng, nhóm maturity

### QA — Tài liệu

| | | |
| :--- | :--- | :--- |
| [Ổn định và tuân thủ](stability-and-conformance.md) | [Validation](validation-guidance.md) | [Phát hành và quản trị](release-governance.md) |

### QA — Ngưỡng tối thiểu

* Checklist lặp lại được cho từng actor; phân biệt lỗi nội dung / package / guidance / môi trường.

### QA — Bằng chứng sẵn sàng

* Script kiểm tra mức cơ sở xanh trên bản phát hành mục tiêu; có ít nhất một implementation report; có release note giải thích breaking changes.

## Nếu một hệ thống đóng nhiều vai trò

Nhiều hệ thống ở Việt Nam vừa là EMR server, vừa là client BHYT, đôi khi kiêm cổng bệnh nhân. Khuyến nghị:

* Không dùng một `CapabilityStatement` duy nhất cho mọi vai trò.
* Không trộn ràng buộc `BHYT Submission` vào profile lõi nếu chúng chỉ đúng cho một luồng.
* Tách đánh giá theo actor trước, sau đó mới lập ma trận tích hợp tổng thể.

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

| | |
| :--- | :--- |
| Biết package nào tương ứng với từng actor | [Kiến trúc gói phát hành](package-architecture.md) |
| Tự kiểm tra nhanh mức sẵn sàng thí điểm | [Checklist sẵn sàng thí điểm theo vai trò](pilot-readiness-checklists.md) |
| Biết cách diễn giải nghĩa vụ đọc/ghi ở cấp element | [Hướng dẫn Must Support](must-support-guidance.md) |
| Biết cách kiểm tra hệ thống trước pilot | [Hướng dẫn kiểm tra hợp lệ](validation-guidance.md) |

## English Summary

This page organizes VN Core conformance by implementation actor. For each actor, it states the minimum package scope, the relevant `CapabilityStatement` or registry, the minimum obligations that must be supported, and the evidence that should exist before the actor is considered pilot-ready. The page is intended to prevent implementers from inferring conformance from profiles alone.

