Tài Liệu Thiết Kế Tổng Quan — API Backend Traffic Tools V2

1. Mục Đích Và Vai Trò

Project api/ là backend engine trung tâm của hệ thống Traffic Tools V2. Đây là nơi duy nhất lưu trữ toàn bộ dữ liệu cấu hình (chiến dịch, proxy, từ khóa, tài khoản người dùng), xử lý xác thực JWT, phân phối tác vụ đến các node thực thi và thu thập kết quả.

Ứng dụng được xây dựng bằng Go framework Fiber v2 và lắng nghe trên cổng 33003 theo mặc định. Nó giao tiếp với ba hệ thống chính:

Admin Dashboard (admin/): Nhận yêu cầu từ người quản trị thông qua REST API có xác thực JWT. Mọi thao tác cấu hình, giám sát và báo cáo đều đi qua lớp này.

tools_v2: Nhận yêu cầu tác vụ từ worker engine, trả về tác vụ cần thực thi, xử lý webhook kết quả. Đây là luồng dữ liệu thời gian thực quan trọng nhất.

Máy chủ Worker: Giao tác vụ qua API POST và nhận kết quả qua webhook GET/POST. Worker không có quyền truy cập trực tiếp vào database.

2. Ngăn Xếp Công Nghệ

Thành Phần	Công Nghệ	Phiên Bản	Vai Trò
Ngôn ngữ	Go	1.22.4	Ngôn ngữ nền tảng — compiled, statically typed
Web Framework	Fiber v2	v2.52.5	HTTP router và middleware chain
WebSocket	gofiber/contrib/socketio	v1.1.3	Real-time socket cho giám sát live server
ORM	GORM	v1.25.12	Tương tác với MySQL (models, migrations)
Driver MySQL	go-sql-driver/mysql	v1.8.1	Kết nối thấp đến MySQL
Driver MongoDB	go.mongodb.org/mongo-driver	v1.17.1	Tương tác trực tiếp với MongoDB
Cache	go-redis/redis v8	v8.11.5	Redis — lưu token blacklist, cache dữ liệu
In-memory Cache	patrickmn/go-cache	v2.1.0	Cache nhanh trong RAM không cần Redis
Scheduler	gocron/v2	v2.12.4	Cron job điều phối tác vụ định kỳ
Cron parser	robfig/cron/v3	v3.0.1	Parse biểu thức cron từ .env
JWT	gofiber/contrib/jwt	v1.0.10	Middleware xác thực JWT trên route bảo vệ
JWT parser	golang-jwt/jwt/v5	v5.2.1	Tạo và verify JWT token
TOTP	xlzd/gotp	v0.1.0	Tạo mã 2FA theo chuẩn TOTP (Google Auth)
Config	spf13/viper	v1.19.0	Đọc `.env` file vào struct typed
Logger	go.uber.org/zap	v1.27.0	Structured logging hiệu suất cao
Log Rotation	lumberjack.v2	v2.2.1	Tự động cuộn file log theo ngày/kích thước
Validator	go-playground/validator/v10	v10.22.1	Validate DTO struct từ request body
Excel Export	xuri/excelize/v2	v2.9.0	Xuất báo cáo dạng .xlsx
UUID	google/uuid	v1.6.0	Tạo UUID cho các entity mới
Utility	samber/lo	v1.47.0	Generics utilities (map, filter, contains)
Crypto	golang.org/x/crypto	v0.30.0	Mã hóa password bcrypt
AWS SDK	aws/aws-sdk-go	v1.55.8	Tích hợp upload file lên S3/DigitalOcean Spaces
DI Container	go.uber.org/dig	v1.18.0	Dependency injection framework
Mattermost	(HTTP client)	—	Gửi thông báo qua Mattermost

3. Sơ Đồ Luồng Dữ Liệu Tổng Thể

Admin Dashboard (Vue 3)
        |
        | JWT REST API (port 33003)
        v
