Tài liệu Base Source Laravel
Hệ thống mã nguồn chuẩn hóa với Kiến trúc Layered (Controller → Service → Repository → Model), 100% Local Assets (No CDN), giao diện Admin Blade Components hiện đại và tối ưu trải nghiệm Taste Skill.
Cài đặt & Triển khai nhanh
Triển khai source base hoàn chỉnh trên môi trường local (Laragon / XAMPP / Docker) trong 5 bước cơ bản:
# 1. Clone repository về máy
git clone https://github.com/Thanhphuc1230/source_base_laravel.git
cd source_base_laravel
# 2. Cài đặt các gói phụ thuộc Composer & NPM
composer install
npm install
# 3. Khởi tạo file cấu hình .env & sinh App Key
cp .env.example .env
php artisan key:generate
# 4. Chạy Migration & Seeder dữ liệu mẫu (kèm ảnh demo slider)
php artisan migrate --seed
# 5. Xóa sạch cache hệ thống & khởi chạy Server
php artisan optimize:clear
php artisan serve
Kiến trúc Layered (Architecture)
Dự án tuân thủ nghiêm ngặt mô hình phân tách trách nhiệm 4 lớp chuẩn mực:
1. Controller App\Http\Controllers
Điều hướng Request, validate đầu vào, gọi Service tương ứng và trả về View (Blade) hoặc JSON Response. Tuyệt đối không viết SQL query trực tiếp trong Controller.
2. Service App\Services
Chứa toàn bộ nghiệp vụ xử lý logic (Business Logic), quản lý Cache, gọi ImageService tối ưu ảnh WebP, gửi email, và điều phối thao tác dữ liệu.
3. Repository App\Repositories
Tầng tương tác dữ liệu duy nhất với Database. Đảm nhận các truy vấn Eloquent / Query Builder giúp dễ dàng mock test và bảo trì.
4. Model App\Models
Định nghĩa các mối quan hệ Eloquent (Relationships), thuộc tính `$fillable`, Accessors / Mutators và xử lý chuyển đổi dữ liệu tự động.
7 Quy tắc Cốt lõi của Dự án (Base Core Rules)
QUY TẮC SỐ 1 – TUYỆT ĐỐI KHÔNG HARDCODE
Mọi thông tin doanh nghiệp (Tên công ty, SĐT, Email, Địa chỉ, Logo, Google Maps) bắt buộc phải dùng biến động $website từ Database. Không ghi cứng văn bản trong Blade View.
QUY TẮC SỐ 2 – KIẾN TRÚC LAYERED
Tuân thủ luồng: Controller → Service → Repository → Model. Giữ Controller gọn nhẹ và tái sử dụng code cao.
QUY TẮC SỐ 3 – BLADE COMPONENTS ADMIN
100% trang Admin sử dụng Blade Components hệ thống: <x-admin.table-wrapper>, <x-admin.table-switch>, <x-admin.localized-fields>, <x-admin.image-upload>.
QUY TẮC SỐ 4 – DỌN DẸP CACHE HỆ THỐNG
Sau khi chỉnh sửa code/config luôn chạy php artisan optimize:clear hoặc sử dụng nút "Xóa cache" trên menu Admin.
QUY TẮC SỐ 5 – THẨM MỸ GIAO DIỆN TASTE SKILL
Sử dụng Google Fonts (Inter, Outfit, Montserrat), hiệu ứng hover mượt transition: all 0.3s ease, hiển thị tin tức/sản phẩm 2 cột trên di động.
QUY TẮC SỐ 6 – KHÔNG DÙNG CDN (DOWNLOAD LOCAL ASSETS)
Tất cả thư viện JS/CSS, Font (RemixIcon, Select2, Choices.js, Flatpickr, Toastify, HKGrotesk) phải được lưu trữ cục bộ tại public/admin/libs/ & public/admin/fonts/.
QUY TẮC SỐ 7 – TÁCH BIỆT CODE CSS & JS (NO INLINE/EMBEDDED)
Không viết code CSS (thẻ <style>) hoặc JS (thẻ <script>) trực tiếp trong các file Blade view.
Bảng Biến Động $website (Quy tắc 1)
| Thông tin | Cách viết Sai ❌ | Cách viết Đúng ✅ |
|---|---|---|
| Tên Công ty | Base Company |
{{ $website->name_vn }} |
| Số Điện Thoại | 0979.248.298 |
{{ $website->phone }} |
| Email Liên hệ | contact@base.local |
{{ $website->email }} |
| Bản đồ Google Map | src="https://maps.google..." |
src="{{ $website->map }}" |
| Logo Website | src="/images/logo.png" |
src="{{ asset($website->logo) }}" |
Tính năng Slider Responsive (Desktop & Mobile)
Hệ thống hỗ trợ 2 bộ banner riêng biệt cho Desktop & Mobile với đa ngôn ngữ, tự động render thẻ HTML5 <picture> tối ưu tốc độ tải trang:
<picture>
<!-- Mobile Banner -->
<source media="(max-width: 767px)" srcset="{{ asset($slider->image_mobile) }}">
<!-- Desktop Fallback Banner -->
<img src="{{ asset($slider->image_desktop) }}" alt="{{ $slider->name_vn }}" class="img-fluid">
</picture>
Tài khoản Thử nghiệm Admin (RBAC)
| Vai trò (Role) | Email Đăng nhập | Mật khẩu | Quyền hạn |
|---|---|---|---|
| Admin | admin@gmail.com |
@admin123 |
Full 61 Permissions (Toàn quyền) |
| Manager | manager@gmail.com |
@manager123 |
Quản lý sản phẩm & tin tức (40+ Permissions) |
| Editor | editor@gmail.com |
@editor123 |
Biên tập nội dung (14 Permissions) |