Hệ thống quản lý phòng trọ

Hệ thống quản lý phòng trọ hiện đại và toàn diện được xây dựng với Next.js 15, TypeScript và MongoDB.

🚀 Tính năng chính

📊 Dashboard

Thống kê tổng quan về phòng, doanh thu, hóa đơn
Biểu đồ doanh thu theo tháng
Danh sách hóa đơn sắp đến hạn
Danh sách sự cố cần xử lý
Hợp đồng sắp hết hạn

🏢 Quản lý tòa nhà

CRUD thông tin tòa nhà
Upload ảnh tòa nhà
Quản lý tiện ích chung
Xem danh sách phòng theo tòa nhà

🏠 Quản lý phòng

CRUD thông tin phòng
Upload ảnh phòng
Lọc phòng theo trạng thái
Xem lịch sử thuê phòng
Quản lý tiện nghi phòng

👥 Quản lý khách thuê

CRUD thông tin khách thuê
Upload ảnh CCCD
Lịch sử thuê phòng
Lịch sử thanh toán

📄 Quản lý hợp đồng

Tạo hợp đồng mới
Upload file hợp đồng PDF
Gia hạn hợp đồng
Chấm dứt hợp đồng
In hợp đồng

⚡ Quản lý chỉ số điện nước

Ghi chỉ số hàng tháng
Upload ảnh chỉ số
Tự động tính tiêu thụ
Lịch sử chỉ số

🧾 Quản lý hóa đơn

Tạo hóa đơn tự động theo chu kỳ
Tính toán tự động: tiền điện, nước, dịch vụ
Gửi thông báo hóa đơn
In hóa đơn
Xuất báo cáo Excel

💰 Quản lý thanh toán

Ghi nhận thanh toán
Upload biên lai
Lịch sử thanh toán
Xuất phiếu thu

🚨 Quản lý sự cố

Khách thuê báo cáo sự cố
Phân loại và ưu tiên sự cố
Theo dõi tiến độ xử lý
Upload ảnh sự cố

🔔 Thông báo

Gửi thông báo đến khách thuê
Thông báo theo phòng/tòa nhà
Lịch sử thông báo

⚙️ Cài đặt hệ thống

Quản lý người dùng
Cấu hình hệ thống
Sao lưu và khôi phục dữ liệu
Cài đặt thông báo

🛠 Tech Stack

Frontend

Framework: Next.js 15 (App Router)
Language: TypeScript
UI Components: shadcn/ui
Styling: Tailwind CSS v4.1
State Management: React Hooks, Context API
Form Handling: React Hook Form + Zod validation
Icons: lucide-react

Backend

API: Next.js API Routes (App Router)
Authentication: NextAuth.js (JWT + Session)
Database: MongoDB với Mongoose ODM

Additional Libraries

Date handling: date-fns
Charts: recharts
Toast notifications: sonner
File upload: uploadthing hoặc cloudinary

📦 Cài đặt

Yêu cầu hệ thống

Node.js: Phiên bản 18 trở lên (Khuyến nghị: Node.js 20+)
npm: Đi kèm với Node.js
MongoDB Atlas: URI connection string (hoặc MongoDB local)
Git: Để clone repository
Code Editor: VS Code (khuyến nghị) hoặc bất kỳ editor nào

🚀 HƯỚNG DẪN SETUP CHO KHÁCH HÀNG MỚI

Bước 1: Chuẩn bị môi trường

1.1. Cài đặt Node.js

Tải và cài đặt Node.js từ: https://nodejs.org/
Kiểm tra cài đặt thành công:

node --version    # Nên >= v18.0.0
npm --version     # Nên >= 9.0.0

1.2. Cài đặt Git (nếu chưa có)

Windows: https://git-scm.com/download/win
Mac: https://git-scm.com/download/mac
Linux: sudo apt-get install git

Bước 2: Clone dự án

# Clone repository (thay <repository-url> bằng link git của bạn)
git clone <repository-url>

# Di chuyển vào thư mục dự án
cd demo-phong-tro

Bước 3: Cài đặt dependencies

# Cài đặt tất cả package cần thiết (có thể mất 2-5 phút)
npm install

# Hoặc nếu gặp lỗi, thử:
npm install --legacy-peer-deps

Bước 4: Cấu hình Environment Variables

4.1. Tạo file .env.local

# Windows (PowerShell)
Copy-Item env.example .env.local

# Mac/Linux
cp env.example .env.local

4.2. Cấu hình MongoDB URI

Mở file .env.local bằng editor và cập nhật các thông tin sau:

# Database - QUAN TRỌNG: Thêm tên database vào URI
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/TENDATABASE?retryWrites=true&w=majority&appName=AppName



# NextAuth - Tạo secret key ngẫu nhiên
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-random-secret-key-here-make-it-long-and-complex

# Cloudinary (upload ảnh) - QUAN TRỌNG
NEXT_PUBLIC_CLOUD_NAME=your-cloudinary-name
NEXT_PUBLIC_UPLOAD_PRESET=your-upload-preset

# Email (tùy chọn - để gửi thông báo)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

4.3. Tạo NEXTAUTH_SECRET

