Hướng dẫn cài đặt Wsport API (Branch: wcip-rapid)

Tài liệu này hướng dẫn chi tiết các bước để cài đặt và chạy mã nguồn Wsport API từ nhánh wcip-rapid.

1. Yêu cầu hệ thống (Prerequisites)

Trước khi bắt đầu, hãy đảm bảo máy bạn đã cài đặt các công cụ sau:

Go: Phiên bản 1.24.0 trở lên.

Docker & Docker Compose: Để chạy Redis và Elasticsearch.

MySQL: Phiên bản 8.0 trở lên.

Công cụ hỗ trợ (Optional nhưng nên có):

golang-migrate: Để quản lý database schema.

sqlc: Để sinh mã nguồn Go từ SQL.

air: Để tự động reload khi sửa code.

2. Các bước cài đặt (Installation Steps)

Bước 1: Clone và Chuyển nhánh

Mở terminal và chạy các lệnh sau:

Bước 2: Cài đặt Dependencies

Cài đặt các thư viện Go cần thiết:

Bước 3: Thiết lập môi trường (Environment Variables)

Tạo file .env từ file mẫu:

Sau đó, hãy mở file .env và cập nhật các thông số sau cho phù hợp với máy của bạn:

DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME: Thông tin kết nối MySQL.

REDIS_HOST, REDIS_PORT: Thông tin kết nối Redis.

ES_ADDR: Địa chỉ Elasticsearch.

RAPID_KEY: API Key của bạn từ RapidAPI.

3. Chạy ứng dụng

Bạn có thể chạy ứng dụng bằng lệnh:

Hoặc nếu đã cài air để phát triển:

Các lệnh bổ trợ khác:

Đồng bộ Elasticsearch: Nếu cần đánh index lại dữ liệu tìm kiếm:

Sinh code SQLC: Nếu bạn có thay đổi trong các file SQL ở thư mục db/queries:

Cấu trúc dự án

├── cmd/                        # Các điểm chạy (Entry points) của ứng dụng
│   ├── searchsync/            # Script đồng bộ dữ liệu vào Elasticsearch
│   └── worker/                # Script khởi chạy Worker xử lý background jobs
├── commons/                    # Các thành phần dùng chung (Shared layer)
│   ├── appError.go            # Chuẩn hóa xử lý lỗi toàn hệ thống
│   ├── appSuccess.go          # Chuẩn hóa phản hồi (Response) thành công
│   ├── errors/                # Định nghĩa các mã lỗi tùy chỉnh theo module
│   ├── models/                # Các struct model dùng chung
│   ├── pagination.go          # Logic phân trang cho API
│   ├── queryBuilder.go        # Bộ xây dựng câu lệnh truy vấn linh hoạt
│   └── uows/                  # Pattern Unit of Work quản lý transaction
├── config/                     # Quản lý cấu hình (Configuration)
│   ├── config.go              # Load biến môi trường, cấu hình Viper
│   ├── database.go            # Khởi tạo kết nối MySQL (Read/Write)
│   └── redis.go               # Cấu hình Redis và Asynq
├── db/                         # Lớp dữ liệu (Database layer)
│   ├── migrations/            # Các file schema SQL quản lý version DB
│   ├── models/                # Định nghĩa bảng (SQL schema) cho SQLC
│   ├── queries/               # Các câu lệnh SQL dùng để generate code Go
│   └── *.sql.go               # Code Go được SQLC tự động tạo ra
├── internal/                   # Logic xử lý nội bộ (Core backend logic)
│   ├── cron/                  # Đăng ký và quản lý tất cả các lịch chạy Cron
│   └── worker/                # Cấu hình và chạy Asynq worker server
├── modules/                    # Các module tính năng (Feature-based - Clean Arch)
│   ├── [feature_name]/        # Ví dụ: team, player, schedule...
│   │   ├── domain.go         # Chứa các Model và Interface của module
│   │   ├── handler.go        # Xử lý HTTP Request/Response (Fiber)
│   │   ├── usecase.go        # Xử lý logic nghiệp vụ (Business logic)
│   │   ├── routes.go         # Khai báo các endpoint API của module
│   │   └── rapidsync/        # Logic đồng bộ riêng từ RapidAPI cho module đó
├── pkg/                        # Các gói thư viện bao gói (Wrappers)
│   ├── cloudinary/            # Tích hợp lưu trữ ảnh Cloudinary
│   ├── elasticsearch/         # Wrapper truy vấn Elasticsearch
│   ├── redis/                 # Wrapper quản lý Redis client
│   └── external/rapidapi/     # Client gọi API hệ thống RapidAPI
├── server/                     # Khởi tạo và vận hành Server
│   ├── index.go               # Cấu hình Fiber app, Graceful shutdown
│   └── router.go              # Đăng ký Route và Middleware toàn hệ thống
├── utils/                      # Các hàm tiện ích bổ trợ (Helpers)
│   ├── convertTime.go         # Xử lý chuyển đổi định dạng thời gian
│   ├── validate.go            # Logic validation dữ liệu đầu vào
│   └── random.go              # Tạo chuỗi hoặc số ngẫu nhiên
├── main.go                     # File chạy chính của toàn bộ hệ thống
└── sqlc.yaml                   # File cấu hình của SQLC tool

