FleetHub Tài liệu

Tổng quan

FleetHub là hệ thống quản lý tài sản đội xe doanh nghiệp cho xe công ty nội bộ (50–200 xe). Xây dựng bằng Laravel 11, Vue 3 và Tailwind CSS — bao gồm xe, tài xế, yêu cầu xe, bàn giao có sơ đồ hư hỏng, nhật ký nhiên liệu, chi phí, phân tích TCO, theo dõi tuân thủ và điểm sức khỏe đội xe. Không dành cho taxi hay cho thuê xe.

Yêu cầu máy chủ

• PHP 8.2 trở lên (khuyến nghị 8.3)
• MySQL 5.7+ hoặc MariaDB 10.3+
• Composer 2.x (chỉ cho phát triển local — không bắt buộc trên shared hosting)
• Node.js 18+ và npm 9+ (chỉ để build frontend local)
• Web server: Apache hoặc Nginx

Extension PHP bắt buộc

• OpenSSL, PDO, PDO_MySQL, Mbstring, Tokenizer, XML, Ctype, JSON, GD, Fileinfo

Dung lượng ổ đĩa

Tối thiểu ~200 MB. Dự phòng thêm cho ảnh xe, biên lai nhiên liệu, ảnh bàn giao và tài liệu tuân thủ.

Cài đặt

Tùy chọn A — Trình cài đặt web (Khuyến nghị)

1. Upload file dự án lên web server.
2. Trỏ document root tới thư mục public/.
3. Phân quyền: storage/ và bootstrap/cache/ phải ghi được (chmod 775).
4. Sao chép .env.example thành .env và đặt APP_KEY (chạy php artisan key:generate nếu có SSH, hoặc xem Cài đặt cPanel → Bước 5).
5. Truy cập https://yourdomain.com/install trên trình duyệt.
6. Làm theo wizard — Yêu cầu → Cơ sở dữ liệu → Migrate → Tài khoản Admin → Hoàn tất. Chọn Include demo data để nạp dữ liệu mẫu (xem Người dùng & Vai trò).

Tùy chọn B — Cài đặt CLI

# 1. Cài dependency
composer install --no-dev --optimize-autoloader
npm install
npm run build

# 2. Cấu hình môi trường
cp .env.example .env
php artisan key:generate

# 3. Sửa .env để đặt thông tin DB
# DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 4. Tạo bảng và seed dữ liệu ban đầu
php artisan migrate --seed

# 5. Tạo symlink storage cho upload
php artisan storage:link

# 6. Cache cấu hình cho production
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 7. Đánh dấu đã cài đặt
echo "Installed" > storage/installed.lock

Wizard Bước 2 — Cấu hình cơ sở dữ liệu

Khi wizard chạy đến Bước 2, bạn cần nhập thông tin kết nối MySQL của cơ sở dữ liệu đã tạo trong bảng điều khiển hosting. Database phải tồn tại sẵn (có thể trống — bước tiếp theo sẽ tạo các bảng).

Tìm thông tin DB ở đâu theo từng loại hosting

• Hostinger: hPanel → Databases → Management → click vào database. Trang chi tiết hiện tên, username và nút "Show password".
• cPanel: cPanel → MySQL Databases. Danh sách database ở trên, danh sách user ở dưới. Dùng "Change Password" nếu cần.
• Plesk: Plesk → Databases → click tên database. Trang chi tiết hiện credentials và có nút reset password.
• DirectAdmin: DirectAdmin → MySQL Management → click vào database. Credentials và reset password nằm ở trang chi tiết.
• DB ngoài / managed: AWS RDS, DigitalOcean Managed Database, v.v. Dùng hostname tùy chỉnh, port (thường là 3306 nhưng nên kiểm tra), tên DB, user và password từ cloud console. Đảm bảo IP của server được whitelist trong firewall DB.

Lỗi thường gặp và cách sửa

Localhost (Phát triển cục bộ)

Hướng dẫn nhanh để chạy FleetHub trên máy tính của bạn cho mục đích kiểm thử hoặc phát triển trước khi triển khai production. Chọn môi trường phù hợp với hệ điều hành của bạn.

Lựa chọn 1 — Laravel Herd (Khuyến nghị, macOS & Windows)

Laravel Herd là môi trường local chính thức từ đội Laravel — miễn phí, native, không Docker. Đi kèm PHP 8.2/8.3/8.4, Nginx, và (trong Herd Pro) MySQL/Redis.

1. Tải và cài Laravel Herd từ herd.laravel.com.
2. Đặt thư mục dự án FleetHub vào ~/Herd/ (macOS) hoặc %USERPROFILE%\Herd\ (Windows). Herd tự tạo domain .test — ví dụ http://fleethub.test.
3. Mở Herd → Sites và xác nhận phiên bản PHP là 8.2 hoặc 8.3. Chuột phải site → Secure để bật HTTPS (cần cho QR scanner).
4. Tạo cơ sở dữ liệu MySQL. Với Herd Pro, vào Services → MySQL → Open in TablePlus. Không có Pro thì cài MySQL Community hoặc dùng SQLite (DB_CONNECTION=sqlite, touch database/database.sqlite).
5. Sao chép .env.example thành .env, điền thông tin DB, rồi chạy php artisan key:generate ở gốc dự án.
6. Mở http://fleethub.test/install trong trình duyệt và làm theo wizard.

Lựa chọn 2 — XAMPP (Windows, macOS, Linux)

XAMPP gói sẵn Apache, MySQL/MariaDB và PHP. Miễn phí, đa nền tảng. Chú ý chọn phiên bản PHP 8.2 trở lên.

1. Tải XAMPP 8.2+ từ apachefriends.org và cài đặt.
2. Sao chép dự án FleetHub vào C:\xampp\htdocs\FleetHub\ (Windows) hoặc /Applications/XAMPP/htdocs/FleetHub/ (macOS).
3. Mở XAMPP Control Panel và khởi động Apache và MySQL. Nếu port bị chiếm, vào Config → service.conf để chuyển Apache sang 8080.
4. Vào http://localhost/phpmyadmin → New → tạo database tên fleethub với collation utf8mb4.
5. Trong thư mục dự án: sao chép .env.example thành .env, đặt DB_DATABASE=fleethub, DB_USERNAME=root, để trống DB_PASSWORD (mặc định XAMPP). Chạy php artisan key:generate.
6. Truy cập http://localhost/FleetHub/public/install để chạy wizard cài đặt.

Lựa chọn 3 — Laragon (Windows)

Laragon là stack Windows portable thiết kế cho Laravel — tự sinh vhost, URL gọn, MySQL/MariaDB và HeidiSQL đi kèm.

1. Tải Laragon Full từ laragon.org và cài đặt.
2. Trong Laragon: Menu → PHP → Version — chuyển sang PHP 8.2 hoặc 8.3.
3. Sao chép dự án FleetHub vào C:\laragon\www\FleetHub\.
4. Bấm Start All. Laragon tự tạo vhost: http://fleethub.test (trỏ đến thư mục public/).
5. Mở HeidiSQL (đi kèm) → tạo database fleethub. Thông tin mặc định: user root, password để trống.
6. Sửa .env với thông tin DB, chạy php artisan key:generate, rồi truy cập http://fleethub.test/install.

Lựa chọn 4 — Máy chủ PHP có sẵn (không cần web server)

Lựa chọn đơn giản nhất: Laravel đi kèm artisan serve, khởi động một development PHP server. Không cần Apache hay Nginx. Tốt nhất cho test nhanh.

# Cài dependency và cấu hình
cd /path/to/FleetHub
composer install
cp .env.example .env
php artisan key:generate

# Chạy migration và seed dữ liệu ban đầu
php artisan migrate --seed

# Khởi động dev server
php artisan serve
# Rồi truy cập: http://127.0.0.1:8000/install

Các vấn đề thường gặp khi chạy localhost

QR scanner không mở camera trên http://

API camera trình duyệt yêu cầu HTTPS, có một ngoại lệ: http://localhost và http://127.0.0.1 được xem là secure context. Nếu bạn truy cập FleetHub qua IP LAN (ví dụ http://192.168.1.10), camera sẽ bị từ chối. Dùng localhost cho dev, hoặc bật HTTPS qua Herd / mkcert.

Permission denied trên storage (macOS / Linux)

Nếu gặp lỗi khi app ghi log hoặc cache, sửa quyền: chmod -R 775 storage bootstrap/cache. Trên Windows thường không cần.

Port đang được dùng

Nếu port 8000 đã bị app khác chiếm, dùng port khác:

php artisan serve --port=8001

Test email cục bộ

SMTP thật thường không có trên localhost. Hai lựa chọn an toàn: (1) đặt MAIL_MAILER=log trong .env — email được ghi vào storage/logs/laravel.log thay vì gửi; hoặc (2) dùng Mailtrap / MailHog để bắt email gửi đi vào hộp inbox giả.

MAIL_MAILER=log
# Mọi email được ghi vào storage/logs/laravel.log

Frontend assets (Vite / Tailwind)

Frontend Vue/Tailwind của FleetHub đã được build sẵn trong gói. Nếu bạn sửa Vue component hay Tailwind config thì cần Node.js 18+:

npm install
npm run dev    # Hot-reload khi phát triển
npm run build  # Build production (chạy trước khi deploy)

Triển khai trên Hostinger Single (Shared Hosting)

Đây là cách được khuyến nghị cho người không có VPS hoặc kinh nghiệm kỹ thuật. FleetHub tương thích hoàn toàn với gói Hostinger Single Web Hosting rẻ nhất (~$2.99/tháng). Không cần SSH, Composer hay dòng lệnh — Single đã có cron jobs gốc, PHP 8.3 và SSL miễn phí.

Bước 1 — Chuẩn bị hosting

1. Đăng nhập Hostinger hPanel.
2. Vào Hosting → Quản lý cho tên miền của bạn.
3. Đặt phiên bản PHP thành 8.2 hoặc 8.3 qua Nâng cao → Cấu hình PHP.
4. Đảm bảo các PHP extension này được bật (thường mặc định đã có):
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo

Bước 2 — Tạo cơ sở dữ liệu MySQL

1. Trong hPanel, vào Cơ sở dữ liệu → MySQL Databases.
2. Bấm Tạo cơ sở dữ liệu mới.
3. Ghi lại 3 giá trị này:
   • Tên cơ sở dữ liệu — ví dụ u123_FleetHub
   • Tên đăng nhập — ví dụ u123_admin
   • Mật khẩu — được tự sinh, giữ kỹ

Bước 3 — Upload file

1. Vào Tệp → File Manager trong hPanel.
2. Điều hướng tới public_html/ (đây là gốc của tên miền).
3. Xóa mọi file index.html hoặc default.php mặc định trong thư mục này.
4. Bấm Upload Files và tải toàn bộ source.zip từ gói cài đặt.
   Hoặc tải trực tiếp nội dung thư mục /source/ qua FTP nếu bạn muốn.
5. Nếu upload ZIP, chuột phải → Giải nén. Sau khi giải nén, tất cả file phải nằm ở gốc public_html/.
6. Xác nhận public_html/ chứa: app/, public/, vendor/, .htaccess, index.php (trong public/), .env, v.v.

Bước 4 — Chạy trình cài đặt

1. Mở trình duyệt và truy cập https://yourdomain.com/install.
2. Bạn sẽ thấy FleetHub Installer.
3. Bước 1: Requirements — Mọi mục phải pass (xanh). Nếu có mục lỗi, liên hệ Hostinger support để bật PHP extension còn thiếu.
4. Bước 2: Database — Nhập thông tin từ Bước 2 ở trên:
   • Host: localhost
   • Port: 3306
   • Database: u123_FleetHub
   • Username: u123_admin
   • Mật khẩu: (do Hostinger tự sinh)
5. Bước 3: Migrate — Bấm "Run Migrations & Seed". Mất ~10 giây. Đừng refresh.
6. Bước 4: Admin — Tạo tài khoản quản trị. Dùng mật khẩu mạnh.
7. Xong! — Bạn sẽ thấy URL Cron (lưu lại!) và nút đăng nhập.

Bước 5 — Cài cảnh báo email tự động qua Hostinger Cron

FleetHub dùng Laravel scheduler: cảnh báo tuân thủ, nhắc bảo trì, yêu cầu quá hạn, bằng lái, cập nhật giá trị xe và tính lại điểm sức khỏe đội xe. Cấu hình một cron trên hPanel.

1. Trong hPanel, vào Nâng cao → Công việc định kỳ.
2. Bấm Tạo Cron job.
3. Chọn loại: Custom (không phải "PHP" — vì cần truyền tham số).
4. Nhập lệnh sau (thay uXXXXXX bằng username Hostinger của bạn):

   /usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

   Mẹo: mở File Manager, tìm file artisan (gốc dự án), chuột phải → Thuộc tính để sao chép đường dẫn đầy đủ.
5. Đặt lịch Mỗi phút — cả năm trường (Minute, Hour, Day, Month, Day of week) đặt thành *.
6. Bấm Lưu.

FleetHub sẽ gửi nhắc yêu cầu quá hạn, cảnh báo bảo trì, tuân thủ và bằng lái, cập nhật khấu hao và tính lại điểm sức khỏe đội xe tự động.

Bước 6 — Cấu hình email (SMTP)

Hostinger cung cấp tài khoản email kèm theo từng gói. Để dùng cho thông báo của FleetHub:

1. Trong hPanel, vào Email → Tài khoản email và tạo một tài khoản (ví dụ noreply@yourdomain.com).
2. Chỉnh sửa file .env trong public_html/ qua File Manager:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.hostinger.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. Lưu file.
4. Đăng nhập FleetHub → Cài đặt → tab Email → Gửi Test Email. Nếu bạn nhận được là xong.

Sự cố thường gặp trên Hostinger Single

"500 Internal Server Error" sau khi upload

• Xác nhận .htaccess tồn tại ở gốc public_html/ và chứa các rule rewrite.
• Xác nhận phiên bản PHP được đặt thành 8.2 hoặc 8.3 trong hPanel.
• Kiểm tra storage/logs/laravel.log qua File Manager để xem lỗi thật.

"Permission denied" khi upload

Hostinger thường tự đặt quyền đúng, nhưng nếu không:

• Chuột phải storage/ trong File Manager → Quyền → đặt thành 755 đệ quy.
• Tương tự với bootstrap/cache/.

Trình quét QR không mở được camera

API camera của trình duyệt yêu cầu HTTPS. Hostinger cung cấp SSL miễn phí qua Let's Encrypt — bật trong hPanel ở mục SSL → Quản lý.

Email theo lịch không được gửi

• Trong hPanel → Cron Jobs → kiểm tra cột Last run ở entry cron. Nếu trống, cron chưa chạy — xác nhận đường dẫn artisan đúng.
• Test lệnh thủ công: mở Terminal trong hPanel (nếu có) và chạy lệnh cron. Nếu lỗi, thông báo lỗi sẽ chỉ rõ vấn đề (sai phiên bản PHP, sai đường dẫn, v.v.).
• Xác nhận SMTP được cấu hình đúng (Cài đặt → Email → Gửi Test).
• Kiểm tra storage/logs/laravel.log tìm lỗi scheduler.

Hiệu năng chậm

Hostinger Single dùng chung CPU/RAM. Nếu nhóm bạn hơn 20 người, cân nhắc:

• Nâng cấp lên Premium (~$3.99/tháng) — server nhanh hơn, nhiều tài nguyên hơn, nhiều cơ sở dữ liệu.
• Hoặc Business (~$5.99/tháng) — tài nguyên riêng, backup hàng ngày, môi trường staging.

Triển khai trên cPanel (Shared Hosting)

Hướng dẫn này dành cho cPanel shared hosting tiêu chuẩn (Namecheap, Bluehost, GoDaddy và hầu hết host giá rẻ). FleetHub đã có sẵn vendor/ và frontend build — không cần Composer, npm hay Terminal trên server. Nếu cPanel không có Terminal, dùng SSH Access hoặc các cách trong File Manager bên dưới.

Bước 1 — Đặt phiên bản PHP và extensions

1. Đăng nhập cPanel.
2. Mở MultiPHP Manager (hoặc Select PHP Version) và chọn PHP 8.2 hoặc 8.3 cho domain.
3. Mở MultiPHP INI Editor hoặc PHP Extensions và xác nhận các extension sau đã bật:
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo
4. Nếu thiếu extension, bật trong danh sách hoặc liên hệ support host.

Bước 2 — Bật SSL (HTTPS)

1. Vào SSL/TLS Status (hoặc Let's Encrypt SSL / AutoSSL).
2. Chạy AutoSSL hoặc cài chứng chỉ miễn phí cho domain.
3. HTTPS bắt buộc để trình quét QR mở camera trình duyệt.

Bước 3 — Tạo database và user MySQL

1. Mở Manage My Databases (trong mục Databases).
2. Ở Create New Database, nhập tên (vd. fleethub) và Create. cPanel tự thêm prefix — tên đầy đủ dạng cpaneluser_fleethub.
3. Ở MySQL Users, tạo user với mật khẩu mạnh. Copy username có prefix.
4. Ở Add User To Database, chọn user và database, Add, rồi cấp ALL PRIVILEGES. Bước này dễ bỏ sót — thiếu sẽ lỗi Access denied (1045).
5. Ghi chính xác 3 giá trị hiển thị trong cPanel:
   • Tên cơ sở dữ liệu — ví dụ u123_FleetHub
   • Tên đăng nhập — ví dụ u123_admin
   • Mật khẩu — được tự sinh, giữ kỹ

Bước 4 — Upload file

1. Mở File Manager, vào public_html/ (document root).
2. Bật Settings → Show Hidden Files để thấy .htaccess và .env.
3. Xóa index.html mặc định trong public_html/ nếu có.
4. Upload source.zip và Extract, hoặc upload nội dung thư mục /source/ qua FTP.
5. Sau giải nén, public_html/ phải có app/, public/, vendor/, .htaccess gốc và artisan cùng cấp.

Bước 5 — Chuẩn bị .env trước khi chạy installer

Hoàn thành bước này trước khi mở /install. Laravel cần APP_KEY hợp lệ và cấu hình DB đúng trong .env.

1. Trong File Manager, copy .env.example thành .env (cùng thư mục với artisan).
2. Sửa .env và đặt tối thiểu:

   APP_NAME=FleetHub
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://yourdomain.com
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=cpaneluser_fleethub
   DB_USERNAME=cpaneluser_admin
   DB_PASSWORD="your_password"
   
   SESSION_DRIVER=file
   CACHE_STORE=file

3. Đặt DB_CONNECTION=mysql — .env.example mặc định dùng SQLite; shared hosting cần MySQL.
4. Đặt SESSION_DRIVER=file và CACHE_STORE=file trước migration đầu (tránh lỗi bảng sessions).
5. Bọc DB_PASSWORD trong dấu ngoặc kép nếu mật khẩu có ký tự đặc biệt (#, $, !, v.v.).

Tạo APP_KEY (không cần Terminal)

Nhiều gói cPanel không có Terminal web. Dùng một trong các cách:

• SSH Access (cPanel → Security → SSH Access): kết nối PuTTY/PowerShell, chạy cd ~/public_html && php artisan key:generate.
• File Manager — tạo tạm public/genkey.php, mở trình duyệt, copy kết quả vào APP_KEY=, rồi xóa file ngay.

  <?php
  echo 'base64:' . base64_encode(random_bytes(32));

• Trên máy PC — nếu có PHP local: php -r "echo 'base64:'.base64_encode(random_bytes(32));" rồi dán vào .env.

• Đặt quyền storage/ và bootstrap/cache/ là 755 (recursive) nếu installer báo lỗi ghi.

Bước 6 — Chạy web installer

1. Mở https://yourdomain.com/install trong trình duyệt.
2. Bước 1: Requirements — tất cả phải ĐẠT (xanh). Sửa extension PHP ở Bước 1 nếu thiếu.
3. Bước 2: Database — nhập tên có prefix từ Bước 3:
   • Host: 127.0.0.1 or localhost
   • Port: 3306
   • Database: cpaneluser_fleethub
   • Username: cpaneluser_admin
   • Password: (your MySQL password)
4. Bước 3: Migrate — bấm "Run Migrations & Seed". ~10 giây. Không refresh trang.
5. Bỏ tick Include demo data nếu cài production sạch.
6. Bước 4: Admin — tạo tài khoản quản trị.
7. Xong! — lưu Cron URL ở màn hình cuối.

Bước 7 — Cấu hình Cron Jobs cho email cảnh báo

FleetHub cần một cron chạy mỗi phút để Laravel gửi cảnh báo tuân thủ, nhắc bảo trì, yêu cầu quá hạn và email theo lịch khác.

1. Trong cPanel, vào Advanced → Cron Jobs.
2. Ở Add New Cron Job, đặt lịch Every minute (* * * * *).
3. Nhập lệnh (thay CPANELUSER bằng username cPanel trong General Information):

   /usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

   Mẹo: đường dẫn PHP có thể là /usr/local/bin/php hoặc /usr/bin/php. Đường dẫn artisan thường là /home/CPANELUSER/public_html/artisan.
4. Bấm Add New Cron Job để lưu.

Bước 8 — Cấu hình email (SMTP)

Tạo tài khoản email cPanel cho thông báo gửi đi:

1. Vào Email Accounts → tạo vd. noreply@yourdomain.com.
2. Sửa .env trong File Manager:

   MAIL_MAILER=smtp
   MAIL_HOST=mail.yourdomain.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. Lưu, rồi trong FleetHub: Settings → Email → Send Test Email.

Sự cố thường gặp trên cPanel

"Access denied for user" (SQLSTATE 1045)

• Copy tên database và username chính xác từ cPanel — kể cả prefix.
• Xác nhận đã Add User To Database với ALL PRIVILEGES.
• Reset mật khẩu MySQL trong cPanel và cập nhật .env — dùng dấu ngoặc quanh DB_PASSWORD nếu có ký tự đặc biệt.

Migration fail sau khi bước Database đã pass

• Wizard test từ form, nhưng Migrate đọc .env. Đảm bảo khớp nhau.
• Xóa bootstrap/cache/config.php nếu có, rồi thử lại.
• Đảm bảo DB_CONNECTION=mysql trong .env (không phải sqlite).

"Invalid default value" khi migration (1067)

Chế độ strict của MySQL trên shared hosting có thể từ chối default value một số cột. Xem storage/logs/laravel.log và đảm bảo PHP 8.2+ với đủ extension.

"500 Internal Server Error" sau upload

• Kiểm tra .htaccess gốc và PHP 8.2+.
• Xem storage/logs/laravel.log để biết lỗi thực.
• Xác nhận APP_KEY đã set trong .env — key trống gây lỗi 500.

Không có Terminal trong cPanel

Bình thường trên nhiều gói shared. Dùng SSH Access (nếu bật), genkey.php tạm ở Bước 5, hoặc tạo key trên PC local.

Trình quét QR không mở camera

Bật SSL qua SSL/TLS Status → AutoSSL và truy cập bằng https://.

Cấu hình

Tệp .env

Cài đặt trong app

Hầu hết tùy chọn không nhạy cảm cấu hình tại Admin → Settings:

• Chung: tên/email/điện thoại công ty, thương hiệu
• Đội xe: tiền tố mã xe, mẫu checklist bàn giao, mặc định bảo trì, chế độ trang xe công khai
• Email: gửi email thử để kiểm tra SMTP
• Thông báo: bật/tắt cảnh báo tuân thủ, bảo trì, yêu cầu xe, bằng lái
• Đa ngôn ngữ: múi giờ, định dạng ngày, tiền tệ — áp dụng toàn app
• Tuân thủ: quản lý preset loại tuân thủ (bảo hiểm, đăng kiểm, thuế đường bộ...)
• Thương hiệu: tên app và logo — cập nhật đăng nhập, footer, tiêu đề tab
• Giao diện: tùy chỉnh màu thương hiệu, trạng thái và chữ cho sáng/tối — xem hướng dẫn đổi thương hiệu trong FAQ

Hỗ trợ đa ngôn ngữ

FleetHub đi kèm sẵn 11 ngôn ngữ, bao gồm Ả Rập (RTL) và Hindi. Người dùng đổi ngôn ngữ qua dropdown cờ ở góc trên bên phải.

Các ngôn ngữ có sẵn

Cách chuyển ngôn ngữ

1. Click vào icon cờ ở góc trên bên phải để mở dropdown.
2. Chọn ngôn ngữ từ danh sách.
3. Trang sẽ reload; toàn bộ nhãn UI, ngày tháng và định dạng tiền tệ chuyển theo.
4. Lựa chọn được lưu cả vào tài khoản người dùng và cookie (1 năm).

Thêm ngôn ngữ tùy chỉnh (admin)

Vào Administration → Translations (admin có quyền manage translations):

• Click "Add Locale" — nhập mã (vd mk cho tiếng Macedonia), tên hiển thị, tên bản ngữ, tên file cờ SVG, hướng (LTR/RTL), và locale gốc để copy bản dịch.
• Locale mới xuất hiện trong language switcher và danh sách ngôn ngữ mặc định ở Settings → Localization.
• Bản dịch DB tự động override file trong lang/{code}/.

Translation Editor

Editor liệt kê mọi key bản dịch theo file (assets, nav, settings…). Mỗi key hiển thị baseline file và override DB (nếu có).

• Lọc theo locale, nhóm bản dịch, hoặc tìm kiếm text.
• Click giá trị để sửa inline; lưu vào DB ngay.
• Reset key để quay về baseline file.
• Locale built-in (en, vi, es…) có thể sửa; locale tùy chỉnh hoàn toàn từ DB.
• Chỉ user có quyền manage translations mới truy cập được trang này.

CSV import / export

• Export — tải mọi key của một locale dạng CSV (group,key,value).
• Import — upload CSV cùng cột; override DB được cập nhật, key mới được thêm.

Locale mặc định theo người dùng

Mỗi user có cột locale. Email thông báo tự động gửi theo ngôn ngữ người nhận nhờ contract HasLocalePreference của Laravel.

Ngôn ngữ mặc định site đặt tại Settings → Localization → Default Language. User cá nhân override qua language switcher trên header.

Danh sách tính năng (15 nhóm module)

Người dùng & Vai trò

FleetHub có 5 vai trò sẵn cho vận hành đội xe nội bộ:

Tài khoản demo (mật khẩu: password): admin@fleethub.test, manager@fleethub.test, dept@fleethub.test, accountant@fleethub.test, driver@fleethub.test. Bật dữ liệu demo khi cài đặt hoặc seed. Phân quyền Spatie — admin có thể tinh chỉnh từng quyền.

Quản lý xe

Tạo xe mới

1. Điều hướng tới Xe → Xe mới.
2. Điền biển số, hãng, model, năm, loại nhiên liệu, danh mục và phòng ban.
3. Thêm ngày mua và giá (bắt buộc cho khấu hao và TCO).
4. Upload ảnh (nhiều tệp, tối đa 5 MB mỗi tệp — tự nén trên mobile).
5. Lưu — mã xe và mã QR được tự sinh.

Định dạng mã xe

Mặc định: {PREFIX}-{YEAR}-{NNNN}, ví dụ VH-2026-0001. Cấu hình tại Cài đặt → Đội xe → Tiền tố mã xe.

Import hàng loạt

1. Bấm Import trên trang Xe.
2. Tải template Excel.
3. Điền dữ liệu — cột bắt buộc: license_plate, make, model, category_name.
4. Upload tệp.

Mã QR & Quét nhanh

Mỗi xe tự động có mã QR khi tạo. Quét mở trang xe công khai hoặc thao tác nhanh trong app cho tài xế đã đăng nhập.

In nhãn QR

• Nhãn đơn: Bấm biểu tượng máy in trên dòng xe.
• In hàng loạt: Chọn nhiều xe → In nhãn QR. Khổ A4, 2 nhãn/hàng.

Quét trong app

Bấm Quét QR trên trang Xe. Cho phép camera. Hoạt động trên trình duyệt hiện đại với HTTPS hoặc localhost.

Trang xe công khai

Mỗi xe có URL công khai tại /v/{vehicle_code} — hữu ích khi nhận diện nhanh không cần đăng nhập.

• Cấu hình tại Cài đặt → Đội xe → Trang xe công khai: Công khai, Yêu cầu đăng nhập hoặc Tắt.
• Chế độ khách chỉ xem thông tin cơ bản (biển số, hãng/model). Thao tác nhanh cần đăng nhập.
• Sau khi đổi APP_URL, bấm Tạo lại tất cả mã QR trong Cài đặt.

Quy trình

Yêu cầu xe

Nhân viên gửi yêu cầu xe cần dùng. Luồng: requested → approved → returned (hoặc rejected). Quản lý đội xe hoặc Trưởng phòng duyệt. Lịch hiển thị đặt xe toàn đội. Trả xe quá hạn gửi email cảnh báo.

Bàn giao xe

1. Khi yêu cầu được duyệt, tạo Bàn giao xuất trước khi tài xế nhận xe.
2. Ghi đồng hồ, hoàn thành checklist, đánh dấu hư hỏng trên sơ đồ 2D, đính ảnh và chữ ký số.
3. Lưu và tải báo cáo bàn giao PDF để lưu hồ sơ.
4. Khi trả xe, tạo Bàn giao nhập — so sánh tình trạng, cập nhật đồng hồ, xóa gán tài xế.
5. Hoàn tất bàn giao nhập đánh dấu yêu cầu đã trả và đặt trạng thái xe về sẵn sàng.

Khấu hao & TCO

FleetHub tính khấu hao xe bằng một trong ba phương pháp. Khấu hao đưa vào bảng TCO cùng nhật ký nhiên liệu và chi phí.

Mặc định kế thừa từ danh mục xe. current_value tự cập nhật hàng tháng qua fleethub:update-vehicle-values. TCO = giá mua + tổng chi phí xe trong kỳ đã chọn.

Trường tùy chỉnh

Admin → Trường tùy chỉnh cho phép thêm thuộc tính không giới hạn cho xe:

• Loại: văn bản, số, ngày, lựa chọn, vùng văn bản, tệp, hộp kiểm
• Phạm vi: áp dụng mọi danh mục hoặc danh mục xe cụ thể
• Sắp xếp: kéo-thả tay nắm
• Trường bắt buộc được kiểm tra khi lưu xe

Báo cáo

Bảy báo cáo đội xe tích hợp, truy cập từ menu Báo cáo:

1. Tổng hợp TCO — tổng chi phí sở hữu theo xe và toàn đội xe
2. Lịch khấu hao — mất giá theo xe, có xuất file
3. Chi phí bảo trì — chi tiêu theo xe, loại và tháng
4. Tiêu thụ & Chi phí nhiên liệu — xu hướng km/l, đánh dấu bất thường
5. Sử dụng yêu cầu xe — tỷ lệ đặt xe theo thời gian
6. Hết hạn tuân thủ — giấy tờ xe và bằng lái tài xế sắp hết hạn
7. Phân bổ xe theo phòng ban — xe và mức sử dụng theo phòng ban

Mọi báo cáo hỗ trợ xuất Excel và PDF qua nút trên đầu trang.

Tích hợp Webhook

FleetHub có thể thông báo dịch vụ bên ngoài khi có sự kiện đội xe quan trọng.

Sự kiện khả dụng

• vehicle.created, vehicle.updated, vehicle.deleted
• requisition.approved, requisition.rejected, requisition.overdue, requisition.returned
• handover.completed
• compliance.expiring, compliance.expired
• maintenance.due, maintenance.overdue, maintenance.completed
• fleet_health_score.dropped

Định dạng payload

{
  "event": "handover.completed",
  "timestamp": "2026-06-23T08:00:00+00:00",
  "data": {
    "vehicle_id": 1,
    "vehicle_code": "VH-2026-0001",
    "license_plate": "51A-12345",
    "handover_id": 12,
    "direction": "outgoing",
    "driver_id": 4
  }
}

Xác minh chữ ký

Nếu cấu hình secret, request có header X-FleetHub-Signature chứa HMAC-SHA256 của body. Xác minh phía bạn:

$expected = hash_hmac('sha256', $rawBody, $secret);
if (hash_equals($expected, $request->header('X-FleetHub-Signature'))) {
  // hợp lệ
}

Chính sách thử lại

Giao thất bại thử lại 3 lần, cách 200 ms. Sau 10 lần liên tiếp thất bại, webhook tự tắt.

Tác vụ theo lịch

FleetHub dùng Laravel scheduler cho tác vụ nền. Chỉ cần một cron — Laravel chạy từng lệnh fleethub: đúng giờ.

Shared hosting (Cron Jobs cPanel / Hostinger)

Xem Cài đặt cPanel → Bước 7 hoặc Cài đặt Hostinger → Bước 5. Tóm lại: Advanced → Cron Jobs, lệnh:

/usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

Lịch: mỗi phút (* ở cả năm trường).

Lệnh cron cPanel

Thay CPANELUSER bằng username cPanel của bạn:

/usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

VPS / máy chủ riêng (crontab)

Chạy crontab -e với user web và thêm:

* * * * * cd /path/to/FleetHub && php artisan schedule:run >> /dev/null 2>&1

Dự phòng: ping URL bên ngoài

Nếu host không có cron, dùng Cron URL trong app (Cài đặt → System) với cron-job.org (miễn phí, 15 phút/lần).

Tác vụ chạy tự động

Hướng dẫn nâng cấp

FleetHub v1.0.0 là bản phát hành đầu tiên trên CodeCanyon.

Xử lý sự cố

"Permission denied" trên storage

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Trình quét QR không mở camera

API camera trình duyệt yêu cầu HTTPS. Cài SSL hoặc dùng localhost khi thử.

Email không nhận được

Kiểm tra storage/logs/laravel.log tìm lỗi. Dùng Cài đặt → Email → Gửi Test Email để xác nhận thông tin SMTP. Đảm bảo máy chủ SMTP cho phép IP gửi.

Database "Access denied" (1045) trên cPanel

Sai user/mật khẩu, chưa gán user vào database, hoặc ký tự đặc biệt trong mật khẩu làm hỏng .env. Xem Cài đặt cPanel → Sự cố thường gặp.

Lỗi migration 1067 (Invalid default value)

MySQL strict mode trên shared hosting từ chối nhiều cột timestamp NOT NULL. Đã sửa từ v2.1.0+. Cập nhật gói hoặc đổi yêu cầu xe_date / expected_return_date sang dateTime trong migration yêu cầu xes.

Thiếu APP_KEY / lỗi 500 trước khi cài

Laravel cần APP_KEY trong .env trước khi app chạy. Nếu cPanel không có Terminal, xem Cài đặt cPanel → Bước 5 (SSH, genkey.php hoặc tạo trên PC).

Reset cài đặt

Xóa storage/installed.lock và truy cập /install lại. Dữ liệu hiện có sẽ bị xóa nếu chạy migration lại.

Hiệu năng — danh sách xe chậm

Chạy php artisan optimize. Đảm bảo index MySQL trên vehicles.vehicle_code, vehicles.license_plate, vehicles.status.

Nhật ký thay đổi

v1.0.0 — Phát hành đầu tiên (2026-06)

• CRUD xe với mã QR tự sinh và trang công khai /v/{vehicle_code}
• 5 vai trò (Admin, Quản lý đội xe, Trưởng phòng, Kế toán, Tài xế)
• Quản lý tài xế, đồng bộ hết hạn bằng lái sang mục tuân thủ
• Quy trình yêu cầu xe với lịch và cảnh báo quá hạn
• Bàn giao xe với sơ đồ hư hỏng 2D, checklist, chữ ký và PDF
• Nhật ký nhiên liệu, chống gian lận đồng hồ, đồng bộ chi phí tự động
• Chi phí xe và bảng TCO với phân tích chi phí/km
• Khấu hao — đường thẳng, số dư giảm dần, đơn vị sản xuất (km)
• Mục tuân thủ với cảnh báo hết hạn 30/14/7/1 ngày
• Lên lịch bảo trì, tự gia hạn phòng ngừa, theo dõi chi phí
• Điểm sức khỏe đội xe, tính lại hàng ngày và modal chi tiết
• 7 báo cáo đội xe, xuất Excel và PDF
• Trường tùy chỉnh (7 loại) theo danh mục xe
• Webhooks ký HMAC (X-FleetHub-Signature) và tự thử lại
• Nhật ký kiểm toán Spatie Activitylog với diff
• UI đa ngôn ngữ: 11 locale gồm Ả Rập RTL và Hindi
• Cài đặt công ty, đội xe, email, thông báo, preset tuân thủ
• Trình cài đặt web với seeder dữ liệu demo
• Dark mode, UI mobile-first, nén ảnh khi upload

Ghi nhận

Thư viện mã nguồn mở đã dùng

• Laravel 11 — MIT
• Vue 3 — MIT
• Inertia.js — MIT
• Tailwind CSS — MIT
• Spatie Permission, Media Library, Activitylog — MIT
• Phosphor Icons — MIT (duotone weight)
• ApexCharts — MIT
• html5-qrcode — Apache 2.0
• Simple QrCode — MIT
• Laravel Excel — MIT
• Laravel DomPDF — MIT