Hệ thống RESTful API cho nền tảng thương mại điện tử chuyên cung cấp thiết bị máy tính. Dự án được xây dựng với kiến trúc phần mềm chuyên nghiệp, đảm bảo tính mở rộng, bảo mật cao và tối ưu hóa quy trình xử lý nghiệp vụ.
- Ngôn ngữ: Java 21
- Framework chính: Spring Boot 3.5.9
- Bảo mật: Spring Security & JSON Web Token (Thư viện
nimbus-jose-jwt) - Tương tác CSDL (DAL): Spring Data JPA / Hibernate
- Cơ sở dữ liệu: MySQL (
mysql-connector-j) - Mapping Dữ liệu: MapStruct 1.5.5.Final
- Thanh toán (Payment Gateway): Tích hợp VNPay Sandbox API
- Tiện ích: Lombok, Spring Boot Validation, Hibernate Batching
- Build Tool: Maven
- Đăng ký, Đăng nhập và bảo mật stateless bằng JWT.
- Phân quyền chi tiết (Role-based access control) cho
AdminvàUser. - Quản lý vòng đời Token bảo mật nghiêm ngặt: Hỗ trợ Refresh Token, cơ chế Blacklist Token khi người dùng Logout (
InvalidatedToken). - Background Jobs: Tích hợp
TokenCleanupJobchạy ngầm để tự động dọn dẹp các token đã hết hạn khỏi CSDL.
- Thiết kế hệ thống sản phẩm phức tạp: Hỗ trợ quản lý sản phẩm đi kèm với nhiều biến thể (Product Variants) dựa trên định nghĩa thuộc tính động (Attribute Definitions & Variant Attribute Values).
- Tổ chức theo danh mục (Category) và thương hiệu (Brand).
- Upload và lưu trữ hình ảnh sản phẩm nội bộ an toàn (1MB/file, max 10MB/request).
- Quản lý giỏ hàng (
Cart,CartItem) với hiệu suất cao. Tích hợpCartCleanupItemjob để dọn dẹp giỏ hàng rác. - Xử lý Đặt hàng (Checkout) và theo dõi chặt chẽ lịch sử trạng thái đơn hàng (
OrderStatusHistory). - Hỗ trợ công cụ tìm kiếm đơn hàng nâng cao cho Admin qua
OrderSpecification.
- Tích hợp trực tiếp với cổng thanh toán VNPay.
- Khởi tạo URL giao dịch (
PaymentTransaction), xác minh chữ ký mã hóa SHA-512 (checksum) an toàn. - Webhook/Return URL (
VNPayController) để nhận và cập nhật trạng thái đơn hàng tự động từ VNPay.
- Chuẩn hóa toàn bộ luồng dữ liệu trả về cho Client thông qua
GlobalExceptionHandlervà cácErrorCodetùy chỉnh (AppException,StorageException). Giúp Frontend dễ dàng bắt lỗi và hiển thị thân thiện.
Dự án áp dụng mô hình phân lớp tiêu chuẩn để tách biệt rõ ràng các trách nhiệm:
- configuration/: Cấu hình hệ thống (Web, VNPay, File Storage, Initializer)
- security/: Cấu hình Spring Security, JWT Filters, Cookie Utilities
- controller/: Presentation Layer (API Endpoints) - Tiếp nhận HTTP requests
- service/: BLL (Business Logic Layer) - Chứa Interfaces và Impl xử lý nghiệp vụ lõi
- repository/: DAL (Data Access Layer) - Giao tiếp CSDL qua Spring Data JPA
- entity/: Các lớp thực thể (Domain Models) ánh xạ với bảng MySQL
- dto/: Data Transfer Objects - Chuẩn hóa Input/Output (Request/Response)
- mapper/: MapStruct interfaces tự động chuyển đổi giữa DTO và Entity
- exception/: Xử lý lỗi toàn cục và định nghĩa ErrorCodes
- enums/: Các tập hằng số (OrderStatus, PaymentStatus, RoleType,...)
- job/: Các tác vụ chạy ngầm định kỳ (Spring Scheduling)
- specification/: Xây dựng các câu truy vấn động phức tạp (OrderSpecification)
- utils/: Các hàm tiện ích dùng chung (Slug generator, Order utils)
- Java 21
- Maven 3.x
- MySQL Server (Port mặc định 3306)
Bước 1: Clone kho lưu trữ
git clone https://github.com/giap0201/computer-shop.git cd computer-shop
Bước 2: Cấu hình Cơ sở dữ liệu & Môi trường
Mở file src/main/resources/application.properties và điều chỉnh các thông số:
- MySQL: Đảm bảo bạn đã tạo database
computer_shop_db. Hệ thống sẽ tự động tạo bảng (ddl-auto=update). - JWT & VNPay: Nếu cần, bạn có thể thay đổi chuỗi bí mật JWT hoặc Sandbox keys của VNPay để test trên tài khoản merchant riêng.
Bước 3: Build và Chạy ứng dụng Dùng Maven Wrapper có sẵn để chạy dự án:
Đối với Windows:
mvnw.cmd clean install mvnw.cmd spring-boot:run
Đối với Linux/macOS:
./mvnw clean install ./mvnw spring-boot:run
Server sẽ khởi chạy tại: http://localhost:8080/api