Khái niệm cốt lõi

Mọi thứ trong Averosi đều chạy qua một cấu trúc duy nhất: canonical event (sự kiện đã chuẩn hóa). Payload webhook thô được chuẩn hóa thành canonical event, gắn attribution, lưu lại, rồi fan-out tới mọi đích đã kết nối qua một hàng đợi job có cơ chế thử lại. Trang này giải thích từng phần.

Workspace

Mọi bản ghi trong Averosi — endpoint, cấu hình attribution, connection, event, sync job — đều thuộc về một workspace. Người dùng mới được cấp một workspace ngay lần đăng nhập đầu tiên, kèm sẵn một cấu hình attribution mặc định, một webhook endpoint, và các destination connection sẵn sàng để cấu hình.

Canonical events

Dữ liệu mà form, cửa hàng, hay webhook gửi lên vốn dĩ không đồng nhất — mỗi nguồn có một cấu trúc payload riêng. Averosi chỉ xác thực phần bao ngoài và giữ nguyên toàn bộ nội dung dưới dạng raw; phần còn lại được chuẩn hóa về một trong 5 loại event chuẩn:

Một canonical event gồm type, occurred_at, một source (ngữ cảnh channel/gclid/UTM), một payload (dữ liệu nghiệp vụ đã chuẩn hóa, ví dụ lead), một đối tượng attribution, nội dung gốc raw, và một dedupe_key để gộp các lượt submit trùng lặp.

Ingest endpoint

Mỗi workspace có một hoặc nhiều ingest endpoint dùng token tại POST /api/hooks/<token>. Token này trỏ tới một workspace và một cấu hình attribution; endpoint xác thực JSON body, chạy qua normalizeLead() để tạo ra một canonical event lead_created, lưu lại (có tính idempotent — trùng dedupe_key được coi là thành công mà không tạo bản ghi mới), rồi enqueue job giao tin cho mọi đích đang hoạt động. Xem Webhook & API để biết chính xác cấu trúc payload.

Attribution

Một cấu hình attribution định nghĩa các quy tắc trích xuất — đường dẫn dot-notation (ví dụ query_params.gclid) để lấy ra các field đã biết (gclid, utm_source, utm_medium, utm_campaign, utm_term, utm_content, referrer, landing_page, lead_email, lead_phone, lead_name) từ payload gốc, bất kể cấu trúc payload đó ra sao — cộng với quy tắc chuẩn hóa (trim, viết thường, riêng các định danh như gclid và email được giữ nguyên chữ hoa/thường).

Việc phân loại channel khá đơn giản: có gclid nghĩa là google_ads; nếu không, channel lấy theo utm_source, hoặc rơi về giá trị mặc định đã cấu hình (ví dụ direct). Mô hình hiện tại là last-touch — đối tượng attribution ghi lại tên model, chiến lược, cửa sổ lookback, và source/campaign/keyword/gclid khớp được lấy thẳng từ ngữ cảnh UTM/click đã trích xuất. Quản lý tại Nguồn chuyển đổi.

Destination (đích đến)

Mọi tích hợp đầu ra (Telegram, Zalo OA, Google Sheets, HubSpot, Webhook tổng quát) đều là một đích đến — nơi một lead được gửi tới. Chúng hoạt động giống nhau, nên một canonical event được fan-out tới mọi destination connection đang hoạt động trong workspace — xem Kết nối để thiết lập.

Hàng đợi job & worker

Việc giao tin không xảy ra ngay khi ingest. Thay vào đó, enqueueEventJobs() ghi một dòng sync_jobs cho mỗi destination connection đang hoạt động, dùng khóa <event_id>:<connection_id> để lần chạy lại không bao giờ giao tin trùng. Một worker chạy nền lấy các job đến hạn theo lô, gọi deliver() của destination, và ghi lại kết quả:

• Thành công — job và connection được đánh dấu khỏe mạnh.
• Thất bại (có thể thử lại) — job được lên lịch lại theo backoff tăng dần theo cấp số nhân (30 giây khởi điểm, nhân đôi mỗi lần, tối đa 1 giờ) cho tới khi đạt max_attempts.
• Chết (dead) — lỗi không thể thử lại hoặc đã hết số lần thử sẽ rơi vào trạng thái này; worker cũng phát sinh một canonical event sync_failed để lỗi hiển thị trên Giám sát, chứ không chỉ nằm trong bảng job.