Giới thiệu 🏗️ RealCRM Project

Hệ thống RealCRM để quản lý khách hàng, nhân viên và tổ chức một cách có hệ thống. Được thiết kế dựa trên TypeScript, Next.js 14 (App Router), Prisma, NextAuth và bao gồm RBAC (Kiểm soát truy cập dựa

🚀 Tổng quan dự án

RealCRM là hệ thống quản lý khách hàng chuyên biệt cho ngành môi giới bất động sản, cung cấp các giá trị cốt lõi sau:

• 🔐 Bảo mật: Kiểm soát truy cập dựa trên vai trò (RBAC) và nhật ký kiểm tra

• 📊 Hiệu quả: Phân bổ khách hàng hàng loạt dựa trên Excel, quản lý lịch thăm bằng lịch

• 🎯 Chính xác: Xác thực schema Zod, chuẩn hóa số điện thoại, phát hiện trùng lặp

• 🚀 Khả năng mở rộng: Next.js 14 App Router, triển khai Vercel Edge

• 📱 Facebook Integration: Tích hợp Facebook Messenger Conversions API để tracking và optimization ads

---

🧱 Tính năng chính

UI/UX

• ✅ Màn hình intro thương hiệu → Animation Framer Motion, tối ưu 1.8 giây → Chuỗi logo + typography, bỏ qua session storage → Hỗ trợ khả năng truy cập (prefers-reduced-motion)

• ✅ PWA (Progressive Web App) → Thêm vào màn hình chính, hỗ trợ offline, màn hình splash

Tích hợp Facebook

• ✅ Facebook Messenger Conversions API → Gửi sự kiện chuyển đổi (LeadSubmitted, QualifiedLead) về Meta → Tự động tạo/linking AdCallNumber khi có events từ Facebook Ads → Tracking khách hàng qua PSID (Page-Scoped User ID) từ Messenger → Xem chi tiết: Facebook Messenger Setup Guide

Xác thực & Quản lý quyền

• ✅ Xác thực dựa trên NextAuth v5 → Credentials Provider (ID/mật khẩu)

• ✅ 5 cấp độ vai trò → PENDING → EMPLOYEE → TEAM_LEADER → HEAD → ADMIN

• ✅ Luồng chờ phê duyệt → PENDING khi đăng ký, kích hoạt sau khi ADMIN phê duyệt

• ✅ Kiểm soát quyền chi tiết → Kết hợp resource/action dựa trên mô hình Permission

Quản lý khách hàng

• ✅ Thẻ quản lý khách hàng RealCRM → Giới tính, độ tuổi, khu vực cư trú, xu hướng đầu tư, ngân sách dự kiến và hơn 15 trường

• ✅ Chuẩn hóa số điện thoại → 010-1234-5678 → 01012345678 (chỉ lưu số)

• ✅ Phát hiện khách hàng trùng lặp → Kiểm tra trùng lặp theo số điện thoại, modal xem/ghép

• ✅ Quản lý cấp độ khách hàng → Cấp độ A/B/C, hiển thị thẻ quan tâm

Lịch & Thông báo

• ✅ Tích hợp FullCalendar → Lịch thăm theo tháng, toggle kiểm tra, tính tỷ lệ kiểm tra

• ✅ Hệ thống thông báo → Danh mục, tính năng ghim, hỗ trợ Markdown

Tích hợp Excel

• ✅ Import khách hàng hàng loạt → Tải lên Excel dựa trên SheetJS, kiểm tra trùng lặp rồi phân bổ

• ✅ Tải xuống mẫu template → name, phone, region, team, assigneeEmail, memo

---

🛠 Công nghệ sử dụng

Phân loại	Công nghệ
Framework	Next.js 14 (App Router)
Ngôn ngữ	TypeScript 5.x
Cơ sở dữ liệu	PostgreSQL (Vercel Postgres)
ORM	Prisma 6.x
Xác thực	NextAuth v5
Xác thực dữ liệu	Zod 4.x
UI	TailwindCSS 4.x, Radix UI, ShadCN/UI
Lịch	FullCalendar 6.x
Biểu đồ	Recharts 3.x
Excel	SheetJS (xlsx)
Kiểm thử	Vitest, Playwright
CI/CD	GitHub Actions
Triển khai	Vercel

---

📊 Import/Export Excel

Tải xuống mẫu template

Cách 1: Tải xuống từ UI

1. Dashboard → Quản lý khách hàng → Đăng ký hàng loạt

2. Nhấn nút "Tải xuống mẫu template"

Cách 2: Tạo thủ công Tạo file Excel với các cột sau:

name	phone	email	residenceArea	gender	ageRange	source	assignedUserEmail	memo
Nguyễn Văn A	010-1234-5678	[email protected]	Quận 1, TP.HCM	MALE	THIRTIES	AD	[email protected]	Khách hàng VIP
Trần Thị B	010-9876-5432	[email protected]	Quận 2, TP.HCM	FEMALE	FORTIES	TM	[email protected]	Có ý định tái thăm

Quy trình tải lên Excel

1. Chọn file: Hỗ trợ định dạng .xlsx hoặc .csv

2. Xác thực tự động:

   • Chuẩn hóa số điện thoại (chỉ trích xuất số)

   • Phát hiện số điện thoại trùng lặp

   • Xác thực trường bắt buộc (name, phone)

3. Tùy chọn xử lý trùng lặp:

   • Bỏ qua: Bỏ qua khách hàng trùng lặp

   • Ghép: Cập nhật thông tin khách hàng hiện có

   • Xác nhận từng mục: Chọn cho từng mục trùng lặp

4. Xử lý phân bổ:

   • Phân bổ tự động dựa trên cột assignedUserEmail

   • Nếu không có thì gán cho người tải lên

Quy tắc xử lý khách hàng trùng lặp

Tiêu chí trùng lặp: Số điện thoại (chỉ so sánh số)

Luồng xử lý:

Tải lên Excel
  ↓
Chuẩn hóa số điện thoại [phone] → 01012345678)
  ↓
