# Giới thiệu dự án Web Thuê Xe
## 1. Tổng quan
Dự án `Web_Thue_Xe` là một nền tảng cho thuê xe toàn diện, bao gồm cả backend API và frontend quản lý. Ứng dụng hỗ trợ thuê xe tự lái, thuê xe có tài xế, đặt chuyến đi theo tuyến và thanh toán QR nội bộ.
- Backend: Node.js + Express + MongoDB
- Frontend: Vue 3 + Vite + TailwindCSS
- Thanh toán QR: QR code cho chuyển khoản, MOMO, Zalo Pay, VNPay
- Hợp đồng tự động: tạo hợp đồng dạng văn bản cho từng loại booking
## 2. Mục tiêu chính
- Giúp người dùng dễ dàng tìm và đặt xe thuê.
- Quản lý booking, tài xế, hợp đồng và thanh toán.
- Cho phép chủ xe/đại lý theo dõi lịch trình, doanh thu và trạng thái xe.
- Tích hợp phương thức thanh toán QR hiện đại và bảo mật.
## 3. Các chức năng chính
### 3.1 Quản lý người dùng
- Đăng ký/đăng nhập người dùng với xác thực JWT.
- Quản lý hồ sơ người dùng, ảnh đại diện và thông tin liên hệ.
- Đăng ký trở thành chủ xe, cộng tác viên hoặc tài xế.
- Quản lý trạng thái tài khoản và xác minh người dùng.
### 3.2 Quản lý xe
- Thêm, sửa, xóa và duyệt xe cho thuê.
- Quản lý trang thái xe: hoạt động, bảo trì, không khả dụng.
- Kiểm tra lịch trình và tình trạng sẵn có của xe.
- Lưu trữ hình ảnh xe, giấy tờ và thông tin kỹ thuật.
### 3.3 Quản lý booking
- Tạo booking cho thuê xe tự lái và thuê xe có tài xế.
- Kiểm tra tính khả dụng xe và điều kiện ngày/giờ.
- Xem danh sách booking của người thuê và chủ xe.
- Hủy booking, xác nhận booking và theo dõi trạng thái.
- Tính phí giao nhận và các khoản chi phí phát sinh.
### 3.4 Thanh toán và QR Code
- Hỗ trợ các phương thức thanh toán:
- Chuyển khoản ngân hàng
- MOMO
- Zalo Pay
- VNPay
- Tiền mặt
- Tạo QR code thanh toán tự động theo booking.
- Lưu trữ thông tin giao dịch và trạng thái thanh toán.
- Xác nhận thanh toán và cập nhật trạng thái booking.
### 3.5 Hợp đồng và giấy tờ
- Tạo hợp đồng tự động theo từng loại booking:
- Self-drive (tự lái)
- With-driver (có tài xế)
- Trip driver (chuyến đi)
- Lưu hợp đồng dưới dạng file văn bản trong thư mục `uploads/contracts`.
- Quản lý hồ sơ hợp đồng và ký duyệt.
### 3.6 Quản lý tài xế và lịch trình
- Quản lý thông tin tài xế và trạng thái trực tuyến.
- Quản lý lịch trình tài xế: ca làm việc, lịch trình online/offline.
- Theo dõi chuyến đi của tài xế và cập nhật trạng thái hoàn thành.
- Xem thu nhập và báo cáo công việc của tài xế.
### 3.7 Đánh giá và thông báo
- Người dùng có thể đánh giá và bình luận về xe và dịch vụ.
- Quản lý phản hồi, báo cáo đánh giá và trả lời.
- Hệ thống thông báo nội bộ gửi trạng thái booking, thanh toán, duyệt xe.
### 3.8 Bảng điều khiển admin
- Thống kê tổng quan: số người dùng, số booking, doanh thu, xe.
- Quản lý người dùng, xe, booking và hợp tác viên.
- Kiểm duyệt và phê duyệt listing, tài xế, cộng tác viên.
- Xem báo cáo và phân tích hoạt động.
## 4. Dành cho người dùng
- Tìm kiếm và lọc xe theo loại, khu vực, giá, chất lượng, số chỗ.
- Xem chi tiết xe, hình ảnh, giấy tờ, mô tả, review và thông tin chủ xe.
- Đặt xe tự lái, thuê xe có tài xế hoặc đặt chuyến đi theo lịch trình.
- Chọn điểm nhận/tra xe, thời gian thuê, dịch vụ cộng thêm và phí giao nhận.
- Thanh toán linh hoạt bằng QR code, chuyển khoản, MOMO, ZaloPay, VNPay hoặc tiền mặt.
- Nhận mã giao dịch, mã QR và xác nhận thanh toán ngay trong hệ thống.
- Xem lịch sử booking, trạng thái booking, chi tiết hợp đồng và biên lai thanh toán.
- Đánh giá xe, tài xế và trải nghiệm sau mỗi chuyến đi.
- Quản lý hồ sơ, cập nhật thông tin cá nhân và hồ sơ xác minh.
## 5. Dành cho tài xế
- Đăng ký và cập nhật hồ sơ tài xế với thông tin cá nhân, giấy tờ và ảnh thẻ.
- Kích hoạt/ẩn trạng thái online để nhận chuyến và quản lý ca làm việc.
- Xem bảng điều khiển tài xế với các chuyến sắp tới, lịch trình và nhiệm vụ.
- Nhận booking, bắt đầu chuyến đi, hoàn thành chuyến và cập nhật trạng thái trong thời gian thực.
- Xem chi tiết địa điểm đón/trả khách, thời gian, yêu cầu dịch vụ và thông tin liên lạc của khách.
- Theo dõi thu nhập, lịch sử chuyến đi và báo cáo doanh thu cá nhân.
- Nhận thông báo khi có booking mới, khi booking được xác nhận hoặc khi thanh toán hoàn tất.
## 6. Dành cho admin
- Xem dashboard tổng quan với thống kê người dùng, booking, xe, doanh thu và hoạt động hệ thống.
- Quản lý người dùng: xem danh sách, thay đổi trạng thái, xác minh tài khoản, khoá/mở khóa.
- Quản lý xe: duyệt xe mới, phê duyệt hình ảnh/giấy tờ, đổi trạng thái hoạt động/bảo trì.
- Quản lý booking: theo dõi booking, xác nhận hoặc huỷ booking, phân công tài xế và xử lý khiếu nại.
- Quản lý cộng tác viên: duyệt hồ sơ cộng tác viên, theo dõi thu nhập và chiết khấu.
- Quản lý tài xế: duyệt hồ sơ tài xế, kiểm soát tài liệu, theo dõi hoạt động và hiệu suất.
- Kiểm soát thanh toán: xem giao dịch, trạng thái QR, xác nhận thanh toán và xử lý sai sót.
- Thiết lập cài đặt hệ thống, cấu hình trip và quy tắc phê duyệt.
## 7. Kiến trúc kỹ thuật
- `backend/`: server API, routes, models, middleware, helper QR code, hợp đồng.
- `frontend/`: giao diện Vue 3, router, store Pinia, component UI và trang quản lý.
- `uploads/`: lưu contract, file giấy tờ, ảnh người dùng.
- `tmp/`: tập tin hỗ trợ chạy script, migration.
## 5. Các module chính
- `backend/routes/auth.js`: đăng ký, đăng nhập, profile, quản lý tài khoản.
- `backend/routes/cars.js`: quản lý xe, availability, document, operational status.
- `backend/routes/bookings.js`: flow booking, kiểm tra xe, confirm/cancel, tính phí giao nhận.
- `backend/routes/payments.js`: tạo QR code, gửi thông tin thanh toán, confirm, webhook.
- `backend/routes/contracts.js`: tạo, lấy, xoá hợp đồng theo booking.
- `backend/routes/driver.js`: dashboard tài xế, lịch trình, chuyến đi, thu nhập.
- `backend/routes/admin.js`: admin analytics, quản lý users/cars/bookings/drivers/collaborators.
- `backend/routes/reviews.js`: review, rating, báo cáo, phản hồi.
- `backend/routes/addresses.js`: quản lý địa chỉ người dùng.
- `backend/routes/tripSettings.js`: cấu hình trip và cài đặt chung.
## 6. Công nghệ sử dụng
- Node.js + Express
- MongoDB + Mongoose
- Vue 3 + Vite + TailwindCSS
- Pinia
- Axios
- JWT
- Multer, QRCode, Express Validator, Helmet, CORS
## 7. Ưu điểm của dự án
- Hệ thống cho thuê xe tích hợp đầy đủ từ đặt xe đến thanh toán.
- Tự động tạo hợp đồng và quản lý giấy tờ.
- Hỗ trợ đa dạng phương thức thanh toán QR.
- Phân quyền rõ ràng cho user, owner, driver và admin.
- Giao diện responsive, dễ mở rộng.
## 8. Hướng phát triển tiếp theo
- Tích hợp thực tế với MOMO/ZaloPay/VNPay API chính thức.
- Thêm báo cáo KPI và dashboard doanh thu chi tiết.
- Hệ thống chat hoặc tin nhắn giữa khách hàng và chủ xe/tài xế.
- Tự động gửi email/SMS thông báo booking và thanh toán.
- Mobile app hoặc PWA cho trải nghiệm người dùng tốt hơn.
# Hướng dẫn cài đặt và chạy dự án Web Thuê Xe
## 1. Yêu cầu hệ thống
- Node.js 18+ hoặc 20+ (đề xuất dùng Node.js 20)
- npm 10+ hoặc Yarn
- MongoDB đang chạy cục bộ hoặc kết nối tới MongoDB Atlas
- Trình duyệt web hiện đại để truy cập frontend
## 2. Cấu trúc dự án
- `backend/`: backend API Node.js + Express + MongoDB
- `frontend/`: frontend Vue 3 + Vite + TailwindCSS
- `uploads/`: lưu trữ file ảnh, hợp đồng, giấy tờ
- `tmp/`: các script hỗ trợ và migration
## 3. Cài đặt backend
1. Mở terminal vào thư mục `backend`:
```bash
cd backend
```
2. Cài đặt các package:
```bash
npm install
```
3. Tạo file môi trường `.env` trong `backend` và thêm các biến sau:
```env
MONGODB_URI=<ĐƯỜNG DẪN MONGODB CỦA BẠN>
PORT=5000
NODE_ENV=development
BANK_ACCOUNT_NUMBER=1234567890
BANK_ACCOUNT_HOLDER=CAR RENTAL CO., LTD
BANK_BRANCH=Chi nhánh Hà Nội
MOMO_PHONE_NUMBER=0987654321
MOMO_MERCHANT_CODE=MOMOXXXXXX
MOMO_PARTNER_CODE=MOMO
ZALOPAY_APP_ID=ZALOPAY_APP_ID
ZALOPAY_KEY1=ZALOPAY_KEY1
ZALOPAY_KEY2=ZALOPAY_KEY2
VNPAY_TMN_CODE=VNPAY_TMN_CODE
VNPAY_HASH_SECRET=VNPAY_HASH_SECRET
VNPAY_URL=https://sandbox.vnpayment.vn/paygate
```
4. Chạy backend:
```bash
npm run dev
```
Hoặc chạy production:
```bash
npm start
```
5. Kiểm tra backend đã chạy:
Mở `http://localhost:5000/api/health`
Nếu thành công, bạn sẽ nhận được phản hồi dạng JSON:
```json
{ "status": "OK", "timestamp": "..." }
```
## 4. Cài đặt frontend
1. Mở terminal vào thư mục `frontend`:
```bash
cd frontend
```
2. Cài đặt các package:
```bash
npm install
```
3. Chạy frontend trong môi trường phát triển:
```bash
npm run dev
```
4. Truy cập giao diện tại địa chỉ được Vite hiển thị mặc định, thường là:
```text
http://localhost:5173
```
## 5. Cấu hình kết nối frontend và backend
- Frontend gọi API backend tại đường dẫn `/api/...`.
- Backend đang cho phép CORS với các origin sau trong môi trường phát triển:
- `http://localhost:3000`
- `http://localhost:5173`
> Nếu bạn chạy frontend ở port khác, hãy cập nhật cấu hình CORS trong `backend/server.js`.
## 6. Chạy dự án đầy đủ
1. Mở terminal ở thư mục `backend`, chạy `npm run dev`.
2. Mở terminal ở thư mục `frontend`, chạy `npm run dev`.
3. Truy cập frontend bằng trình duyệt.
4. Đăng ký hoặc đăng nhập để bắt đầu sử dụng.
## 7. Các lệnh hữu ích
- Backend:
- `npm install` — cài dependencies
- `npm run dev` — chạy server với nodemon
- `npm start` — chạy server Node bình thường
- Frontend:
- `npm install` — cài dependencies
- `npm run dev` — chạy Vite server
- `npm run build` — build frontend
- `npm run preview` — xem thử build sau khi build xong
## 8. Ghi chú quan trọng
- Thư mục `uploads/` được tạo tự động khi backend khởi động.
- Nếu bạn dùng MongoDB Atlas, thay giá trị `MONGODB_URI` bằng chuỗi kết nối Atlas.
- Để kích hoạt thanh toán MOMO/ZaloPay/VNPay thật, bạn cần điền thông tin API chính xác vào file `.env`.
- Nếu cần thay đổi port backend, cập nhật `PORT` trong file `.env` và đường dẫn API trong frontend.
## 9. Tham khảo thêm
- Mã nguồn backend: `backend/`
- Mã nguồn frontend: `frontend/`
- File cấu hình thanh toán: `backend/config/paymentConfig.js`
- Các route API chính:
- `backend/routes/auth.js`
- `backend/routes/cars.js`
- `backend/routes/bookings.js`
- `backend/routes/payments.js`
- `backend/routes/contracts.js`
- `backend/routes/driver.js`
- `backend/routes/admin.js`
Chúc bạn cài đặt và chạy dự án thành công!