Environment Variables (.env)

1. Server & Logging

PORT=8080
ENV=production

LOG_LEVEL=info
LOG_FILE=logs/app.log

2. Database Pool & Storage

DB_POOL_MAX_OPEN=80
DB_POOL_MAX_IDLE=20


REDIS_HOST=74.82.63.183
REDIS_PORT=21002
REDIS_PASSWORD=
REDIS_DB=0

#REDIS_HOST_SPORT_READ=redis-14740.c10.us-east-1-4.ec2.cloud.redislabs.com
#REDIS_PORT_SPORT_READ=14740
#REDIS_PASSWORD_SPORT_READ=
#REDIS_DB_SPORT_READ=0

REDIS_HOST_SPORT_READ=74.82.63.183
REDIS_PORT_SPORT_READ=21002
REDIS_PASSWORD_SPORT_READ=
REDIS_DB_SPORT_READ=1

REDIS_PREFIX_RAPID_SYNC=api_soccer_database_api_soccer_cache_:


REDIS_HOST_ELASTIC_SEARCH_READ=74.82.63.183
REDIS_PORT_ELASTIC_SEARCH_READ=21002
REDIS_PASSWORD_ELASTIC_SEARCH_READ=
REDIS_DB_ELASTIC_SEARCH_READ=0

3. External APIs

API_ISPORT=http://api.demo.com/
KEY_API_ISPORT=***

RAPID_API=https://data.rapid-api.icu/v1
RAPID_KEY=***

RAPID_API_ENDPOINT_TEAMS=/football/team/additional/list
RAPID_API_ENDPOINT_ODDS=/football/odds/live

ENDPOINT_SCHEDULE_RESULTS=path_demo

4. S3 & CDN

AWS_ENDPOINT_URL=https://img.nospace.network
AWS_DEFAULT_REGION=auto

AWS_ACCESS_KEY_ID=***
AWS_SECRET_ACCESS_KEY=***

AWS_ENDPOINT=https://35666.oss.swiftserve.com

AWS_BUCKET_DATA=cdn-dien-sport
AWS_BUCKET=cdn-sport

DISK=s3
S3_TYPE=total

5. Cron Control (Bật/Tắt)

ENABLE_CRON_HEAD_TO_HEAD=ON
ENABLE_CRON_MATCH_ANALYSIS=ON

ENABEL_CRON_RAPID_TEAMS=OFF
ENABEL_CRON_RAPID_DETAIL_LIVE=ON
ENABEL_CRON_RAPID_SCHEDULE_CHANGES=ON
ENABEL_CRON_RAPID_TEAM_STATS=ON
ENABEL_CRON_RAPID_ODDS=ON
ENABEL_CRON_RAPID_PLAYER_STATS=ON
ENABEL_CRON_RAPID_REFEREE=ON
ENABEL_CRON_RAPID_ODDS_DETAIL=ON

6. AI / External Service (Optional)

GROK_API_KEY=***
GROK_API_ENDPOINT=

Source Code

Hướng dẫn cài đặt Wsport API (Branch: wcip-rapid)#

1. Yêu cầu hệ thống (Prerequisites)#

2. Các bước cài đặt (Installation Steps)#

Bước 1: Clone và Chuyển nhánh#

Bước 2: Cài đặt Dependencies#

Bước 3: Thiết lập môi trường (Environment Variables)#

3. Chạy ứng dụng#

Các lệnh bổ trợ khác:#

Cấu trúc dự án#

Environment Variables (.env)#

1. Server & Logging#

2. Database Pool & Storage#

3. External APIs#

4. S3 & CDN#

5. Cron Control (Bật/Tắt)#

6. AI / External Service (Optional)#