# 04 — Hướng dẫn sử dụng chi tiết theo từng vai trò

## Những điểm cần biết trong 0.2.30-r2

Ứng dụng là **0.2.30**; **r2** là revision bộ cài sửa quyền đọc mã chương trình trong image NAS. Tài liệu chốt ngày **30/09/2026**. NAS hiện tại đã cập nhật và đăng nhập bình thường; nhận tài liệu này không cần chạy cập nhật lại.

- Danh sách bệnh nhân lấy dữ liệu từ server, **25 hồ sơ mỗi trang**. Xem tổng số hồ sơ, dùng nút trang trước/trang sau; không kết luận bệnh nhân không tồn tại chỉ vì chưa thấy ở trang hiện tại. Tìm kiếm, lọc và sắp xếp áp dụng trên toàn bộ phạm vi được phép. Các số ca/cần bổ sung trong trang phản ánh trang hiện tại; tổng hồ sơ phản ánh kết quả tìm/lọc.
- Khi chọn đồng thời Bác sĩ và Dịch vụ, kết quả phải có **cùng một ca điều trị** thỏa cả hai điều kiện. Muốn tìm ca khác, điều chỉnh bộ lọc thay vì mở rộng quyền tài khoản.
- Back/Forward khôi phục hồ sơ đã mở kể cả khi hồ sơ không ở trang danh sách hiện tại; quyền truy cập vẫn được kiểm lại.
- Xóa ca điều trị sẽ thu hồi các link chia sẻ của ca. **Khôi phục ca không phục hồi link cũ**; người có quyền phải tạo link mới và gửi lại cho người nhận được phép.
- Nếu đăng nhập báo quá nhiều yêu cầu, chờ rồi thử lại; không bấm liên tục hoặc mở nhiều phiên đăng nhập cùng lúc.
- Trong Cài đặt, tiêu đề các khối không còn icon đứng trước. Icon trên menu và các nút vẫn được giữ. Các quyền nghiệp vụ của ADMIN, DOCTOR, LABO không đổi.

Ảnh trong PDF được chụp lại từ frontend build 0.2.30 ngày 30/09/2026, API mô phỏng và dữ liệu giả. Ảnh minh họa cách thao tác; không chứng nhận ghi dữ liệu, authorization hay UAT trên NAS.

## 1. Mục đích và cách dùng tài liệu

Tài liệu này dành cho người dùng **NCV DCIMS — NCV Dental Clinical Image Management System** phiên bản 0.2.30. Nội dung được chia độc lập theo ba vai trò ADMIN, DOCTOR và LABO để mỗi người có thể đọc đúng phần công việc của mình.

Quyền thực tế không chỉ phụ thuộc tên vai trò. Một thao tác chỉ được phép khi tài khoản đang hoạt động, có permission phù hợp, thuộc data scope, đúng quan hệ bệnh nhân/ca/phiên và đúng field policy. Giao diện ẩn nút chỉ là hỗ trợ trải nghiệm; backend mới là ranh giới bảo mật.

### 1.1 Ma trận thao tác nhanh

| Chức năng | ADMIN | DOCTOR | LABO |
|---|:---:|:---:|:---:|
| Xem Dashboard | Có theo scope | Có theo scope | Có theo scope |
| Tìm/xem bệnh nhân | Có theo scope | Own/assigned/branch | Có, dữ liệu giảm trường |
| Tạo/cập nhật bệnh nhân | Có | Có theo scope | Không |
| Tạo ca/lần tái khám | Có | Có theo scope | Không |
| Upload ảnh/phim | Có | Có theo scope | Chỉ nhóm Labo được cấp |
| Upload/xóa/khôi phục hợp đồng | Có | Có theo scope | Không |
| Xem hợp đồng | Có theo scope | Có theo scope | Preview theo scope |
| Tải original hợp đồng | Có | Có | Không |
| Xác nhận/mở lại bộ ảnh | Có | Có theo scope | Không |
| Chia sẻ preview cho khách hàng | Có | Có theo scope | Không |
| Tạo/cập nhật bảo hành | Có | Có | Có theo quan hệ ca |
| Lưu trữ bảo hành | Có | Có theo scope | Không |
| Quản lý cơ sở/tài khoản/API Client | Có đủ quyền | Không | Không |
| Xem audit/vận hành storage | Có permission riêng | Không mặc định | Không |

### 1.2 Các trạng thái cần hiểu

- **DRAFT**: phiên đang soạn; được upload, thay thế hoặc xóa mềm khi có quyền.
- **VALIDATING/PROCESSING/COMMITTING**: tệp đang được hệ thống kiểm tra; chưa tính là hợp lệ.
- **VALID**: tệp đã hợp lệ và có thể dùng trong tổng quan/xác nhận.
- **REJECTED**: tệp không vượt kiểm tra; phải sửa file gốc rồi tải lại.
- **RECOVERY_REQUIRED**: xử lý dở dang cần hệ thống thử lại hoặc quản trị kiểm tra.
- **CONFIRMED**: phiên đã xác nhận; khóa các thay đổi thông thường.
- **REOPENED**: phiên đã mở lại có lý do; được tiếp tục cập nhật.
- **ARCHIVED/DELETED**: dữ liệu đã rời danh sách làm việc nhưng chưa mặc nhiên bị xóa vật lý.

