Smart Digital Library - Hệ Thống Thư Viện Số Thông Minh

Dự án phát triển Hệ thống Quản lý và Chia sẻ Tài nguyên Thư viện số dành cho Học sinh, Sinh viên và Thủ thư. Hệ thống được thiết kế theo mô hình tách biệt hiện đại (Decoupled Architecture) với Spring MVC ở phía Backend (đóng gói chạy trên Tomcat Container) và React JS ở phía Frontend (Single Page Application).

🚀 1. Công Nghệ Sử Dụng

🔹 Backend (Spring MVC API Server)

Core: Spring MVC 6, Jakarta EE 10, Java 17.
Bảo mật: Spring Security 6, JSON Web Token (JWT) để xác thực không lưu trạng thái (Stateless Authentication).
ORM & Database: Hibernate 6, MySQL 8, JPA Criteria API cho các truy vấn động phức tạp.
Lưu trữ đám mây: Cloudinary SDK (Upload và CDN hóa tài liệu số, hình ảnh đại diện, tệp tin nhị phân).
Quản lý thanh toán: Tích hợp cổng thanh toán kép VNPAY API và PayOS SDK.
Công cụ build: Maven 3.

🔹 Frontend (React Client)

Core: React JS 18, React Router DOM v6.
Giao tiếp API: Axios Client (quản lý Interceptors tự động gắn JWT Token).
Giao diện: CSS Vanilla thiết kế theo phong cách giao diện học đường thanh lịch (Academic Clean Theme), tối ưu hóa trải nghiệm người dùng (UX/UI).

🔹 Container & DevOps

Dockerization: Viết sẵn Dockerfile tối ưu cho cả Frontend và Backend.
Orchestration: Docker Compose quản lý đồng bộ toàn bộ stack hệ thống (Database, Backend, Frontend).
Production Platforms: Triển khai trên hạ tầng đám mây phân tán: Vercel (Frontend), Render (Backend), Aiven Cloud (Managed MySQL).

📐 2. Kiến Trúc Hệ Thống & Luồng Dữ Liệu

Kiến trúc tách biệt (Decoupled Architecture) hoạt động theo cơ chế Client-Server truyền nhận dữ liệu phi trạng thái:

graph TD
    subgraph Frontend [React JS - Client Side - Port 3000]
        UI[Giao diện React SPA] -->|Gửi yêu cầu HTTP| Axios[Axios HTTP Client]
    end
    
    subgraph Backend [Spring MVC - API Server - Port 8080]
        Axios -->|1. Xác thực CORS / JWT| Security[Spring Security & JWT Filter]
        Security -->|2. Ánh xạ Endpoint| Controller[Rest Controller]
        Controller -->|3. Xử lý nghiệp vụ| Service[Service Layer]
        Service -->|4. Hibernate HQL/Criteria| Repository[Repository Layer]
        Repository -->|5. Truy vấn SQL| DB[(MySQL Database)]
        Service -->|6. Tải tài liệu số| Cloudinary[Cloudinary Cloud Storage]
    end

🌟 3. Các Tính Năng Cốt Lõi

Xác thực & Phân quyền đa cấp: Phân chia rõ ràng 3 vai trò người dùng (ROLE_USER độc giả, ROLE_LIBRARIAN thủ thư, ROLE_ADMIN quản trị viên) dựa trên cơ chế Stateless JWT token.
Quản lý học liệu số & Tải lên đám mây: Hỗ trợ thủ thư upload tài liệu (PDF, DOCX, MP3, MP4), tự động phân tích định dạng file nhị phân và đẩy trực tiếp lên Cloudinary CDN.
Bộ lọc tìm kiếm thông minh nâng cao: Tìm kiếm kết hợp theo từ khóa, danh mục chuyên ngành, và lượt xem phổ biến bằng JPA Criteria API tối ưu hóa.
Cổng thanh toán kép đồng bộ:
- VNPAY: Xác thực đồng bộ an toàn qua chữ ký số SHA-512 và redirect URL.
- PayOS: Xác thực bất đồng bộ thời gian thực thông qua hệ thống Webhook an toàn (Server-to-Server).
Đánh giá & Xếp hạng cộng đồng: Cho phép thành viên chấm điểm đánh giá (1-5 sao) và ghi nhận ý kiến phản hồi về chất lượng tài liệu.
So sánh học liệu đa tiêu chí: Bảng đối chiếu so sánh song song tối đa 3 cuốn sách theo tác giả, năm xuất bản, điểm đánh giá và giá cả.

💻 4. Hướng Dẫn Cài Đặt & Chạy Local

📦 Bước 1: Chuẩn bị Cơ sở dữ liệu (MySQL)

Tạo một cơ sở dữ liệu mới trong MySQL có tên là sdldb.

Kiểm tra hoặc cấu hình lại thông tin kết nối trong tệp tin: SpringDigitalLibrary/src/main/resources/databases.properties

hibernate.connection.url=jdbc:mysql://localhost:3306/sdldb
hibernate.connection.username=root
hibernate.connection.password=Admin@123

☕ Bước 2: Khởi chạy API Server (Spring MVC)

