📋 Giới thiệu
E-Invoice là hệ thống POS (Point of Sale) và quản lý hóa đơn điện tử
dành cho cửa hàng bán lẻ, quán cà phê, nhà hàng nhỏ.
Được xây dựng với Next.js 16, React 19, Shadcn UI
và Firebase — triển khai nhanh, hoạt động trên mọi thiết bị.
✨ Tính năng
|
Module |
Mô tả |
|
🛒 POS |
Giao diện bán hàng trực quan, giỏ hàng, thanh toán nhanh |
|
📦 Sản phẩm |
CRUD sản phẩm & danh mục, bảng hiển thị search + pagination |
|
👥 Khách hàng |
Quản lý thông tin KH, lịch sử mua hàng, ghi nhận công nợ |
|
🧾 Hóa đơn |
Tạo hóa đơn điện tử, in thermal K80 & A4, xuất PDF |
|
📊 Báo cáo |
6 loại biểu đồ: Column, Bar, Line, Combo, Treemap, Waterfall |
|
💾 Sao lưu |
Xuất/nhập JSON, backup toàn bộ hệ thống |
|
🌱 Seed Data |
Tạo dữ liệu mẫu (danh mục, SP, KH, hóa đơn) để demo |
|
🔐 Auth |
Đăng nhập/đăng ký Firebase Authentication |
|
🌙 Theme |
Chuyển đổi giao diện sáng/tối |
🛠️ Tech Stack
|
Layer |
Công nghệ |
|
Framework |
Next.js 16 (Turbopack), React 19 |
|
Language |
TypeScript 5.9 |
|
UI |
Shadcn UI, Radix Primitives, Tailwind CSS 4 |
|
Icons |
Lucide React |
|
Charts |
Recharts 3 |
|
Backend |
Firebase (Firestore, Authentication) |
|
PDF |
jsPDF, html2canvas |
|
QR Code |
qrcode.react |
|
Excel |
SheetJS (xlsx) |
|
Testing |
Vitest |
|
Linting |
ESLint 9 |
📁 Cấu trúc dự án
E-Invoice/
├── public/ # Static assets (logo, icons)
├── src/
│ ├── actions/ # Server actions
│ ├── app/ # Next.js App Router (page, layout)
│ ├── components/ # React components
│ │ ├── Auth/ # └─ Authentication forms
│ │ └── ui/ # └─ Shadcn UI primitives
│ ├── context/ # React Context providers
│ │ ├── AuthContext # └─ Firebase Auth state
│ │ ├── InvoiceContext # └─ Invoice CRUD + Firebase
│ │ ├── ProductContext # └─ Product & Category CRUD
│ │ ├── CustomerContext # └─ Customer management
│ │ ├── StoreContext # └─ Store settings
│ │ ├── ThemeContext # └─ Light/Dark mode
│ │ └── ToastContext # └─ Notifications
│ ├── docs/ # In-app user guides (markdown)
│ ├── lib/ # Firebase config, utilities
│ ├── types/ # TypeScript interfaces
│ └── utils/ # Report calculations, helpers
├── .env.local # Firebase credentials (not committed)
├── firebase_rule.md # Firestore security rules
├── CHANGELOG.md # Version history
├── INSTALLATION.md # Detailed setup guide
└── USERGUIDE.md # User manual
🚀 Cài đặt
Yêu cầu
1. Clone repository
git clone https://github.com/nhatdev99/E-Invoice.git
cd E-Invoice
2. Cài đặt dependencies
npm install
3. Cấu hình Firebase
Tạo project trên Firebase Console,
kích hoạt Firestore Database và Authentication (Email/Password).
Tạo file .env.local ở thư mục gốc:
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
📌 Copy nội dung firebase_rule.md
vào Firestore → Rules để thiết lập quyền truy cập.
4. Chạy ứng dụng
# Development (Turbopack)
npm run dev
# Production build
npm run build
npm start
Mở http://localhost:3000 trong trình duyệt.
🧪 Testing
# Chạy toàn bộ test
npx vitest run
# Chạy test cụ thể
npx vitest run src/utils/reportUtils.test.ts
# Watch mode
npx vitest
📖 Hướng dẫn sử dụng
Xem hướng dẫn chi tiết từng tính năng:
Hoặc truy cập Trợ giúp trong ứng dụng (tab Trợ giúp ở sidebar).
📊 Hệ thống báo cáo
Hệ thống cung cấp 6 loại biểu đồ phân tích kinh doanh:
|
Biểu đồ |
Công dụng |
|
📊 Column Chart |
So sánh doanh thu theo tháng |
|
📊 Bar Chart |
So sánh doanh thu các sản phẩm |
|
📈 Line Chart |
Xu hướng doanh thu theo ngày (30 ngày gần nhất) |
|
📊 Combo Chart |
Kết hợp doanh thu + số đơn hàng |
|
🌳 Treemap |
Tỷ trọng doanh thu từng sản phẩm |
|
📉 Waterfall Chart |
Phân tích tăng/giảm doanh thu theo sản phẩm |
🌱 Seed Data (Dữ liệu mẫu)
Để trải nghiệm nhanh, vào Cài đặt → Dữ liệu mẫu:
-
8 danh mục (Cà phê, Trà, Nước ép, Sinh tố, ...)
-
35 sản phẩm với giá cả thực tế
-
20 khách hàng mẫu
-
50 hóa đơn trải đều 8 tháng
🤝 Đóng góp
-
Fork repository
-
Tạo branch mới:
git checkout -b feature/ten-tinh-nang
-
Commit:
git commit -m "feat: mo ta thay doi"
-
Push:
git push origin feature/ten-tinh-nang
-
Tạo Pull Request
👤 Tác giả
RONCODES
📄 Giấy phép
Dự án này là phần mềm proprietary.
Liên hệ tác giả để biết chi tiết về giấy phép sử dụng.
© 2026 E-Invoice. All rights reserved.
XEM THÊM ==> Hướng dẫn cài đặt chi tiết
HƯỚNG DẪN CÀI ĐẶT
Hướng dẫn Cài đặt E-Invoice
Yêu cầu hệ thống
-
Node.js phiên bản 20.x trở lên
-
npm hoặc yarn hoặc pnpm hoặc bun
-
Tài khoản Firebase
-
Trình duyệt hiện đại (Chrome, Firefox, Safari, Edge)
Bước 1: Giải nén mã nguồn
# Tải về và giải nén
cd E-Invoice
Bước 2: Cài đặt dependencies
# Sử dụng npm
npm install
# Hoặc sử dụng yarn
yarn install
# Hoặc sử dụng pnpm
pnpm install
# Hoặc sử dụng bun
bun install
Bước 3: Cấu hình Firebase
-
Tạo project mới trên Firebase Console
-
Kích hoạt Firestore Database trong chế độ test mode (để phát triển)
-
Sao chép file
.env.example thành .env.local và điền thông tin Firebase:
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key_here
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain_here
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id_here
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket_here
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id_here
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id_here
-
Sao chép nội dung từ file
firebase_rule.md vào tab Rules của Firestore Database và nhấn Publish
Bước 4: Chạy ứng dụng
# Chạy môi trường phát triển
npm run dev
# Ứng dụng sẽ chạy tại http://localhost:3000
Bước 5: Xây dựng để sản xuất
# Xây dựng ứng dụng
npm run build
# Chạy ứng dụng sản xuất
npm start
Ghi chú quan trọng
-
Đối với môi trường production, hãy chắc chắn rằng Firestore Rules được cấu hình đúng để bảo mật
-
Khi triển khai lên Vercel, các biến môi trường cần được thiết lập trong phần Settings của project
-
Đảm bảo rằng phiên bản Node.js tương thích với các dependencies trong package.json
Khắc phục sự cố
Lỗi "Module not found: Can't resolve 'firebase'"
-
Đảm bảo rằng bạn đã chạy
npm install để cài đặt dependencies
-
Kiểm tra xem firebase có nằm trong danh sách dependencies trong package.json không
Lỗi liên quan đến environment variables
-
Đảm bảo file
.env.local tồn tại ở thư mục gốc project
-
Kiểm tra xem tên biến môi trường có khớp với những gì được sử dụng trong code không
-
Khởi động lại máy chủ phát triển sau khi thay đổi file
.env.local
Lỗi Firestore Permission Denied
-
Kiểm tra lại Firestore Rules trong Firebase Console
-
Đảm bảo rằng bạn đã đăng nhập và UID của bạn khớp với đường dẫn documento được truy cập
Nguồn: Topcode.vn