Skip to main content

🛠️ Kiến trúc Backend Laravel 13 Modular

Tài liệu kỹ thuật dành riêng cho Lập trình viên Backend phát triển và mở rộng các tính năng trên nền tảng LMS API (Laravel 13, PHP 8.3+).

1. Công nghệ & Nguyên tắc Cốt lõi​

Thành phầnCông nghệ / Thư việnQuy chuẩn áp dụng
FrameworkLaravel 13 (PHP 8.3+)Strict types, Backed Enums
Modular Enginenwidart/laravel-modulesĐóng gói nghiệp vụ độc lập trong backend/Modules/
Kiến trúc TầngThin Controller - Fat ServiceController chỉ nhận request → delegate Service → trả API Resource
AuthenticationLaravel SanctumBearer Token kết hợp X-Center-ID header
Tenant BoundaryDynamic Host ResolutionHasTenantScope, HasOrganizationScope

2. Cấu trúc Thư mục Module Backend​

Mỗi module chức năng trong backend/Modules/< ModuleName>/ tuân thủ nghiêm ngặt cấu trúc chuẩn sau:

Modules/< ModuleName>/
├── App/
│   ├── Http/
│   │   ├── Controllers/     # Thin controllers (chỉ validate & gọi Service)
│   │   ├── Requests/        # Form Request validation rules
│   │   └── Resources/       # JsonResource transformers chuẩn hóa đầu ra JSON
│   ├── Models/              # Eloquent Models (sử dụng Traits HasTenantScope, Auditable)
│   ├── Services/            # Fat Services: Toàn bộ Business logic & Database transactions
│   ├── Enums/               # Backed PHP Enums (UserRole, ClassStatus, InvoiceStatus...)
│   ├── Events/              # Domain Events (EnrollmentCreated, InvoicePaid...)
│   └── Listeners/           # Event Listeners xử lý tự động hóa nền
├── Database/
│   ├── Migrations/          # Database migrations của module
│   └── Seeders/             # Database seeders
└── routes/
    ├── api.php              # API Routes (Prefix /api/v1/< module>)
    └── web.php              # Public Web routes (nếu có Blade views)

3. Mẫu Code Chuẩn theo Quy chuẩn LMS​

3.1. Thin Controller Pattern​

namespace Modules\Academic\App\Http\Controllers;

use App\Http\Controllers\Controller;
use Modules\Academic\App\Http\Requests\CreateClassRequest;
use Modules\Academic\App\Http\Resources\AcademicClassResource;
use Modules\Academic\App\Services\AcademicClassService;
use Modules\Core\App\Traits\ApiResponse;

class AcademicClassController extends Controller
{
    use ApiResponse;

    public function __construct(
        protected AcademicClassService $classService
    ) {}

    public function store(CreateClassRequest $request)
    {
        class = this->classService->createClass($request->validated());
        return $this->success(
            new AcademicClassResource($class),
            'Khởi tạo lớp học thành công',
            201
        );
    }
}

3.2. Fat Service Pattern & Domain Events​

namespace Modules\Academic\App\Services;

use Illuminate\Support\Facades\DB;
use Modules\Academic\App\Models\AcademicClass;
use Modules\Academic\App\Events\ClassCreatedEvent;
use Modules\Core\App\Services\TenantManager;

class AcademicClassService
{
    public function createClass(array $data): AcademicClass
    {
        return DB::transaction(function () use ($data) {
            $data['center_id'] = TenantManager::getCenterId();
            $data['organization_id'] = TenantManager::getOrganizationId();
            
            class = AcademicClass::create(data);
            
            // Tự động sinh danh sách buổi học
            this->generateClassSessions(class, $data['schedule_rules']);
            
            // Phát sự kiện miền để các module khác lắng nghe
            event(new ClassCreatedEvent($class));
            
            return $class->load('sessions', 'teacher');
        });
    }
}

4. Docker CLI Commands​

Tất cả lệnh thao tác Backend BẮT BUỘC thực thi bên trong Docker container:

# Chạy Migration
docker exec -it lms-backend php artisan migrate

# Chạy Seeder dữ liệu mẫu
docker exec -it lms-backend php artisan db:seed

# Xóa cache cấu hình và routes
docker exec -it lms-backend php artisan optimize:clear

# Chạy kiểm thử tự động (Unit / Feature Tests)
docker exec -it lms-backend php artisan test

🔗 Xem thêm​