Tài Liệu Kiến Trúc Hệ Thống — API Backend Traffic Tools V2

1. Kiến Trúc Phân Lớp

Project api/ áp dụng kiến trúc phân lớp truyền thống trong Go, được tổ chức rõ ràng thành các nhóm thư mục:

api/
├── cmd/              ← Entry point — khởi động ứng dụng
├── bootstrap/        ← Khởi tạo app: routes, cron, DI injection
│   ├── routes.go     ← Khai báo toàn bộ HTTP routes
│   ├── background_services.go ← Quản lý HealthCheckCron và TaskMonitor
│   ├── cron/         ← Định nghĩa và khởi động các cron job
│   ├── injection/    ← Khởi tạo dependency (DB, Redis, Services)
│   └── socket/       ← WebSocket handler
├── internal/         ← Business logic theo module (36 module)
│   ├── user/
│   │   ├── user.go          ← Model GORM
│   │   ├── dto/             ← Data Transfer Objects
│   │   ├── handler/         ← HTTP handler
│   │   ├── service/         ← Business logic
│   │   └── repository/      ← Data access
│   └── ... (35 module khác)
├── pkg/              ← Shared packages dùng chung toàn app
│   ├── env.go        ← EnvStruct và load cấu hình Viper
│   ├── logger/       ← Zap structured logging + channel logger
│   ├── middleware/   ← Auth, JWT, Admin middleware
│   ├── database/     ← Kết nối MySQL, MongoDB, Redis
│   ├── jwt/          ← Tạo/verify JWT token
│   ├── cache/        ← Redis cache wrapper
│   ├── enum/         ← Hằng số enum toàn hệ thống
│   ├── helper/       ← Các hàm tiện ích phổ biến
│   ├── telegram/     ← Gửi thông báo Telegram
│   ├── excel/        ← Tạo file Excel báo cáo
│   ├── scheduler/    ← Wrapper gocron
│   ├── apperror/     ← Custom error types
│   ├── messages/     ← Chuỗi thông điệp chuẩn hóa
│   ├── validate/     ← Wrapper go-playground/validator
│   └── types/        ← Kiểu dữ liệu dùng chung
├── common/           ← Các interface và struct dùng toàn dự án
├── deploy/           ← Docker Compose và cấu hình triển khai
├── scripts/          ← Shell scripts tiện ích
├── .env              ← Biến môi trường thực tế (không commit)
├── .env.example      ← Template biến môi trường
├── .gitlab-ci.yml    ← CI/CD pipeline GitLab
├── Makefile          ← Tất cả lệnh thường dùng
└── go.mod / go.sum   ← Dependency management

2. Kiến Trúc Module Internal

Mỗi module trong internal/ tuân theo cấu trúc 4 lớp nhất quán. Lấy module user làm ví dụ tiêu chuẩn:

2.1. Lớp Model (user.go)

Định nghĩa struct GORM map với bảng MySQL:

2.2. Lớp DTO (dto/)

Định nghĩa struct cho request/response, gắn tag validate cho tự động kiểm tra:

2.3. Lớp Handler (handler/)

Nhận HTTP request từ Fiber, gọi Service, trả về JSON response:

2.4. Lớp Service (service/)

Chứa toàn bộ business logic, gọi Repository để đọc/ghi dữ liệu. Không trực tiếp chạm vào HTTP context.

2.5. Lớp Repository (repository/)

Thực thi câu lệnh SQL qua GORM hoặc MongoDB query. Service không biết gì về chi tiết SQL hay MongoDB query syntax.

3. Kiến Trúc Middleware

Fiber middleware chain được áp dụng theo thứ tự sau cho route bảo vệ:

Request
   |
   v
Recover Middleware
  - Bắt panic, ngăn server crash
  - Trả về 500 thay vì 502
   |
   v
CORS Middleware
  - Kiểm tra Origin header
  - Thêm CORS response headers
   |
   v
Helmet Middleware
  - Thêm security headers (X-Frame-Options, CSP, v.v.)
   |
   v
Timeout Middleware
  - Hủy request nếu xử lý quá lâu
   |
   v
Error Handler Middleware
  - Chuẩn hóa format lỗi JSON
   |
   v
AuthMiddleware (pkg/middleware/auth.go)
  - Đọc header Device-Token
  - Kiểm tra device_token trong bảng users MySQL
  - Xác nhận is_logged_in = true
  - Cập nhật last_active_at
  - Kiểm tra session timeout
  - Lưu user_id vào c.Locals("user_id")
   |
   v
JWTMiddleware (pkg/middleware/jwt_middleware.go)
  - Verify chữ ký JWT bằng JWT_SECRET
  - Lấy user_id từ JWT claims
  - Kiểm tra last_active_at trong Redis
  - Kiểm tra session timeout
   |
   v
