🧭 VTripPlanner - Hệ Thống Lập Kế Hoạch Du Lịch Thông Minh & Mạng Xã Hội Du Lịch
Đồ án / Dự án: Nền tảng Web lập lịch trình du lịch thông minh (Smart Trip Planner), gợi ý địa điểm cá nhân hóa theo thời gian thực (ETA), ngân sách, mùa du lịch và mạng xã hội chia sẻ trải nghiệm du lịch tại Việt Nam.
📌 1. Yêu cầu môi trường (Prerequisites)
Trước khi chạy dự án, máy tính cần được cài đặt sẵn:
- Node.js: Phiên bản
>= 18.18.0 hoặc >= 20.x (Khuyến nghị Node.js 20 LTS).
- Trình quản lý gói:
npm (đi kèm Node.js) hoặc pnpm / yarn.
- Cơ sở dữ liệu: PostgreSQL (hỗ trợ phiên bản 14+ hoặc Supabase PostgreSQL).
🚀 2. Hướng dẫn cài đặt & Khởi chạy (Quick Start)
Bước 1: Cài đặt các gói phụ thuộc (Dependencies)
Mở terminal tại thư mục gốc của dự án và chạy:
npm install
Bước 2: Cấu hình biến môi trường
Tạo tệp .env.local ở thư mục gốc (dựa trên tệp mẫu .env.example):
cp .env.example .env.local
Điền các thông tin kết nối Supabase và PostgreSQL của bạn vào .env.local:
# Cấu hình Supabase (Auth & Storage)
NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY="your-supabase-anon-key"
SUPABASE_SECRET_KEY="your-supabase-service-role-secret-key"
# Cấu hình Database (PostgreSQL / Supabase Transaction & Session Pooler)
DATABASE_URL="postgresql://postgres:password@host:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres:password@host:5432/postgres"
# (Tùy chọn) Google Routes API Key để đo khoảng cách và ETA thời gian thực
# Nếu không cấu hình, hệ thống sẽ tự động dùng thuật toán nội bộ Haversine Fallback
# GOOGLE_MAPS_API_KEY=""
Bước 3: Khởi tạo Cơ sở dữ liệu & Sinh Prisma Client
Sinh client tương thích cho Prisma:
npm run prisma:generate
(Tùy chọn nếu khởi tạo DB mới) Áp dụng migration và nạp dữ liệu mẫu:
# Đẩy migration vào database:
npx prisma migrate deploy
# Nạp dữ liệu mẫu các địa điểm du lịch tại Việt Nam:
npm run seed:places
Bước 4: Chạy ứng dụng ở môi trường phát triển (Dev)
npm run dev
Bước 5: Mở ứng dụng
Truy cập trình duyệt tại địa chỉ: http://localhost:3000
🗺️ 3. Sơ đồ các Phân hệ & Đường dẫn chính (Routes Map)
| Đường dẫn | Tên phân hệ / Chức năng | Mô tả |
|---|
/ | Trang chủ & Bảng tin | Giới thiệu hệ thống, bảng tin cộng đồng (Infinite Feed), tương tác bài viết. |
/lap-lich-trinh | Lập lịch trình thông minh | Nhập điểm đi/đến, ngày giờ, số người, ngân sách; tính ETA và gợi ý lịch trình. |
/lap-lich-trinh/tuy-chinh | Biên tập Draft Lịch trình | Thay đổi giờ, hoán đổi thứ tự (↑/↓), thêm/xóa địa điểm trước khi lưu. |
/chuyen-di-cua-toi | Chuyến đi của tôi | Quản lý danh sách chuyến đi đã lưu, checklist hành trang và theo dõi chi tiêu. |
/uu-dai | Săn ưu đãi du lịch | Danh sách voucher/khuyến mãi từ đối tác đã được kiểm duyệt. |
/voucher-cua-toi | Kho voucher của tôi | Xem danh sách voucher đã nhận kèm mã QR sử dụng tại điểm dịch vụ. |
/bai-viet-cua-toi | Bài viết của tôi | Quản lý các bài viết chia sẻ kinh nghiệm du lịch của người dùng. |
/bai-viet-da-luu | Bài viết đã lưu | Bộ sưu tập bài viết đã bookmark. |
/dang-ky-doi-tac | Đăng ký Đối tác | Form nộp hồ sơ doanh nghiệp (khách sạn, nhà hàng, điểm tham quan,...). |
/doi-tac | Trung tâm Đối tác (Partner) | Quản lý chi nhánh, địa điểm và các chương trình ưu đãi giảm giá. |
/quan-tri | Trung tâm Quản trị (Admin) |
👥 4. Phân quyền Người dùng (Role-Based Access Control)
Hệ thống hỗ trợ 3 nhóm vai trò:
- Khách du lịch (
USER):
- Sử dụng đầy đủ tính năng cá nhân: lập lịch trình, lưu chuyến đi, đăng bài viết, tương tác (Like/Love/Wow, bình luận), nhận voucher.
- Doanh nghiệp Đối tác (
PARTNER):
- Truy cập khu vực
/doi-tac sau khi hồ sơ đăng ký được Admin phê duyệt.
- Thêm địa điểm, chi nhánh và phát hành voucher khuyến mãi.
- Quản trị viên (
ADMIN):
- Truy cập khu vực
/quan-tri.
- Kiểm duyệt đơn đăng ký đối tác, địa điểm, khuyến mãi, bài viết vi phạm, quản lý danh mục địa phương và tài khoản người dùng.
📂 5. Cấu trúc Thư mục Dự án
vtripplanner/
├── prisma/ # Định nghĩa Database Schema & Script Seeds
│ ├── schema.prisma # Prisma Schema 20+ bảng dữ liệu
│ ├── migrations/ # Lịch sử các bản migration SQL
│ └── seed/ # Script seed địa điểm mẫu & hình ảnh
├── public/ # Static Assets (Hình ảnh, logo thương hiệu, icons)
├── src/
│ ├── app/ # Next.js App Router (Giao diện & API Endpoints)
│ ├── components/ # React Components theo từng phân hệ
│ ├── generated/prisma/ # Prisma Generated Client
│ ├── lib/ # Logic thuật toán & Thư viện dùng chung
│ │ ├── auth/ # RBAC, phân quyền và xác thực
│ │ ├── prisma.ts # Kết nối Database qua Postgres Adapter
│ │ ├── social-feed/ # Logic truy vấn và tương tác bài viết
│ │ ├── supabase/ # Supabase Auth & Storage Clients
│ │ └── trip-planner/ # Thuật toán cốt lõi: ETA, Budget, Slot Scoring
│ └── proxy.ts # Middleware proxy xử lý session Supabase SSR
├── PROJECT_SPEC_FOR_REPORT.md # Tài liệu đặc tả kiến trúc & giải thuật phục vụ viết báo cáo
├── .env.example # Tệp mẫu hướng dẫn cấu hình biến môi trường
├── package.json # Khai báo các gói thư viện
└── tsconfig.json # Cấu hình TypeScript
🛠️ 6. Các lệnh Script hữu ích trong dự án
npm run dev: Chạy server phát triển (Development mode).npm run build: Build dự án thành bản sản phẩm (Production build).npm run start: Chạy bản build sản phẩm.npm run lint: Kiểm tra chất lượng mã nguồn bằng ESLint.npm run prisma:generate: Tạo mã Prisma Client tương thích.npm run seed:places: Chạy script nạp dữ liệu địa điểm du lịch mẫu.
