Luồng hoạt động của App và SDK/API
TÀI LIỆU KIẾN TRÚC HỆ THỐNG MULTI-TENANT SAAS & TÍCH HỢP SDK/API
Hệ thống lõi đa dịch vụ: Gọi xe, Giao đồ ăn, Ship hộ, Lái hộ, Mua hộ.
1. Tổng Quan Kiến Trúc Lai (Hybrid Architecture)
Hệ thống hoạt động theo mô hình Multi-tenant SaaS, hỗ trợ đồng thời hai phương thức triển khai giao diện (Client-side) nhưng chia sẻ chung một hệ thống logic và hạ tầng core backend:
- Ứng dụng White-label (SaaS Apps): Bộ ứng dụng (User/Driver) được đóng gói độc lập theo thương hiệu của từng khách hàng, gọi trực tiếp vào API Core thông qua định danh ứng dụng.
- Bộ giải pháp Headless API & SDK: Cung cấp cho các ứng dụng của bên thứ ba (đối tác đã có ứng dụng sẵn) để nhúng trực tiếp các tính năng gọi xe/giao hàng. SDK đóng vai trò như một lớp trung gian, chuẩn hóa dữ liệu và xử lý các kết nối real-time tương đương như một ứng dụng White-label.
[ HÌNH 01: SƠ ĐỒ TỔNG QUAN KIẾN TRÚC HỆ THỐNG ]
(Mô tả luồng tương tác giữa SaaS Apps, 3rd Party App qua SDK kết nối tới API Gateway và Real-time Server)
2. Cơ Chế Phân Ranh Giới Dữ Liệu (Multi-tenancy)
Để đảm bảo tính độc lập dữ liệu giữa các ứng dụng White-label và các đối tác tích hợp SDK, hệ thống áp dụng cơ chế định tuyến dựa trên Tenant ID:
Nguyên tắc đồng bộ dữ liệu: Mọi yêu cầu cấu hình, đăng ký, khởi tạo đơn hàng từ SDK hoặc App White-label khi gửi về API Gateway bắt buộc phải đính kèm mã định danh đối tác (Tenant Identifier). Backend Core sẽ dựa vào mã này để phân tách phân vùng cơ sở dữ liệu (Database Isolation hoặc Row-level Security).
3. Quy Trình Đăng Ký Tài Khoản Qua SDK & API
Khi ứng dụng của bên thứ ba thực hiện đăng ký tài khoản cho User hoặc Tài xế, SDK sẽ thực hiện đóng gói dữ liệu để đảm bảo tính đồng nhất:
| Đối tượng | Cơ chế xử lý của SDK & API |
|---|---|
| Khách hàng (User) | Gọi hàm đăng ký từ SDK -> SDK đính kèm Tenant-ID -> Đẩy về Auth Service -> Tạo tài khoản người dùng thuộc phân vùng của đối tác đó. Đảm bảo dữ liệu mapping chính xác tương đương App White-label. |
| Tài xế (Driver) | Đăng ký thông tin qua giao diện nhúng SDK -> Gửi dữ liệu về hệ thống phê duyệt -> Sau khi kích hoạt, SDK kích hoạt kết nối nền lắng nghe (Listen) luồng nổ đơn theo đúng cấu hình Tenant của tài xế. |
[ HÌNH 02: BIỂU ĐỒ TUẦN TỰ (SEQUENCE DIAGRAM) LUỒNG ĐĂNG KÝ QUA SDK ]
(Mô tả các bước: 3rd Party App -> SDK đóng gói + Tenant ID -> API Gateway -> Auth Service -> Database)
4. Quy Trình Đặt Đơn & Điều Phối Nổ Đơn Real-Time
Cơ chế cốt lõi để duy trì tính năng vận hành thời gian thực (Real-time) cho hệ thống dựa trên sự phối hợp giữa Firebase và Socket.io:
- Khởi tạo đơn hàng: Khi User (tại App đối tác hoặc App White-label) thực hiện lệnh đặt đơn (Giao đồ ăn, ship hộ, lái hộ,...), một request chứa thông tin tọa độ, dịch vụ và Tenant ID được gửi về
Order Service. - Xử lý điều phối: Hệ thống core backend ghi nhận trạng thái đơn hàng mới, lập tức kích hoạt bộ chuyển mạch điều phối (Dispatch Engine) để quét tìm tài xế khả dụng gần nhất thuộc cùng hệ sinh thái/Tenant cấu hình.
- Kênh truyền tải Real-time: Dispatch Engine đẩy một sự kiện (Event) nổ đơn qua cụm máy chủ Real-time (Firebase Notification / Socket.io Gateway).
- Nhận tín hiệu nổ đơn: Tất cả tài xế đang ở trạng thái trực tuyến (Bao gồm tài xế chạy app White-label và tài xế chạy app tích hợp SDK) có cơ chế lắng nghe chung một cấu trúc dữ liệu socket/firebase. Thiết bị của tài xế phù hợp sẽ nhận tín hiệu, SDK/App phân tích gói dữ liệu và tự động kích hoạt màn hình nhận đơn ngay tức thì.
[ HÌNH 03: SƠ ĐỒ LUỒNG ĐIỀU PHỐI ĐƠN HÀNG THỜI GIAN THỰC ]
(Thể hiện luồng từ lúc Đặt đơn -> Dispatch Engine xử lý -> Kích hoạt Firebase/Socket.io -> Bắn đơn đồng thời xuống App White-label Driver và SDK Driver)
Kết luận kỹ thuật: Toàn bộ cấu trúc payload dữ liệu, tham số truyền nhận API, và cơ chế bắt sự kiện (Event Listener) qua socket/firebase của hệ thống SDK đều được thiết kế chuẩn hóa, đồng nhất 1:1 với ứng dụng SaaS White-label gốc. Điều này giúp tối ưu hóa tài nguyên bảo trì backend và tối đa tốc độ tích hợp cho đối tác thứ ba.
