LandingP CMS — Hệ Thống Quản Trị Nội Dung Toàn Diện
LandingP CMS — Website bán hàng + Admin quản trị toàn diện, sẵn sàng deploy, dễ dàng tuỳ biến. Công nghệ NestJS + React hiện đại, code sạch, có sẵn Swagger API.
1. Tổng Quan Dự Án
LandingP CMS là hệ thống quản trị nội dung (CMS) được xây dựng theo kiến trúc monorepo, bao gồm 3 thành phần chính:
-
Backend API (NestJS + PostgreSQL) — Xử lý logic nghiệp vụ, cung cấp REST API
-
Admin Panel (React + Ant Design) — Giao diện quản trị cho người vận hành
-
Landing Page (React + Tailwind) — Giao diện người dùng cuối, hiển thị nội dung ra công chúng
2. Tính Năng Chi Tiết
2.1. Landing Page (Giao diện khách hàng)
-
Trang chủ với Hero section, banner slider, sản phẩm nổi bật
-
Danh sách sản phẩm theo danh mục, tìm kiếm, phân trang vô hạn
-
Chi tiết sản phẩm: hình ảnh slider, mô tả rich text (HTML), giá khuyến mãi, tab đánh giá
-
Trang tin tức / blog với danh sách + chi tiết + sidebar bài viết liên quan
-
Trang giới thiệu, quy trình sản xuất, chính sách, liên hệ
-
Form gửi thông tin liên hệ → gửi email tự động qua SMTP
-
Giỏ hàng yêu thích (Wishlist)
-
Chia sẻ Facebook, responsive toàn bộ giao diện
2.2. Admin Panel (Quản trị viên)
-
Site Config: Tuỳ chỉnh giao diện real-time — màu sắc, logo, favicon, banner, top bar, contact, hero section. Thay đổi ở Admin → Landing Page cập nhật ngay lập tức.
-
Products: Thêm/sửa/xoá sản phẩm, upload ảnh kéo thả, CKEditor cho mô tả, chế độ Draft/Publish, ghim sản phẩm nổi bật (pin).
-
Blogs: Viết bài với CKEditor, upload thumbnail, Draft/Publish.
-
Categories: Quản lý danh mục sản phẩm.
-
Policies: Quản lý nội dung chính sách (đổi trả, vận chuyển, bảo mật...).
-
About: Tuỳ chỉnh nội dung giới thiệu, tầm nhìn, sứ mệnh, giá trị cốt lõi.
-
Manufacturing Process: Quản lý các bước quy trình sản xuất kèm hình ảnh.
-
Uploads: Quản lý hình ảnh đã upload theo từng loại (product, blog, site-config...).
-
Sidebar thu gọn, breadcrumb động, giao diện responsive, dark mode.
2.3. REST API
-
API công khia cho khách truy cập (products, blogs, categories, config...)
-
API Admin bảo vệ bằng JWT Bearer token
-
Upload file đa năng: product, blog, site-config, manu-process
-
Phân trang, tìm kiếm, lọc theo danh mục
-
Định dạng response chuẩn:
{ success, data, meta, error }
-
Swagger UI tại
/api-docs — test API trực quan ngay trên trình duyệt
-
API tìm kiếm toàn văn (products + blogs)
3. Công Nghệ Sử Dụng
3.1. Backend
|
Công nghệ |
Phiên bản |
Mục đích |
|
NestJS |
11 |
Framework Node.js enterprise |
|
TypeScript |
5.9 |
Ngôn ngữ |
|
PostgreSQL |
16 |
Cơ sở dữ liệu |
|
TypeORM |
0.3 |
ORM — tự động đồng bộ schema |
|
JWT + Passport |
|
Xác thực Admin |
|
Swagger |
11 |
API Documentation |
|
Nodemailer |
8 |
Gửi email SMTP (Resend, Ethereal...) |
|
Multer |
|
Upload file |
3.2. Frontend — Admin Panel
|
Công nghệ |
Mục đích |
|
React 19 |
UI Framework |
|
TypeScript |
Ngôn ngữ |
|
Vite 7 |
Build tool — HMR siêu nhanh |
|
Ant Design 6 |
UI Components chuyên nghiệp |
|
Tailwind CSS 4 |
Utility CSS linh hoạt |
|
Redux Toolkit + RTK Query |
State management & API calls |
|
React Router v7 |
Routing & bảo vệ route |
|
CKEditor 5 |
Rich text editor (soạn thảo HTML) |
|
Leaflet |
Bản đồ tương tác |
|
react-dropzone |
Kéo thả upload ảnh |
3.3. Frontend — Landing Page
|
Công nghệ |
Mục đích |
|
React 19 |
UI Framework |
|
TypeScript |
Ngôn ngữ |
|
Vite 7 |
Build tool |
|
Ant Design 6 |
UI Components |
|
Tailwind CSS 4 |
Utility CSS |
|
Redux Toolkit + RTK Query |
State management & API calls |
|
React Router v7 |
Routing & lazy loading |
|
Leaflet |
Bản đồ |
3.4. Devops & Tools
-
Docker & Docker Compose — Chạy toàn bộ hệ thống với 1 lệnh
-
PostgreSQL 16 — Cơ sở dữ liệu container hoá
-
ESLint + Prettier — code style
-
Jest — Unit / E2E testing
4. Cấu Trúc Thư Mục
LandingP CMS
├ cms-be-master/ # NestJS Backend (port 3000)
│ ├ src/
│ │ ├ auth/ # JWT Authentication
│ │ ├ product/ # Product management
│ │ ├ blog/ # Blog management
│ │ ├ category/ # Category management
│ │ ├ policy/ # Policy management
│ │ ├ about/ # About page
│ │ ├ site-config/ # Site configuration
│ │ ├ image/ # Image upload management
│ │ ├ search/ # Full-text search
│ │ ├ notification/ # Contact form & email
│ │ ├ common/ # Shared (guards, interceptors)
│ │ ├ scripts/ # Seeding scripts
│ │ └ ...
│ │ Dockerfile
│ └ ...
│
├ content-management-system-main/ # Admin Panel (port 5174)
│ ├ src/
│ │ ├ pages/ # Admin pages
│ │ ├ components/ # Shared components
│ │ ├ services/ # RTK Query API services
│ │ ├ routes/ # Routing + guards
│ │ ├ providers/ # Context providers
│ │ └ ...
│ │ Dockerfile
│ └ ...
│
├ landing-page-main/ # Landing Page (port 5173)
│ ├ src/
│ │ ├ pages/
│ │ ├ components/
│ │ ├ services/
│ │ ├ routes/
│ │ ├ provider/
│ │ └ ...
│ │ Dockerfile
│ └ ...
│
└ docker-compose.yml # Docker orchestration
5. API Endpoints
|
Method |
Endpoint |
Auth |
Mô tả |
|
GET |
/ |
— |
Redirect → Swagger UI |
|
POST |
/auth/login |
— |
Đăng nhập Admin |
|
GET |
/auth/me |
JWT |
Thông tin Admin |
|
GET |
/products |
— |
Danh sách sản phẩm (public) |
|
GET |
/products/:id |
— |
Chi tiết sản phẩm |
|
GET |
/popular-products |
— |
Sản phẩm nổi bật |
|
GET |
/blogs |
— |
Danh sách bài viết (public) |
|
GET |
/blogs/:id |
— |
Chi tiết bài viết |
|
GET |
/categories |
— |
Danh sách danh mục |
|
GET |
/policies |
— |
Danh sách chính sách |
|
GET |
/config |
— |
Site config (public) |
|
POST |
/notifications |
— |
Gửi liên hệ |
|
GET |
/search |
— |
Tìm kiếm toàn văn |
|
GET/POST/PUT/DELETE |
/admin/* |
JWT |
Quản trị CRUD |
|
POST |
/admin/uploads |
JWT |
Upload ảnh |
📖 Swagger UI: http://localhost:3000/api-docs
6. Tài Khoản Mặc Định
|
Vai trò |
Email |
Password |
|
Admin |
admin@gmail.com |
admin123 |
7. Yêu Cầu Hệ Thống
-
Node.js 20.x trở lên
-
Docker & Docker Compose (khuyên dùng)
-
Hoặc: PostgreSQL 16 + Node.js (nếu chạy thủ công)
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 Và Chạy LandingP CMS
🚀 Cách 1: Docker (Khuyên dùng)
Chạy toàn bộ hệ thống (PostgreSQL + Backend + Admin + Landing Page) với một lệnh duy nhất.
Yêu cầu
Các bước thực hiện
-
Clone dự án:
git clone <url-repo>
cd LandingP-CMS
-
Khởi động tất cả services:
docker compose up -d
-
Seed dữ liệu mẫu (chạy 1 lần đầu):
docker compose exec backend npm run seed
-
Mở trình duyệt:
|
Service |
URL |
|
Landing Page |
http://localhost:5173 |
|
Admin Panel |
http://localhost:5174 |
|
Backend API |
http://localhost:3000 |
|
Swagger UI |
http://localhost:3000/api-docs |
|
Database (PostgreSQL) |
localhost:5432 |
Các lệnh Docker thường dùng
|
Lệnh |
Mô tả |
docker compose up -d |
Khởi động tất cả |
docker compose logs -f |
Xem log tất cả services |
docker compose logs -f backend |
Xem log 1 service |
docker compose down |
Dừng tất cả |
docker compose down -v |
Dừng và xoá dữ liệu (DB + uploads) |
docker compose build --no-cache backend |
Rebuild sau khi thay đổi code |
🛠 Cách 2: Chạy thủ công (không Docker)
Yêu cầu
-
Node.js 20.x trở lên
-
PostgreSQL 16 (đã cài và đang chạy)
-
npm (đi kèm Node.js)
Bước 1: Cài đặt dependencies
# Backend
cd cms-be-master
npm install
# Admin Panel
cd ../content-management-system-main
npm install
# Landing Page
cd ../landing-page-main
npm install
Bước 2: Cấu hình môi trường
Backend — tạo file cms-be-master/.env:
DATABASE_URL=postgresql://postgres:password@localhost:5432/cms
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d
ADMIN_EMAIL=admin@gmail.com
ADMIN_PASSWORD=admin123
PORT=3000
CMS_ORIGIN=http://localhost:5174
LANDING_ORIGIN=http://localhost:5173
# SMTP (dùng Resend, Ethereal, Mailhog...)
SMTP_HOST=smtp.resend.com
SMTP_PORT=465
SMTP_USER=resend
SMTP_PASS=re_your-api-key
SMTP_FROM=LandingP <noreply@yourdomain.com>
MAIL_TO=admin@gmail.com
Admin Panel — file content-management-system-main/.env.development:
VITE_BASE_URL=http://localhost:3000
VITE_GOONG_API_KEY=
Landing Page — file landing-page-main/.env:
VITE_BASE_URL=http://localhost:3000
Bước 3: Tạo database
psql -U postgres -c "CREATE DATABASE cms;"
Bước 4: Chạy project (3 terminal)
# Terminal 1 — Backend
cd cms-be-master
npm run dev
# Terminal 2 — Admin Panel
cd content-management-system-main
npm run dev
# Terminal 3 — Landing Page
cd landing-page-main
npm run dev
Bước 5: Seed dữ liệu mẫu
Đợi backend chạy xong (tự động đồng bộ database), sau đó mở terminal thứ 4:
cd cms-be-master
npm run seed
🔑 Tài Khoản Mặc Định
|
Vai trò |
Email |
Password |
|
Admin |
admin@gmail.com |
admin123 |
📦 Seed Dữ Liệu Mẫu
Lệnh npm run seed sẽ tạo toàn bộ dữ liệu demo:
-
15 sản phẩm (trà atiso, tinh bột nghệ, tinh dầu, viên uống...) với mô tả HTML chi tiết
-
5 bài blog về thảo dược, sức khỏe
-
6 danh mục sản phẩm
-
5 chính sách (đổi trả, vận chuyển, bảo mật, thành viên, bảo hành)
-
~45 cấu hình website (màu sắc, banner, contact, top bar...)
-
Quy trình sản xuất 6 bước
-
Thông tin About + 5 giá trị cốt lõi
⚠ Lưu ý: Seed sẽ xoá toàn bộ dữ liệu cũ trước khi tạo mới.
☁ Triển Khai Production
Backend
cd cms-be-master
npm run build
npm run prod
Hoặc dùng PM2:
npm install -g pm2
pm2 start dist/main.js --name cms-backend
Frontend (Admin Panel & Landing Page)
cd content-management-system-main
npm run build # Output: dist/
cd landing-page-main
npm run build # Output: dist/
Copy thư mục dist/ lên server (Nginx, Apache, Vercel...).
🐞 Lỗi Thường Gặp
|
Vấn đề |
Giải pháp |
relation "products" does not exist |
Chạy npm run seed sau khi backend đã start (synchronize xong) |
ECONNREFUSED database |
Kiểm tra PostgreSQL đã chạy chưa, đúng port chưa |
Cannot find module |
Chạy npm install |
|
Docker: port already allocated |
Đổi port trong docker-compose.yml hoặc tắt service đang chiếm port |
|
Mail: Invalid from field |
SMTP_FROM phải có định dạng email hoặc Tên <email> |
Nguồn: Topcode.vn