## 2. Thao tác chung cho mọi vai trò

Tên tab trình duyệt của bản 0.2.30 là **DCIMS - Nụ Cười Việt**. Mỗi người dùng tài khoản riêng. Ảnh trong tài liệu chụp từ giao diện 0.2.30 với API mô phỏng và dữ liệu giả, không phải dữ liệu bệnh nhân hay bằng chứng nghiệm thu NAS.


### 2.1 Đăng nhập và phiên làm việc

1. Mở đúng địa chỉ HTTPS do quản trị viên cung cấp.
2. Nhập username và mật khẩu; không dùng tài khoản của người khác.
3. Có thể nhấn biểu tượng mắt để kiểm tra nội dung vừa nhập; nhấn lại để che mật khẩu trước khi người khác nhìn màn hình.
4. Nếu hệ thống yêu cầu đổi mật khẩu, đặt mật khẩu mới trước khi tiếp tục.
5. Khi rời máy, dùng menu tài khoản để đăng xuất; không chỉ đóng tab trình duyệt.
6. Nếu tài khoản bị khóa, đổi vai trò/cơ sở hoặc bị xóa, các phiên đang mở có thể bị thu hồi và trở về màn hình đăng nhập.

Không lưu mật khẩu vào tài liệu, ảnh chụp hoặc trình nhắn tin. Không gửi cookie, token, secret API hoặc URL chia sẻ còn hiệu lực cho người không được phép.

### 2.2 Điều hướng và responsive

- Desktop/tablet ngang dùng menu trái; tablet dọc/điện thoại dùng menu mở từ nút hamburger.
- Điện thoại ngang có vùng cuộn menu riêng; cuộn trong menu để thấy đủ mục.
- Dùng **Tổng quan** cho công việc gần đây, **Bệnh nhân** cho hồ sơ/ca, **Hồ sơ đã xóa gần đây** cho dữ liệu có thể khôi phục và **Cài đặt** cho chức năng quản trị.
- Có thể dùng Back/Forward hoặc vuốt lùi/tiến của trình duyệt để trở lại lần lượt menu, hồ sơ, ca/lần khám hoặc tab Cài đặt đã mở trước đó; mỗi thao tác chỉ lùi hoặc tiến một bước trong lịch sử nội bộ.
- Khi quay về entry trước, sidebar, menu tài khoản hoặc popup tạm đang mở sẽ đóng để tránh che màn hình đích.
- Popup đóng bằng X, phím Esc hoặc click vùng nền. Nếu popup lồng nhau, mỗi lần chỉ đóng lớp trên cùng.
- Khi upload/ghi dữ liệu đang chạy, không refresh hoặc đóng popup bằng cách cưỡng ép; chờ kết quả hoặc dùng nút hủy nếu có.

### 2.3 Tìm kiếm bệnh nhân an toàn

1. Tìm bằng họ tên trước khi tạo hồ sơ mới.
2. ADMIN/DOCTOR có quyền cập nhật có thể tìm bằng số điện thoại; tài khoản chỉ có quyền xem không được dùng số điện thoại để dò hồ sơ.
3. Kiểm tra ngày sinh/cơ sở và cảnh báo ứng viên trùng.
4. Không tự gộp hai hồ sơ chỉ vì trùng tên hoặc số điện thoại; chuyển ADMIN xử lý nếu chưa chắc chắn.
5. Kết quả ngoài data scope sẽ không xuất hiện; việc không tìm thấy không chứng minh hồ sơ không tồn tại trong toàn hệ thống.

### 2.4 Upload ảnh, phim và hợp đồng

1. Mở đúng bệnh nhân, ca và lần khám.
2. Chọn đúng ô checklist trước khi chọn file.
3. Ảnh/avatar chỉ dùng JPEG hoặc PNG tối đa 10 MiB.
4. Hợp đồng dùng JPEG/PNG tối đa 10 MiB hoặc PDF tối đa 5 MiB.
5. Kiểm tra tên nhóm và số thứ tự trước khi tải lên; không đưa PII vào tên file vật lý.
6. Chờ trạng thái chuyển sang hợp lệ. Response upload thành công ban đầu chỉ có nghĩa file đã vào vùng kiểm tra, chưa có nghĩa đã VALID.
7. Nếu bị từ chối, xem thông báo, sửa file nguồn và tải lại. Không đổi phần mở rộng để giả định dạng.

Runtime production không có malware scanner. Việc file vượt MIME/signature/decode không phải chứng nhận file sạch mã độc; chỉ nhận file từ nguồn công việc được kiểm soát.

### 2.5 Báo sự cố

Ghi thời điểm, tài khoản/vai trò, màn hình, bước tái hiện, request ID và thông báo lỗi. Không đính kèm full hợp đồng, original bệnh nhân, secret hoặc storage path vào kênh hỗ trợ không được duyệt.

## 3. Hướng dẫn chi tiết cho ADMIN

### 3.1 Phạm vi và trách nhiệm

ADMIN quản trị cơ sở, tài khoản, API Client và có thể thực hiện nghiệp vụ lâm sàng khi permission/scope cho phép. ADMIN không mặc nhiên vượt data scope; tài khoản thiếu `ALL_BRANCHES` vẫn bị giới hạn. ADMIN chịu trách nhiệm bảo vệ tài khoản hệ thống, secret, backup và cấu hình tích hợp.

### 3.2 Thiết lập lần đầu

1. Đăng nhập bằng tài khoản bootstrap và đổi mật khẩu tạm ngay.
2. Vào **Cài đặt → Cơ sở**, tạo hoặc kiểm tra từng cơ sở theo tên, mã và địa chỉ.
3. Vào **Cài đặt → Tài khoản**, tạo tài khoản ADMIN/DOCTOR/LABO bằng dữ liệu thật của nhân viên nhưng không đưa mật khẩu vào file bàn giao.
4. DOCTOR bắt buộc có một cơ sở chính đang hoạt động; ADMIN và LABO dùng phạm vi toàn hệ thống và không chọn cơ sở chính.
5. Cấp mật khẩu tạm; bàn giao qua kênh an toàn và yêu cầu đổi ở lần đăng nhập đầu.
6. Kiểm tra **Mẫu checklist** để xác nhận đúng loại dịch vụ/version đang hoạt động; không sửa template cũ đã có ca sử dụng.
7. Giữ External API tắt cho tới khi hoàn thành TEST/UAT, IP allowlist, quyền hợp đồng và bàn giao credential.

### 3.3 Quản lý cơ sở

1. Mở **Cài đặt → Cơ sở**.
2. Tìm theo tên, mã hoặc địa chỉ để tránh tạo trùng.
3. Tạo cơ sở mới và kiểm tra trạng thái hoạt động.
4. Dùng **Chỉnh sửa** để cập nhật thông tin cho phép.
5. Dùng **Ngừng hoạt động** khi cơ sở không còn nhận hồ sơ mới; không xóa dữ liệu lịch sử của cơ sở.
6. Trước khi ngừng hoạt động, kiểm tra tài khoản DOCTOR, bệnh nhân và ca đang gắn với cơ sở để có kế hoạch chuyển giao.
7. Đọc số liệu trên thẻ cơ sở theo quy tắc: bệnh nhân chỉ tính hồ sơ ACTIVE chưa xóa; ca loại ca đã xóa/lưu trữ và ca của bệnh nhân không còn hoạt động. Ca COMPLETED chưa lưu trữ vẫn được tính.

Nếu nút Ngừng hoạt động không xuất hiện, kiểm tra quyền `branch.manage`, trạng thái cơ sở và kích thước màn hình; backend vẫn quyết định cuối cùng.

### 3.4 Tạo và quản lý tài khoản

1. Mở **Cài đặt → Tài khoản** và tìm username/họ tên trước khi tạo.
2. Chọn đúng vai trò; với DOCTOR chọn cơ sở chính đang hoạt động.
3. Sau khi tạo, ghi nhận username và trạng thái buộc đổi mật khẩu; không lưu mật khẩu tạm trong tài liệu.
4. **Chỉnh sửa tài khoản** cập nhật họ tên, vai trò và cơ sở trong một thao tác. Đổi vai trò/cơ sở sẽ thu hồi session cũ; chỉ đổi họ tên không nhất thiết làm gián đoạn phiên.
5. **Cấp mật khẩu** tạo mật khẩu tạm mới, hiển thị một lần; đóng popup sẽ không xem lại được.
6. **Khóa** dùng khi cần dừng truy cập nhưng vẫn giữ tài khoản và lịch sử. Các session bị thu hồi.
7. **Mở khóa** chỉ thực hiện sau khi xác minh người dùng và nguyên nhân khóa.
8. **Xóa** là thao tác không có thùng rác tài khoản; tài khoản bị vô danh hóa và không thể đăng nhập/khôi phục từ UI.

Hệ thống chặn tự sửa quyền nhạy cảm, tự khóa/xóa, xóa ADMIN hoạt động cuối cùng và khóa/xóa username chuẩn hóa `admin`. Không cố vượt các guard này bằng thao tác database thủ công.

### 3.5 Kiểm soát tài khoản định kỳ

- Hằng tuần kiểm tra tài khoản bị khóa, chờ đổi mật khẩu và nhân viên đã nghỉ/chuyển cơ sở.
- Xác minh mỗi DOCTOR có đúng cơ sở chính; ADMIN/LABO không mang branch ID sai.
- Không dùng một tài khoản chung cho nhiều người.
- Khi nhân viên nghỉ ngay lập tức, khóa trước; sau khi hoàn tất đối soát/audit mới cân nhắc xóa.
- Kiểm tra ít nhất một ADMIN dự phòng hợp lệ nhưng không tạo dư tài khoản toàn quyền.

### 3.6 Quản lý bệnh nhân và ca

ADMIN có thể thực hiện quy trình của DOCTOR nếu có quyền/scope. Khi tạo ca, ADMIN chọn bác sĩ đang hoạt động thuộc cơ sở bệnh nhân; không chọn nhân viên khác cơ sở chỉ để vượt data scope. Dùng lưu trữ/xóa mềm và khôi phục theo quy trình, không hard-delete dữ liệu lâm sàng.

### 3.7 Quản lý API Client

1. Mở **Cài đặt → Tích hợp API** khi có `api_client.manage`.
2. Tạo client với tên rõ ràng, IP allowlist tối thiểu và quyền cần thiết.
3. Quyền hợp đồng mặc định tắt; chỉ bật khi hệ thống ngoài thực sự cần danh sách/tải hợp đồng.
4. Sao chép Client ID và secret riêng từng trường. Secret chỉ hiển thị một lần.
5. Chuyển credential qua kênh bí mật; không chụp màn hình hoặc dán vào ticket.
6. Đổi IP hoặc quyền nhạy cảm sẽ thu hồi token cũ; thông báo cho đơn vị tích hợp.
7. Xem thống kê sử dụng, xoay secret hoặc thu hồi client khi có dấu hiệu bất thường.

IP allowlist có thể để trống theo giao diện hiện hành; khi trống, client không bị hạn chế bởi danh sách IP. Nếu backend tích hợp có IP cố định, nhập đúng IP để thu hẹp truy cập. External API chỉ trả preview ảnh theo quyền; original ảnh lâm sàng không public. Hợp đồng chỉ được tải khi client đã được bật quyền tương ứng và vượt đầy đủ relationship/scope check.

### 3.8 Khôi phục dữ liệu đã xóa

- Mở **Hồ sơ đã xóa gần đây** hoặc khu vực **Đã xóa gần đây** trong đúng ca/lần khám.
- Kiểm tra loại dữ liệu: hồ sơ, ca, avatar, ảnh lâm sàng hay hợp đồng.
- Xác minh đúng bệnh nhân/slot, ngày hết hạn và không có file current xung đột.
- Khôi phục chỉ trong 30 ngày và sau kiểm tra integrity; hết 30 ngày thì UI/backend từ chối kể cả purge chưa chạy.
- Không khôi phục chỉ để “xem thử”; thao tác phải có lý do nghiệp vụ rõ ràng.

### 3.9 Trách nhiệm vận hành và backup

- Snapshot/RAID không thay thế backup.
- Không bật purge khi offsite, backup policy, recovery key test, receipt và restore drill chưa đạt.
- Không public PostgreSQL, API nội bộ, original media, hợp đồng, backup hoặc đường dẫn NAS.
- Khi storage mount guard báo lỗi, không tạo thư mục giả để ép app chạy; kiểm tra shared folder mã hóa và mount thực.
- Cập nhật hệ thống bằng updater được cung cấp; không dùng `docker compose down -v`, **Clean** hoặc **Delete** project production.

### 3.10 Tình huống lỗi thường gặp của ADMIN

- **Không tạo được DOCTOR**: cơ sở chưa hoạt động, ngoài scope hoặc thiếu đủ `user.manage`/`role.manage`/`branch.manage`.
- **Không sửa/xóa được tài khoản**: đó là chính tài khoản đang đăng nhập, username `admin`, ADMIN cuối cùng hoặc target ngoài scope.
- **Session người dùng vẫn mở**: yêu cầu người dùng focus lại tab/chờ heartbeat; kiểm tra API health nếu quá thời gian.
- **Không thấy hồ sơ cần khôi phục**: đã quá 30 ngày, ngoài scope, patient cha đang archived hoặc dữ liệu đã purge.
- **API Client không kết nối**: feature flag tắt, IP không nằm allowlist đã cấu hình, credential/token hết hiệu lực hoặc quyền client không đủ.

### 3.11 Checklist bàn giao ADMIN

- Đổi mật khẩu bootstrap và bảo vệ tài khoản `admin`.
- Kiểm tra cơ sở, tài khoản và scope bằng dữ liệu thử.
- Test khóa/mở khóa, mật khẩu tạm và thu hồi session.
- Test chéo một hồ sơ khác cơ sở để xác nhận không rò dữ liệu.
- Kiểm tra backup/restore drill và người giữ recovery key.
- External API để tắt hoặc có hồ sơ UAT/allowlist/credential handover đầy đủ.
- Biết cách lấy request ID và báo sự cố mà không gửi dữ liệu nhạy cảm.

## 4. Hướng dẫn chi tiết cho DOCTOR

### 4.1 Phạm vi và trách nhiệm

DOCTOR làm việc với ca mình phụ trách, được phân công hoặc thuộc branch scope hiệu lực. Không thấy một bệnh nhân/ca có thể là do ngoài scope, assignment hết hạn hoặc hồ sơ đã lưu trữ; không yêu cầu ADMIN mở toàn hệ thống nếu không có nhu cầu nghiệp vụ.

### 4.2 Quy trình đầu ngày

1. Đăng nhập và kiểm tra thông báo bảo mật/upload nếu có.
2. Mở **Tổng quan** để xem bộ ảnh chưa hoàn tất và bệnh nhân mới cập nhật trong scope.
3. Vào **Bệnh nhân**, tìm hồ sơ trước khi tạo mới.
4. Kiểm tra các ca/lần khám cần xử lý, đặc biệt file đang pending/rejected.
5. Chỉ mở link chia sẻ hoặc hợp đồng từ chính NCV DCIMS; không dùng bản tải về cũ làm dữ liệu authoritative.

### 4.3 Tạo hồ sơ bệnh nhân

1. Tìm bằng tên và số điện thoại theo quyền để tránh trùng.
2. Chọn **Thêm bệnh nhân**.
3. Nhập họ tên, số điện thoại, ngày sinh, địa chỉ và cơ sở tiếp nhận.
4. Kiểm tra cảnh báo ứng viên trùng; nếu chưa chắc, hủy tạo và đối soát với ADMIN.
5. Lưu hồ sơ, sau đó tải ảnh nhận diện bằng bước riêng.
6. Nếu hồ sơ lưu thành công nhưng avatar lỗi, không tạo hồ sơ thứ hai; sửa/tải lại avatar trên hồ sơ đã có.

Số điện thoại không phải khóa duy nhất. Hai bệnh nhân có thể trùng số điện thoại; người dùng phải đối soát bằng nhiều trường.

### 4.4 Cập nhật hồ sơ và avatar

1. Mở hồ sơ và chọn **Sửa thông tin**.
2. Cập nhật các trường được phép, kiểm tra cơ sở và lưu.
3. Nếu hệ thống báo xung đột dữ liệu, tải lại hồ sơ rồi thực hiện lại; không ghi đè mù.
4. Avatar chỉ nhận JPEG/PNG tối đa 10 MiB. Khi thay avatar, ảnh cũ vẫn current cho tới khi ảnh mới VALID.
5. Xóa avatar là xóa mềm; có thể khôi phục trong 30 ngày khi chưa có avatar current/upload đang chạy.

### 4.5 Tạo ca điều trị

1. Trong hồ sơ bệnh nhân, chọn tạo lần điều trị mới.
2. Chọn Implant, Răng sứ, Chỉnh nha mắc cài hoặc Chỉnh nha Invisalign.
3. Nhập ngày bắt đầu không ở tương lai.
4. DOCTOR tự phụ trách ca mình tạo; ADMIN mới có thể chọn một bác sĩ active khác thuộc cơ sở bệnh nhân.
5. Kiểm tra checklist snapshot được tạo đúng loại trước khi upload.

Implant/Răng sứ tạo một session điều trị đầy đủ. Chỉnh nha có session đầu và các lần tái khám riêng; hợp đồng Chỉnh nha chỉ thuộc session đầu.

### 4.6 Thứ tự checklist theo dịch vụ

**Implant v6:** Hợp đồng → Kết quả xét nghiệm → Ảnh trước điều trị 01–12 → Phim trước → Phim phân tích → Ảnh trụ sử dụng → Phim sau cắm trụ → Ảnh phục hình tạm 01–12 → Ảnh thiết kế răng phục hình → Ảnh phôi sứ → Phim sau phục hình → Ảnh sau điều trị 01–12 → Bảo hành Implant → Bảo hành răng sứ.

**Răng sứ v4:** Hợp đồng → Ảnh trước điều trị 01–12 → Ảnh thiết kế DSD → Ảnh thiết kế răng phục hình → Ảnh phôi sứ → Ảnh sau điều trị 01–12 → Bảo hành răng sứ.

**Chỉnh nha:** giữ checklist ảnh lần khám và phim pano/cephalo theo session. Mỗi lần tái khám phải được chọn đúng trước khi upload để không đưa file vào session khác.

### 4.7 Upload và kiểm tra bộ ảnh

1. Chọn đúng lần khám ở phần **Các lần khám**.
2. Chọn đúng ô ảnh/phim/hợp đồng; kiểm tra nhãn và số thứ tự.
3. Tải file và chờ VALID.
4. Mở **Xem tổng quan bộ ảnh** để kiểm tra thumbnail, hướng ảnh và nhóm.
5. Nếu có quyền, tải original/ZIP phục vụ nghiệp vụ nội bộ. ZIP ảnh lâm sàng không tự chứa hợp đồng, avatar hoặc version lịch sử.
6. Với PDF hợp đồng, dùng trình xem trong website; không suy diễn rằng PDF có trường chữ ký `/Sig` đã được xác thực pháp lý.

### 4.8 Thay thế, lịch sử và xóa mềm

1. Chỉ thay file current trong session DRAFT/REOPENED.
2. Nhập lý do thay thế rõ ràng; bản cũ được giữ trong lịch sử version.
3. Bản mới phải vượt kiểm tra rồi mới thành current; không xóa bản cũ để “dọn chỗ”.
4. Xóa mềm ảnh/hợp đồng chỉ khi đúng bệnh nhân/slot và có reason code phù hợp.
5. Khi xóa nhầm, mở **Đã xóa gần đây** và khôi phục trước 30 ngày nếu có quyền/không xung đột.

