Chi nhánh & nhân sự

Branch và staff là nền tảng vận hành của DentIQ. Branch gộp khách hàng, lịch hẹn, tài chính — nhân viên được gán quyền và phạm vi chi nhánh. Phần này hướng dẫn tạo chi nhánh, quản lý nhân sự, phân quyền, và hiểu chi nhánh ownership.

Giao diện quản lý chi nhánh: danh sách branch, chi tiết, giờ hoạt động

Chi nhánh (Branch) là gì

Branch là đơn vị vận hành độc lập của clinic. Mỗi branch có:

Tên riêng, địa chỉ, số điện thoại.
Giờ mở cửa hàng tuần (phục vụ Scheduler grid).
Danh sách nhân viên gán vào branch đó.
Tài chính riêng (nếu cần: công nợ, doanh thu, cash per branch).
Quota / billing tùy chọn (nếu clinic có tính năng cấp độ).

Ví dụ: Phòng khám ABC có 2 chi nhánh — Hà Nội (ghế 1–3, giờ 8–17) và Sài Gòn (ghế 4–6, giờ 9–19). Lễ tân HN chỉ xem lịch HN; bác sĩ SG chỉ mở visit SG.

Tạo chi nhánh mới

Vào Tổ chức → Chi nhánh hoặc /admin/clinic/branches.
Nút Thêm chi nhánh → form:

Tên chi nhánh: "Chi nhánh Hà Nội", "Cơ sở 2".
Địa chỉ, TP, ĐT.
Giờ mở cửa: (nêu dưới).
Quota (tuỳ chọn): số bệnh nhân tối đa / số lịch hẹn / tháng.

Bấm Tạo → chi nhánh sẵn sàng gán nhân viên.

Cấu hình giờ mở cửa

Giờ hoạt động kiểm soát những khung giờ nào Scheduler cho phép đặt lịch hẹn.

Vào branch detail (Chi nhánh → chọn chi nhánh → Sửa).
Cuộn đến card Giờ hoạt động.
7 hàng = 7 ngày tuần (Thứ Hai→Chủ Nhật). Mỗi hàng:

Giờ mở / Giờ đóng: chọn từ time picker (vd 08:00 → 17:00).
Đóng cửa: toggle để đánh dấu ngày nghỉ (Thứ Bảy, Chủ Nhật); lấy lại giờ khi bật lại.

Bấm Lưu → toast xác nhận.
Scheduler ngay lập tức phản chiếu giờ mới khi tải lại.

Lưu ý

Ngay cả khi đánh dấu "Đóng cửa" (Thứ Bảy), nhân viên vẫn có thể tạo cuộc hẹn ngoại lệ. Scheduler sẽ hiện banner cảnh báo.

Quản lý nhân sự

Thêm nhân viên

Vào Tổ chức → Nhân sự hoặc /admin/clinic/staff.
Nút Thêm nhân viên → form:

Tên, SĐT, Email: thông tin cơ bản.
Vai trò: chọn từ 7 role mặc định (Doctor, Receptionist, …) hoặc custom role.
Mã số nhân viên (staffCode): mã định danh ngắn (VD: DOC-001, AST-001) hiển thị trong dropdown để phân biệt nhân viên trùng tên. Phải duy nhất trong phòng khám — nếu trùng, hệ thống báo lỗi "Mã số nhân viên đã tồn tại". Để trống thì được phép.
Vị trí chuyên môn (StaffPosition): chọn vị trí vận hành (DENTIST, ASSISTANT, HYGIENIST, TECHNICIAN, OTHER). Quyết định 2 việc: (1) tỉ lệ hoa hồng tự động; (2) nhân viên xuất hiện ở dropdown nào — chỉ DENTIST hiện trong ô "Chọn bác sĩ"; DENTIST + ASSISTANT + HYGIENIST + TECHNICIAN hiện trong ô "Chọn phụ tá". Đây không phải vai trò truy cập (role) — role quản lý quyền, vị trí quản lý lương + dropdown.
Branch scope:

ALL — nhân viên này truy cập tất cả chi nhánh (clinic admin, regional manager).
SPECIFIC — chọn chi nhánh cụ thể (lễ tân HN, bác sĩ SG).

Gửi lời mời: checkbox → hệ thống gửi SMS/email kích hoạt tài khoản.

Bấm Tạo → nhân viên được gán role + vị trí + branch.

Chỉnh sửa & deactivate

Nhân viên hoạt động hiển thị dạng danh sách (nếu 7+) hoặc thẻ (nếu 2–6). Nhấn nhân viên để chỉnh roles, vị trí nhân sự, branch scope, hoặc deactivate (vẫn giữ lịch sử). Thay đổi vị trí sẽ ảnh hưởng đến tỉ lệ hoa hồng trong các công đoạn mới và việc nhân viên xuất hiện ở dropdown chọn bác sĩ / phụ tá.

Branch scope (CI-01, CI-03)