+----------------------------------------------------------+
|                  Go Fiber API Server                     |
|                                                          |
|  +---------------+  +-------------+  +---------------+  |
|  |  Auth Layer   |  |  Business   |  |  Cron Jobs    |  |
|  |  (JWT/2FA/    |  |  Layer      |  |  (gocron)     |  |
|  |   Device-     |  |  (36 module)|  |  (15+ jobs)   |  |
|  |   Token)      |  |             |  |               |  |
|  +-------+-------+  +------+------+  +-------+-------+  |
|          |                 |                 |           |
|          +-----------------+-----------------+           |
|                            |                             |
|               +------------+------------+                |
|               |    Data Access Layer    |                |
|               |  GORM (MySQL)           |                |
|               |  mongo-driver (MongoDB) |                |
|               |  go-redis (Redis)       |                |
|               +------------+------------+                |
+----------------------------+-----------------------------+
                             |
          +------------------+------------------+
          v                  v                  v
       MySQL              MongoDB             Redis
   (user, proxy,       (task_log,          (token,
    campaign,           evidence,           session,
    keyword,            reports,            cron lock)
    server, task)       keyword_result)

4. Kiến Trúc Route — Nhóm API Đầy Đủ

Toàn bộ route được khai báo trong bootstrap/routes.go. Có ba loại route chính:

4.1. Route Công Khai (Không Xác Thực)

Method	Path	Handler	Mục Đích
GET	`/`	inline	Trả về thông tin cơ bản API
POST	`/api/user/login`	`userHandler.Login`	Đăng nhập, nhận JWT token
POST	`/api/user/register`	`userHandler.Create`	Đăng ký tài khoản mới
GET	`/api/reset-create-task`	`taskHandler.ResetCreateTask`	Reset tác vụ bị kẹt
POST	`/api/task/request`	`taskHandler.RequestTasks`	tools_v2 yêu cầu tác vụ mới
POST	`/api/report/request-task`	`reportDashboardHandler.RequestReportTask`	tools_v2 yêu cầu tác vụ báo cáo
GET	`/api/campaign/reports`	`campaignHandler.GetReport`	Báo cáo chiến dịch
GET	`/api/campaigns/reports`	`campaignHandler.GetAllReports`	Báo cáo tất cả chiến dịch
GET	`/api/servers/reports`	`serverHandler.GetReport`	Báo cáo server
`*`	`/api/reports/...`	`reportHandler`	Báo cáo CSV (công khai để download)
`*`	`/api/dashboard/...`	`dashboardHandler`	Data cho Looker Studio (công khai)
POST	`/api/monitor`	`monitorHandler.Monitor`	Ping giám sát từ worker
`*`	`/api/system-settings/...`	`systemSettingsHandler`	Cấu hình hệ thống
`*`	`/api/evidence/...`	`evidenceHandler`	Truy vấn ảnh bằng chứng

4.2. Route Webhook (Luôn Công Khai)

Webhook routes được đặt dưới prefix /webhook và tuyệt đối không được thêm authentication middleware. Đây là điểm nhận callback từ worker và tools_v2.

Path	Mô Tả
`/webhook/task/update-status`	Worker cập nhật trạng thái tác vụ sau khi hoàn thành
`/webhook/task/update-process`	Worker cập nhật tiến trình thực thi theo thời gian thực
`/webhook/proxy/get-proxy`	Worker yêu cầu proxy IP cho tác vụ mới
`/webhook/keyword-result`	Ghi nhận kết quả tìm kiếm từ khóa từ worker
`/webhook/report/...`	Webhook xử lý kết quả báo cáo từ tools_v2
`/webhook/coccoc-token/...`	Nhận token CocCoc từ worker sau khi đăng nhập

4.3. Route Bảo Vệ (Yêu Cầu JWT)

Áp dụng hai middleware theo thứ tự:

middleware.AuthMiddleware — Kiểm tra Device-Token header trong database MySQL và kiểm tra session timeout.