### 4.9 Xác nhận bộ ảnh

1. Đợi mọi upload đang chạy kết thúc; không xác nhận khi còn pending/rejected/recovery.
2. Kiểm tra tổng quan, hợp đồng và dữ liệu bảo hành bắt buộc.
3. Chọn **Xác nhận bộ ảnh**.
4. Hệ thống cho phép xác nhận khi thiếu vị trí ảnh ở các dịch vụ đã áp cơ chế 0.2.17, nhưng vẫn chặn sai quyền/scope, tệp chưa hợp lệ và thiếu bảo hành bắt buộc.
5. Sau xác nhận, session bị khóa chỉnh sửa; phiên TREATMENT có thể đồng thời hoàn tất ca.

Không dùng khả năng xác nhận thiếu ảnh như cách bỏ qua kiểm soát chất lượng. Bác sĩ vẫn chịu trách nhiệm chuyên môn về bộ ảnh được xác nhận.

### 4.10 Mở lại bộ ảnh

1. Chỉ mở lại session đang CONFIRMED.
2. Chọn lý do: thiếu ảnh, ảnh sai, cập nhật lâm sàng hoặc lý do khác.
3. Nếu chọn lý do khác, nhập ghi chú đủ rõ.
4. Bổ sung/thay file rồi xác nhận lại để tạo manifest mới.
5. Manifest và lịch sử cũ vẫn được giữ; không yêu cầu ADMIN xóa lịch sử xác nhận.

### 4.11 Chia sẻ với khách hàng

1. Mở **Xem tổng quan bộ ảnh** trong đúng ca/lần khám rồi chọn chức năng chia sẻ.
2. Chọn đúng ảnh, preview hợp đồng và/hoặc thông tin bảo hành cần gửi trong danh sách hệ thống cho phép. Kiểm tra lại bệnh nhân, lần khám và từng mục trước khi tạo link; không chọn tất cả theo thói quen.
3. Link tồn tại tối đa 72 giờ, không có passcode và người có link có thể xem preview đã chọn.
4. Sao chép link qua kênh được duyệt. Link chỉ cho xem nội dung đã chọn; preview hợp đồng không phải tệp original/PDF đầy đủ. Không đưa original lên nơi công khai.
5. Kiểm tra preview có watermark.
6. Thu hồi link khi gửi nhầm, hoàn tất mục đích hoặc nghi ngờ lộ link.

### 4.12 Lưu trữ/xóa và khôi phục ca

- **Lưu trữ ca** đưa ca ra khỏi danh sách làm việc nhưng giữ dữ liệu con/lịch sử.
- **Xóa ca** là xóa mềm có cửa sổ khôi phục 30 ngày; không phải purge ngay.
- Không lưu trữ khi còn upload chưa kết thúc.
- Khôi phục yêu cầu patient đang active và đúng scope; ca Chỉnh nha khác không chặn khôi phục.
- Không tạo ca mới để thay thế ca bị xóa nếu ca cũ vẫn còn khôi phục được.

### 4.13 Tình huống lỗi thường gặp của DOCTOR

- **Không thấy bệnh nhân**: ngoài own/assigned/branch scope, assignment hết hạn hoặc hồ sơ archived.
- **Không upload được**: session đã CONFIRMED/ARCHIVED, sai slot, file sai loại/dung lượng hoặc có intent active.
- **File biến mất sau upload**: kiểm tra trạng thái upload gần nhất; file có thể REJECTED/RECOVERY_REQUIRED chứ không phải đã mất dữ liệu.
- **Không xác nhận được**: còn pending/rejected, bảo hành bắt buộc chưa đủ, màn hình dùng version cũ hoặc permission thiếu.
- **Không chia sẻ được**: asset không current/VALID, không thuộc session, link cũ đã hết hạn/thu hồi hoặc thiếu `media.share`.
- **Báo xung đột 409**: dữ liệu đã đổi ở tab/người khác; tải lại trước khi thao tác lại.

### 4.14 Bảo hành cho Bác sĩ

1. Trong ca Implant/Răng sứ, tìm thẻ **Thông tin bảo hành** và chọn **Thêm mã**.
2. Nhập mã đúng vật tư, thời hạn 1–30 năm và ngày bắt đầu không ở tương lai. Ngày hết hạn do hệ thống tính.
3. Một ca có thể có nhiều mã; không gộp nhiều vật tư vào một mã nếu quy trình nghiệp vụ không cho phép. Implant có bảo hành Implant và răng sứ; Chỉnh nha không có thẻ bảo hành.
4. Chỉ sửa khi phiên còn nháp/đã mở lại. DOCTOR có quyền lưu trữ bảo hành theo scope; LABO chỉ thêm/sửa.
5. Kiểm tra đủ mã bắt buộc trước khi xác nhận bộ ảnh.

### 4.15 Checklist bàn giao DOCTOR