Chạy lệnh sau để tạo secret key ngẫu nhiên:

# Windows PowerShell
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Mac/Linux/Git Bash
openssl rand -base64 32

Copy kết quả vào NEXTAUTH_SECRET trong file .env.local

4.4. Cấu hình Cloudinary (để upload ảnh)

Đăng ký tài khoản miễn phí tại: https://cloudinary.com/
Vào Dashboard, lấy:
- Cloud Name: Điền vào NEXT_PUBLIC_CLOUD_NAME
- Upload Preset:
  - Vào Settings → Upload
  - Tạo Upload Preset mới (unsigned)
  - Copy tên preset vào NEXT_PUBLIC_UPLOAD_PRESET

Bước 5: Chạy ứng dụng

5.1. Khởi động Development Server

npm run dev

Đợi vài giây cho đến khi thấy thông báo:

✓ Ready in 3.2s
○ Local:   http://localhost:3000

5.2. Truy cập ứng dụng

Mở trình duyệt và truy cập: http://localhost:3000

Bước 6: Tạo dữ liệu mẫu (Optional)

Nếu muốn test với dữ liệu mẫu:

6.1. Mở Terminal mới (giữ server đang chạy)

6.2. Gọi API seed data

# Windows PowerShell
Invoke-WebRequest -Uri http://localhost:3000/api/seed -Method POST

# Mac/Linux/Git Bash
curl -X POST http://localhost:3000/api/seed

# Hoặc dùng browser: Truy cập http://localhost:3000/api/seed trong trình duyệt

6.3. Đăng nhập với tài khoản mặc định

Email: admin@example.com
Password: admin123

🔧 Xử lý lỗi thường gặp

Lỗi 1: "Cannot connect to MongoDB"

Nguyên nhân: MongoDB URI không đúng hoặc IP chưa được whitelist

Giải pháp:

Kiểm tra MongoDB URI trong file .env.local
Vào MongoDB Atlas → Network Access → Add IP Address
Chọn "Allow access from anywhere" (0.0.0.0/0) để test

Lỗi 2: "Module not found"

Nguyên nhân: Dependencies chưa được cài đặt đầy đủ

Giải pháp:

# Xóa node_modules và cài lại
rm -rf node_modules package-lock.json
npm install

Lỗi 3: "Port 3000 already in use"

Nguyên nhân: Port 3000 đang được sử dụng

Giải pháp:

# Chạy trên port khác
npm run dev -- -p 3001

Lỗi 4: Upload ảnh không hoạt động

Nguyên nhân: Chưa cấu hình Cloudinary

Giải pháp: Xem lại Bước 4.4

📝 Checklist Setup

🌐 Deploy lên Production

Deploy lên Vercel (Khuyến nghị - Miễn phí)

Push code lên GitHub

git add .
git commit -m "Initial commit"
git push origin main