Mở dự án SpringDigitalLibrary bằng các công cụ như IntelliJ IDEA hoặc Eclipse.
Biên dịch dự án qua Maven:
```
mvn clean install
```
Cấu hình máy chủ Apache Tomcat (Phiên bản 10.1+) trong IDE để trỏ đến tệp tin .war được sinh ra trong thư mục target.
Khởi động Tomcat. Máy chủ API sẽ lắng nghe tại địa chỉ: http://localhost:8080/SpringDigitalLibrary/.
Khi khởi động lần đầu, trình DatabaseInitializer sẽ tự động tạo bảng dữ liệu và chèn các tài khoản mẫu sau:
- Admin: admin / Mật khẩu: 123456
- Librarian: librarian / Mật khẩu: 123456
- User: user / Mật khẩu: 123456

⚛️ Bước 3: Khởi chạy Client (React JS)

Di chuyển vào thư mục libraryweb:
```
cd libraryweb
```
Cài đặt các thư viện cần thiết:
```
npm install
```
Tạo tệp tin .env trong thư mục libraryweb nếu chưa có và cấu hình:
```
REACT_APP_API_URL=http://localhost:8080/SpringDigitalLibrary/api
```
Khởi chạy dự án:
```
npm start
```
Trình duyệt sẽ tự động mở trang chủ tại địa chỉ: http://localhost:3000.

🐳 5. Khởi Chạy Nhanh Bằng Docker Compose (Chạy Toàn Bộ Hệ Thống)

Hệ thống đã được đóng gói đầy đủ dưới dạng Docker container. Bạn có thể khởi chạy toàn bộ ứng dụng (Database, Backend, Frontend) chỉ với duy nhất một câu lệnh mà không cần cài đặt môi trường phức tạp:

Đảm bảo máy tính của bạn đã cài đặt Docker và Docker Compose.
Đứng tại thư mục gốc của dự án (nơi chứa tệp tin docker-compose.yml), chạy lệnh sau:
```
docker-compose up --build -d
```
Docker Compose sẽ tự động:
- Khởi tạo container MySQL (sdl_db) và tạo cơ sở dữ liệu sdldb.
- Biên dịch mã nguồn Java, đóng gói WAR và chạy trong container Tomcat (sdl_backend).
- Biên dịch mã nguồn React, cấu hình máy chủ Nginx để phục vụ static files (sdl_frontend).
Truy cập giao diện người dùng tại địa chỉ: http://localhost:3001. API Server chạy tại: http://localhost:8081/admin/login.

☁️ 6. Hướng Dẫn Triển Khai Thực Tế (Production Deployment)

Video demo deloy:

0602.1.mp4

Hệ thống hỗ trợ cấu trúc triển khai đám mây phân tán, giúp chịu tải tốt và độc lập về mặt tài nguyên:

graph LR
    Client([Độc giả truy cập]) -->|HTTPS| Vercel[Vercel - Frontend React]
    Vercel -->|REST API Calls| Render[Render - Backend Tomcat Docker]
    Render -->|Kết nối Secure JDBC| Aiven[(Aiven Cloud - Managed MySQL)]

🗄️ A. Triển khai Cơ sở dữ liệu đám mây (Aiven Managed MySQL)

Truy cập Aiven Console và tạo một dịch vụ MySQL mới (gói Free Tier).
Khi trạng thái dịch vụ chuyển sang Running, sao chép các thông tin kết nối an toàn được cấp:
- Host: Ví dụ: mysql-xxxx.l.aivencloud.com
- Port: Ví dụ: 12345
- User: avnadmin
- Password: Mật khẩu do Aiven cung cấp
- Database Name: defaultdb (Hoặc tạo cơ sở dữ liệu mới tên là sdldb).

⚙️ B. Triển khai API Server (Render - Backend)

Tạo tài khoản trên Render và liên kết với tài khoản Github chứa kho mã nguồn này.
Tạo một Web Service mới trên Render và trỏ tới repository của dự án.
Thiết lập thông số cơ bản:
- Name: libraryweb-backend
- Environment: Docker
- Docker Command: Để mặc định (Render tự động đọc Dockerfile trong thư mục SpringDigitalLibrary để build).
Đi tới mục Environment Variables và cấu hình các biến môi trường sau để ghi đè cấu hình local:
- DB_URL = jdbc:mysql://<Aiven_Host>:<Aiven_Port>/<Database_Name>?useSSL=true&requireSSL=true (Thay thế Host, Port, Database tương ứng).
- DB_USER = Tên đăng nhập cơ sở dữ liệu Aiven (ví dụ: avnadmin).
- DB_PASSWORD = Mật khẩu Aiven.
- PORT = 8080 (Cổng mặc định của Tomcat).
Nhấn Deploy Web Service. Render sẽ tiến hành kéo code, thực hiện multi-stage build và khởi chạy ứng dụng Tomcat trực tuyến.

🌐 C. Triển khai Giao diện (Vercel - Frontend)

Tạo dự án mới trên Vercel liên kết với Github repository này.
Thiết lập cấu hình thư mục gốc:
- Root Directory: Chọn thư mục libraryweb.
- Framework Preset: Chọn Create React App (hoặc Other).
Trong tab Environment Variables, cấu hình biến API kết nối đến Backend vừa triển khai trên Render:
- REACT_APP_API_URL = Địa chỉ Web Service Render của bạn kèm /api (Ví dụ: https://libraryweb-backend.onrender.com/api).
Nhấn Deploy. Vercel sẽ tự động tối ưu hóa dung lượng React client và cung cấp đường dẫn truy cập công khai dạng HTTPS.

FilesExpand file tree

README.md

Latest commit

History