middleware.JWTMiddleware — Verify chữ ký JWT bằng JWT_SECRET và kiểm tra session timeout trong Redis.

Module	Path Prefix	Handler Module
User	`/api/user`	`internal/user/handler`
Campaign	`/api/campaign`	`internal/campaign/handler`
Server	`/api/server`	`internal/server/handler`
Project	`/api/project`	`internal/project/handler`
Project Detail	`/api/project-detail`	`internal/project_detail/handler`
Task Log	`/api/task-log`	`internal/task_log/handler`
Activity Log	`/api/activity-log`	`internal/activity_log/handler`
Proxy	`/api/proxy`	`internal/proxy/handler`
Backup Proxy	`/api/backup-proxy`	`internal/backup_proxy/handler`
Proxy IP Log	`/api/proxy-ip-log`	`internal/proxy_ip_log/handler`
Proxy Provider	`/api/proxy-providers`	`internal/proxy_providers/handler`
Proxy Package	`/api/proxy-packages`	`internal/proxy_packages/handler`
Profile	`/api/profiles`	`internal/profiles/handler`
Keyword	`/api/keywords`	`internal/keyword/handler`
Keyword Analytics	`/api/keyword-analytics`	`internal/keyword_analytics/handler`
Keyword Result	`/api/keyword-result`	`internal/keyword_result/handler`
Keyword Schedule	`/api/keyword-schedule`	`internal/keyword_schedule/handler`
Setup Fire	`/api/setup-fire`	`internal/setup_fire/handler`
Location	`/api/locations`	`internal/location/handler`
Files	`/api/files`	`internal/storage/handler`
Server Hourly Report	`/api/server-hourly-report`	`internal/server_hourly_report/handler`
Admin Dashboard	`/api/dashboard/admin/...`	Admin middleware + `dashboardHandler`

5. Hệ Thống Cron Job

Tất cả cron job được khởi tạo trong bootstrap/cron/cron.go và chạy theo biểu thức cron cấu hình qua .env. Có 15+ cron job chạy song song:

Tên Cron	Biến Env	Tần Suất	Chức Năng
Task Send	`SCHEDULE_SEND_TASK`	Mỗi phút	Giao tác vụ mới đến các server worker
Task Reset	`SCHEDULE_RESET_TASK`	Mỗi 10 phút	Reset các tác vụ bị kẹt quá lâu
Report Traffic	`SCHEDULE_REPORT_TRAFFIC`	Mỗi 2 giờ (2h-22h)	Tổng hợp báo cáo traffic
Report Traffic Extra	`SCHEDULE_REPORT_TRAFFIC_EXTRA`	23:59 mỗi ngày	Báo cáo cuối ngày
Server Hourly Report	`SCHEDULE_SERVER_HOURLY_REPORT`	Mỗi đầu giờ	Báo cáo tình trạng từng server
Search Keyword	`SCHEDULE_SEARCH_KEYWORD`	Mỗi 30 phút	Kiểm tra thứ hạng từ khóa
Confirm Fire	`SCHEDULE_CONFIRM_FIRE`	Mỗi 30 phút	Xác nhận các tác vụ đã hoàn thành
Proxy Change Active	`SCHEDULE_CHANGE_ACTIVE_PROXY`	Theo cấu hình	Kích hoạt/vô hiệu hóa proxy theo lịch
Project Dead Check	`SCHEDULE_CHECK_PROJECT_DEAD`	Theo cấu hình	Phát hiện project không còn hoạt động
Backup Proxy Update	(hardcoded 5 phút)	Mỗi 5 phút	Cập nhật danh sách backup proxy
Backup Proxy Health	(hardcoded 2 phút)	Mỗi 2 phút	Kiểm tra sức khỏe backup proxy
Free Proxy Fetch	(hardcoded)	Theo cấu hình	Thu thập proxy miễn phí
Free Proxy Health	(hardcoded)	Theo cấu hình	Kiểm tra sức khỏe free proxy
MongoDB Cleanup	(hardcoded)	Theo cấu hình	Dọn dẹp dữ liệu cũ trong MongoDB
Mattermost Report	`MATTERMOST_SCHEDULE`	9:00 sáng hàng ngày	Gửi báo cáo tổng hợp qua Mattermost
Report Sync	(hardcoded)	Theo cấu hình	Đồng bộ dữ liệu báo cáo
Search Dispatch	(hardcoded)	Theo cấu hình	Phân phối tác vụ tìm kiếm
Log Cleanup	(hardcoded)	Theo cấu hình	Dọn dẹp file log cũ