Branch scope định phạm vi dữ liệu mà nhân viên có thể xem + quản lý:

Branch scope	Ý nghĩa	VD
`ALL`	Xem/sửa toàn bộ clinic, mọi chi nhánh	Clinic Admin, Regional Manager
`SPECIFIC`	Chỉ chi nhánh đã chọn (1 hoặc nhiều)	Bác sĩ HN, Lễ tân SG

Quan trọng (CI-01)

Chip "Chi nhánh" ở top header là bộ lọc, không phải quyền sở hữu. Khi bác sĩ chọn "Chi nhánh SG" rồi tạo visit, visit đó vẫn thuộc chi nhánh gốc của bệnh nhân — không thay đổi vì UI branch chip. Source branch lấy từ appointment, không từ active UI branch.

Phân quyền (role & permission)

7 role mặc định đã đủ cho hầu hết phòng khám:

Role	Mục đích	Quyền chính
Clinic Admin	Quản lý toàn clinic	clinic.manage, branch.manage, user.manage, role.manage, tất cả domain
Doctor	Điều trị, chẩn đoán, kớp	visit.manage, diagnosis.manage, treatment_plan.manage, treatment_plan.execute, prescription.manage, lab_order.manage
Assistant (Phụ tá)	Hỗ trợ, thực hiện công đoạn	treatment_plan.execute, visit.manage, diagnosis.read, document.print, earnings.read (MỚI)
Receptionist	Lễ tân, lịch hẹn, checkin	appointment.manage, reception.manage, patient.read, payment.manage (thu cọc)
Customer Care	Chăm sóc, recall, follow-up	customer_care.manage, communication.manage, patient.read
Accountant	Kế toán, tài chính	payment.read, cash.manage, einvoice.manage, dashboard.read
Inventory Operator	Quản lý kho	inventory.manage, medicine.manage, service.read

Custom role

Nếu cần role khác (vd "Quản lý HN" — full quyền HN nhưng không quản lý user hệ thống):

Vào Tổ chức → Roles & Permissions.
Nút Tạo role → nhập tên, chọn các mã quyền từ bảng 60 quyền (xem trang 60 mã quyền clinic).
Bấm Lưu.

Smart Directory (giao diện danh sách branch)

Danh sách chi nhánh tự điều chỉnh hiển thị theo số lượng:

Số branch	Hiển thị
0	Empty state — "Tạo chi nhánh đầu tiên"
1	Profile card chi nhánh đó (không table)
2–6	Thẻ card dạng grid
7+	Table (1 hàng = 1 branch)
Mobile	Luôn card (không bao giờ table trên mobile)

Quyền liên quan (permission codes)

Khi cấu hình role hoặc kiểm tra quyền của nhân viên, hãy tìm các code này:

branch.read — xem chi nhánh, giờ hoạt động (read-only).
branch.manage — tạo, sửa, xóa chi nhánh + giờ hoạt động.
user.read — xem danh sách nhân viên.
user.manage — tạo, sửa, deactivate nhân viên.
role.read — xem danh sách role.
role.manage — tạo, chỉnh custom role.
permission.read — xem danh sách mã quyền (dùng khi setup role).

Edge cases

Nhân viên có nhiều chi nhánh

Lễ tân có thể gán scope SPECIFIC rồi chọn cả HN + SG. Khi xem danh sách lịch hẹn, lễ tân thấy cả 2 chi nhánh; khi tạo lịch, phải chọn chi nhánh đích.

Trùng mã số nhân viên

Mã số (staffCode) phải duy nhất trong phòng khám. Nếu nhập mã đã có người dùng, form báo lỗi "Mã số nhân viên đã tồn tại trong phòng khám" (HTTP 409) và không lưu. Để trống mã số thì được phép (nhiều nhân viên có thể cùng để trống).

Bác sĩ / phụ tá không hiện trong dropdown

Dropdown "Chọn bác sĩ" chỉ hiện nhân viên có vị trí DENTIST; "Chọn phụ tá" hiện DENTIST + ASSISTANT + HYGIENIST + TECHNICIAN. Nếu một bác sĩ không xuất hiện, kiểm tra vị trí chuyên môn của họ ở trang Nhân sự — vị trí OTHER hoặc bỏ trống sẽ bị ẩn khỏi các dropdown này. Vai trò (role) không còn quyết định dropdown — chỉ vị trí.

Audit nhân sự

Khi sửa branch scope hoặc role nhân viên, hành động ghi audit log (yêu cầu audit.read). Audit không bao gồm dữ liệu nhạy cảm — chỉ metadata: ai, khi nào, hành động gì.

Branch bị disable / billing vượt quota

Nếu clinic hết quota bệnh nhân hoặc billing đóng chi nhánh, nút "Tạo chi nhánh" mất hoặc disable (tooltip giải thích). Backend vẫn là nguồn sự thật — quyền hạn áp dụng ở server, UI chỉ phản chiếu.