Haravan Helpdesk

Giao diện

🛠️ Phân công Kỹ thuật Chi tiết (Cửa A & C) ​

Mục tiêu: Bổ sung tài liệu làm rõ trách nhiệm ("Ai làm gì?") ở cấp độ kỹ thuật liên quan đến API, Webhook, Script, và Test để hai bên Haravan và Tư vấn (Tody) phối hợp dứt điểm hoàn toàn dự án, tiến hành go-live.

Cửa A — Cấu hình Email (Bắt buộc trước triển khai) ​

Luồng Kịch bản-001 (Email vào → Tự động tạo phiếu) đang bị chặn lại ở bước kết nối hộp thư support@haravan.com.

🔵 Việc Haravan cần làm (IT/Quản trị hệ thống) ​

  1. Chuẩn bị cấu hình: Lấy thông số (Host, Port) cho máy chủ IMAP (để nhận email) và SMTP (để gửi email).
  2. Xác thực ứng dụng: Tạo Mật khẩu ứng dụng (App Password) riêng cho hệ thống Frappe thay vì dùng mật khẩu chính (đặc biệt với Google Workspace/M365).
  3. Mở khóa tường lửa: Đảm bảo hệ thống mail không chặn luồng truy cập/gửi mail từ địa chỉ IP của máy chủ haravandesk.s.frappe.cloud.

🟢 Việc Tôi cần làm (Tody / Nhóm Tư vấn) ​

  1. Khai báo Frappe: Cấu hình Email Domain và Email Account trong Frappe bằng thông số Haravan cung cấp.
  2. Kiểm tra luồng (Test): Sử dụng công cụ chẩn đoán của Frappe để test gửi một email báo cáo, và test nhận thư từ bên ngoài. Xác nhận Kịch bản-001 hoạt động trơn tru.

Cửa C — Tích hợp Giai đoạn 2 (Wave 2) ​

Sau khi Helpdesk vận hành ổn định thực tế (Core go-live), chúng ta sẽ bước sang tích hợp với hệ thống bên ngoài. Dưới đây là hợp đồng kết nối (Endpoint contract) rõ ràng cho 6 hạng mục.

1. Hàm Inside API enrichment (Bổ sung thông tin khách hàng) ​

Cơ chế: Chạy tự động trích xuất thông tin khách hàng từ hệ thống Inside của Haravan.

  • 🔵 Haravan cần làm:
    • Cung cấp tài liệu API Inside (Swagger/Postman).
    • Cung cấp Endpoint URL truy vấn theo email hoặc số điện thoại.
    • Cung cấp phương thức xác thực (Bearer Token hoặc API Key).
  • 🟢 Tôi cần làm:
    • Script: Viết một Server Script (Python) trong Frappe để bật event after_insert mỗi khi tạo phiếu.
    • API Call: Khởi tạo lời gọi (call API) sang hệ thống Inside dựa trên SĐT/Email của phiếu, lấy dữ liệu và gán ngược lại vào các trường Custom Fields (Khu vực, Cấp độ, Nhân viên sales phụ trách).
    • Test: Đoạn test nội bộ API Call trên console để bảo đảm không làm chậm quá trình tạo Ticket.

2. Haravan Bitrix → Frappe Helpdesk (Won Deal) ​

Cơ chế: Khi một Deal trong Bitrix được đóng thành công (Thắng), tự động chuyển sang Frappe tạo Phiếu Yêu cầu triển khai.

  • 🔵 Haravan cần làm:
    • Webhook: Cấu hình Outbound Webhook/Automation Rule trên hệ thống Bitrix.
    • Logic: Khi Deal = "Won", hệ thống Bitrix chủ động gửi HTTP POST Request chứa payload (JSON) sang phía Frappe.
  • 🟢 Tôi cần làm:
    • API Target: Mở sẵn Frappe REST API Endpoint (VD: POST /api/resource/HD Ticket hoặc phương thức tùy chỉnh).
    • Auth: Cấp phát API Key & API Secret (Token) của Frappe cho kỹ thuật viên Haravan để nhúng vào header Bitrix.
    • Data Map: Hướng dẫn Haravan định dạng gói JSON payload gửi đi (Trường nào bên Bitrix nối vào trường nào bên Frappe).

