AssetHub Tài liệu

Tổng quan

AssetHub là hệ thống quản lý tài sản xây dựng bằng Laravel 11, Vue 3 và Tailwind CSS. Phiên bản 3.0 bổ sung Translation Editor đầy đủ, locale tùy chỉnh, CSV import/export và bản địa hóa múi giờ/tiền tệ thực sự có hiệu lực — trên nền v2 (batch/lot, cấp phát, thanh lý, QR bàn giao công khai).

Yêu cầu máy chủ

• PHP 8.2 trở lên
• MySQL 5.7+ hoặc MariaDB 10.3+
• Composer 2.x
• Node.js 18+ và npm 9+
• Máy chủ web: Apache hoặc Nginx

PHP Extension 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. Cần thêm dung lượng cho ảnh tài sản và tệp đính kèm tài liệu.

Cài đặt

Lựa chọn A — Trình cài đặt qua web (Khuyến nghị)

1. Upload file dự án lên máy chủ web.
2. Trỏ document root của tên miền tới public/.
3. Đặt 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/Terminal, hoặc xem Cài đặt cPanel → Bước 5 nếu không có Terminal).
5. Mở https://yourdomain.com/install trong trình duyệt.
6. Làm theo wizard — Requirements → Database → Migrate → Admin Account → Done.

Lựa chọn B — Cài đặt qua 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 storage symlink cho upload
php artisan storage:link

# 6. Cache config 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 AssetHub 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 AssetHub vào ~/Herd/ (macOS) hoặc %USERPROFILE%\Herd\ (Windows). Herd tự tạo domain .test — ví dụ http://assethub.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://assethub.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 AssetHub vào C:\xampp\htdocs\AssetHub\ (Windows) hoặc /Applications/XAMPP/htdocs/AssetHub/ (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 assethub với collation utf8mb4.
5. Trong thư mục dự án: sao chép .env.example thành .env, đặt DB_DATABASE=assethub, DB_USERNAME=root, để trống DB_PASSWORD (mặc định XAMPP). Chạy php artisan key:generate.
6. Truy cập http://localhost/AssetHub/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 AssetHub vào C:\laragon\www\AssetHub\.
4. Bấm Start All. Laragon tự tạo vhost: http://assethub.test (trỏ đến thư mục public/).
5. Mở HeidiSQL (đi kèm) → tạo database assethub. 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://assethub.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/AssetHub
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 AssetHub 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 AssetHub đã đượ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. AssetHub 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_AssetHub
   • 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 AssetHub 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_AssetHub
   • 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

AssetHub dùng scheduler của Laravel cho các tác vụ nền: cảnh báo bảo hành, nhắc bảo trì, hạn tài liệu, refresh khấu hao và checkout quá hạn. Cấu hình một cron job duy nhất trong hPanel rồi Laravel sẽ quyết định chạy tác vụ nào lúc nào.

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.

Xong — AssetHub bây giờ tự gửi nhắc checkout quá hạn, cảnh báo bảo trì, hạn tài liệu, cảnh báo bảo hành, và refresh giá trị khấu hao tài sản tự động. Laravel tự lên lịch từng job ở tần suất đúng (hàng ngày 08:00, hàng tháng, v.v.).

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 AssetHub:

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 AssetHub → 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ẻ). AssetHub đã 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. assethub) và Create. cPanel tự thêm prefix — tên đầy đủ dạng cpaneluser_assethub.
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_AssetHub
   • 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=AssetHub
   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_assethub
   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_assethub
   • 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

AssetHub cần một cron job chạy mỗi phút để Laravel gửi cảnh báo bảo hành, bảo trì và email theo lịch.

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 AssetHub: 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)

Đã sửa trong AssetHub v2.1.0+ (bảng checkouts dùng dateTime). Nếu dùng bản cũ, cập nhật file migration hoặc tải gói mới từ CodeCanyon.

"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 các tùy chọn không nhạy cảm đều cấu hình được từ Admin → Cài đặt:

• Chung: tên/email/điện thoại công ty, tiền tố asset tag
• Email: gửi test email để xác nhận SMTP
• Thông báo: ngưỡng cảnh báo bảo hành, cửa sổ nhắc bảo trì
• Bản địa hóa: múi giờ (danh sách tìm kiếm, gồm Europe/Skopje), định dạng ngày, mã tiền tệ (gồm MKD — Denar Macedonia), ký hiệu và vị trí ký hiệu — áp dụng toàn app sau khi lưu
• Chung → Trang tài sản công khai: hiển thị QR (public / đăng nhập / tắt) và tạo lại QR sau khi đổi URL
• Tab Bản địa hóa có link tới Administration → Translations (Translation Editor, chỉ admin)
• Branding: tên app và logo — cập nhật logo login, footer, badge và tiêu đề tab trình duyệt (v4.0+). Subtitle login: sửa auth.login_subtitle trong Administration → Translations
• Appearance (v4.0+): tùy chỉnh màu thương hiệu, trạng thái và chữ cho chế độ sáng/tối — xem hướng dẫn rebrand trong FAQ

Hỗ trợ đa ngôn ngữ

AssetHub đ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

Người dùng & Vai trò

AssetHub đi kèm 5 vai trò cấu hình sẵn:

Quyền hạn được lưu dưới dạng vai trò Spatie — quản trị viên có thể tinh chỉnh theo từng quyền qua cơ sở dữ liệu.

Quản lý tài sản

Tạo tài sản

1. Điều hướng tới Tài sản → Tài sản mới.
2. Điền tên, danh mục, thương hiệu, model, số serial.
3. Thêm ngày mua và giá (bắt buộc cho khấu hao).
4. Upload ảnh (hỗ trợ nhiều tệp, mỗi tệp tối đa 5 MB).
5. Lưu — asset tag và mã QR được tự sinh.

Định dạng Asset Tag

Mặc định: {PREFIX}-{YEAR}-{NNNN}, ví dụ AS-2026-0001. Cấu hình được qua Cài đặt → Chung → Tiền tố Asset Tag.

Import hàng loạt

1. Bấm Import ở trang Tài sản.
2. Tải template Excel.
3. Điền dữ liệu của bạn — các cột bắt buộc: name, category_name.
4. Upload tệp.

Tài sản lô / Batch (v2)

Với hàng giống nhau theo số lượng (ghế, bàn phím, đồng phục), chọn Loại theo dõi → Batch / Lot trên form Tạo tài sản thay vì tạo nhiều bản ghi trùng.

1. Nhập số lượng và đơn vị (cái, bộ, thùng). Khi lưu, toàn bộ được đưa vào kho.
2. Mở tài sản → tab Phân bổ → Cấp phát cho nhân viên hoặc phòng ban.
3. Dùng Thu hồi, Điều chỉnh (hư/mất/sửa) — bảng tổng hợp phải cân bằng với tổng số lượng.
4. Batch hỗ trợ chỉ đơn giá; khấu hao tùy chọn và mặc định tắt để cài nhanh.

Mã QR

Mọi tài sản tự nhận mã QR khi tạo. Quét mở trang công khai hoặc chi tiết trong app (xem bên dưới). Quét trong app nhảy thẳng tới màn hình chi tiết.

In nhãn

• Nhãn đơn: Bấm icon máy in trên bất kỳ hàng tài sản nào.
• Định dạng PDF: A4, 2 nhãn mỗi hàng, gồm asset tag, tên, thương hiệu, serial.

Quét

Bấm Quét QR ở trang Tài sản. Cho phép quyền camera. Trình quét dùng html5-qrcode và chạy được trên mọi trình duyệt hiện đại. Lưu ý: truy cập camera yêu cầu HTTPS hoặc localhost.

Trang QR bàn giao công khai (v2)

Mỗi tài sản có URL công khai tại /a/{asset_tag} — in làm phiếu bàn giao mà không cần đăng nhập.

