Sơ Đồ Luồng Tích Hợp Toàn Trình (Workflow)

Tài liệu mô tả chi tiết chu trình tương tác giữa Ứng Dụng Client (Mobile/Web App), Pango GraphQL Gateway và Firebase Firestore Realtime từ lúc khởi tạo đến khi hoàn tất nhận câu trả lời.

---

1. Sơ Đồ Tuần Tự (Sequence Diagram)

---

2. Diễn Giải Từng Bước Xử Lý

Bước 1: Kiểm Tra Cấu Hình Bật/Tắt (Pre-flight Check)

• Hành động: Gửi query AgentConfigDetail(code: "buddy").
• Mục đích: Xác định trạng thái hoạt động của Agent trước khi người dùng tương tác.
• Xử lý nhánh:
  • Nếu isEnabled == false: Ẩn hoàn toàn nút Chat hoặc hiển thị tooltip bảo trì (disabledAnswer). Tuyệt đối không gọi thêm request đăng nhập để tiết kiệm tài nguyên.
  • Nếu isEnabled == true: Hiển thị nút chat và cho phép tiếp tục.

Bước 2: Đăng Nhập & Lấy Access Token

• Hành động: Gửi mutation ExternalLogin kèm mã băm Checksum (MD5).
• Mục đích: Xác thực danh tính người dùng trong hệ thống AI và lấy chuỗi accessToken ngắn hạn (JWT).
• Lưu trữ: Lưu accessToken vào Secure Storage (Keychain / Keystore đối với Mobile, hoặc LocalStorage/Cookie đối với Web).

Bước 3: Tải Lịch Sử Tin Nhắn Cũ

• Hành động: Gửi query MyConversation với limit: 20 hoặc 50.
• Mục đích: Hiển thị lại ngữ cảnh đàm thoại trước đó của người dùng.
• Xử lý UX & Tin nhắn dở dang:
  • Sau khi nạp xong, Client cần tự động gán scrollTop = scrollHeight để cuộn xuống tin nhắn mới nhất.
  • Xử lý dang dở (Status PENDING): Nếu tin nhắn cuối cùng từ bot có status == "PENDING" (do người dùng từng tắt app hoặc mất mạng giữa chừng), Client chuyển ngay sang trạng thái "Đang trả lời..." và mở kết nối Firestore lắng nghe document này để tiếp nhận kết quả khi AI hoàn thành.

Bước 4: Gửi Câu Hỏi Cho AI

• Hành động: Gửi mutation SendAiMessage.
• Mục đích: Bắt đầu một lượt hỏi đáp mới với AI.
• Tính năng đặc thù: API phản hồi ngay lập tức sau khoảng 200ms với payload { chatSessionId, assistantMessageId, idempotencyKey } mà không bắt Client phải chờ kết quả AI sinh văn bản hoàn chỉnh.

Bước 5: Lắng Nghe Câu Trả Lời Realtime Stream

• Hành động: Lắng nghe Document Firestore theo path quy định bằng SDK onSnapshot.
• Mục đích: Nhận từng mảnh văn bản (Streaming tokens) hiển thị mượt mà trên màn hình.
• Kết thúc: Khi requestStatus chuyển sang COMPLETED, FAILED hoặc CANCELLED, Client tự động gọi unsubscribe() để đóng kết nối và giải phóng tài nguyên.