Xử lý sự cố
Gặp một triệu chứng lạ? Tra bảng theo khu vực nghiệp vụ — hầu hết "lỗi" thực ra là một chốt chặn cố ý đang làm đúng việc của nó.
Trang này gom các bảng "Khi nào hỏng & cách xử lý" rải rác trong các tình huống thực tế về một chỗ, xếp theo năm khu vực. Nguyên tắc chung của DentIQ Lab: mặc định từ chối, không tạo dữ liệu nửa vời, và mọi bước chặn đều có lý do (thường là một business rule bảo vệ tính đúng của case). Khi một thao tác bị chặn, hãy đọc cột "Nguyên nhân" trước khi coi đó là bug.
Đặt đơn (intake)
Từ quét QR, gửi ảnh/Rx, tới nhận mẫu vật lý và tải STL. Chi tiết ở Đơn đầu tiên, Mẫu vật lý gửi kèm và Case digital (STL).
| Triệu chứng | Nguyên nhân | Khắc phục |
|---|---|---|
| Quét QR báo hết hạn / labo ngừng nhận | QR đã bị vô hiệu hoặc labo tạm dừng nhận đơn | Thông báo rõ, không tạo đơn mồ côi; xin QR/link mới của labo, hoặc dùng fallback ảnh gửi qua Zalo |
| Không mở được form / không quét được QR | Máy cũ, mạng yếu, camera lỗi | Fallback ảnh: chụp phiếu giấy + ảnh gửi qua Zalo như cũ; labo nhập hộ đơn |
| Ảnh quá lớn, upload đứng (mạng VN yếu) | File nặng, băng thông kém | Hệ thống nén ảnh, cho gửi lại, lưu nháp — không mất dữ liệu đã điền |
| Cùng phòng khám có nhiều danh tính (trùng tên/số) | Đặt nhiều lần trước khi claim, seed trùng | Hệ thống gộp theo số điện thoại đã chuẩn hóa (E.164, +84); giữ toàn bộ lịch sử đơn, không tạo đơn mồ côi |
| Link công khai bị spam / lạm dụng | Ai đó gửi đơn rác qua link | Chống bằng rate-limit + OTP qua Zalo/SMS, không dựng tường đăng nhập chặn phòng khám thật |
Không đẩy được case vào sản xuất dù đơn đã accepted | Mẫu vật lý chưa tới (sampleReceived=false) | Chờ mẫu; điều phối bấm "Nhận mẫu" khi mẫu tới để mở cổng (guard BR-W1) |
| Đơn số đã có nhưng mẫu quá hạn dự kiến chưa tới | Mẫu thất lạc / trễ trên đường ship | Mở sự cố mẫu vào, cảnh báo hai phía qua Zalo, không tự set sampleReceived; yêu cầu gửi lại / lấy dấu lại |
| Tưởng labo đã bắt đầu làm khi vừa gửi đơn | Nhầm đơn số submitted với "đã nhận mẫu" | Hiển thị rõ trạng thái "chờ nhận mẫu"; đơn số và leg inbound là hai mốc tách biệt (BR-09) |
| Relay bến xe: mẫu đến bến nhưng chưa ai ra nhận | Không có người ra bến, trễ chuyến | Leg inbound treo; nhắc + ghi chú "đang ở bến", cử người nhận; không auto thất lạc tới khi quá ngưỡng |
| Mẫu tới nhưng hỏng/không dùng được | Dấu rách, biến dạng khi vận chuyển | Không đóng leg inbound; báo phòng khám lấy dấu lại; sản xuất vẫn bị gác |
| Upload STL đứng / đứt giữa chừng (mạng VN yếu) | File nặng, băng thông kém | Upload resumable nối lại từ phần đã tải, không phải tải lại từ đầu (BR-03) |
| Hệ thống từ chối file STL | Định dạng lạ (.dcm, .zip linh tinh) ngoài STL/PLY/OBJ, hoặc vượt quota | Báo rõ định dạng chấp nhận, export lại đúng STL/PLY/OBJ; file quá lớn thì nén hoặc tách hàm (BR-02, BR-07) |
| Preview mesh lỗi | File hỏng khi export/truyền | Báo phòng khám tải lại; STL là tùy chọn nên không chặn việc gửi đơn (BR-01, BR-06) |
| Phòng khám không có máy scan | Chỉ ~30–35% có scanner ở VN | Bỏ qua bước STL hoàn toàn; gửi đơn bằng ảnh + dấu vật lý (đường chính, P2) |
Sản xuất & QC
Từ chuyển trạng thái case, phân technician, tới cổng QC pass/fail. Chi tiết ở Vòng đời case A→Z, Đơn gấp (48h) và QC trượt → làm lại.
| Triệu chứng | Nguyên nhân | Khắc phục |
|---|---|---|
Không đẩy được case sang in_production | Mẫu vật lý chưa tới (sampleReceived=false) hoặc chưa phân technician | Ghi nhận mẫu vào (đóng leg inbound) + phân technician; case STL-only thì coi như đã nhận mẫu ngay |
Case treo ở submitted nhưng mẫu quá hạn dự kiến chưa tới | Sự cố mẫu vào (thất lạc trên đường ship) | Mở trạng thái sự cố mẫu vào, cảnh báo hai phía qua Zalo, yêu cầu gửi lại / lấy dấu lại; sản xuất vẫn bị gác |
Cố chuyển thẳng sang delivered mà chưa qua QC | Bỏ qua cổng QC | Bất khả thi theo máy trạng thái — phải qua qc → ready_to_ship bằng một lần QC pass (BR-W2) |
| Trễ due date | SLA chạy từ khi nhận mẫu; công đoạn kéo dài | Cảnh báo trễ nổi ở labo board + đẩy Zalo cho clinic; ghi lý do trễ, điều phối tái ưu tiên |
| Thao tác chuyển trạng thái bị từ chối | Sai cạnh clinic↔labo hoặc sai vai (mặc định từ chối) | Chỉ đúng actor trong đúng cạnh mới trigger được transition (BR-W4); kiểm lại vai và quyền |
| Phòng khám tưởng trễ dù labo chưa quá 48h (rush) | Hiểu SLA đếm từ lúc gửi đơn, không phải từ lúc nhận mẫu | Giải thích & hiển thị rõ mốc sampleReceivedAt; 48h đếm từ lúc nhận mẫu (BR-W1) |
| Muốn giao gấp bỏ qua QC | Áp lực thời gian | Không được — rush vẫn phải QC pass mới đi giao (bất biến BR-W2); ưu tiên thứ tự chấm QC thay vì bỏ bước |
| Nút Pass QC không sáng | Còn hạng mục checklist trống/không đạt, chưa đính ảnh thành phẩm, hoặc chưa ghi phôi/lô | Chấm đủ 6 hạng mục, đính ≥1 ảnh thành phẩm, ghi mã phôi/lô từng unit (BR-04, BR-08, BR-09) |
| Fail nhưng không chuyển được trạng thái | Thiếu lý do / chưa chọn công đoạn quay lại / chưa đính ảnh lỗi | Ghi đủ lý do + công đoạn + ảnh nêu lỗi; đây là chốt chặn cứng, không phải lỗi hệ thống (BR-05) |
| Case nhiều unit: một số đạt, một số trượt | Chỉ một phần unit đạt | Ghi nhận theo unit; cả case vẫn fail tới khi tất cả unit đạt (BR-07) |
| Phôi/lô thực dùng không khớp material đã đặt | Nhập/dùng sai phôi | Đánh hạng mục material KHÔNG ĐẠT → không cho pass → fail về công đoạn tương ứng, ghi rõ ở lý do (BR-05 + BR-09) |
| Người không phải QC cố mở cổng | Sai vai | Từ chối theo quyền — chỉ vai QC được ghi kết quả và mở cổng (BR-02) |
Giao nhận & bảo hành
Từ giao thành phẩm, redo sau giao, tới yêu cầu bảo hành. Chi tiết ở Redo sau giao và Yêu cầu bảo hành.
| Triệu chứng | Nguyên nhân | Khắc phục |
|---|---|---|
| Giao gấp thất lạc / giao nhầm | Phương thức nhanh dễ sự cố (Grab/xe ôm) | Mở trạng thái sự cố, không auto delivered; thu hồi/giao lại đúng, giữ bằng chứng để truy nguồn |
| Không mở được redo | Chưa gán bên chịu trách nhiệm (để trống) | Gán bắt buộc do-labo hoặc do-clinic — không cho để trống (BR-02) |
| Tranh cãi lỗi shade do ai | Không có bằng chứng ai chỉ định shade | Mở labo slip/lịch sử đơn: mã shade đã ghi + ảnh tab màu/cùi đã gửi là trọng tài (BR-08) |
| Nghi vỡ do phôi sai chứ không do technician | Chưa đối chiếu phôi/lô thực dùng | Kéo material provenance của case gốc; phôi sai → có thể lỗi nhập vật liệu của labo (BR-10) |
| Redo do-clinic nhưng không thu được tiền | Chưa chốt trách nhiệm trước khi tính phí | Chốt bằng bằng chứng BR-08 trước; who_pays=do-clinic → tính phí ở feature công nợ (BR-09) |
| Clinic tự ý đổi trạng thái sản xuất | Sai cổng quyền | Clinic chỉ được báo lỗi; mở redo và quy trách nhiệm là thao tác phía labo (QC/điều phối) |
| Nút tạo claim bảo hành bị khóa | Case đã hết hạn bảo hành, hoặc không ở delivered | Xử lý như đơn mới (work order mới), không phải claim; màn tra cứu vẫn hiện lịch sử + provenance để báo giá có cơ sở (BR-08) |
| Ngày giao thiếu/sai trong dữ liệu cũ | Dữ liệu nhập trước khi lên hệ thống | Không tự suy hạn; đánh dấu "cần xác minh ngày giao" trước khi cho tạo claim |
| Case cũ thiếu nguồn gốc phôi | Phôi/lô không được ghi khi làm | Hiển thị "thiếu nguồn gốc" thay vì bịa; vẫn cho tra cứu/claim nhưng nhắc bổ sung khi làm lại (BR-10) |
| Báo lại cùng một hỏng hóc | Claim trùng | Gộp vào claim đang mở, không tạo bản sao |
| Tranh chấp bên chịu trách nhiệm bảo hành | Chưa rõ lỗi labo hay clinic | Cho "tạm duyệt làm lại" nhưng treo cờ tranh chấp để kế toán đối soát sau |
Tài chính & HĐĐT
Từ chốt công nợ cuối kỳ tới phát hành hóa đơn điện tử. Chi tiết ở Chốt công nợ cuối tháng và HĐĐT thất bại.
| Triệu chứng | Nguyên nhân | Khắc phục |
|---|---|---|
| Cần sửa số sau khi đã chốt sao kê | Sao kê đã chốt là bất biến | Không sửa số cũ; tạo bút toán điều chỉnh sang kỳ sau (BR-W3) |
| Deposit lớn hơn nợ trong kỳ | Cọc trả trước vượt phát sinh | Trừ tối đa về 0, không âm; phần thừa giữ on-account, trừ tiếp kỳ sau (BR-W2) |
| Cả labo và phòng khám cùng định phát hành HĐĐT một kỳ | Nguy cơ xuất hóa đơn hai lần | Mặc định chỉ labo phát hành; một sao kê kỳ chỉ xuất HĐĐT một lần (BR-W4) |
| Clinic cố sửa số trên sao kê | Sai vai — clinic chỉ được xem | Từ chối theo quyền; chỉ role tài chính của labo chốt/phát hành/ghi nhận (BR-W6) |
| Quá due date vẫn chưa thu đủ | Clinic trả trễ | Chuyển overdue, nhắc nợ khéo qua Zalo kèm sao kê; thu nốt hội tụ về paid (BR-W5) |
| Provider down / timeout khi phát hành HĐĐT | Hạ tầng nhà cung cấp lỗi | Không tạo hoá đơn nửa vời; cho thử lại, hệ thống không cấp trùng số |
| Chặn phát hành, báo thiếu/sai MST người mua | Hồ sơ phòng khám chưa đủ | Bổ sung MST, tên, địa chỉ người mua; link DentIQ có thể lấy từ identity phòng khám (BR-10) |
| Chữ ký số hết hạn / thông tin người bán sai | Cấu hình labo lỗi thời | Chặn phát hành, báo lỗi rõ; cấu hình lại người bán/chữ ký số rồi thử lại |
| Đã phát hành nhưng "chờ xác nhận GDT" | Báo cáo GDT same-day thất bại | Retry tự động; chưa coi là hoàn tất, không phát hành trùng (BR-09) |
| Cố phát hành khi labo chưa bật HĐĐT | Feature tắt / provider chưa cấu hình | Khóa hành động, gợi ý bật + cấu hình; công nợ vẫn dùng đủ (BR-04/BR-05) |
| Phát hành nhầm rồi cần sửa | Sai dữ liệu sau khi đã phát hành | Dùng hủy/điều chỉnh/thay thế, không xóa cứng (giữ lưu trữ 10 năm) (BR-06) |
Mạng lưới & kết nối
Từ nâng cấp tài khoản clinic, liên kết clinic DentIQ, tới go-live một labo. Chi tiết ở Nâng cấp tài khoản clinic, Liên kết clinic DentIQ và Labo go-live.
| Triệu chứng | Nguyên nhân | Khắc phục |
|---|---|---|
| OTP không tới (đổi SIM, mất số, sai số khi seed) | Số đã đăng ký không còn dùng | Nhánh labo vouch: labo có quan hệ xác nhận đúng phòng khám → cập nhật số mới rồi phát OTP về số mới; vẫn phải có OTP đạt trước khi lên claimed (BR-W6) |
| Nhập sai OTP nhiều lần / hết hạn thử thách | Quá 5 lần sai hoặc quá 10 phút | Tự quay claim_pending → light (không mất đơn); resend bị rate-limit; tín hiệu lạm dụng thì → blocked (BR-W8, BR-W5) |
| Hai bên cùng đòi một danh tính | Tranh chấp sở hữu / OTP fail và không có vouch | Chuyển disputed: tạm dừng nâng cấp nhưng vẫn cho đặt đơn; người có quyền đối chiếu bằng chứng rồi kết về claimed/light/blocked (BR-W7) |
| Labo cố tự claim hộ phòng khám | Sai mô hình quyền | Từ chối — chỉ chủ thực claim/merge được; labo chỉ vouch, không chiếm danh tính (BR-W4) |
| Dán mã kết nối DentIQ không đồng ý được | Mã đã hết TTL hoặc đã dùng rồi (dùng-một-lần) | Cạnh → expired; labo phát mã mới rồi dán lại (LC-4) |
Cạnh tự chuyển suspended, đơn không chảy | Webhook lỗi quá ngưỡng hoặc đang xoay secret | Đơn được xếp hàng không mất; sửa webhook/secret rồi nối lại — không cần tạo case lại (LC-5) |
| Đồng ý lại/phát lại tạo cạnh trùng | Lo nhân đôi cạnh kết nối | Không xảy ra: idempotent theo external-ref, một labo ↔ một phòng khám DentIQ đúng một cạnh (LC-1) |
| Phòng khám lo mất dữ liệu khi gỡ kết nối | Hiểu nhầm gỡ = xoá | revoked/suspended/expired không xoá case đã sync; giữ lab_work_order, rớt về thủ công (LC-5) |
| Mời nhiều nhưng không lên đơn | Cạnh dừng ở invited, chưa active | Thước đo là mật độ cạnh sống, không phải số lời mời (NG-3); rep hâm nóng qua Zalo đúng lúc |
| Phòng khám im lâu, không đặt đơn | Quá N ngày không đơn | Hệ thống suy ra dormant; labo/rep hâm nóng → reactivated → active; bỏ lâu hơn khép lại churned (NG-4) |
| Cùng phòng khám xuất hiện nhiều cạnh | Mời trùng | Không tạo cạnh trùng: một labo ↔ một phòng khám đúng một cạnh (NG-1) |
| Đơn đầu tính giá sai / thiếu vật liệu | Chưa cấu hình xong nền trước khi mời | Hoàn tất wizard (vật liệu + công đoạn + bảng giá) trước khi phát lời mời |
Vẫn chưa gỡ được?
Nếu triệu chứng không nằm trong bảng nào ở trên, xem Câu hỏi thường gặp để hiểu vì sao hệ thống hành xử như vậy, hoặc tra Thuật ngữ nếu một khái niệm chưa rõ. Cần hỗ trợ trực tiếp: [email protected].