• Cấu hình tại Cài đặt → Chung → Public Asset Page: Công khai, Cần đăng nhập, hoặc Tắt.
• Trang hiển thị ảnh, trường chính và (với batch) chi tiết số lượng. Có thể in làm biên bản bàn giao.
• Sau khi đổi APP_URL, bấm Regenerate all QR codes trong cùng mục cài đặt.

Quy trình

Cấp phát tài sản

1. Mở trang chi tiết tài sản.
2. Bấm Cấp phát (hiển thị nếu tài sản đang sẵn).
3. Chọn người dùng, ngày trả tùy chọn, ghi chú.
4. Submit — giao dịch được tạo và email thông báo được gửi.

Yêu cầu tài sản

Nhân viên có thể gửi yêu cầu tài sản họ cần. Yêu cầu có 4 trạng thái: pending → approved → fulfilled, hoặc rejected. Email duyệt được gửi tự động.

Check-in / Check-out

Dành cho tài sản dùng chung (camera, máy chiếu, xe). Đặt chỗ có khoảng ngày; hệ thống chặn checkout chồng lấn. Xem dạng lịch cho phép theo dõi tất cả đặt chỗ trong nháy mắt.

Thanh lý — Write-off chính thức (v2)

Hàng hư/mòn được thanh lý theo đợt có tài liệu, phân quyền duyệt (người đề xuất ≠ người duyệt). Cần quyền manage disposals và approve disposals.

1. Sidebar → Disposals → New Disposal. Đặt tiêu đề và kỳ (Q1–Q4, hàng năm, ad-hoc).
2. Mở bản nháp → Add items — đơn vị batch hư hoặc tài sản đơn ở tình trạng Poor.
3. Bấm Submit for approval — đợt bị khóa.
4. Người duyệt khác bấm Approve & execute — tài sản/đơn vị chuyển sang disposed.
5. In disposal minutes (PDF) để lưu hồ sơ tuân thủ.

Khấu hao

AssetHub tính khấu hao tài sản bằng một trong ba phương pháp:

Mặc định được kế thừa từ danh mục của tài sản. Mục lịch trình được sinh hàng tháng. current_value của tài sản được cập nhật tự động vào ngày 1 mỗi tháng.

Trường tùy chỉnh

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

• Loại: văn bản, số, ngày, lựa chọn (dropdown), 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 cụ thể
• Sắp xếp lại: kéo-thả tay nắm
• Trường bắt buộc được kiểm tra khi lưu tài sản

Báo cáo

Mười hai báo cáo tích hợp sẵn, truy cập từ menu Báo cáo:

1. Tổng hợp tài sản — tổng theo trạng thái, tình trạng, danh mục, phòng ban
2. Khấu hao — mất giá theo danh mục, các tài sản khấu hao nhiều nhất
3. Giao dịch — hoạt động cấp phát, trả, chuyển theo thời gian
4. Chi phí bảo trì — chi tiêu theo tháng, danh mục, loại
5. Hết hạn bảo hành — tài sản cần lưu ý trong 30/60/180 ngày
6. Tài sản theo phòng ban — phân bổ tài sản & sử dụng ngân sách theo phòng ban
7. Tài sản theo nguồn — phân bổ theo nguồn mua sắm, dự án, hiến tặng, chuyển giao
8. Tổng hợp Kiểm kê — chênh lệch qua các kỳ kiểm kê định kỳ
9. Cấp phát nhân viên (v2) — ai đang giữ gì, gồm phân bổ batch
10. Phòng ban / Vị trí (v2) — tài sản và số lượng theo phòng ban hoặc vị trí
11. Đối soát tồn kho (v2) — tồn kho vs đã cấp vs hư/mất/thanh lý
12. Tài sản hư hỏng (v2) — hàng cần sửa hoặc thanh lý

Mọi báo cáo đều hỗ trợ xuất Excel và PDF qua các nút ở đầu trang. Báo cáo v2 theo số lượng (số bản ghi + tổng đơn vị).

Webhook

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

Sự kiện có sẵn

• asset.created, asset.updated, asset.deleted
• asset.assigned, asset.returned, asset.transferred
• request.created, request.approved, request.rejected, request.fulfilled
• maintenance.scheduled, maintenance.started, maintenance.completed
• checkout.created, checkout.returned

Định dạng Payload

{
  "event": "asset.assigned",
  "timestamp": "2026-05-05T08:00:00+00:00",
  "data": {
    "asset_id": 1,
    "asset_tag": "AS-2026-0001",
    "asset_name": "HP EliteDesk 800",
    "to_user_id": 4,
    "transaction_id": 12
  }
}

Xác thực chữ ký

Nếu đã cấu hình secret, request bao gồm header X-AssetHub-Signature chứa HMAC-SHA256 của body. Xác thực ở phía bạn:

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

Chính sách Retry

Gửi thất bại retry 3 lần với độ trễ 200 ms. Sau 10 lần thất bại liên tiếp, webhook tự bị vô hiệu hóa.

Tác vụ theo lịch

AssetHub dùng scheduler của Laravel cho job nền. Bạn chỉ cần một entry cron — Laravel tự điều phối từng job đúng giờ.

Shared hosting (Cron Jobs trên cPanel / Hostinger)

Xem Cài đặt cPanel → Bước 7 hoặc Cài đặt Hostinger → Bước 5. Tóm tắt: Nâng cao → 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 (thường là www-data) và thêm:

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

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

Nếu host bạn không có cron, dùng URL Cron trong app (Cài đặt → tab Hệ thống) với cron-job.org (miễn phí, mỗi 15 phút).

Các job tự chạy

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

Hướng dẫn từng bước để cập nhật bản cài đặt hiện có. Mở hướng dẫn phù hợp với phiên bản bạn đang dùng.

• v3.1 → v4.0 — Hướng dẫn nâng cấp đầy đủ — Cài đặt Giao diện, tiêu đề tab trình duyệt từ Thương hiệu. Không cần migration.
• v3.0 → v3.1 — Hướng dẫn nâng cấp đầy đủ — Checklist ngôn ngữ hiển thị trên bộ chọn navbar. Không cần migration.
• v2.x → v3.0 — Hướng dẫn nâng cấp đầy đủ — Translation Editor, locale tùy chỉnh, cài đặt bản địa hóa.
• v1.x → v2.0 — Hướng dẫn nâng cấp đầy đủ — Tài sản lô, thanh lý, trang QR công khai, báo cáo vận hành.

Khắc phục 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 của trình duyệt yêu cầu HTTPS. Cài SSL hoặc dùng localhost để test.

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 checkout_date / expected_return_date sang dateTime trong migration checkouts.

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 tài sản chậm

Chạy php artisan optimize để cache config, route, view. Đảm bảo MySQL có index trên assets.asset_tag, assets.serial_number, assets.status (migration đã tự tạo).

Nâng cấp từ v3.0.x lên v3.1

Tải gói v3.1 từ CodeCanyon, thay file ứng dụng (giữ .env và upload trong storage/). Không cần migration mới. Cài đặt visible_locales là tùy chọn — nếu chưa cấu hình, tất cả ngôn ngữ vẫn hiển thị trên bộ chọn navbar.

v3.0 → v3.1 — Hướng dẫn nâng cấp đầy đủ

Nâng cấp từ v2.x lên v3.0

Tải ZIP v3 từ CodeCanyon, thay file ứng dụng (giữ .env và upload trong storage/), rồi chạy php artisan migrate. Bảng locale tùy chỉnh và override bản dịch được thêm tự động. Cài đặt và tài sản hiện có được giữ nguyên.

v2.x → v3.0 — Hướng dẫn nâng cấp đầy đủ

Nâng cấp từ v1.x lên v2.0

Tải ZIP v2 từ CodeCanyon, thay file ứng dụng (giữ .env và upload trong storage/), rồi chạy php artisan migrate. Nâng cấp không phá vỡ — tài sản đơn chiếc v1 vẫn hoạt động; bảng batch/thanh lý được thêm tự động.