Handler (internal/*/handler/)
  - Truy cập user_id đã xác thực qua c.Locals("user_id")

Route admin thêm một middleware nữa:

AdminMiddleware (pkg/middleware/admin_middleware.go)
  - Đọc user_id từ c.Locals("user_id")
  - Load user từ MySQL
  - Kiểm tra user.Role === "admin"
  - Trả về 403 nếu không phải admin

4. Hệ Thống Dependency Injection

Dự án dùng go.uber.org/dig để quản lý dependency injection. Các dependency được khởi tạo trong bootstrap/injection/injection.go:

dig.Container
  ├── *pkg.EnvStruct              ← Cấu hình từ .env
  ├── *database.DbConn            ← MySQL + MongoDB connections
  ├── *cache.RedisCache           ← Redis connection
  ├── *http.Client                ← HTTP client cho external calls
  ├── Repositories:
  │   ├── *proxy.Repository
  │   ├── *location.Repository
  │   ├── *systemSettings.Repository
  │   └── *campaign.Repository
  └── Services (36 services):
      ├── *user.Service
      ├── *campaign.Service
      ├── *server.Service
      ├── *task.Service
      ├── *proxy.Service
      ├── *report.Service
      ├── *reportDashboard.Service
      ├── *pcReport.Service
      ├── *keyword.Service
      ├── *profile.Service
      └── ... (26 services khác)

Handler nhận dependency qua constructor injection, không dùng global variable. Ví dụ:

5. Kiến Trúc Cơ Sở Dữ Liệu Chi Tiết

5.1. MySQL — Dữ Liệu Quan Hệ

Kết nối qua GORM với connection pool. Auto-migrate được kiểm soát bởi AUTO_MIGRATE_DATABASE=true/false:

Bảng	Module	Mô Tả
`users`	user	Tài khoản, mật khẩu (bcrypt), vai trò, 2FA secret, device token
`campaigns`	campaign	Chiến dịch traffic: tên, trạng thái, cấu hình
`servers`	server	Danh sách máy chủ worker: IP, port, limit_process, current_process
`proxies`	proxy	Danh sách địa chỉ IP proxy với thông tin xác thực và rotate
`backup_proxies`	backup_proxy	IP dự phòng khi proxy chính hỏng
`proxy_packages`	proxy_packages	Gói proxy: hạn dùng, dung lượng, nhà cung cấp
`proxy_providers`	proxy_providers	Nhà cung cấp proxy: URL API, key tích hợp, thống kê dữ liệu
`keywords`	keyword	Từ khóa SEO với cấu hình engine, device, geolocation
`keyword_schedules`	keyword_schedule	Lịch kiểm tra thứ hạng từ khóa
`tasks` (projects)	task	Bản ghi tác vụ traffic: trạng thái, kết quả, cấu hình
`projects`	project	Project của khách hàng
`project_details`	project_detail	Chi tiết từng link trong project
`locations`	location	Vị trí địa lý với tọa độ lat/lng
`system_settings`	system_settings	Cấu hình hệ thống toàn cục

5.2. MongoDB — Dữ Liệu Log Và Báo Cáo

Collection	Mô Tả
`task_logs`	Log chi tiết từng lượt thực thi: timestamp, proxy dùng, kết quả click
`evidences`	Ảnh chụp màn hình bằng chứng lưu dưới base64 hoặc URL CDN
`reports`	Báo cáo tổng hợp theo giờ/ngày
`keyword_results`	Kết quả kiểm tra thứ hạng từ khóa theo ngày
`server_hourly_reports`	Báo cáo theo giờ của từng server (process, success, fail, captcha)
`proxy_ip_logs`	Nhật ký sử dụng từng địa chỉ IP
`report_tasks`	Tác vụ báo cáo từ module report
`report_sites`	Danh sách site đang được theo dõi báo cáo
`keyword_analytics`	Phân tích xu hướng từ khóa theo thời gian

5.3. Redis — Cache Và Session

Key Pattern	TTL	Nội Dung
`user:activity:{user_id}`	SESSION_TIMEOUT	Thời điểm hoạt động cuối của user (RFC3339)
`cache:proxy:{id}`	5 phút	Cache thông tin proxy thường dùng
`lock:cron:{job_name}`	Thời gian job	Distributed lock ngăn cron chạy trùng

6. Kiến Trúc WebSocket

Module bootstrap/socket/ dùng gofiber/contrib/socketio để cung cấp real-time monitoring:

Admin Dashboard kết nối WebSocket tại endpoint /ws để nhận cập nhật trạng thái server theo thời gian thực.

Khi một worker hoàn thành tác vụ và gọi webhook, API server có thể emit event qua socket để cập nhật Dashboard mà không cần polling.

Socket server được khởi tạo với pkg.Env để đọc cấu hình cần thiết.

7. Kiến Trúc Background Services

background_services.go quản lý hai loại tiến trình nền chạy song song với HTTP server:

7.1. HealthCheckCron

7.2. TaskMonitor

Cả hai nhận context.Context từ BackgroundServices để hỗ trợ graceful shutdown:

8. Kiến Trúc Xử Lý Lỗi

8.1. Custom Error Types

Package pkg/apperror định nghĩa các loại lỗi chuẩn:

8.2. Error Handler Middleware

pkg/middleware/error_handler.go bắt tất cả lỗi và chuẩn hóa format JSON response:

8.3. Recover Middleware

pkg/middleware/recover.go bắt panic trong handler và trả về 500 thay vì để server crash. Đây là middleware đầu tiên trong chain để đảm bảo mọi panic đều được xử lý.

9. Kiến Trúc Module Report

Module internal/report là module phức tạp nhất, có cấu trúc đặc biệt:

internal/report/
├── report.go              ← Module entry point
├── csv_generator.go       ← Tạo file CSV báo cáo
├── data_analysis.go       ← Phân tích dữ liệu báo cáo
├── dto/                   ← Data Transfer Objects
├── handler/               ← HTTP handlers
├── model/                 ← MongoDB models
├── models/                ← Thêm models
├── repository/            ← Data access (MongoDB)
├── service/               ← Business logic
│   ├── service.go         ← Service chính
│   ├── report_dashboard_service.go ← Service cho dashboard
│   └── pc_report_service.go        ← Service cho PC report
├── utils/                 ← Tiện ích xử lý báo cáo
├── webhook/               ← Webhook handlers cho report
│   └── handler/
└── cron/                  ← Cron jobs cho report
    ├── report_cron.go
    └── report_sync_scheduler.go

Ba service riêng biệt phục vụ các mục đích khác nhau:

Service — Service chính xử lý CRUD báo cáo cơ bản.

ReportDashboardService — Service cho dashboard với MongoDB repositories: ReportTaskRepository, MongoReportSiteRepository, KeywordAnalyticsRepository.

PCReportService — Service tổng hợp báo cáo PC với cả MySQL và MongoDB.

10. Kiến Trúc Module Proxy

Module internal/proxy có cấu trúc phức tạp nhất về mặt business logic:

internal/proxy/
├── proxy.go
├── common/    ← Các hàm dùng chung trong module proxy
├── config/    ← Cấu hình proxy providers
├── cron/      ← Cron jobs: rotate, health check, change active
├── dto/       ← Request/Response DTOs
├── handler/   ← HTTP handlers với 15+ endpoints
├── repository/← Data access
└── service/   ← Business logic: rotate, import, health check

Handler proxy cung cấp các endpoint đặc biệt:

POST /api/proxy/import — Import proxy từ file Excel (multipart/form-data).

POST /api/proxy/import-all — Import từ tất cả nhà cung cấp cùng lúc (timeout 5 phút).

POST /api/proxy/multiple — Tạo nhiều proxy cùng lúc.

GET /api/proxy/demo-excel — Tải file Excel mẫu để import.

GET /api/proxy/export — Xuất danh sách proxy ra Excel.

POST /api/proxy/bulk-delete — Xóa nhiều proxy cùng lúc.

PUT /api/proxy/:id/change-status — Kích hoạt/vô hiệu hóa proxy.

System Architecture

Tài Liệu Kiến Trúc Hệ Thống — API Backend Traffic Tools V2#

1. Kiến Trúc Phân Lớp#

2. Kiến Trúc Module Internal#

2.1. Lớp Model (user.go)#

2.2. Lớp DTO (dto/)#

2.3. Lớp Handler (handler/)#

2.4. Lớp Service (service/)#

2.5. Lớp Repository (repository/)#

3. Kiến Trúc Middleware#

4. Hệ Thống Dependency Injection#

5. Kiến Trúc Cơ Sở Dữ Liệu Chi Tiết#

5.1. MySQL — Dữ Liệu Quan Hệ#

5.2. MongoDB — Dữ Liệu Log Và Báo Cáo#

5.3. Redis — Cache Và Session#

6. Kiến Trúc WebSocket#

7. Kiến Trúc Background Services#

7.1. HealthCheckCron#

7.2. TaskMonitor#

8. Kiến Trúc Xử Lý Lỗi#

8.1. Custom Error Types#

8.2. Error Handler Middleware#

8.3. Recover Middleware#

9. Kiến Trúc Module Report#

10. Kiến Trúc Module Proxy#