🧧 Tết Countdown & Mini Games System 🎆

Giao diện Web tương tác Real-time Sảnh Game Ngày Tết

Một ứng dụng Web hiện đại mang không khí Tết truyền thống lên không gian mạng. Hệ thống cung cấp trải nghiệm mượt mà với các sảnh game dân gian (Bầu Cua, Lô Tô) chơi theo thời gian thực nhiều người, kết hợp các hoạt động tương tác độc đáo như Hái Lộc Đầu Xuân và Xin Chữ Ông Đồ.

🌟 Hệ sinh thái Lễ hội & SSO: Dự án này là một phần của Festive Ecosystem, chia sẻ chung hệ thống tài khoản (Single Sign-On - SSO) và cơ sở dữ liệu với dự án Christmas Wishes. Người dùng chỉ cần đăng ký một lần để trải nghiệm xuyên suốt các mùa lễ hội!

💻 FRONTEND WEB APPLICATION

Đây là Repository chứa mã nguồn Frontend, cung cấp giao diện tương tác trực quan, hiệu ứng sống động và kết nối WebSockets thời gian thực dành cho người chơi.

🛠️ Công nghệ & Phiên bản

Dự án được xây dựng với các công nghệ hiện đại trong hệ sinh thái React/Next.js:

🏗️ Core Stack

Công nghệ	Phiên bản	Vai trò
Next.js	16.1.6	Framework React sử dụng App Router, xử lý Layout & Routing
React	19.2.3	Thư viện UI core, xây dựng giao diện Component-based
react-dom	19.2.3	Thư viện kết xuất DOM cho React
Zustand	5.0.13	Quản lý Global State (duy trì trạng thái nhạc nền xuyên suốt các trang)

---

🎨 UI & Styling

Công nghệ	Phiên bản	Vai trò
Tailwind CSS	4.1.18	Utility-first CSS framework (Phiên bản v4 mới nhất)
lucide-react	0.564.0	Bộ icon SVG tối giản, sắc nét và tối ưu cho React

---

🌐 Networking & Real-time

Công nghệ	Phiên bản	Vai trò
Socket.io Client	4.8.3	Kết nối WebSockets, đồng bộ trạng thái Game Real-time
Axios	1.13.5	HTTP Client gọi RESTful API (Lịch sử, Auth, Thông tin User)
@react-oauth/google	0.13.5	Cung cấp Provider và Hook xử lý luồng đăng nhập Google OAuth2

---

✨ Animations & Utilities

Công nghệ	Phiên bản	Vai trò
react-confetti	6.4.0	Hiệu ứng pháo giấy nổ tung màn hình khi trúng thưởng/Hái lộc
@fireworks-js/react	2.10.8	Hiệu ứng pháo hoa nền động chân thực
lunar-javascript	1.7.7	Tính toán Lịch Âm, kiểm tra giờ Giao Thừa & Ngày Tết ở Client
react-use	17.6.0	Bộ custom hooks đa năng (ví dụ: lấy kích thước màn hình cho Confetti)

🌟 Tính năng giao diện

• 🎲 Sảnh Bầu Cua Tôm Cá (Real-time):

  • Giao diện bàn cược trực quan với hiệu ứng Glassmorphism (Kính mờ).
  • Đồng bộ đếm ngược, xóc đĩa và hiển thị số lượng người chơi thời gian thực qua WebSockets.
  • Popup tính toán và thông báo Lời/Lỗ tự động cực kỳ bắt mắt.

• 🎟️ Sảnh Lô Tô Đầu Xuân (Real-time):

  • Thuật toán tự sinh và hiển thị ma trận vé 3x9 chuẩn chỉ.
  • Hiệu ứng "Dạ quang" phát sáng các con số được gọi.
  • Nút "Kinh!" thông minh: Ẩn/Hiện dựa trên thuật toán check hàng ngang tự động.

• 🌳 Hái Lộc & Xin Chữ:

  • Hái Lộc: Giao diện chia 2 cột hiện đại, hiển thị rõ tỷ lệ rơi lộc (Ngày thường/Giao thừa). Hiệu ứng rung rinh lì xì và nổ pháo giấy khi hái trúng.
  • Xin Chữ: Giao diện cuộn giấy thư pháp truyền thống, cho phép nhập từ khóa và nhận câu chúc sinh bởi AI.

• 📱 Trải nghiệm người dùng (UX) tối ưu:

  • Giao diện Responsive 100%, tự động thay đổi Layout linh hoạt trên Mobile và PC.
  • Xử lý triệt để các lỗi Accessibility (Viền trắng focus outline) trên Chrome/Edge.
  • Ngăn chặn hành vi thao tác sai (Anti-spam clicks) và bảo vệ route bằng Middleware.

• 🔐 Xác thực & Định danh (SSO):

  • Tích hợp đăng nhập nhanh bằng Google mượt mà, tiện lợi.
  • Giao diện form đăng ký/đăng nhập tích hợp hiệu ứng tương tác (hover/active scale) trau chuốt.
  • Hệ thống tài khoản liên thông hoàn toàn với nền tảng Christmas Wishes.

• 🎵 Quản lý Âm thanh Toàn cục (Global State):

  • Tách biệt logic âm thanh sử dụng Zustand, đảm bảo nhạc nền và tiếng pháo hoa được duy trì liền mạch, không bị re-render hay đứt quãng khi chuyển đổi giữa các sảnh game.

• 🚫 Custom Pages (Trang 404 Lễ hội):

  • Giao diện Not Found (404) được thiết kế riêng biệt "chuẩn concept" Tết (kết hợp hiệu ứng lấp lánh, hộp quà và văn phong dí dỏm về Ông Đồ/Lô Tô).

📸 Demo Giao diện

Sảnh Bầu Cua

Sảnh Lô Tô

Hái Lộc

Xin Chữ

🚀 Cài đặt & Khởi chạy

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

Dự án được xây dựng trên Next.js 16 và React 19, yêu cầu môi trường tối thiểu:

• Node.js: >= 20.x LTS
• Package Manager: npm >= 9, yarn, pnpm hoặc bun

2️⃣ Clone & Cài đặt Dependencies

git clone https://github.com/hvt299/Tet-Countdown-Web.git
cd Tet-Countdown-Web
npm install

3️⃣ Cấu hình môi trường (.env)

Tạo file .env tại thư mục gốc của dự án:

NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_GOOGLE_CLIENT_ID=YourSecretKeyHere

4️⃣ Lệnh chạy (Scripts)

# Chạy môi trường phát triển (Hot Reload)
npm run dev

# Build ra production (Tối ưu hóa)
npm run build

# Chạy bản production
npm run start

Sau khi chạy, truy cập giao diện tại:

http://localhost:3000

📂 Cấu trúc dự án

src/
├── app/                 # Next.js App Router (Pages, Layouts, Middleware)
├── components/          # Reusable UI Components
├── lib/                 # API Calls (Axios interceptors)
├── store/               # Zustand Global States (useMusicStore)
└── utils/               # Utilities (tetHelper)

🔗 Kết nối Backend

Dự án Frontend này bắt buộc phải chạy song song với Backend Service (mặc định ở cổng 3001) để các API Authentication và máy chủ Socket.io (Real-time Games) có thể hoạt động.

👨‍💻 Author

Developed by Mr.T (hvt299)
GitHub: https://github.com/hvt299