Mô tả chi tiết
🎯 Giới thiệu
Online PC Store System là một đồ án full-stack thương mại điện tử hoàn chỉnh, chuyên bán máy tính, laptop, linh kiện và phụ kiện PC. Hệ thống được xây dựng theo kiến trúc tách biệt 3 tầng
rõ ràng:
- Backend API (NestJS) chạy ở cổng 4000, đảm nhiệm toàn bộ logic nghiệp vụ, xác thực, và truy cập cơ sở dữ liệu.
- Admin Dashboard (Next.js 15) chạy ở cổng 3001, là trang quản trị nội bộ dành cho chủ shop và nhân viên.
- Customer Storefront (Next.js 15) chạy ở cổng 3000, là website bán hàng dành cho khách.
Sản phẩm phù hợp làm đồ án tốt nghiệp Đại học/Cao đẳng, đồ án môn học Công nghệ phần mềm / Lập trình Web / Thương mại điện tử, hoặc dùng làm base thương mại để phát triển sản phẩm thật.
---
🧩 Công nghệ sử dụng
Backend sử dụng NestJS 10 kết hợp TypeORM, MySQL 8 làm cơ sở dữ liệu chính, Redis 7 cho cache và session. Xác thực bằng JWT với cơ chế access token + refresh token, có Swagger để test API
trực quan, BullMQ cho hàng đợi nền, và Nodemailer để gửi email.
Admin Dashboard dùng Next.js 15 (App Router) với TypeScript strict mode, styling bằng Tailwind CSS, font DM Sans, form sử dụng React Hook Form kết hợp Zod để validate.
Customer Storefront cũng dùng Next.js 15 (App Router) với TypeScript strict, Tailwind CSS, font Inter, hỗ trợ SSR và ISR để tối ưu SEO và tốc độ tải trang.
Toàn bộ hệ thống có file seed.sql chứa schema và dữ liệu mẫu đầy đủ, phân quyền theo Role (admin / nhân viên kho / nhân viên bán hàng / khách hàng).
---
📦 Tính năng nổi bật
🛒 Phía khách hàng (Storefront)
Khách hàng có thể đăng ký, đăng nhập, quên mật khẩu thông qua email OTP. Trang chủ hiển thị Flash Sale giờ vàng, sản phẩm hot, danh mục sản phẩm bắt mắt. Hệ thống tìm kiếm hỗ trợ lọc nâng
cao theo thông số kỹ thuật (CPU, RAM, GPU, dung lượng ổ cứng…).
Trang chi tiết sản phẩm có hỗ trợ biến thể (variants) — ví dụ cùng một mẫu laptop nhưng nhiều cấu hình RAM/SSD khác nhau, kèm gallery ảnh đa góc nhìn. Đặc biệt có công cụ Build PC giúp
khách tự cấu hình một bộ máy theo nhu cầu, hệ thống tự kiểm tra tương thích linh kiện.
Khách hàng có giỏ hàng, danh sách yêu thích (Wishlist), so sánh sản phẩm, thanh toán online (đã tích hợp sẵn flow payment), xem lịch sử đơn hàng, theo dõi trạng thái giao hàng, và gửi yêu
cầu đổi/trả hàng. Hệ thống Loyalty tự động tích điểm thành viên, phân hạng khách (Đồng, Bạc, Vàng, Kim cương) với mức ưu đãi khác nhau. Khách cũng có thể đánh giá sản phẩm và liên hệ với
shop qua trang hỗ trợ trực tuyến.
🛠️ Phía quản trị (Admin Dashboard)
Trang Dashboard hiển thị thống kê tổng quan với biểu đồ trực quan: doanh thu theo ngày/tháng, số đơn hàng, sản phẩm bán chạy, khách hàng mới.
Module Quản lý sản phẩm cho phép tạo/sửa/xóa sản phẩm cùng biến thể, giá cả, hình ảnh và thông số kỹ thuật chi tiết. Module Danh mục, Thương hiệu, Nhà cung cấp quản lý cây danh mục đa cấp,
logo thương hiệu, và thông tin nhà cung cấp.
Module Kho (Inventory) quản lý nhập/xuất hàng, theo dõi tồn kho thời gian thực, cảnh báo khi sản phẩm sắp hết. Module Đơn hàng cho phép duyệt đơn, đổi trạng thái, in hóa đơn; Đổi/Trả hàng
(Returns) quản lý quy trình hoàn tiền và đổi sản phẩm.
Module Khách hàng hiển thị danh sách khách, hạng thành viên, điểm tích lũy, lịch sử mua. Module Nhân viên & Phân quyền quản lý tài khoản nhân viên với phân quyền theo Role.
Flash Sale cho phép cấu hình các chương trình giờ vàng với % giảm giá tùy chỉnh. Khuyến mãi & Voucher tạo các mã giảm giá theo nhiều điều kiện. Module CMS quản lý banner, trang tĩnh, blog.
Module Báo cáo xuất báo cáo doanh thu, lợi nhuận, tồn kho theo nhiều khoảng thời gian.
Đặc biệt có Audit Log — nhật ký ghi lại mọi thao tác của admin (ai làm gì, lúc nào, sửa từ giá trị gì sang giá trị gì) — rất thích hợp để show với giảng viên hướng dẫn. Module Thông báo đẩy
notification trong hệ thống, và Cài đặt quản lý thông tin shop, SMTP email, cổng thanh toán.
---
📁 Cấu trúc thư mục
Thư mục gốc Source/ chứa 3 dự án con cùng các tài liệu hỗ trợ. Backend nằm trong computer-store-backend/, gồm 27 module nghiệp vụ tại src/modules/, các interceptor/filter/guard dùng chung
tại src/common/. Admin Dashboard nằm trong computer-store-admin-frontend/ với các trang quản trị ở src/app/(dashboard)/, trang đăng nhập ở src/app/(auth)/, các service gọi API ở
src/services/, và type contracts ở src/types/. Storefront khách nằm trong computer-store-client-frontend/ với cấu trúc tương tự.
Ngoài ra ở thư mục gốc còn có seed.sql (dữ liệu mẫu), README.md, API-CONTRACT.md, INTEGRATION.md, requirements.md và auditlog_guide.md.
---
✅ Điểm mạnh của đồ án
Code được viết sạch với TypeScript strict mode ở cả 3 dự án, không lạm dụng any. Kiến trúc tách biệt rõ ràng Service / Controller / DTO / Entity theo đúng chuẩn NestJS. Swagger sẵn sàng tại
http://localhost:4000/api/docs để bạn test API trực quan và ghi vào báo cáo đồ án.
Hệ thống có Design System đầy đủ — token màu, font, spacing thống nhất giữa các trang. Kèm theo bộ tài liệu chi tiết bao gồm API contract, integration tracker, module spec, và database
mapping — rất tiện để bạn nắm code nhanh và viết báo cáo.
XEM THÊM ==> Hướng dẫn cài đặt chi tiết
HƯỚNG DẪN CÀI ĐẶT
Hướng dẫn cài đặt chi tiết
📋 Yêu cầu hệ thống
Trước khi cài đặt, máy tính của bạn cần có sẵn các phần mềm sau. Node.js phiên bản 20 LTS trở lên (tải tại nodejs.org). MySQL 8.0+ — có thể cài qua XAMPP, Laragon hoặc MySQL Workbench.
Redis 7.x — trên Windows dùng Memurai hoặc Redis-Windows, trên Linux/macOS cài trực tiếp. Ngoài ra cần Git để quản lý code và khuyến nghị dùng VS Code để mở file Source.code-workspace đã
được cấu hình sẵn. Máy nên có RAM tối thiểu 8GB vì sẽ chạy đồng thời 3 dự án.
---
🔧 Bước 1 — Chuẩn bị Database
Mở MySQL Workbench (hoặc phpMyAdmin nếu dùng XAMPP) và tạo một database mới với câu lệnh:
CREATE DATABASE computer_store
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
Sau đó import file seed.sql ở thư mục gốc bằng command line:
mysql -u root -p computer_store < seed.sql
Hoặc nếu dùng MySQL Workbench, chọn File → Open SQL Script, mở seed.sql rồi nhấn nút Run (biểu tượng tia sét).
Ghi nhớ thông tin kết nối để dùng ở bước sau: host là localhost, port 3306, user thường là root, password là mật khẩu MySQL bạn đã đặt khi cài, database tên computer_store.
---
🔧 Bước 2 — Cài đặt và chạy Redis
Trên Windows, cách đơn giản nhất là tải Memurai bản miễn phí tại memurai.com/get-memurai. Sau khi cài, Memurai sẽ tự chạy như một Windows Service ở localhost:6379.
Trên macOS, mở Terminal và chạy brew install redis, rồi brew services start redis.
Trên Linux (Ubuntu/Debian), dùng sudo apt install redis-server và khởi động bằng sudo systemctl start redis.
Để kiểm tra Redis đã chạy chưa, chạy lệnh redis-cli ping — nếu trả về PONG là thành công.
---
🔧 Bước 3 — Cài đặt Backend (NestJS)
Mở terminal, di chuyển vào thư mục backend và cài đặt dependencies (lần đầu sẽ mất khoảng 3–5 phút):
cd computer-store-backend
npm install
Tạo file .env từ template bằng lệnh copy .env.example .env trên Windows, hoặc cp .env.example .env trên macOS/Linux.
Mở file .env vừa tạo và chỉnh sửa các giá trị cho khớp với môi trường của bạn:
# === Database ===
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_mysql_password
DB_DATABASE=computer_store
# === Redis ===
REDIS_HOST=localhost
REDIS_PORT=6379
# === JWT ===
JWT_ACCESS_SECRET=super-secret-access-key-change-me
JWT_REFRESH_SECRET=super-secret-refresh-key-change-me
JWT_ACCESS_EXPIRES=15m
JWT_REFRESH_EXPIRES=30d
# === App ===
PORT=4000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000
ADMIN_URL=http://localhost:3001
# === Email (tùy chọn — để test gửi mail OTP) ===
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USER=your_email@gmail.com
MAIL_PASS=your_app_password
Lưu ý: phần MAIL_PASS nếu dùng Gmail phải tạo App Password riêng, không dùng mật khẩu Gmail thường.
Chạy backend bằng lệnh npm run start:dev. Khi terminal hiển thị log "Application is running on: http://localhost:4000", mở trình duyệt vào http://localhost:4000/api/docs — nếu thấy giao
diện Swagger là backend đã chạy thành công.
---
🔧 Bước 4 — Cài đặt Admin Frontend
Mở một terminal mới (đừng tắt terminal backend ở bước 3) và làm các bước sau:
cd computer-store-admin-frontend
npm install
copy .env.example .env.local
Mở file .env.local và đặt biến môi trường:
NEXT_PUBLIC_API_URL=http://localhost:4000
Lưu ý cực kỳ quan trọng: KHÔNG được thêm /api vào cuối URL này — code đã tự xử lý thêm phần đó, nếu bạn thêm vào sẽ gây lỗi gọi API hai lần /api/api/....
Chạy admin dashboard bằng npm run dev, sau đó truy cập http://localhost:3001. Đăng nhập bằng tài khoản admin mặc định từ seed.sql: email admin@store.com, password Admin@123.
---
🔧 Bước 5 — Cài đặt Client Frontend
Mở terminal thứ ba và lặp lại các bước tương tự:
cd computer-store-client-frontend
npm install
copy .env.example .env.local
Chỉnh .env.local với NEXT_PUBLIC_API_URL=http://localhost:4000 (cũng không thêm /api).
Chạy storefront bằng npm run dev, truy cập http://localhost:3000. Đăng nhập bằng tài khoản khách mẫu: email customer@example.com, password Customer@123.
---
🧪 Bước 6 — Kiểm tra toàn hệ thống
Khi cả 3 dự án đã chạy, mở 3 tab trình duyệt: tab đầu vào http://localhost:4000/api/docs để xem Swagger và test API, tab thứ hai vào http://localhost:3001 để dùng Admin Dashboard, tab thứ
ba vào http://localhost:3000 để xem trang khách hàng.
Để test flow hoàn chỉnh một cách nhanh chóng: vào storefront ở tab 3, đăng nhập tài khoản khách, thêm vài sản phẩm vào giỏ hàng, đặt hàng. Sau đó chuyển sang tab admin, vào mục Đơn hàng —
bạn sẽ thấy đơn vừa tạo. Đổi trạng thái đơn từ "Chờ xác nhận" sang "Đang xử lý", rồi vào mục Audit Log để thấy hệ thống đã ghi lại thao tác này.
---
🚨 Xử lý sự cố thường gặp
Nếu backend báo lỗi ECONNREFUSED 3306, nghĩa là MySQL chưa chạy — vào Services (Windows) hoặc Activity Monitor để bật MySQL lên. Nếu báo ECONNREFUSED 6379 thì Redis chưa chạy, hãy khởi động
Memurai/Redis. Nếu báo Access denied for user 'root' thì sai mật khẩu MySQL, kiểm tra lại biến DB_PASSWORD trong file .env backend.
Lỗi Port already in use xảy ra khi cổng 4000/3000/3001 đã bị app khác chiếm — đóng app đó hoặc đổi sang port khác trong .env. Nếu frontend hiện trắng trang và console báo CORS, kiểm tra
FRONTEND_URL và ADMIN_URL trong backend .env đã trùng với URL frontend thực tế chưa.
Nếu npm install báo lỗi conflict, xóa thư mục node_modules và file package-lock.json, sau đó chạy lại npm install --legacy-peer-deps. Nếu Swagger không hiển thị, đảm bảo
NODE_ENV=development trong file .env backend. Nếu đăng nhập admin thất bại, có thể seed chưa chạy đủ — chạy lại file seed.sql để khôi phục dữ liệu mẫu.
---
📦 Build production (tùy chọn — nếu muốn deploy)
Sau khi đã chạy ổn ở môi trường dev, bạn có thể build cho production. Với backend, chạy npm run build để biên dịch TypeScript ra JavaScript, sau đó npm run start:prod để chạy bản
production. Với admin và client frontend, cũng chạy npm run build để Next.js tối ưu hóa, sau đó npm run start để khởi động server production.
---
📞 Hỗ trợ cài đặt
Nếu gặp khó khăn trong quá trình cài đặt, vui lòng liên hệ shop và gửi kèm ảnh chụp màn hình báo lỗi, nội dung file .env (nhớ che password trước khi gửi), và log từ terminal. Shop sẽ hỗ trợ
remote cài đặt qua UltraViewer/AnyDesk hoàn toàn miễn phí kể từ ngày mua, đảm bảo bạn chạy được hệ thống mới tính hoàn tất giao dịch.
Nguồn: Topcode.vn