v1.x → v2.0 — Hướng dẫn nâng cấp đầy đủ

Lịch sử thay đổi

v3.1.0 — Bộ chọn ngôn ngữ hiển thị (2026-06)

• Settings → Localization: checklist chọn ngôn ngữ hiển thị trên menu ngôn ngữ navbar (built-in + custom)
• Ngôn ngữ mặc định luôn hiển thị; bộ chọn tự ẩn khi chỉ còn một ngôn ngữ
• Backend kiểm tra chuyển locale; người dùng đang dùng ngôn ngữ bị ẩn sẽ về ngôn ngữ mặc định
• Không cần migration — nâng cấp chỉ thay file
• Branding trang login: footer copyright và badge cột phải theo Settings → Branding → App Name (không cần sửa code)

v3.0.0 — Bản địa hóa & Translation Editor (2026-06)

• Translation Editor tại Administration → Translations (Thêm Locale, sửa inline, tìm/lọc theo nhóm)
• Locale tùy chỉnh lưu DB — mã, tên hiển thị, tên bản ngữ, cờ SVG, hướng, locale gốc
• CSV import/export cập nhật bản dịch hàng loạt
• Múi giờ và tiền tệ áp dụng toàn app (config/localization.php gồm Europe/Skopje, MKD)
• Settings → Localization: dropdown múi giờ/tiền tệ có tìm kiếm, hỗ trợ giá trị tùy chỉnh
• Thêm Hindi (hi) làm locale thứ 11; date_format được dùng trên các trang Vue
• Quyền manage translations; override DB merge với baseline file lang/

v2.0.0 — Bản vận hành (2026-06)

• Tài sản lô/batch — theo dõi số lượng, cấp phát, thu hồi, đối soát trực tiếp
• 4 báo cáo vận hành: Cấp phát nhân viên, Phòng ban/Vị trí, Đối soát tồn kho, Tài sản hư hỏng
• Module thanh lý — đợt write-off, duyệt phân quyền, biên bản PDF in được
• Trang QR công khai tại /a/{tag} với tùy chọn hiển thị
• Báo cáo cũ cập nhật hiển thị số bản ghi + tổng đơn vị
• Mã QR trỏ trang bàn giao công khai; log giao dịch ghi số lượng khi di chuyển batch
• Cập nhật demo data, user guide (giao riêng trong documentation/) và chuỗi i18n

v1.0.0 — Bản phát hành đầu tiên (2026-05)

• Asset CRUD với tự sinh mã QR
• 5 vai trò (Admin, IT Manager, Kế toán, Supervisor, Nhân viên) với phân quyền chi tiết
• Theo dõi Nguồn tài sản (mua sắm tập trung, mua sắm phân tán, dự án đầu tư, hiến tặng, chuyển giao nội bộ)
• Quy trình cấp phát, trả với email thông báo
• Quy trình duyệt Chuyển giao (pending → approved/rejected) với gating quyền
• Quy trình duyệt yêu cầu tài sản
• Check-in/check-out có xem dạng lịch
• Lên lịch bảo trì có tự gia hạn
• Đính kèm tài liệu kèm cảnh báo hết hạn
• Khấu hao với 3 phương pháp + cảnh báo cuối vòng đời
• Module Kiểm kê — kiểm kê định kỳ, theo dõi chênh lệch
• Trường tùy chỉnh với 7 loại input và sắp xếp kéo-thả
• 8 báo cáo có biểu đồ, xuất Excel và PDF (gồm Tài sản theo nguồn, Tổng hợp Kiểm kê)
• Nhật ký kiểm toán qua Spatie Activitylog với trình xem diff
• Webhook với ký HMAC và tự retry
• Giao diện đa ngôn ngữ: 10 ngôn ngữ (en, vi, es, fr, de, zh, ja, pt-BR, ru, ar có RTL)
• Giao diện Cài đặt cho công ty, email, thông báo, bản địa hóa, bản dịch
• Trình cài đặt qua web
• Chế độ tối với bảng màu emerald-teal

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