Tổng Quan Tích Hợp GraphQL (Mẫu)

🛡️ Lưu Ý Về An Toàn & Bảo Mật Schema Mẫu (Example Schemas): Nhằm bảo vệ an toàn kiến trúc hệ thống và tránh lộ mã nguồn, toàn bộ danh mục Schema, Mutation, Query và tên các trường (Fields) dưới đây được trình bày ở dạng mẫu minh họa (Example/Mock Schemas). Hợp đồng tích hợp (Contract Schema) chính thức và thông tin môi trường chi tiết sẽ được Pango AI Team bàn giao riêng theo từng thỏa thuận đối tác.

Hệ thống Pango Chatbot Service có bộ GraphQL/API và SSO Authentication cốt lõi được thiết kế chuẩn mực theo kiến trúc bảo mật.

1. Bảng Tóm Tắt Tích Hợp GraphQL (Mẫu)

Thao Tác Mẫu	Kiểu	Mô Tả Chức Năng	Yêu Cầu Token
ExampleAgentConfig	`Query`	Kiểm tra cấu hình trạng thái của trợ lý AI (Pre-flight check)	Bắt buộc
ExampleExternalLogin	`Mutation`	Đăng nhập tài khoản trên hệ thống đối tác & cấp Access Token Hoặc dùng cơ chế SSO Authentication	Cần Checksum MD5
ExampleSendAiMessage	`Mutation`	Gửi câu hỏi cho AI và nhận session ID khởi tạo	Bắt buộc
ExampleMyConversation	`Query`	Tải danh sách lịch sử hội thoại phân trang	Bắt buộc
ExampleChatSessionDetail	`Query`	Tải toàn bộ tin nhắn thuộc một Session chỉ định	Bắt buộc
ExampleSubmitFeedback	`Mutation`	Gửi đánh giá 1-5 sao và phản hồi chất lượng câu trả lời	Bắt buộc
ExampleCloseSession	`Mutation`	Đóng phiên làm việc hiện tại khi người dùng làm mới chat	Bắt buộc

Bảng Phạm Vi Các Nhóm GraphQL Mở Rộng

Ngoài 7 thao tác tiêu chuẩn trên, Chatbot Service còn có các nhóm GraphQL/API để tích hợp thêm luồng quản trị, vận hành, báo cáo và Widget:

Nhóm GraphQL/API	Luồng tích hợp tham khảo
General	Contract & Authentication, Enum, Response/Error, Upload và Firebase Realtime.
Authentication & Profile	Login, refresh token, hồ sơ tài khoản, đổi mật khẩu, reset password và logout.
Account Management	Danh sách, tìm kiếm/lọc, chi tiết, tạo, cập nhật, trạng thái và reset tài khoản.
Team Management	Team, thành viên, tìm kiếm, phân công tài khoản và thiết lập quota theo team.
Agent Management	Danh sách, tìm kiếm, cấu hình, trạng thái, chi tiết và query metrics của Agent.
Quota Management	Danh sách, tìm kiếm, tạo, cập nhật, trạng thái và reset quota.
Usage & Export	Lưu lượng sử dụng, phiên chat, chi tiết session và export CSV.
Chat Screen	Tạo session, hội thoại, lịch sử, regenerate AI message, feedback và đóng session.
Feedback Management	Danh sách, tìm kiếm, chi tiết, reply, execution link và export feedback.
Firebase Realtime	Tạo Firebase Custom Token và hỗ trợ các luồng cập nhật realtime.
Admin & Destructive Actions	Soft delete account/team/Agent/quota/session/feedback và xử lý hội thoại bị chặn.
Chatbot Widget Integration	Suggestion request, additional context, regenerate suggestion, feedback, external login và hội thoại theo `exConversationId`.

Pango Chatbot AI vẫn hỗ trợ Restful API để tích hợp. Danh mục này chỉ mô tả phạm vi tích hợp tổng quát như Schema, tên operation, quyền truy cập và contract chi tiết sẽ được cung cấp theo scope hợp tác.

2. Quy Ước Chung Khi Gọi GraphQL

Endpoint Duy Nhất: https://domain-pango-chatbotai-svc/graphql
Phương Thức: Luôn sử dụng HTTP POST.

Cấu Trúc Body Chuẩn:

{
  "query": "query ExampleOperationName(...) { ... }",
  "variables": { ... },
  "operationName": "ExampleOperationName"
}

Cấu Trúc Response Thành Công:

{
  "data": {
    "exampleOperationName": {
      ...
    }
  }
}

Cấu Trúc Response Khi Gặp Lỗi:

{
  "errors": [
    {
      "message": "Thông điệp mô tả lỗi",
      "locations": [{ "line": 2, "column": 3 }],
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ],
  "data": null
}

3. Nhận Phản Hồi Realtime Qua Firebase Firestore (Mô Hình Mẫu)

ExampleSendAiMessage trả về session_id và assistant_msg_id trước khi AI hoàn tất câu trả lời. Client dùng assistant_msg_id để lắng nghe Firestore, thay vì polling liên tục.

chat_sessions/messages/{assistant_msg_id}

`stream_status`	Client cần làm gì?
`IN_PROGRESS`	Cập nhật `message` lên giao diện và tiếp tục lắng nghe.
`COMPLETED`	Hiển thị hoàn tất và gọi `unsubscribe()`.
`FAILED`	Hiển thị lỗi và gọi `unsubscribe()`.
`CANCELLED`	Dừng phiên và gọi `unsubscribe()`.

Ví dụ tối thiểu:

const unsubscribe = onSnapshot(doc(db, documentPath), (snapshot) => {
  const data = snapshot.data();
  updateMessage(data?.message ?? '');

  if (['COMPLETED', 'FAILED', 'CANCELLED'].includes(data?.stream_status)) {
    unsubscribe();
  }
});

Xem thêm chi tiết Firebase listener nếu cần cấu hình Firebase SDK, timeout và xử lý lỗi đầy đủ.

4. Best Practices Cốt Lõi

Kiểm tra AgentConfigDetail trước khi hiển thị nút Chat.
Vô hiệu hóa nút gửi trong lúc xử lý và dùng idempotencyKey để tránh request trùng.
Tự động cuộn khi người dùng đang ở cuối khung chat; không ép cuộn khi họ đang xem lịch sử.
Đặt timeout cho listener và luôn gọi unsubscribe() khi stream kết thúc hoặc màn hình bị đóng.
Lưu token an toàn và chỉ gọi lại ExternalLogin khi token hết hạn hoặc nhận lỗi 401.