Nền tảng ôn tập trực tuyến HUBT — Spring Boot 4, Leaderboard API, Frontend tĩnh tích hợp

🎓 HUBT Review Platform

Nền tảng ôn tập trực tuyến dành cho sinh viên HUBT — tích hợp backend Spring Boot 4 phục vụ API và frontend tĩnh trong cùng một ứng dụng.

Build ↗

✨ Tính năng

📚 Ôn tập nhiều môn: Cơ sở dữ liệu, C++, Python, Tin học 2
🎯 Thi thử với tùy chỉnh số câu, thời gian, chế độ xem đáp án ngay
🏆 Leaderboard online — bảng xếp hạng theo điểm %, số câu đúng, thời gian
🖼️ Hỗ trợ ảnh câu hỏi cho các môn cần hình minh họa
🎵 Tích hợp nhạc YouTube — người dùng tự nhập link/video ID
⚡ Không cần database để chạy — leaderboard lưu trong bộ nhớ backend
🐳 Docker Compose sẵn sàng để mở rộng (PostgreSQL, MongoDB, Redis)

🧰 Tech Stack

Công nghệ	Phiên bản	Vai trò
Java	21	Ngôn ngữ chính
Spring Boot	4.0.6	Backend framework
Spring WebMVC	-	REST API + Serve static files
Spring Security	-	Bảo mật API
Spring Actuator	-	Health check & monitoring
Lombok	latest	Giảm boilerplate
Gradle	9.x	Build tool
Docker Compose	-	Services tùy chọn (DB, Cache)

📦 Yêu cầu hệ thống

Công cụ	Phiên bản	Link tải
Java JDK	21+	Adoptium
Git	2.x+	git-scm.com
Docker Desktop (tùy chọn)	4.x+	docker.com

✅ Không bắt buộc có Docker — app chạy được ngay mà không cần database.

⚡ Chạy nhanh

# 1. Clone repo
git clone https://github.com/ilcde/hubt-review-platform.git
cd hubt-review-platform

# 2. Chạy ứng dụng
./gradlew bootRun          # Linux / macOS
gradlew.bat bootRun        # Windows

Mở trình duyệt tại: http://localhost:8080

🖥️ Hướng dẫn chạy trên máy mới (từ đầu)

Bước 1 — Cài Java 21

Windows:

Vào https://adoptium.net/ → chọn Temurin 21 LTS → tải file .msi
Cài đặt, tích chọn "Set JAVA_HOME variable" khi được hỏi
Kiểm tra trong Command Prompt / PowerShell:
```
java -version
```
Kết quả mong đợi: openjdk version "21.x.x"

macOS (Homebrew):

brew install --cask temurin@21

Ubuntu / Debian:

sudo apt update && sudo apt install openjdk-21-jdk -y
java -version

Bước 2 — Clone project

git clone https://github.com/ilcde/hubt-review-platform.git
cd hubt-review-platform

Bước 3 — Cấu hình môi trường (tùy chọn)

Mặc định app chạy được ngay không cần cấu hình gì thêm.

Nếu muốn tùy chỉnh, copy file .env.example thành .env:

# Windows
copy .env.example .env

# Linux / macOS
cp .env.example .env

Rồi chỉnh các giá trị trong .env:

SERVER_PORT=8080                              # Port chạy app (mặc định 8080)
LEADERBOARD_MAX_ROWS=50                       # Số dòng tối đa leaderboard
LEADERBOARD_ADMIN_TOKEN=your-secret-token     # Token để xóa leaderboard

⚠️ Không commit file .env lên GitHub — đã có trong .gitignore

Bước 4 — Chạy ứng dụng

# Windows
gradlew.bat bootRun

# Linux / macOS
chmod +x gradlew
./gradlew bootRun

App sẵn sàng khi thấy log:

Started HubtReviewPlatformApplication in X.XXX seconds

Bước 5 — Kiểm tra

URL	Mô tả
http://localhost:8080	🌐 Trang ôn tập chính
http://localhost:8080/api/health	✅ Health check
http://localhost:8080/api/leaderboard	🏆 Leaderboard API
http://localhost:8080/actuator/health	📊 Spring Actuator

⚙️ Cấu hình

Tất cả config đọc từ biến môi trường (file .env) hoặc dùng giá trị mặc định:

