Tài Liệu Cấu Trúc Mã Nguồn — API Backend Traffic Tools V2

1. Toàn Bộ Cây Thư Mục

api/
├── bootstrap/
│   ├── routes.go                ← Khai báo toàn bộ 50+ HTTP routes
│   ├── background_services.go   ← Quản lý HealthCheckCron và TaskMonitor
│   ├── cron/
│   │   ├── cron.go              ← Khởi động tất cả cron jobs
│   │   ├── clean_log_schedule.go← Dọn dẹp file log cũ
│   │   └── health_check_cron.go ← Ping server worker định kỳ
│   ├── injection/
│   │   └── injection.go         ← DI container setup — DB, Redis, Services
│   └── socket/
│       └── socket.go            ← WebSocket event handlers
│
├── cmd/
│   └── main.go                  ← Entry point: khởi tạo Fiber + gọi bootstrap
│
├── common/
│   ├── const.go                 ← Hằng số dùng chung
│   └── paging.go                ← Struct phân trang chuẩn
│
├── internal/                    ← 36 modules nghiệp vụ
│   ├── activity_log/            ← Nhật ký hoạt động người dùng
│   ├── backup_proxy/            ← Proxy dự phòng
│   ├── campaign/                ← Chiến dịch traffic
│   ├── coccoc_token/            ← Token xác thực CocCoc từ worker
│   ├── dashboard/               ← Dữ liệu biểu đồ cho Admin Dashboard
│   ├── evidence/                ← Ảnh bằng chứng chụp màn hình
│   ├── free_proxy/              ← Proxy miễn phí tự động thu thập
│   ├── keyword/                 ← Từ khóa SEO
│   ├── keyword_analytics/       ← Phân tích xu hướng từ khóa
│   ├── keyword_pool_task/       ← Pool tác vụ kiểm tra từ khóa
│   ├── keyword_result/          ← Kết quả thứ hạng từ khóa
│   ├── keyword_schedule/        ← Lịch kiểm tra từ khóa
│   ├── location/                ← Vị trí địa lý (tỉnh/thành, quốc gia)
│   ├── mattermost/              ← Tích hợp Mattermost notify
│   ├── mongodb_cleanup/         ← Dọn dẹp dữ liệu cũ trong MongoDB
│   ├── monitor/                 ← Endpoint nhận ping từ worker
│   ├── profiles/                ← Hồ sơ trình duyệt (Browser Fingerprint)
│   ├── project/                 ← Project của khách hàng
│   ├── project_detail/          ← Chi tiết link trong project
│   ├── project_settings/        ← Cấu hình tùy chỉnh project
│   ├── proxy/                   ← Proxy IP chính
│   ├── proxy_ip_log/            ← Nhật ký sử dụng IP
│   ├── proxy_ip_log_detail/     ← Chi tiết từng lần dùng IP
│   ├── proxy_packages/          ← Gói mua proxy
│   ├── proxy_providers/         ← Nhà cung cấp proxy
│   ├── report/                  ← Tổng hợp và xuất báo cáo
│   ├── search_dispatch/         ← Phân phối tác vụ tìm kiếm
│   ├── server/                  ← Máy chủ worker
│   ├── server_hourly_report/    ← Báo cáo theo giờ của server
│   ├── setup_fire/              ← Cấu hình kích hoạt tác vụ
│   ├── storage/                 ← Quản lý file upload (DigitalOcean Spaces)
│   ├── system_settings/         ← Cấu hình hệ thống toàn cục
│   ├── task/                    ← Tác vụ thực thi traffic
│   ├── task_log/                ← Log chi tiết tác vụ
│   ├── user/                    ← Người dùng và xác thực
│   └── webhook/                 ← Nhận callback từ worker
│
├── pkg/                         ← Shared utilities
│   ├── env.go                   ← EnvStruct + Viper load (40+ biến)
│   ├── api/                     ← Helper gọi HTTP đến services khác
│   │   ├── _http/               ← HTTP client wrapper
│   │   ├── check_ip/            ← Kiểm tra IP còn sống
│   │   ├── proxy/               ← Gọi API nhà cung cấp proxy
│   │   └── search_keyword/      ← Gọi API tìm kiếm từ khóa
│   ├── apperror/                ← Custom application errors (401, 403, 500)
│   ├── cache/                   ← Redis wrapper (get, set, delete)
│   ├── database/                ← MySQL + MongoDB connection factories
│   │   ├── database.go          ← DbConn struct chứa cả hai connection
│   │   ├── mysql.go             ← Kết nối MySQL với GORM
│   │   ├── mysql_pool.go        ← Connection pool MySQL
│   │   ├── mongo.go             ← Kết nối MongoDB
│   │   └── mongo_pool.go        ← Connection pool MongoDB
│   ├── enum/                    ← Hằng số enum toàn hệ thống
│   │   └── traffic.go           ← Enum loại traffic, trạng thái tác vụ
│   ├── excel/                   ← Tạo file .xlsx với excelize
│   │   ├── read.go              ← Đọc file Excel
│   │   └── write.go             ← Ghi file Excel
│   ├── helper/                  ← Các hàm tiện ích
│   │   ├── mysql_helper/        ← Helper cho MySQL queries
│   │   ├── number_helper/       ← Xử lý số
│   │   ├── string_helper/       ← Xử lý chuỗi
│   │   ├── task_helper/         ← Helper cho task logic
│   │   ├── user_helper/         ← Helper cho user logic
│   │   └── validate_password_helper/ ← Kiểm tra độ mạnh mật khẩu
│   ├── jwt/                     ← Tạo và verify JWT với golang-jwt
│   │   ├── generate_jwt.go      ← Tạo JWT token
│   │   └── get_user_from_token.go ← Decode user_id từ JWT
│   ├── logger/                  ← Zap logger + channel-based logging
│   │   └── logger.go            ← Logger với kênh và ngày
│   ├── messages/                ← Chuỗi thông báo chuẩn hóa
│   │   └── messages.go          ← Các message constant
│   ├── middleware/               ← HTTP middleware
│   │   ├── activity_logger.go   ← Ghi nhật ký hoạt động
│   │   ├── admin_middleware.go  ← Kiểm tra quyền admin
│   │   ├── auth.go              ← AuthMiddleware (Device-Token)
│   │   ├── context.go           ← Context utilities
│   │   ├── error_handler.go     ← Chuẩn hóa format lỗi JSON
│   │   ├── jwt_middleware.go    ← JWTMiddleware (verify JWT)
│   │   ├── recover.go           ← Bắt panic, ngăn server crash
│   │   ├── timeout.go           ← Request timeout middleware
│   │   ├── validate_api_key.go  ← Kiểm tra API key header
│   │   ├── validate_ip.go       ← Kiểm tra IP whitelist
│   │   └── webhook_middleware.go← Xác thực webhook requests
│   ├── scheduler/               ← Wrapper gocron
│   │   └── scheduler.go         ← Khởi tạo gocron scheduler
│   ├── telegram/                ← Bot Telegram send message
│   │   └── send_message.go      ← Gửi tin nhắn Telegram
│   ├── time/                    ← Tiện ích xử lý múi giờ VN
│   │   └── time.go              ← Parse và format thời gian VN
│   ├── types/                   ← Kiểu dữ liệu dùng chung
│   │   └── message.go           ← Message response types
│   └── validate/                ← Wrapper go-playground/validator
│       └── validate.go          ← Validate struct với custom messages
│
├── deploy/                      ← Cấu hình triển khai
│   ├── development/
│   │   ├── Dockerfile           ← Multi-stage build cho dev
│   │   ├── entrypoint.sh        ← Script khởi động container dev
│   │   └── run_script.sh        ← Script chạy ứng dụng
│   └── production/
│       ├── Dockerfile           ← Dockerfile cho production
│       ├── entrypoint.sh        ← Script khởi động container prod
│       └── run_script.sh        ← Script chạy ứng dụng
│
├── scripts/                     ← Scripts tiện ích
│   ├── batch-delete-collections.js ← Xóa hàng loạt MongoDB collections
│   ├── check_task_counts.js     ← Kiểm tra số lượng task
│   └── create_report_indexes/   ← Tạo indexes MongoDB cho report
│
├── testdata/                    ← Dữ liệu test
│   ├── main.go                  ← Entry point tạo test data
│   ├── generators/              ← Generators cho từng loại data
│   │   ├── profile/
│   │   ├── proxy/
│   │   ├── report/
│   │   └── server/
│   ├── models/                  ← Models cho test data
│   └── utils/                   ← Tiện ích tạo random data
│
├── docs/                        ← Tài liệu kỹ thuật (thư mục này)
├── logs/                        ← Thư mục log tự động tạo khi chạy
├── .air.toml                    ← Cấu hình Air hot-reload cho development
├── .env                         ← Biến môi trường thực tế
├── .env.example                 ← Template (commit vào Git)
├── .gitlab-ci.yml               ← CI/CD pipeline
├── docker-compose.yaml          ← Khởi động toàn bộ hạ tầng local
├── docker-compose-mac.yaml      ← Dành cho macOS Apple Silicon
├── go.mod                       ← Go module dependencies
├── go.sum                       ← Checksum dependencies
└── Makefile                     ← Lệnh build, test, deploy