Deploy với Vercel
- Truy cập: https://vercel.com/
- Đăng nhập bằng GitHub
- Click "New Project"
- Import repository demo-phong-tro
- Cấu hình Environment Variables (copy từ .env.local)
- Click "Deploy"
Cập nhật NEXTAUTH_URL
- Sau khi deploy xong, copy URL Vercel (vd: https://demo-phong-tro.vercel.app)
- Vào Settings → Environment Variables
- Sửa NEXTAUTH_URL thành URL mới
- Redeploy

💡 Tips cho khách hàng mới

Backup MongoDB URI: Lưu lại MongoDB URI ở nơi an toàn
Đổi mật khẩu admin: Đăng nhập và đổi password ngay
Tạo tài khoản riêng: Không dùng chung tài khoản admin
Backup database: Thường xuyên export data từ MongoDB Atlas
Check logs: Nếu có lỗi, xem logs trong terminal
Update thường xuyên: Chạy npm update để update dependencies

📞 Hỗ trợ

Nếu gặp vấn đề trong quá trình setup:

Kiểm tra lại từng bước trong hướng dẫn
Xem phần "Xử lý lỗi thường gặp"
Liên hệ người phát triển

📊 Database Schema

Hệ thống sử dụng MongoDB với các collection chính:

NguoiDung: Quản lý người dùng (admin, chủ nhà, nhân viên)
ToaNha: Thông tin tòa nhà
Phong: Thông tin phòng trọ
KhachThue: Thông tin khách thuê
HopDong: Hợp đồng thuê phòng
ChiSoDienNuoc: Chỉ số điện nước hàng tháng
HoaDon: Hóa đơn thanh toán
ThanhToan: Giao dịch thanh toán
SuCo: Báo cáo sự cố
ThongBao: Thông báo hệ thống

🔐 Authentication

Hệ thống sử dụng NextAuth.js với:

JWT tokens
Session management
Role-based access control (admin, chủ nhà, nhân viên)
Protected routes

📱 Responsive Design

Mobile-first approach
Sidebar collapse trên mobile
Bảng responsive với horizontal scroll
Form stack trên mobile

🚀 Deployment

Vercel (Recommended)

Push code lên GitHub
Connect với Vercel
Cấu hình environment variables
Deploy

Docker

docker build -t motel-management .
docker run -p 3000:3000 motel-management

📝 API Documentation

Authentication

POST /api/auth/register - Đăng ký tài khoản
POST /api/auth/[...nextauth] - Đăng nhập

Tòa nhà

GET /api/toa-nha - Lấy danh sách tòa nhà
POST /api/toa-nha - Tạo tòa nhà mới
GET /api/toa-nha/[id] - Lấy thông tin tòa nhà
PUT /api/toa-nha/[id] - Cập nhật tòa nhà
DELETE /api/toa-nha/[id] - Xóa tòa nhà

Phòng

GET /api/phong - Lấy danh sách phòng
POST /api/phong - Tạo phòng mới
GET /api/phong/[id] - Lấy thông tin phòng
PUT /api/phong/[id] - Cập nhật phòng
DELETE /api/phong/[id] - Xóa phòng

Khách thuê

GET /api/khach-thue - Lấy danh sách khách thuê
POST /api/khach-thue - Tạo khách thuê mới
GET /api/khach-thue/[id] - Lấy thông tin khách thuê
PUT /api/khach-thue/[id] - Cập nhật khách thuê
DELETE /api/khach-thue/[id] - Xóa khách thuê

Hợp đồng

GET /api/hop-dong - Lấy danh sách hợp đồng
POST /api/hop-dong - Tạo hợp đồng mới
GET /api/hop-dong/[id] - Lấy thông tin hợp đồng
PUT /api/hop-dong/[id] - Cập nhật hợp đồng
DELETE /api/hop-dong/[id] - Xóa hợp đồng

Chỉ số điện nước

GET /api/chi-so-dien-nuoc - Lấy danh sách chỉ số
POST /api/chi-so-dien-nuoc - Ghi chỉ số mới

Hóa đơn

GET /api/hoa-don - Lấy danh sách hóa đơn
POST /api/hoa-don - Tạo hóa đơn mới

Thanh toán

GET /api/thanh-toan - Lấy danh sách thanh toán
POST /api/thanh-toan - Ghi nhận thanh toán

Sự cố

GET /api/su-co - Lấy danh sách sự cố
POST /api/su-co - Báo cáo sự cố
GET /api/su-co/[id] - Lấy thông tin sự cố
PUT /api/su-co/[id] - Cập nhật sự cố
DELETE /api/su-co/[id] - Xóa sự cố

Thông báo

GET /api/thong-bao - Lấy danh sách thông báo
POST /api/thong-bao - Gửi thông báo

Dashboard

GET /api/dashboard/stats - Lấy thống kê dashboard

🤝 Contributing

Fork repository
Tạo feature branch (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'Add some AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Tạo Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

📞 Contact

Project Link: https://github.com/yourusername/demo-phong-tro

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
public		public
scripts		scripts
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
components.json		components.json
env.example		env.example
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Hệ thống quản lý phòng trọ

🚀 Tính năng chính

📊 Dashboard

🏢 Quản lý tòa nhà

🏠 Quản lý phòng

👥 Quản lý khách thuê

📄 Quản lý hợp đồng

⚡ Quản lý chỉ số điện nước

🧾 Quản lý hóa đơn

💰 Quản lý thanh toán

🚨 Quản lý sự cố

🔔 Thông báo

⚙️ Cài đặt hệ thống

🛠 Tech Stack

Frontend

Backend

Additional Libraries

📦 Cài đặt

Yêu cầu hệ thống

🚀 HƯỚNG DẪN SETUP CHO KHÁCH HÀNG MỚI

Bước 1: Chuẩn bị môi trường

1.1. Cài đặt Node.js

1.2. Cài đặt Git (nếu chưa có)

Bước 2: Clone dự án

Bước 3: Cài đặt dependencies

Bước 4: Cấu hình Environment Variables

4.1. Tạo file .env.local

4.2. Cấu hình MongoDB URI

4.3. Tạo NEXTAUTH_SECRET

4.4. Cấu hình Cloudinary (để upload ảnh)

Bước 5: Chạy ứng dụng

5.1. Khởi động Development Server

5.2. Truy cập ứng dụng

Bước 6: Tạo dữ liệu mẫu (Optional)

6.1. Mở Terminal mới (giữ server đang chạy)

6.2. Gọi API seed data

6.3. Đăng nhập với tài khoản mặc định

🔧 Xử lý lỗi thường gặp

Lỗi 1: "Cannot connect to MongoDB"

Lỗi 2: "Module not found"

Lỗi 3: "Port 3000 already in use"

Lỗi 4: Upload ảnh không hoạt động

📝 Checklist Setup

🌐 Deploy lên Production

Deploy lên Vercel (Khuyến nghị - Miễn phí)

💡 Tips cho khách hàng mới

📞 Hỗ trợ

📊 Database Schema

🔐 Authentication

📱 Responsive Design

🚀 Deployment

Vercel (Recommended)

Docker

📝 API Documentation

Authentication

Tòa nhà

Phòng

Khách thuê

Hợp đồng

Chỉ số điện nước

Hóa đơn

Thanh toán

Sự cố

Thông báo

Dashboard

🤝 Contributing

📄 License

📞 Contact

🙏 Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages