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.

Laravel 10.x
PHP 8.3+
Layered Architecture
100% Local Assets
RBAC 61 Permissions
🚀

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:

Terminal / Bash Commands
# 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:

Frontend Partial Rendering (slider.blade.php)
<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)