Smart Queue Booking System — Hệ Thống Đặt Lịch & Quản Lý Hàng Chờ Thông Minh

Hệ thống Smart Queue Booking System là ứng dụng web full-stack hiện đại dành cho việc đặt lịch vé số điện tử và quản lý hàng chờ thời gian thực tại các trung tâm dịch vụ, bệnh viện, ngân hàng hoặc cơ quan hành chính.

Hệ thống được thiết kế theo kiến trúc RESTful API với Backend xây dựng trên Spring Boot 3 (Java 21) và Frontend xây dựng trên React 19 (TypeScript, Vite, Tailwind CSS).

---

📌 Tính Năng Chính (Key Features)

1. Khách Hàng (Customer Console)

• Xem danh mục dịch vụ: Tra cứu thông tin dịch vụ, thời gian thực hiện trung bình.
• Đặt vé số điện tử (Virtual Ticket Booking): Đặt vé hàng chờ theo ngày, hệ thống tự động cấp số thứ tự (queueNumber) và mã vé duy nhất (bookingCode: BK-S{serviceId}-{YYYYMMDD}-{queueNumber}).
• Tính toán thời gian chờ tự động: Hiển thị thời gian bắt đầu dự kiến (estimatedStartTime) và số người đang chờ phía trước (remainingAhead).
• Quản lý vé: Theo dõi danh sách vé đang chờ/đang phục vụ và hủy vé trực tiếp.

2. Nhân Viên Quầy (Counter Dispatch Terminal)

• Bảng điều khiển quầy (Dispatch Controller): Chọn dịch vụ phục vụ và gọi lượt tiếp theo (Call Next Customer) theo nguyên tắc FIFO.
• Cập nhật trạng thái lượt phục vụ: Hoàn thành lượt (Complete) hoặc bỏ qua vé vắng mặt (Skip/Cancel).
• Bảng chỉ số KPI thời gian thực: Theo dõi số lượt đang phục vụ, số lượt chờ, lượt hoàn thành và lượt hủy trong ngày.

3. Quản Trị Viên (Admin Console)

• Quản lý danh mục dịch vụ (Service Management): Thêm mới, chỉnh sửa thông tin, bật/tắt trạng thái hoạt động của dịch vụ.
• Quản lý người dùng: Tra cứu và quản lý thông tin các tài khoản trong hệ thống.
• Xem nhật ký hệ thống (Audit Logs): Theo dõi lịch sử thao tác của nhân viên và khách hàng.

4. Bảo Mật & Tối Ưu Hiệu Năng

• Bảo mật: Phân quyền chi tiết dựa trên vai trò (Role-Based Access Control - RBAC) với Spring Security 6 và JWT (JSON Web Token).
• Tối ưu truy vấn SQL: Sử dụng JOIN FETCH ngăn chặn sự cố N+1 Query, đánh chỉ mục B-tree Indexes trên các trường tra cứu chính.
• Xử lý lỗi tập trung: Ghi nhận và phản hồi thông báo lỗi nghiệp vụ rõ ràng qua GlobalExceptionHandler.

---

🛠️ Công Nghệ Sử Dụng (Tech Stack)

Backend

• Core Framework: Java 21 (LTS), Spring Boot 3.3.5
• Security: Spring Security 6, JWT (jjwt 0.12.6), BCrypt Password Encoder
• Database & ORM: Spring Data JPA, Hibernate 6, H2 In-Memory Database (cho Dev) / MySQL Support
• Documentation: Springdoc OpenAPI / Swagger UI
• Build Tool: Maven

Frontend

• Core Library: React 19, TypeScript, Vite
• Styling: Tailwind CSS v4, Lucide React (Icons)
• State & Data Fetching: TanStack React Query v5, Zustand, Axios
• Form & Validation: React Hook Form, Zod
• Notification: React Hot Toast

---

📂 Cấu Trúc Dự Án (Project Structure)

project 2/
├── src/main/java/com/smartqueue/
│   ├── config/              # Cấu hình CORS, Swagger, DataLoader
│   ├── controller/          # REST Controllers (Auth, Booking, Queue, Service, Audit)
│   ├── dto/                 # Data Transfer Objects (Request/Response)
│   ├── entity/              # JPA Entities (User, Service, Queue, Booking, AuditLog)
│   ├── exception/           # Custom Exceptions & GlobalExceptionHandler
│   ├── repository/         # Spring Data JPA Repositories
│   ├── security/           # JwtAuthenticationFilter, JwtService, UserDetailsService
│   └── service/            # Business Logic Services & Implementations
│
├── frontend/                # React Vite Frontend Application
│   ├── src/
│   │   ├── components/      # UI Layout & Reusable Components
│   │   ├── lib/             # Axios Config & Utilities
│   │   ├── pages/           # Pages (UserDashboard, StaffDashboard, AdminDashboard, Auth Pages)
│   │   └── types/           # TypeScript Types & Interfaces
│   ├── package.json
│   └── vite.config.ts
│
├── performance_optimization.md  # Tài liệu phân tích và tối ưu hiệu năng DB/JVM
├── run-project.bat          # Script tự động khởi chạy cả Backend & Frontend
└── pom.xml                  # Maven Build Configuration

---

🚀 Hướng Dẫn Khởi Chạy (Quick Start)

Yêu Cầu Hệ Thống

• Java Development Kit (JDK): Java 21 trở lên.
• Node.js: v18.x trở lên & npm.

---

Cách 1: Khởi chạy nhanh bằng File Script (Khuyên dùng)

Chạy file batch tự động mở 2 cửa sổ terminal cho Backend và Frontend:

double-click vào file: run-project.bat

---

Cách 2: Khởi chạy thủ công từng phần

1. Khởi chạy Backend (Spring Boot API)

Mở cửa sổ Terminal tại thư mục gốc dự án:

# Đặt biến môi trường JAVA_HOME (nếu chưa cấu hình)
set JAVA_HOME=C:\Program Files\Java\jdk-21

# Khởi chạy ứng dụng Spring Boot
.\mvnw.cmd spring-boot:run

• Server Backend chạy tại: http://localhost:8080/api
• Trang tài liệu OpenAPI Swagger UI: http://localhost:8080/api/swagger-ui.html

2. Khởi chạy Frontend (React + Vite)

Mở một cửa sổ Terminal khác tại thư mục frontend:

cd frontend
npm install
npm run dev

• Giao diện web chạy tại: http://localhost:3000

---

🔑 Tài Khoản Mẫu Để Kiểm Thử (Default Test Credentials)

Hệ thống được cấu hình tự động tạo dữ liệu mẫu khi khởi chạy (DataLoader):

Vai Trò	Email	Mật Khẩu	Quyền Hạn
Quản trị viên (Admin)	admin@example.com	Password123!	Toàn quyền quản lý dịch vụ, người dùng, audit logs
Nhân viên quầy (Staff)	staff@example.com	Password123!	Điều phối quầy, gọi số tiếp theo, hoàn thành/bỏ qua lượt
Khách hàng (User)	user@example.com	Password123!	Đặt vé, hủy vé, xem danh sách chờ thời gian thực

---

📑 Tài Liệu Kỹ Thuật & Tối Ưu

Tham khảo chi tiết phân tích tối ưu hiệu năng cơ sở dữ liệu, đánh chỉ mục (Index) và giải pháp chống lỗi N+1 Query tại file performance_optimization.md.