3. Frappe Helpdesk → Haravan Bitrix (Gia hạn / Renewal) ​

Cơ chế: Khi Phòng Dịch vụ hoàn tất phiếu gia hạn, Frappe thông báo lại cho Bitrix (hoặc Inside) để tính doanh số/KPI.

  • 🔵 Haravan cần làm:
    • Cung cấp Inbound Webhook URL (Hoặc REST API endpoint) của Bitrix để nhận lệnh.
    • Cung cấp Token/Key xác thực cho đường dẫn đó.
  • 🟢 Tôi cần làm:
    • Script/Webhook: Viết Server Script trên Frappe để kích hoạt khi Ticket (Nhãn: Gia Hạn) đổi Status thành "Đã đóng" hoặc "Hoàn tất".
    • Bắn một HTTP POST đẩy kết quả xử lý sang thiết lập Bitrix tương ứng từ Haravan. Nhận & ghi log kết nối.

4. Frappe Helpdesk → GitLab (Báo cáo Bug Issue) ​

Cơ chế: Nhân viên CS phân loại phiếu lỗi, Helpdesk tạo Issue trên GitLab để kỹ sư xử lý.

  • 🔵 Haravan cần làm:
    • Xác thực: Cấp một Personal Access Token (PAT) hoặc Bot Token trên hệ thống GitLab với quyền tạo Issue.
    • ID Dự án: Cung cấp ID của thư mục/Group Project GitLab liên quan.
  • 🟢 Tôi cần làm:
    • Scripting: Lập trình Frappe theo dõi khi Agent dán loại lỗi và ấn Nút "Chuyển Bug".
    • API Data: Đóng gói thông tin lỗi, lịch sử chat trao đổi dán vào một GitLab Issue mới thông qua gọi GitLab REST API. Sau khi tạo, ghi lại GitLab Issue ID (VD: #1234) ngược vào Phiếu Frappe.

5. GitLab → Frappe Helpdesk (Đồng bộ trạng thái) ​

Cơ chế: Dev Haravan sửa code và đóng Issue trên GitLab, Helpdesk tự biết trạng thái để báo khách.

  • 🔵 Haravan cần làm:
    • Webhook GitLab: Cấu hình Webhook trong Project GitLab để bắn sự kiện (event trigger) về phía Frappe khi Issue Activity thay đổi (ví dụ: chuyển từ Todo -> Done).
  • 🟢 Tôi cần làm:
    • API Contract: Viết một đoạn mã Whitelisted API Event (endpoint mở đặc chế trên Frappe) để hứng webhook của GitLab.
    • Logic đồng bộ: Bóc tách Webhook GitLab, tìm đúng cái Phiếu Frappe mang GitLab Issue ID tương ứng để đổi tình trạng. (VD: Đổi trạng thái phiếu Frappe thành "Đã sửa lỗi - Đợi theo dõi").

6. Đăng nhập một lần (SSO) qua Haravan ID (OAuth 2.0) ​

Cơ chế: Cho phép nhân viên Haravan dùng tài khoản công ty để log vào Helpdesk nhanh chóng.

  • 🔵 Haravan cần làm:
    • OAuth App: Khởi tạo một Client App trên nền tảng Haravan ID.
    • Cung cấp Client ID và Client Secret.
    • Thiết lập Redirect URI chấp thuận từ https://haravandesk.s.frappe.cloud/api/method/frappe.integrations.oauth2_logins.custom/....
  • 🟢 Tôi cần làm:
    • Khai báo thiết lập Social Login Key trong Frappe. Định tuyến quy tắc liên kết: lấy email, first_name, last_name từ Haravan ID map vào Frappe User Account.
    • Đảm bảo khi ấn đăng nhập, người dùng được nhận diện đúng Nhóm/Phòng ban.

🎯 Chốt lại:

  • Tài liệu này cung cấp danh sách "mảnh ghép" cứng rắn.
  • Kỹ thuật viên hai bên có thể làm việc ngay theo bảng này mà không cần chờ họp hành bổ sung.
  • Cửa C sẽ song song viết code, do Tody review Code và Test Gate cuối.