12 — Khắc phục sự cố thường gặp

Cache

❓ Tôi đã sửa nội dung nhưng site vẫn hiển thị nội dung cũ.

Thứ tự kiểm tra:

1. Refresh trang bằng Ctrl + Shift + R (Windows/Linux) hoặc ⌘ + Shift + R (macOS) — bypass cache trình duyệt.
2. Mở tab ẩn danh (Incognito) và truy cập trang — loại bỏ cache cookie/session.
3. Kiểm tra đã bấm Save trong Desk? Đối với Inline Editor, đã thấy "Đã lưu"?
4. Với Mantis Web Page: field Published đã tick?
5. Nếu vẫn chưa — nhờ Website Manager / dev chạy:

   bench --site <site> clear-website-cache
   bench --site <site> clear-cache
   

6. Với thay đổi block template (dev-only, không phải nội dung): cần bench restart.

404 / Không tìm thấy trang

❓ Trang sản phẩm /products/ trả về 404 dù tôi đã tạo bản ghi.

• Kiểm tra Published = 1 trong Mantis Product.
• Kiểm tra Slug đúng (không dấu, không khoảng trắng).
• Lưu ý: Mantis Product dùng is_published_field = "published" → Frappe sẽ trả 404 ngay cả với editor đã đăng nhập nếu bản ghi chưa publish. Tạm tick Published → xem → untick lại.

❓ Trang /blog trả về danh sách bài blog kiểu mặc định của Frappe, không phải layout của Mantis Tech.

• Website cần được cài app mantistech_web đầy đủ (kiểm tra bench --site <site> list-apps).
• Route rule {"from_route": "/blog", "to_route": "blog"} phải có hiệu lực — nếu không, nhờ dev kiểm tra hooks.py.
• Có thể Mantis Web Page blog đang ẩn (Published = 0).

❓ Trang chi tiết pillar (/solutions/ai) 404.

• Template www/solutions/ai.html là file tĩnh — nếu 404 nghĩa là file bị xoá hoặc chưa build. Cần dev khôi phục.

Inline Editor

❓ Không thấy thanh công cụ Inline Editor trên trang.

• Bạn đã đăng nhập với role Content Editor / Website Manager? Kiểm tra avatar phải có tên của bạn, không phải "Guest".
• Hard refresh (Ctrl+Shift+R) để tải lại JS editor.
• Check console DevTools — nếu có lỗi JS (đỏ), gửi screenshot cho dev.

❓ Click vào chữ/ảnh nhưng không sửa được.

• Đã bật "Bật chỉnh sửa" trên toolbar chưa? Khi đang edit, toolbar hiển thị "Đang chỉnh sửa".
• Một số vùng không có mt-editable (ví dụ danh sách auto-sinh từ DocType) — phải vào Desk sửa DocType nguồn.

❓ Lỗi "Lưu thất bại".

• Kiểm tra mạng (WiFi rớt, VPN).
• Mở DevTools → Network → xem request tới /api/method/mantistech_web.editor_api.* có status 4xx/5xx — gửi screenshot cho dev.
• Session có thể hết hạn. F5 lại Desk để re-login.

Form Liên hệ / Request Demo

❓ Submit form trả lỗi "Xác thực reCAPTCHA thất bại".

• reCAPTCHA site key / secret key chưa cấu hình đúng. Xem 10 — Website Settings §4.3.
• Score của người gửi < 0.5 (bị Google nghi là bot) — điều này là ý đồ.

❓ Form nói "Gửi quá nhanh, thử lại sau 1 phút".

• Rate limit: 5 submit / 60 giây / IP.
• Chờ 1 phút hoặc tạm tắt mt_enable_lead_rate_limit trong Website Settings khi test.

❓ Khách submit xong nhưng không có Lead mới trong /app/lead.

• Xem /app/error-log — có log lỗi không?
• Có thể Frappe lỗi lúc insert (DB connect, custom field missing). Gửi log cho dev.

❓ Không nhận được email thông báo.

• Xem 09 — Xử lý Lead §4.

Hiển thị / Layout

❓ Ảnh bị méo hoặc bể layout sau khi thay.

• Kích thước ảnh chưa đúng aspect ratio. Xem 11 — Kích thước chuẩn.
• Upload lại bằng kích thước đúng.

❓ Text bị tràn trên mobile.

• Tiêu đề quá dài → rút gọn còn < 60 ký tự.
• Paste text có   hoặc ký tự ẩn → dán qua Notepad trước để lọc style.

❓ Navbar thiếu một mục / sai thứ tự.

• Vào Website Settings → Top Bar Items → kiểm tra thứ tự và Parent (cho submenu). Save.

❓ Footer không hiển thị địa chỉ / social link mới.

• Vào Website Settings → Footer Items / Footer Address / Social Links.
• Clear website cache nếu sau 60s vẫn không thấy.

Quyền & Đăng nhập

❓ Tôi không thấy một DocType nào đó trong Desk.

• Có thể role của bạn bị hạn chế. Nhờ Website Manager kiểm tra permission (Role của DocType trong /app/role).
• Content Editor mặc định không thấy: Website Settings, User, System Settings, Lead.

❓ Tôi muốn cấp tài khoản cho biên tập viên mới.

• Nhờ Website Manager / System Manager vào /app/user → + New → điền email, tick role Content Editor, gửi invitation.

Đa ngôn ngữ (nếu bật)

❓ Chuyển ngôn ngữ từ VI sang EN không thấy nội dung EN.

• Có thể trường chưa được dịch. Vào Inline Editor → toggle EN → sửa nội dung EN → Save.
• Toàn site mặc định VI — EN cần được bật rõ ràng trong Website Settings hoặc qua query ?lang=en.

Liên hệ hỗ trợ

Nếu sự cố không nằm trong danh sách trên hoặc cần dev xử lý:

1. Ghi lại:
   • Đường dẫn trang xảy ra lỗi.
   • Thao tác bạn vừa làm (bước-by-bước).
   • Screenshot lỗi (kèm console DevTools nếu có).
   • Role và username của bạn.
2. Gửi cho: Website Manager / PM (Tony) hoặc email contact@mantistech.vn.
3. Tạm thời workaround: nếu là bug hiển thị nghiêm trọng, hãy unpublish trang bị lỗi (hoặc revert đến nội dung cũ) để tránh khách thấy trang lỗi.