Kiểm tra trùng lặp (Truy vấn DB)
  ↓
Phát hiện trùng lặp → Hiển thị modal
  ├─ Xem khách hàng hiện có (liên kết)
  ├─ Bỏ qua
  └─ Ghép (Cập nhật dữ liệu hiện có)
  ↓
Xử lý transaction
  ├─ Tạo Customer
  ├─ Ghi CustomerAllocation
  └─ Ghi AuditLog

---

🔌 API Endpoints

Xác thực

Method	Endpoint	Mô tả	Quyền
POST	/api/auth/signup	Đăng ký (trạng thái PENDING)	Public
POST	/api/auth/[...nextauth]	Đăng nhập/Đăng xuất	Public

Quản lý khách hàng

Method	Endpoint	Mô tả	Quyền
GET	/api/customers	Lấy danh sách khách hàng (phân trang)	EMPLOYEE+
POST	/api/customers	Tạo khách hàng	EMPLOYEE+
GET	/api/customers/[id]	Lấy chi tiết khách hàng	EMPLOYEE+
PATCH	/api/customers/[id]	Sửa thông tin khách hàng	EMPLOYEE+
POST	/api/customers/bulk-import	Đăng ký hàng loạt bằng Excel	ADMIN/HEAD
GET	/api/customers/check-duplicate	Kiểm tra trùng lặp	EMPLOYEE+

Quản trị viên

Method	Endpoint	Mô tả	Quyền
GET	/api/admin/users	Danh sách người dùng	ADMIN
POST	/api/admin/users/[id]/approve	Phê duyệt người dùng	ADMIN
POST	/api/admin/users/[id]/reject	Từ chối người dùng	ADMIN
POST	/api/admin/allocation	Phân bổ khách hàng	ADMIN/HEAD

Lịch & Khác

Method	Endpoint	Mô tả	Quyền
GET/POST	/api/visit-schedules	CRUD lịch thăm	EMPLOYEE+
GET/POST	/api/interest-cards	CRUD thẻ quan tâm	EMPLOYEE+
GET/POST	/api/call-logs	CRUD ghi chép cuộc gọi	EMPLOYEE+

---

📞 Liên hệ và hỗ trợ

• TonyX - 0919887799

---

📄 Giấy phép

Copyright (c) 2025 RealCRM Corporation. All Rights Reserved.

Phần mềm này là tài sản độc quyền của RealCRM Corporation, và việc sao chép, phân phối, sửa đổi trái phép bị cấm.

---

Made with ❤️ & 🔒 by RealCRM Team