Phần mềm quản lý chung cư dành cho Ban Quản Trị và Cư Dân
Tác giả: FIRaci
- Tổng quan
- Tính năng
- Công nghệ sử dụng
- Cấu trúc dự án
- Cài đặt & Chạy
- Biến môi trường
- API Endpoints
- Tài khoản mặc định
BlueMoon là ứng dụng desktop quản lý chung cư gồm 2 phần:
| Phần | Mô tả |
|---|---|
| Backend | REST API chạy trên Bun + Elysia + PostgreSQL |
| Frontend | Ứng dụng desktop Electron |
2 vai trò người dùng:
- 👮 Admin (BQT) — Quản lý toàn bộ hệ thống
- 🏠 Cư Dân — Xem thông tin hộ, đóng tiền online
- ✅ Quản lý Hộ Khẩu (thêm/sửa/xóa, tìm kiếm)
- ✅ Quản lý Nhân Khẩu trong từng hộ
- ✅ Quản lý Khoản Thu (phí cố định, phí điện/nước)
- ✅ Ghi nhận Nộp Tiền, xem lịch sử thanh toán
- ✅ Nhập chỉ số điện/nước hàng loạt (import Excel)
- ✅ Dashboard thống kê — biểu đồ thu phí theo tháng/năm
- ✅ Xuất báo cáo Excel
- ✅ Reset mật khẩu cư dân qua CCCD
- ✅ Xem thông tin hộ khẩu, danh sách nhân khẩu
- ✅ Xem các khoản phí cần đóng + số tiền thực tế
- ✅ Tạo QR Code VietQR để thanh toán
- ✅ Xem lịch sử đã đóng tiền
- ✅ Đổi mật khẩu
| Công nghệ | Mục đích |
|---|---|
| Bun | Runtime + package manager |
| Elysia | Web framework |
| Prisma | ORM |
| PostgreSQL | Database |
| JWT | Xác thực |
| bcrypt/argon2 | Hash mật khẩu |
| ExcelJS | Xuất file Excel |
| Công nghệ | Mục đích |
|---|---|
| Electron | Desktop app framework |
| Tailwind CSS | Styling |
| Vanilla JS | Logic UI |
| Công nghệ | Mục đích |
|---|---|
| Docker + Docker Compose | Container hóa |
| GitHub Actions | CI/CD |
ktpm/
├── backend/ # API server
│ ├── src/
│ │ ├── index.ts # Entry point
│ │ ├── routes/ # Định nghĩa API routes
│ │ │ ├── auth.route.ts
│ │ │ ├── hokhau.route.ts
│ │ │ ├── nhankhau.route.ts
│ │ │ ├── khoanthu.route.ts
│ │ │ ├── thongke.route.ts
│ │ │ ├── resident.route.ts
│ │ │ └── export.route.ts
│ │ ├── services/ # Business logic
│ │ │ ├── auth.service.ts
│ │ │ ├── hokhau.service.ts
│ │ │ ├── nhankhau.service.ts
│ │ │ ├── khoanthu.service.ts
│ │ │ └── thongke.service.ts
│ │ ├── middleware/
│ │ │ └── auth.middleware.ts # JWT auth + phân quyền
│ │ └── utils/
│ │ └── db.ts # Prisma client
│ ├── prisma/
│ │ └── schema.prisma # Database schema
│ ├── Dockerfile
│ └── package.json
│
├── frontend/ # Electron app
│ ├── main.js # Electron main process
│ ├── dashboard.html/js # Trang tổng quan Admin
│ ├── hokhau.html/js # Quản lý hộ khẩu
│ ├── nhankhau.html/js # Quản lý nhân khẩu
│ ├── khoanthu.html/js # Quản lý khoản thu
│ ├── thongke.html/js # Thống kê báo cáo
│ ├── resident.html/js # Portal cư dân
│ └── package.json
│
├── docker-compose.yml # Chạy toàn bộ hệ thống
├── RUN.bat # Script chạy nhanh (Windows)
└── run.ps1 # Script chạy PowerShell
Yêu cầu: Docker Desktop
# Clone repo
git clone https://github.com/FIRaci/Bluemoonproject.git
cd Bluemoonproject/ktpm
# Tạo file .env cho backend
cp backend/.env.example backend/.env
# Chỉnh sửa JWT_SECRET và các biến môi trường trong .env
# Khởi chạy Database + Backend
docker-compose up -d
# Backend sẽ chạy tại: http://localhost:3000
# Swagger docs tại: http://localhost:3000/swaggerYêu cầu:
- Bun >= 1.0
- PostgreSQL >= 14
- Node.js >= 18
Bước 1 — Backend:
cd backend
# Cài dependencies
bun install
# Tạo file .env
# DATABASE_URL="postgresql://user:password@localhost:5432/bluemoon_db"
# JWT_SECRET="your-secret-key-here"
# Chạy migration database
bun run db:migrate
# Seed dữ liệu mẫu (tuỳ chọn)
bun run db:seed
# Khởi động server
bun run dev
# → http://localhost:3000Bước 2 — Frontend:
cd frontend
# Cài dependencies
npm install
# Chạy ứng dụng Electron
npm start# Chạy file RUN.bat hoặc
.\run.ps1Tạo file backend/.env:
# Database
DATABASE_URL="postgresql://bluemoon:bluemoon2025@localhost:5433/bluemoon_db?schema=public"
# JWT - BẮT BUỘC phải đặt, không để trống
JWT_SECRET="your-very-secure-secret-key-minimum-32-chars"
# QR thanh toán VietQR (tuỳ chọn)
BANK_ACCOUNT="so-tai-khoan-bql"
BANK_CODE="MB"
⚠️ Lưu ý:JWT_SECRETlà bắt buộc. Server sẽ không khởi động nếu thiếu biến này.
Truy cập Swagger UI tại: http://localhost:3000/swagger
| Module | Prefix | Mô tả |
|---|---|---|
| Auth | /auth |
Đăng nhập, đăng ký, đổi mật khẩu |
| Hộ Khẩu | /hokhau |
CRUD hộ khẩu |
| Nhân Khẩu | /nhankhau |
CRUD nhân khẩu |
| Khoản Thu | /khoanthu |
CRUD khoản thu, ghi nhận nộp tiền |
| Thống Kê | /thongke |
Dashboard, báo cáo |
| Cư Dân | /resident |
API cho cư dân |
| Xuất file | /export |
Xuất Excel |
Xác thực: Tất cả API (trừ /auth/login, /auth/register) yêu cầu header:
Authorization: Bearer <jwt_token>
Sau khi chạy bun run db:seed:
| Vai trò | Username | Password |
|---|---|---|
| Admin | admin |
admin123 |
| Cư dân mẫu | BM-A1201 |
resident123 |
⚠️ Đổi mật khẩu ngay sau khi đăng nhập lần đầu!
User ──────── HoKhau ──── NhanKhau
│
├── LichSuNopTien ── KhoanThu
└── ChiTietSuDung ── KhoanThu
Các enum quan trọng:
Role:ADMIN|RESIDENTLoaiPhi:BAT_BUOC|TU_NGUYENPhanLoaiPhi:CO_DINH|THEO_MUC_SU_DUNGHangCanHo:BINH_THUONG|TRUNG_CAP|CAO_CAP|PENTHOUSE
Lỗi "JWT_SECRET not set"
→ Kiểm tra file .env đã có JWT_SECRET chưa
Lỗi kết nối database
→ Kiểm tra PostgreSQL đang chạy và DATABASE_URL đúng
Frontend không kết nối được backend
→ Đảm bảo backend đang chạy tại http://localhost:3000
→ Kiểm tra file frontend/config.js có đúng API URL không
Electron không mở được
→ Chạy npm install lại trong thư mục frontend/
MIT © 2025 FIRaci