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 (010-1234-5678 → 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

Last updated