6. Hệ Thống Cơ Sở Dữ Liệu

Backend sử dụng đồng thời ba loại cơ sở dữ liệu với vai trò khác nhau:

Database	Công Nghệ	Dữ Liệu Lưu Trữ
MySQL	GORM	Dữ liệu quan hệ: user, campaign, proxy, server, keyword, task, proxy_package, proxy_provider, location
MongoDB	mongo-driver	Dữ liệu phi cấu trúc: task_log chi tiết, evidence (ảnh bằng chứng), reports tổng hợp, keyword_result, server_hourly_report
Redis	go-redis	Session token, last_active_at tracking, distributed lock cho cron job

7. Hệ Thống Xác Thực Hai Lớp

7.1. Luồng Đăng Nhập

Bước 1: Client gọi POST /api/user/login với email và password.

Bước 2: Server verify password bằng bcrypt, tạo JWT token với JWT_SECRET.

Bước 3: Server tạo device_token (UUID) và lưu vào bảng users.device_token.

Bước 4: Server trả về token (JWT), device_token, is_2fa (trạng thái 2FA của tài khoản).

Bước 5: Nếu is_2fa = true, client phải gọi POST /api/user/verify-totp với mã OTP.

Bước 6: Sau khi verify TOTP thành công, server cập nhật is_logged_in = true và last_active_at.

7.2. Cơ Chế Xác Thực Mỗi Request

Mỗi request đến route bảo vệ phải có hai header:

Authorization: Bearer {jwt_token} — JWT token từ bước đăng nhập.

Device-Token: {device_token} — Device token từ bước đăng nhập.

AuthMiddleware kiểm tra device_token trong bảng users MySQL và xác nhận is_logged_in = true. Sau đó cập nhật last_active_at và kiểm tra session timeout (mặc định 1 giờ, có thể cấu hình qua SESSION_TIMEOUT).

JWTMiddleware verify chữ ký JWT và kiểm tra last_active_at trong Redis. Nếu thời gian từ lần hoạt động cuối vượt quá SESSION_TIMEOUT, session bị hủy.

7.3. Cơ Chế 2FA (TOTP)

Sử dụng thư viện xlzd/gotp theo chuẩn TOTP (Time-based One-Time Password) tương thích với Google Authenticator:

GET /api/user/generate-totp — Tạo secret key và QR code URI cho lần thiết lập đầu tiên.

POST /api/user/verify-totp — Xác minh mã OTP 6 chữ số. Nếu đúng, đánh dấu two_factor = true trong database.

Trong môi trường development, có thể tắt 2FA bằng DISABLE_2FA=true trong .env.

8. Hệ Thống Thông Báo

8.1. Telegram

API gửi thông báo đến ba kênh Telegram riêng biệt:

TELEGRAM_CHAT_ID — Thông báo chung về hoạt động hệ thống.

TELEGRAM_CHAT_REPORT_ID — Báo cáo tự động định kỳ (traffic, hiệu suất).

TELEGRAM_CHAT_ERROR_ID — Cảnh báo lỗi nghiêm trọng cần can thiệp ngay.

Điều kiện gửi được kiểm soát bởi ENABLE_PUSH_MESSAGE_ERROR_TO_TELEGRAM=true/false.

8.2. Mattermost

Tích hợp Mattermost để gửi báo cáo tổng hợp hàng ngày vào lúc 9:00 sáng (cấu hình qua MATTERMOST_SCHEDULE). Báo cáo bao gồm thống kê traffic, hiệu suất server và tình trạng proxy pool.