- Tìm và tạo hồ sơ thử mà không tạo trùng.
- Tạo đủ bốn loại ca và chọn đúng session Chỉnh nha.
- Upload ảnh, phim, PDF hợp đồng và xử lý một file bị từ chối.
- Thay ảnh, xem lịch sử, xóa mềm và khôi phục.
- Xác nhận thiếu ảnh đúng cơ chế, mở lại có lý do và xác nhận lại.
- Tạo link chia sẻ có watermark rồi thu hồi.
- Nhận biết lỗi scope, pending, conflict và cách báo request ID.

## 5. Hướng dẫn chi tiết cho LABO

### 5.1 Phạm vi và nguyên tắc dữ liệu

LABO phục vụ công việc thiết kế/phục hình/phôi sứ và bảo hành. LABO có thể xem hồ sơ/ca theo effective scope nhưng response giảm PII: số điện thoại có thể bị che/không trả, ngày sinh và địa chỉ đầy đủ không được cung cấp mặc định. Không yêu cầu xuất dữ liệu đầy đủ nếu không cần cho công việc.

### 5.2 Quy trình đầu ngày

1. Đăng nhập bằng tài khoản LABO riêng.
2. Vào **Bệnh nhân**, tìm hồ sơ/ca được phép bằng thông tin hiển thị.
3. Chọn đúng loại điều trị và lần khám.
4. Kiểm tra các nhóm thiết kế/phôi sứ/bảo hành cần xử lý.
5. Upload hoặc cập nhật trong đúng nhóm được cấp.
6. Báo DOCTOR/ADMIN khi thiếu dữ liệu lâm sàng; không tự tạo ca hoặc di chuyển file sang nhóm khác.

### 5.3 Nhóm media LABO được thao tác

Theo policy mặc định, LABO chỉ upload/replace ở các nhóm đã duyệt như:

- Ảnh thiết kế DSD.
- Ảnh thiết kế răng phục hình.
- Ảnh phôi sứ.

Khi replace, LABO chỉ thay asset do chính mình upload. Các nhóm lâm sàng, hợp đồng và ba nhóm Implant mới không tự động mở cho LABO. Nếu giao diện không hiện nút upload, không dùng API hoặc tài khoản khác để vượt policy.

### 5.4 Upload file Labo

1. Xác nhận đúng bệnh nhân, ca, session và nhãn nhóm.
2. Chọn file JPEG/PNG dưới 10 MiB.
3. Chờ VALID và mở preview kiểm tra.
4. Nếu sai file, replace bằng lý do rõ ràng; không xóa lịch sử version.
5. Nếu file bị từ chối, sửa file nguồn và tải lại; không đổi đuôi file.
6. Báo DOCTOR khi nhóm đã hoàn tất để họ kiểm tra/xác nhận toàn bộ phiên.

### 5.5 Quản lý bảo hành

1. Mở thẻ **Thông tin bảo hành Implant** hoặc **Thông tin bảo hành răng sứ** trong đúng ca/session.
2. Chọn **Thêm mã**, nhập mã bảo hành, thời hạn 1–30 năm và ngày bắt đầu không ở tương lai.
3. Một session có thể có nhiều bản ghi cùng loại cho nhiều trụ hoặc nhiều răng/phôi.
4. Kiểm tra ngày hết hạn do server tính.
5. Sửa bản ghi khi session còn DRAFT/REOPENED và có quyền.
6. LABO không lưu trữ bảo hành mặc định; chuyển ADMIN hoặc DOCTOR phụ trách ca khi cần lưu trữ.

Mã bảo hành phải thuộc đúng TreatmentCase/TreatmentSession. Không dùng một mã cho bệnh nhân/ca khác. Chỉnh nha không có bảo hành.

### 5.6 Xem và tải dữ liệu

- LABO xem preview media trong scope theo `media.view`.
- Khả năng tải original media phụ thuộc effective permission/capability backend trả về; không suy diễn từ việc nhìn thấy preview.
- LABO không tải original hợp đồng, không upload/archive/restore hợp đồng.
- LABO không xem storage key/path và không được nhận full PII qua frontend.

### 5.7 Những việc LABO không được làm

- Tạo, sửa, lưu trữ hoặc khôi phục bệnh nhân/ca.
- Tạo lần tái khám hoặc thay đổi phân công.
- Upload vào ảnh trước/sau điều trị, ảnh phục hình tạm, phim hoặc nhóm lâm sàng không được cấp.
- Xác nhận, mở lại hoặc chia sẻ bộ ảnh với khách hàng.
- Xóa ảnh của DOCTOR, tải original hợp đồng hoặc quản lý API Client.
- Dùng tài khoản DOCTOR/ADMIN mượn để hoàn tất công việc Labo.

### 5.8 Tình huống lỗi thường gặp của LABO

- **Không tìm thấy bệnh nhân/ca**: ngoài scope hoặc ca chưa được phân công/hiển thị; liên hệ DOCTOR/ADMIN bằng định danh nghiệp vụ tối thiểu.
- **Không thấy nút upload**: nhóm không có `allowedRoles=LABO`, session đã CONFIRMED/ARCHIVED hoặc effective permission bị deny.
- **Không replace được**: file không do chính tài khoản LABO upload, row version đã đổi hoặc có replacement đang chạy.
- **Không lưu bảo hành**: sai loại dịch vụ, ngày bắt đầu ở tương lai, thời hạn ngoài 1–30 năm, mã trùng hoặc session không còn chỉnh sửa.
- **Không tải hợp đồng**: đây là giới hạn chủ đích; chuyển DOCTOR/ADMIN, không xin secret/API riêng.