Biến	Mặc định	Mô tả
`SERVER_PORT`	`8080`	Port của server
`LEADERBOARD_MAX_ROWS`	`50`	Giới hạn số dòng leaderboard
`LEADERBOARD_ADMIN_TOKEN`	(trống)	Token để gọi `DELETE /api/leaderboard`

🐳 Docker (tùy chọn — để mở rộng backend)

Docker không bắt buộc để chạy app. Dùng khi muốn thêm database thật:

# Copy và điền thông tin vào .env trước
cp .env.example .env

# Khởi động services
docker compose up -d

# Kiểm tra
docker ps

Services trong compose.yaml:

🐘 PostgreSQL → localhost:5432
🍃 MongoDB → localhost:27017
🔴 Redis → localhost:6379

📡 API Reference

Health Check

GET /api/health

Response:

{
  "status": "ok",
  "service": "hubt-review-platform",
  "time": "2026-06-17T10:00:00Z"
}

Leaderboard

Lấy bảng xếp hạng

GET /api/leaderboard

Thêm kết quả

POST /api/leaderboard
Content-Type: application/json

{
  "id": "uuid-here",
  "subjectId": "csdl",
  "subjectTitle": "Cơ sở dữ liệu",
  "name": "Nguyễn Văn A",
  "date": "2026-06-17T00:00:00Z",
  "correct": 50,
  "total": 60,
  "percent": 83,
  "timeout": false,
  "infinite": false,
  "elapsedSeconds": 1800
}

Xóa leaderboard (cần Admin Token)

DELETE /api/leaderboard
X-Admin-Token: your-secret-token

Thứ tự xếp hạng:

% điểm cao hơn
Số câu đúng nhiều hơn
Tổng số câu lớn hơn
Thời gian làm bài ngắn hơn

📁 Cấu trúc thư mục

hubt-review-platform/
├── src/
│   ├── main/
│   │   ├── java/com/ilcde/firstproject/
│   │   │   ├── HubtReviewPlatformApplication.java  # Entry point
│   │   │   ├── DemoController.java                 # Test endpoint
│   │   │   ├── LeaderboardController.java           # API leaderboard
│   │   │   ├── LeaderboardEntry.java               # Model
│   │   │   ├── LeaderboardService.java             # Business logic
│   │   │   └── SecurityConfig.java                 # Security config
│   │   └── resources/
│   │       ├── application.properties              # Cấu hình chính
│   │       └── static/                             # Frontend tĩnh
│   │           ├── index.html
│   │           ├── app.js
│   │           ├── styles.css
│   │           └── *-question-data.js              # Ngân hàng câu hỏi
│   └── test/
├── .env.example          # Template cấu hình môi trường
├── .github/workflows/    # GitHub Actions CI
├── compose.yaml          # Docker services (tùy chọn)
├── build.gradle.kts      # Gradle build config
├── gradlew / gradlew.bat # Gradle wrapper
└── README.md

🔧 Lệnh Gradle

# Chạy dev (hot reload với DevTools)
./gradlew bootRun

# Build JAR
./gradlew build -x test

# Chạy tests
./gradlew test

# Clean + build
./gradlew clean build -x test

# Chạy JAR trực tiếp
java -jar build/libs/hubt-review-platform-0.0.1-SNAPSHOT.jar

🔒 Bảo mật khi public GitHub

❌ Không commit .env, token, mật khẩu database
❌ Không commit .zip, .exe, .pdf, .docx
✅ Mọi giá trị nhạy cảm đọc từ biến môi trường
✅ Backend public không yêu cầu login cho API học tập
✅ Cache Gradle, output build, IDE config đều loại bỏ bởi .gitignore

🐛 Xử lý lỗi thường gặp

Port 8080 bị chiếm

# Windows — tìm PID đang dùng port 8080
netstat -ano | findstr :8080
# Kill process (thay XXXX bằng PID)
taskkill /PID XXXX /F

# Linux / macOS
lsof -ti:8080 | xargs kill

`java` không nhận ra

Kiểm tra lại đã cài JDK 21 chưa (không phải JRE)
Trên Windows: thêm C:\Program Files\Eclipse Adoptium\jdk-21...\bin vào PATH

Build thất bại

./gradlew clean build -x test --info

📄 License

MIT License — tự do sử dụng và chỉnh sửa.

hubt-review-platform

README