9. Background Services

Hai dịch vụ nền chạy song song với HTTP server trong goroutine riêng:

9.1. HealthCheckCron

Ping chủ động đến từng server worker theo lịch. Nếu server không phản hồi:

Đánh dấu status = offline trong MySQL.

Ghi log vào kênh background_services.

Gửi thông báo Telegram nếu được bật.

Tác vụ ngừng được giao đến server đó cho đến khi ping thành công lại.

9.2. TaskMonitor

Liên tục scan database để tìm các tác vụ bị kẹt (stuck tasks) — tác vụ đã giao cho worker nhưng không nhận được phản hồi sau khoảng thời gian cấu hình. Khi phát hiện:

Reset tác vụ về trạng thái pending để giao lại cho server khác.

Ghi log chi tiết vào kênh background_services.

Cả hai dịch vụ hỗ trợ graceful shutdown thông qua context.Context — khi server nhận tín hiệu tắt, chúng hoàn thành chu kỳ hiện tại trước khi dừng.

10. Tích Hợp DigitalOcean Spaces

Module internal/storage cung cấp khả năng upload file lên DigitalOcean Spaces (tương thích S3 API) thông qua AWS SDK:

DIGITALOCEAN_ACCESS_KEY và DIGITALOCEAN_SECRET_KEY — Credentials.

DIGITALOCEAN_BUCKET_NAME — Tên bucket lưu trữ.

DIGITALOCEAN_ENDPOINT — Endpoint của DigitalOcean Spaces.

DIGITALOCEAN_CDN_URL — URL CDN để truy cập file đã upload.

File được upload qua POST /api/files (route bảo vệ) và trả về URL CDN để lưu vào database.

11. Cấu Hình CORS

CORS được cấu hình khác nhau theo môi trường:

Development: AllowOrigins = "*", AllowCredentials = false — Cho phép mọi origin để tiện phát triển.

Production: AllowOrigins = "https://traffic.longtu.club,https://traffic-api.longtu.club,http://localhost:5173,http://localhost:3000", AllowCredentials = true — Chỉ cho phép các origin đã biết.

Header được phép: Origin, Content-Type, Accept, Authorization, Device-Token, Cache-Control, Pragma, X-Requested-With.

12. Cấu Hình Timeout

Fiber được cấu hình với các timeout sau:

ReadTimeout: 30s — Thời gian tối đa để đọc toàn bộ request body.

WriteTimeout: 30s — Thời gian tối đa để ghi response.

IdleTimeout: 120s — Thời gian tối đa giữ kết nối idle (keep-alive).

DefaultTimeout (middleware): Timeout mặc định cho xử lý request, cấu hình trong pkg/middleware/timeout.go.

Middleware TimeoutMiddleware được áp dụng toàn cục để ngăn các request xử lý quá lâu làm nghẽn goroutine pool.

13. Danh Sách Đầy Đủ 36 Module Internal

Dưới đây là mô tả chi tiết từng module trong thư mục internal/:

Module	Mô Tả	Database	Có Cron
`activity_log`	Ghi nhật ký mọi hành động của người dùng: tạo, sửa, xóa bản ghi. Lưu giá trị trước và sau khi thay đổi.	MySQL	Không
`backup_proxy`	Quản lý pool proxy dự phòng. Tự động kiểm tra sức khỏe mỗi 2 phút và cập nhật mỗi 5 phút.	MySQL	Có
`campaign`	Quản lý chiến dịch traffic. Mỗi chiến dịch chứa nhiều project/task. Hỗ trợ xuất báo cáo Excel.	MySQL	Không
`coccoc_token`	Nhận và lưu trữ token xác thực CocCoc từ worker sau khi đăng nhập thành công.	MySQL	Có
`dashboard`	Cung cấp dữ liệu tổng hợp cho Admin Dashboard và Looker Studio. Không yêu cầu xác thực.	MySQL + MongoDB	Không
`evidence`	Lưu trữ và truy vấn ảnh chụp màn hình bằng chứng từ worker. Lưu trong MongoDB.	MongoDB	Không
`free_proxy`	Thu thập proxy miễn phí từ các nguồn công khai. Kiểm tra sức khỏe và thêm vào pool.	MySQL	Có
`keyword`	Quản lý từ khóa SEO với cấu hình engine, thiết bị, vị trí địa lý. Hỗ trợ xuất Excel.	MySQL	Có
`keyword_analytics`	Phân tích xu hướng thứ hạng từ khóa theo thời gian. Lưu dữ liệu phân tích vào MongoDB.	MongoDB	Có
`keyword_pool_task`	Quản lý pool tác vụ kiểm tra từ khóa. Phân phối tác vụ đến worker.	MySQL	Có
`keyword_result`	Lưu kết quả kiểm tra thứ hạng từ khóa. Nhận webhook từ worker.	MongoDB	Có
`keyword_schedule`	Lịch kiểm tra thứ hạng từ khóa. Cấu hình tần suất và thời điểm kiểm tra.	MySQL	Không
`location`	Quản lý vị trí địa lý (tỉnh/thành, quốc gia) với tọa độ lat/lng.	MySQL	Không
`mattermost`	Tích hợp Mattermost để gửi báo cáo tổng hợp hàng ngày.	Không	Có
`mongodb_cleanup`	Dọn dẹp dữ liệu cũ trong MongoDB theo lịch. Tạo và quản lý indexes.	MongoDB	Có
`monitor`	Nhận ping từ worker để xác nhận server còn hoạt động.	MySQL	Không
`profiles`	Quản lý hồ sơ trình duyệt (Browser Fingerprint) dùng cho tự động hóa.	MongoDB	Không
`project`	Quản lý project của khách hàng. Mỗi project chứa nhiều link cần traffic.	MySQL	Có
`project_detail`	Chi tiết từng link trong project: thứ hạng, trạng thái, lịch sử.	MySQL + MongoDB	Không
`project_settings`	Cấu hình tùy chỉnh cho từng project: giới hạn traffic, khung giờ.	MySQL	Không
`proxy`	Quản lý pool proxy IP chính. Import từ Excel, xoay vòng, kiểm tra sức khỏe.	MySQL	Có
`proxy_ip_log`	Nhật ký sử dụng từng địa chỉ IP proxy: task nào dùng, kết quả ra sao.	MongoDB	Không
`proxy_ip_log_detail`	Chi tiết từng lần sử dụng IP: timestamp, latency, kết quả.	MongoDB	Không
`proxy_packages`	Quản lý gói proxy đã mua: tên, giá, nhà cung cấp, trạng thái.	MySQL	Không
`proxy_providers`	Quản lý nhà cung cấp proxy: API credentials, thống kê dữ liệu sử dụng.	MySQL	Không
`report`	Tổng hợp và xuất báo cáo traffic. Ba service: chính, dashboard, PC report.	MySQL + MongoDB	Có
`search_dispatch`	Phân phối tác vụ tìm kiếm đến worker. Quản lý hàng đợi tác vụ.	MySQL	Có
`server`	Quản lý máy chủ worker: IP, giới hạn tiến trình, trạng thái.	MySQL	Không
`server_hourly_report`	Báo cáo hiệu suất theo giờ của từng server. Lưu vào MongoDB.	MongoDB	Có
`setup_fire`	Cấu hình kích hoạt tác vụ: điều kiện, thời điểm, số lượng.	MySQL	Không
`storage`	Upload và quản lý file trên DigitalOcean Spaces (S3-compatible).	Không	Không
`system_settings`	Cấu hình hệ thống toàn cục: giới hạn traffic, cấu hình cron.	MySQL	Không
`task`	Tác vụ thực thi traffic. Nhận yêu cầu từ tools_v2, giao cho worker.	MySQL	Có
`task_log`	Log chi tiết từng lượt thực thi tác vụ.	MongoDB	Không
`user`	Quản lý tài khoản người dùng, xác thực JWT, 2FA TOTP.	MySQL	Không
`webhook`	Nhận callback từ worker: cập nhật trạng thái, kết quả, proxy.	MySQL	Không