### 5.9 Checklist bàn giao LABO

- Đăng nhập và nhận biết dữ liệu PII bị giảm trường.
- Tìm đúng ca và chọn đúng session.
- Upload/replace ở ba nhóm Labo mặc định.
- Tạo/sửa nhiều mã bảo hành và nhận biết lỗi mã trùng/ngày/thời hạn.
- Biết rõ không được confirm, share, tải hợp đồng original hoặc sửa nhóm lâm sàng.
- Biết cách báo file rejected/recovery mà không gửi original qua kênh không an toàn.

## 6. Phối hợp giữa các vai trò

### 6.1 Ca Implant/Răng sứ thông thường

1. DOCTOR tạo bệnh nhân/ca và upload dữ liệu lâm sàng/hợp đồng.
2. LABO upload DSD/thiết kế phục hình/phôi sứ và nhập bảo hành được giao.
3. DOCTOR kiểm tổng quan, bổ sung dữ liệu còn thiếu và xác nhận.
4. ADMIN chỉ can thiệp khi có lỗi scope, tài khoản, khôi phục hoặc vận hành.

### 6.2 File bị từ chối

1. Người upload xem lý do và giữ nguyên hồ sơ/slot.
2. Sửa hoặc xuất lại file nguồn đúng định dạng.
3. Tải lại vào đúng slot; không tạo bệnh nhân/ca mới.
4. Nếu lặp lại hoặc RECOVERY_REQUIRED, gửi request ID cho ADMIN; không gửi original qua chat.

### 6.3 Gửi nhầm link chia sẻ

1. DOCTOR/ADMIN thu hồi link ngay.
2. Kiểm tra selection và tạo link mới nếu cần.
3. Báo ADMIN khi nghi ngờ truy cập trái phép để kiểm audit.
4. Không thay link bằng cách public original hoặc tải file lên dịch vụ ngoài chưa duyệt.

### 6.4 Nhân viên chuyển cơ sở hoặc nghỉ việc

1. ADMIN khóa tài khoản để thu hồi session.
2. Đối soát ca/assignment và chuyển giao hợp lệ.
3. Chỉnh vai trò/cơ sở hoặc xóa tài khoản sau khi hoàn tất audit.
4. Không xóa hồ sơ bệnh nhân/media để xử lý thay đổi nhân sự.

## 7. Bảng xử lý lỗi nhanh

| Hiện tượng | Người xử lý đầu tiên | Cách xử lý an toàn |
|---|---|---|
| Không đăng nhập được | Người dùng/ADMIN | Kiểm tra trạng thái khóa, mật khẩu tạm, thời gian hệ thống; không chia sẻ mật khẩu |
| Số liệu cơ sở không như dự kiến | ADMIN | Tải lại trang; đối chiếu trạng thái ACTIVE, deletedAt và ca ARCHIVED; không sửa trực tiếp database |
| Không thấy bệnh nhân/ca | Người dùng/ADMIN | Kiểm scope, branch, assignment, trạng thái archived; không mở quyền toàn hệ thống tùy tiện |
| Upload pending quá lâu | Người upload/ADMIN | Ghi request ID, kiểm health/storage; không upload lặp nhiều lần |
| File REJECTED | Người upload | Sửa file nguồn rồi tải lại; không đổi đuôi giả định dạng |
| Lỗi 409 | Người dùng | Tải lại dữ liệu mới nhất rồi thao tác lại |
| Không xác nhận được | DOCTOR/ADMIN | Kiểm pending/rejected, warranty, version, permission và trạng thái session |
| Không khôi phục được | ADMIN/DOCTOR có quyền | Kiểm 30 ngày, integrity, xung đột slot/avatar và trạng thái patient/session |
| API Client 401/403 | ADMIN/đơn vị tích hợp | Kiểm feature flag, IP, secret/token, scope; xoay secret nếu nghi lộ |
| Storage/NAS lỗi | ADMIN vận hành | Dừng thay đổi, kiểm mount guard/shared folder; không tạo marker giả |

## 8. Tiêu chí đào tạo hoàn tất

Một tài khoản chỉ nên được bàn giao vận hành sau khi người dùng:

- hiểu role không thay thế permission/scope/relationship;
- đăng nhập, đổi mật khẩu và đăng xuất đúng cách;
- thực hiện thành công quy trình mẫu của vai trò bằng dữ liệu giả;
- nhận biết DRAFT, VALID, REJECTED, CONFIRMED, REOPENED và dữ liệu đã xóa;
- biết các hành động không được phép của vai trò;
- biết cách báo request ID mà không làm lộ PII, original, hợp đồng, token hoặc secret;
- hoàn thành checklist riêng ở cuối chương ADMIN, DOCTOR hoặc LABO.