2. Chi Tiết Package `pkg/`

2.1. `pkg/env.go` — Hệ Thống Biến Môi Trường

EnvStruct là struct duy nhất chứa toàn bộ 50+ biến môi trường, được load bằng Viper khi khởi động. Struct này được import vào toàn bộ codebase qua pkg.Env:

Nhóm	Biến Đại Diện	Mô Tả
App Config	`APP_MODE`, `SERVER_PORT`, `API_KEY`	Chế độ chạy và API key
MySQL	`DB_MYSQL_HOST`, `DB_MYSQL_PORT`, `DB_MYSQL_USER`, `DB_MYSQL_PASS`, `DB_MYSQL_NAME`	Kết nối MySQL
MongoDB	`DB_MONGO_HOST`, `DB_MONGO_PORT`, `DB_MONGO_USER`, `DB_MONGO_PASS`, `DB_MONGO_NAME`	Kết nối MongoDB
Redis	`REDIS_HOST`, `REDIS_PORT`, `REDIS_USER`, `REDIS_PASS`, `REDIS_DB`	Kết nối Redis
JWT	`JWT_SECRET`	Secret key ký JWT token
Session	`SESSION_TIMEOUT`, `DISABLE_SESSION_TIMEOUT`, `DEV_SESSION_TIMEOUT`	Cấu hình session
2FA	`DISABLE_2FA`	Tắt 2FA trong development
Cron	`SCHEDULE_SEND_TASK`, `SCHEDULE_RESET_TASK`, `SCHEDULE_REPORT_TRAFFIC`, v.v.	Biểu thức cron
Webhook	`WEBHOOK_KEY`, `WEBHOOK_HOST`, `WEBHOOK_TASK_UPDATE_STATUS_URL`, v.v.	Cấu hình webhook
Telegram	`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `TELEGRAM_CHAT_ERROR_ID`, `TELEGRAM_CHAT_REPORT_ID`	Bot thông báo
Proxy	`PROXY_USE_MAX`, `PROXY_ROTATE_MAX_CONCURRENT`, `LIMIT_SEND_TASK_PER_SERVER`	Giới hạn proxy
IP Whitelist	`WHITE_LIST_IP_TOOL_TRAFFIC`	Danh sách IP worker được phép
Scan URL	`PROXY_SCAN_DOMAIN_URL`, `API_SCAN_DOMAIN_URL`, `API_ACCESS_TOKEN`	URL dịch vụ quét domain
Traffic Pool	`TRAFFIC_GG_ADS`, `TRAFFIC_CC_ADS`, `TRAFFIC_KILL`, `TRAFFIC_HOME`, `TRAFFIC_NORMAL_CLICK`	Giới hạn traffic theo loại
DigitalOcean	`DIGITALOCEAN_ACCESS_KEY`, `DIGITALOCEAN_SECRET_KEY`, `DIGITALOCEAN_BUCKET_NAME`	Lưu trữ file
Mattermost	`MATTERMOST_API_URL`, `MATTERMOST_API_TOKEN`, `MATTERMOST_CHANNEL_ID`, `MATTERMOST_SCHEDULE`	Thông báo Mattermost
Proxy Providers	`PROXY_XOAY_USERNAME`, `PROXY_XOAY_PASSWORD`, `ENODE_PROXY_TOKEN`, `ZING_PROXY_TOKEN`, `M2_PROXY_TOKEN`	Credentials nhà cung cấp

2.2. `pkg/logger/logger.go` — Hệ Thống Logging Có Kênh

Đây là hệ thống logging quan trọng nhất của project. Được xây dựng trên nền go.uber.org/zap với tính năng logging theo kênh (channel-based logging):

Cơ chế hoạt động:

Logger gốc (default): ghi vào ./logs/system/{date}/log.log + stdout.

Logger kênh: GetLogger(channel) ghi vào ./logs/{channel}/{date}/log.log + stdout.

Cache logger: mỗi kênh chỉ tạo Zap instance một lần, cache lại bằng sync.RWMutex với Double-Check Locking pattern.

Cấu trúc file log theo ngày:

logs/
├── system/                       ← Log mặc định toàn hệ thống
│   └── 2026-03-26/log.log
├── background_services/          ← HealthCheck và TaskMonitor
│   └── 2026-03-26/log.log
├── proxy/                        ← Xoay vòng và kiểm tra proxy
│   └── 2026-03-26/log.log
├── task/                         ← Giao task và theo dõi trạng thái
│   └── 2026-03-26/log.log
├── cron/                         ← Cron job execution log
│   └── 2026-03-26/log.log
├── webhook/                      ← Nhận và xử lý webhook từ worker
│   └── 2026-03-26/log.log
├── keyword/                      ← Tìm kiếm từ khóa
│   └── 2026-03-26/log.log
├── keyword_pool_task/            ← Pool tác vụ từ khóa
│   └── 2026-03-26/log.log
├── keyword_result/               ← Kết quả từ khóa
│   └── 2026-03-26/log.log
├── project/                      ← Project và task
│   └── 2026-03-26/log.log
├── report/                       ← Báo cáo
│   └── 2026-03-26/log.log
└── user/                         ← Đăng nhập và xác thực
    └── 2026-03-26/log.log

Định dạng JSON của mỗi dòng log:

{
  "level": "error",
  "time": "26/03/2026 09:30:45",
  "caller": "service/task_service.go:187",
  "func": "tool-traffic-api/internal/task/service.(*Service).SendTask",
  "msg": "[LOG_LEVEL_ERROR] Failed to assign task to server",
  "LOG_ERROR_MESSAGE": "connection refused",
  "LOG_DATA:serverId": 5,
  "LOG_DATA:taskCount": 30
}

API logging functions:

2.3. `pkg/middleware/` — Middleware Xác Thực

AuthMiddleware (auth.go):

Đọc header Device-Token.

Query bảng users MySQL: WHERE device_token = ? AND is_logged_in = ?.

Cập nhật last_active_at = NOW().

Kiểm tra time.Since(last_active_at) > SESSION_TIMEOUT.

Lưu user_id vào c.Locals("user_id").

JWTMiddleware (jwt_middleware.go):

Dùng gofiber/contrib/jwt để verify chữ ký JWT bằng JWT_SECRET.

Lấy user_id từ JWT claims qua jwt.GetUserFromToken(c).

Đọc last_active_at từ Redis key user:activity:{user_id}.

Kiểm tra session timeout.

AdminMiddleware (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.

3. Quy Ước Code Trong Dự Án

3.1. Quy Tắc Tên Package

Package tên theo thư mục: package handler, package service, package repository.

Handler struct: Handler, Service struct: Service, Repository struct: Repository.

Constructor: NewHandler(), NewService(), NewRepository().

3.2. Quy Tắc Response HTTP

Mọi response JSON theo format chuẩn:

// Thành công
{
  "data": { ... },
  "message": "Success"
}

// Thành công với phân trang
{
  "data": [...],
  "total": 100,
  "page": 1,
  "per_page": 20,
  "last_page": 5
}

// Lỗi
{
  "message": "Error description"
}

3.3. Quy Tắc Error Handling

Handler không xử lý lỗi nghiệp vụ trong mình — delegate xuống Service.

Service trả về (result, error) theo convention Go.

Handler kiểm tra error và trả về HTTP status code phù hợp.

Không dùng panic trong business logic — chỉ dùng panic ở tầng init (logger, DB connection).

Dùng apperror.Unauthorized(), apperror.BadRequest(), v.v. thay vì trả về raw error.

3.4. Quy Tắc Sử Dụng Logger

3.5. Sử Dụng Makefile

3.6. Quy Tắc Cấu Trúc DTO

4. Chi Tiết Các Module Quan Trọng

4.1. Module User (`internal/user/`)

Endpoints:

GET /api/user/ — Danh sách user có phân trang.

GET /api/user/get-all — Toàn bộ user không phân trang.

GET /api/user/profile — Thông tin user đang đăng nhập.

GET /api/user/generate-totp — Tạo QR code 2FA.

GET /api/user/:id — Chi tiết user theo ID.

POST /api/user/ — Tạo user mới.

POST /api/user/verify-totp — Xác minh mã OTP.

PUT /api/user/:id — Cập nhật thông tin user.

PUT /api/user/change-password/:id — Đổi mật khẩu.

DELETE /api/user/:id — Xóa user.

4.2. Module Task (`internal/task/`)

Endpoints:

GET /api/task/reset-create-task — Reset tác vụ bị kẹt (public).

POST /api/task/request — tools_v2 yêu cầu tác vụ mới (public).

Webhook endpoints:

POST /webhook/task/update-status — Worker cập nhật trạng thái.

POST /webhook/task/update-process — Worker cập nhật tiến trình.

Module task cũng có TaskMonitor chạy trong background để phát hiện stuck tasks.

4.3. Module Server (`internal/server/`)

Endpoints:

GET /api/server/ — Danh sách server có phân trang.

GET /api/server/:id — Chi tiết server.

POST /api/server/ — Thêm server mới.

PUT /api/server/:id — Cập nhật server.

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

DELETE /api/server/:id — Xóa server.

POST /api/server/bulk-delete — Xóa nhiều server.

GET /api/servers/reports — Báo cáo tổng hợp server (public).

Module server cũng có HealthChecker được sử dụng bởi HealthCheckCron.

4.4. Module Keyword (`internal/keyword/`)

Endpoints:

GET /api/keywords/ — Danh sách từ khóa có phân trang.

GET /api/keywords/:id — Chi tiết từ khóa.

GET /api/keywords/:id/results — Lịch sử kết quả tìm kiếm.

POST /api/keywords/ — Tạo từ khóa mới.

PUT /api/keywords/:id — Cập nhật từ khóa.

PUT /api/keywords/update-status/:id — Cập nhật trạng thái.

POST /api/keywords/confirm-fire — Xác nhận kích hoạt tác vụ.

POST /api/keywords/reset/:id — Reset từ khóa.

POST /api/keywords/reset-all — Reset tất cả từ khóa.

DELETE /api/keywords/:id — Xóa từ khóa.

GET /api/keywords/export-excel — Xuất Excel.

4.5. Module Profile (`internal/profiles/`)

Module profile có cấu trúc đặc biệt — sử dụng MongoDB thay vì MySQL:

Profile service được khởi tạo với MongoDB repository:

Module này có thêm cache/, monitoring/ và routes/ riêng biệt.

4.6. Module Server Hourly Report (`internal/server_hourly_report/`)

Lưu trữ báo cáo hiệu suất theo giờ của từng server vào MongoDB. Mỗi bản ghi chứa:

id — ID server.

name — Tên server.

report[] — Mảng báo cáo theo từng khung giờ (0-23h):

process — Tổng số task đã xử lý.

success — Số task thành công.

fail — Số task thất bại.

hour_start — Giờ bắt đầu (0-23).

captcha — Số task gặp captcha.

error — Số task lỗi kỹ thuật.

unknown — Số task kết quả không xác định.

notfound — Số task không tìm thấy kết quả.

waiting — Số task đang chờ xử lý.

total_task — Tổng số task được giao.

Endpoint: GET /api/server-hourly-report — Trả về dữ liệu cho màn hình Server Performance của Admin Dashboard.

Code Structure

Tài Liệu Cấu Trúc Mã Nguồn — API Backend Traffic Tools V2#

1. Toàn Bộ Cây Thư Mục#

2. Chi Tiết Package pkg/#

2.1. pkg/env.go — Hệ Thống Biến Môi Trường#

2.2. pkg/logger/logger.go — Hệ Thống Logging Có Kênh#

2.3. pkg/middleware/ — Middleware Xác Thực#

3. Quy Ước Code Trong Dự Án#

3.1. Quy Tắc Tên Package#

3.2. Quy Tắc Response HTTP#

3.3. Quy Tắc Error Handling#

3.4. Quy Tắc Sử Dụng Logger#

3.5. Sử Dụng Makefile#

3.6. Quy Tắc Cấu Trúc DTO#

4. Chi Tiết Các Module Quan Trọng#

4.1. Module User (internal/user/)#

4.2. Module Task (internal/task/)#

4.3. Module Server (internal/server/)#

4.4. Module Keyword (internal/keyword/)#

4.5. Module Profile (internal/profiles/)#

4.6. Module Server Hourly Report (internal/server_hourly_report/)#

Tài Liệu Cấu Trúc Mã Nguồn — API Backend Traffic Tools V2

1. Toàn Bộ Cây Thư Mục

2. Chi Tiết Package `pkg/`

2.1. `pkg/env.go` — Hệ Thống Biến Môi Trường

2.2. `pkg/logger/logger.go` — Hệ Thống Logging Có Kênh

2.3. `pkg/middleware/` — Middleware Xác Thực

3. Quy Ước Code Trong Dự Án

3.1. Quy Tắc Tên Package

3.2. Quy Tắc Response HTTP

3.3. Quy Tắc Error Handling

3.4. Quy Tắc Sử Dụng Logger

3.5. Sử Dụng Makefile

3.6. Quy Tắc Cấu Trúc DTO

4. Chi Tiết Các Module Quan Trọng

4.1. Module User (`internal/user/`)

4.2. Module Task (`internal/task/`)

4.3. Module Server (`internal/server/`)

4.4. Module Keyword (`internal/keyword/`)

4.5. Module Profile (`internal/profiles/`)

4.6. Module Server Hourly Report (`internal/server_hourly_report/`)