14. Luồng Xử Lý Tác Vụ Traffic

Đây là luồng quan trọng nhất của hệ thống, mô tả cách một tác vụ traffic được tạo ra và thực thi:

Bước 1: Admin tạo chiến dịch và project qua Admin Dashboard.

Bước 2: Cron job SCHEDULE_SEND_TASK (mỗi phút) quét database tìm tác vụ chờ xử lý.

Bước 3: Cron job giao tác vụ đến các server worker đang online, tối đa LIMIT_SEND_TASK_PER_SERVER tác vụ mỗi server.

Bước 4: tools_v2 trên server worker gọi POST /api/task/request để nhận danh sách tác vụ.

Bước 5: Worker thực thi tác vụ (mở trình duyệt, tìm kiếm, click quảng cáo).

Bước 6: Worker gọi POST /webhook/proxy/get-proxy để lấy proxy IP cho tác vụ.

Bước 7: Worker gọi POST /webhook/task/update-process để cập nhật tiến trình theo thời gian thực.

Bước 8: Sau khi hoàn thành, worker gọi POST /webhook/task/update-status để cập nhật kết quả cuối.

Bước 9: API lưu kết quả vào MySQL và MongoDB, cập nhật thống kê.

Bước 10: Admin Dashboard hiển thị kết quả qua các endpoint dashboard và report.

15. Luồng Xử Lý Từ Khóa SEO

Bước 1: Admin tạo từ khóa với cấu hình engine (Google/CocCoc), thiết bị (Desktop/Mobile), vị trí địa lý.

Bước 2: Cron job SCHEDULE_SEARCH_KEYWORD (mỗi 30 phút) kiểm tra thứ hạng từ khóa.

Bước 3: Worker nhận tác vụ kiểm tra từ khóa, thực hiện tìm kiếm thực tế.

Bước 4: Worker gọi webhook /webhook/keyword-result để gửi kết quả thứ hạng.

Bước 5: API lưu kết quả vào MongoDB collection keyword_results.

Bước 6: Admin Dashboard hiển thị biểu đồ thứ hạng theo thời gian.

Bước 7: Cron job SCHEDULE_CONFIRM_FIRE (mỗi 30 phút) xác nhận các tác vụ đã hoàn thành và kích hoạt tác vụ tiếp theo.

Tổng quan

Tài Liệu Thiết Kế Tổng Quan — API Backend Traffic Tools V2#

1. Mục Đích Và Vai Trò#

2. Ngăn Xếp Công Nghệ#

3. Sơ Đồ Luồng Dữ Liệu Tổng Thể#

4. Kiến Trúc Route — Nhóm API Đầy Đủ#

4.1. Route Công Khai (Không Xác Thực)#

4.2. Route Webhook (Luôn Công Khai)#

4.3. Route Bảo Vệ (Yêu Cầu JWT)#

5. Hệ Thống Cron Job#

6. Hệ Thống Cơ Sở Dữ Liệu#

7. Hệ Thống Xác Thực Hai Lớp#

7.1. Luồng Đăng Nhập#

7.2. Cơ Chế Xác Thực Mỗi Request#

7.3. Cơ Chế 2FA (TOTP)#

8. Hệ Thống Thông Báo#

8.1. Telegram#

8.2. Mattermost#

9. Background Services#

9.1. HealthCheckCron#

9.2. TaskMonitor#

10. Tích Hợp DigitalOcean Spaces#

11. Cấu Hình CORS#

12. Cấu Hình Timeout#

13. Danh Sách Đầy Đủ 36 Module Internal#

14. Luồng Xử Lý Tác Vụ Traffic#

15. Luồng Xử Lý Từ Khóa SEO#