Xử lý sự cố thường gặp
Bảng quick-fix cho những vấn đề phổ biến. Nếu không tìm thấy, liên hệ support.
Đăng nhập & truy cập
| Triệu chứng | Nguyên nhân thường gặp | Cách check | Cách fix |
|---|
| Không login được: "Invalid email/password" | Nhập sai password, hoặc tài khoản chưa activated | Thử reset password (quên mật khẩu?). Kiểm tra email xác nhận | Click "Quên mật khẩu" → nhập email → reset link → set password mới |
| Login thành công nhưng "403 Forbidden" trên mọi page | Tài khoản không gán role/permission, hoặc clinic scope lỗi | Contact admin: "Tôi có role gì không?" trong user management | Admin gán role + permission cho account. User logout rồi login lại |
| "You don't have permission to access this clinic" | Người dùng bị xoá khỏi clinic hoặc multi-clinic setup lỗi | Xem admin → users → [user] → clinic assignment | Admin thêm user vào clinic scope. Hoặc user switch clinic ở header |
| Network timeout khi login (page hang) | WiFi yếu, hoặc API down | Ping server, xem network tab in DevTools | Refresh page, thử lại. Nếu persistent, check server status hoặc network |
Bệnh nhân & Visit
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Không tìm thấy BN cũ khi search | SĐT ghi sai, hoặc BN chưa import | Search bằng tên hoặc ID. Xem Patient list total count | Thử search "keyword" đơn giản, hoặc kiểm tra import log |
| BN duplicate: 2 record cùng SĐT | Import sạch sẽ, hoặc lệnh tạo 2 lần | Patients → sort by phone | Mở BN mới (sai) → Menu → Merge into… → chọn BN gốc |
| Tạo visit nhưng branchId sai (ghi nhánh A thay B) | Active branch lỗi hoặc UI mặc định wrong | Mở visit detail → check branch field | Nếu chưa charge: xoá + tạo lại. Nếu có charge: contact admin (need migration) |
| Patient 360 timeline không hiển thị visit cũ | Cache chưa refresh, hoặc permission missing (CI-04, CI-08) | Refresh page. Check permission: bạn có visit.read không? | Refresh. Nếu vẫn mất, contact admin (cache invalidation issue) |
Thanh toán & Tiền
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Ghi nhận payment nhưng không thấy phiếu thu | Máy in lỗi, hoặc payment ghi nhầm branch | Mở payment detail. Xem print history | In lại từ payment detail, hoặc in từ browser (backup PDF) |
| Cash session không close được: "Balance mismatch" | Có entry ghi sai, hoặc quên ghi expense | Xem cash ledger hôm nay, check tất cả entry | Tìm entry sai, edit/delete nó. Rồi close lại. Nếu cần unlock: admin reopen |
| Payment bị hủy nhưng outstanding không khôi phục | Cache chưa invalidate (CI-04) | Refresh Patient 360. Xem payment history detail | Refresh page. Nếu vẫn sai, contact admin |
| "Permission denied" khi ghi payment | Bạn không có payment.manage, chỉ có payment.read | Xem role settings. Admin check user permission code | Admin gán payment.manage permission. User re-login |
E-invoice
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| E-invoice timeout: "Failed to issue after 3 retries" | Provider API down (VNPT/MISA/Viettel), hoặc sandbox/production config sai | Check e-invoice setting → provider status. Ping provider URL. Xem API logs | Verify provider connection string. Switch sandbox ↔ production setting. Retry issue |
| E-invoice phát hành thành công nhưng không lưu số HĐ | DB insert lỗi sau provider response, hoặc cache miss | Check e-invoice detail: số HĐ có ghi không? | Manual re-fetch từ provider, hoặc contact admin (need DB fix) |
| "Cannot issue e-invoice: payment not found" | E-invoice gắn payment không tồn tại, hoặc payment bị xoá | Mở payment detail. Xem link sang e-invoice | Nếu payment bị xoá: không thể reissue. Ghi payment mới + reissue e-invoice |
| E-invoice status "REJECTED" từ provider | Provider data validation fail: thông tin BN/hóa đơn không hợp lệ | Xem e-invoice error message chi tiết từ provider | Fix data (số điện thoại, địa chỉ BN, amount), rồi retry |
In ấn & Phiếu tư vấn
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Máy in không nhận job | Driver lỗi, WiFi disconnect, hoặc in port sai config | Check system settings → printers. Network → ping printer | Restart printer + computer. Update driver. Re-add printer to system |
| In ra khi không phải A4: "paper size wrong" | Printer setting mặc định khác A4, hoặc job config sai | System preferences → printers → default paper size | Set paper size = A4. Hoặc print từ browser (manual setting per job) |
| Phiếu tư vấn (KHĐT) in ra không đẹp: text lệch, hình bị cắt | CSS print responsive issue, hoặc browser zoom level sai | Mở phiếu preview → check layout. Browser zoom = 100%? | Reset zoom (Cmd+0). Clear browser cache. Thử in từ trình duyệt khác |
| "Print bridge offline" alert | Local print daemon down, hoặc network lost | Check print bridge app running? Network connected? | Start print bridge app (if installed). Fallback: browser print. Reconnect network |
Lab order
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Lab order "PENDING" quá lâu, không update status | Lab chưa nhận order, hoặc SMS/email không đến | Xem order detail: SMS sent? Lab contact thông báo? | Contact lab trực tiếp. Hoặc manual update status nếu lab xác nhận đã nhận |
| Lab order gửi không đến (SMS/email fail) | Provider SMS/email config sai, hoặc lab number sai | Xem lab setting → provider. Check lab phone/email | Verify provider API key. Update lab contact info. Resend order |
| Lab order kết quả không match BN (sai sample) | Lab comment ghi sai sample ID, hoặc order tạo sai BN | Xem order vs result detail. So sánh BN name, tooth | Contact lab xác nhận. Nếu thực sự sai: tạo order mới, old order mark "CANCELED" |
Notification & CRM
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Notification bell không hiển thị badge count | Badge cache stale, hoặc new notification không sync | Refresh page. Xem notification detail | Manual refresh. If persistent: admin check outbox processor running |
| Customer Care task không tự tạo (plan chưa ký quá 3 ngày) | BullMQ scheduler job lỗi, hoặc customer_care feature disabled | Check app logs: "scheduler started", "task created". Settings: CC disabled? | Restart worker role (APP_ROLES=worker). Enable CC feature in settings. Manual trigger job |
| Task outcome saved nhưng queue vẫn show active | Cache invalidation chậm (CI-04) | Refresh CC queue. Check task detail status | Refresh. Wait 30 sec. If stuck: admin invalidate cache manually |
Nhân sự & vị trí chuyên môn
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Bác sĩ không hiện trong ô "Chọn bác sĩ" | Vị trí chuyên môn không phải DENTIST (đang OTHER hoặc bỏ trống) | Tổ chức → Nhân sự → mở nhân viên → xem trường Vị trí chuyên môn | Đặt vị trí = DENTIST. Dropdown "Chọn bác sĩ" chỉ hiện DENTIST |
| Phụ tá / KTV không hiện trong ô "Chọn phụ tá" | Vị trí = OTHER (bị loại) hoặc bỏ trống | Mở nhân viên → xem Vị trí chuyên môn | Đặt vị trí = ASSISTANT / HYGIENIST / TECHNICIAN (hoặc DENTIST). Vị trí OTHER không hiện ở ô chọn phụ tá |
| Lưu nhân viên báo "Mã số nhân viên đã tồn tại" | Mã số (staffCode) trùng với nhân viên khác trong phòng khám (HTTP 409) | Nhân sự → search mã số đang nhập | Đổi sang mã khác chưa dùng, hoặc để trống mã số (cho phép trùng rỗng) |
| 2 nhân viên trùng tên, khó phân biệt trong dropdown | Chưa đặt mã số nên dropdown chỉ thấy tên | Mở dropdown → xem dòng phụ dưới tên | Đặt mã số riêng cho mỗi người (VD DOC-001, DOC-002) → dropdown hiện mã để phân biệt |
Performance
| Triệu chứng | Nguyên nhân | Cách check | Cách fix |
|---|
| Patient 360 load chậm (5+ giây) | N+1 query, hoặc BN có visit/charge nhiều quá | DevTools → Network. Check API call time. Patient visit count? | Refresh. If persistent: Admin check database index. Or contact support (need query optimization) |
| Danh sách BN search kết quả chậm | Search keyword vô tình trigger full table scan, hoặc filter complex | Check search query, filter input. Try simpler keyword | Use shorter search term. Filter by fewer criteria. Admin add database index if needed |
| Browser crash khi mở big appointment calendar | JavaScript render chậm, 1000+ appointment 1 screen | Check calendar date range. Appointment count? | Narrow date range (2 weeks instead of 3 months). Or switch to table view |