Code Structure (Cấu Trúc Mã Nguồn)#
Dự án được phân chia rạch ròi độc lập: ** Backend (api). Mỗi phần tuân thủ nghiêm ngặt các tiêu chuẩn cấu trúc (Scaffold) của Framework tương ứng, kết hợp với các Design Pattern hiện đại nhằm đảm bảo tính dễ đọc, dễ bảo trì và mở rộng (Scalability).
1. Cấu Trúc Backend (api)#
Hệ thống Backend sử dụng bộ khung chuẩn của Laravel Framework 10 (PHP >= 8.1). Điểm nhấn trong kiến trúc là việc áp dụng Repository Pattern nhằm tách biệt khối Logic truy vấn cơ sở dữ liệu ra khỏi Controller.Cây thư mục tổng quan:#
api/
├── app/
│ ├── Console/Commands/ # Chứa các class của Artisan Job (ví dụ: tiến trình Scan Ranking)
│ ├── Http/
│ │ ├── Controllers/ # Điều hướng Request / Response, mapping Swagger UI tags
│ │ └── Middleware/ # Lớp khiên chặn (Intercept) kiểm tra Auth & quyền hạn RBAC
│ ├── Libraries/ # Chứa các Common Utils Services (ví dụ: logging...)
│ ├── Models/ # Tầng Eloquent ORM Model (Domain, Keyword, Proxy...)
│ └── Repositories/ # Tầng trừu tượng (Abstract layer) chuyên xử lý Query dữ liệu
├── config/ # Tệp cấu hình hệ thống (CORS, l5-swagger, horizon, queue...)
├── database/
│ ├── migrations/ # Cấu trúc lịch sử khởi tạo các file schema database tables
│ └── seeders/ # Sinh dữ liệu mẫu (Dummy data) cho quá trình dev mới install
├── routes/
│ ├── api.php # Nơi định nghĩa toàn bộ root Endpoints URL của Backend API
│ └── console.php # Entry point cho các cron-task scheduler queue
└── composer.json # Quản lý thư viện PHP dependencies (Jwt-auth, Elasticsearch...)
Chú thích các thành phần quan trọng:#
app/Repositories/: Thay vì viết thẳng câu lệnh Database Query trong Controller, toàn bộ truy vấn được gom vào tầng Repository. Điều này giúp Controller cực kỳ mỏng và dễ dàng maintain.
app/Console/Commands/: Hệ thống cào dữ liệu (Crawler) và check proxy đòi hỏi chạy ngầm liên tục. Mã nguồn thực thi các tác vụ nặng nề này không nằm ở Controller mà được thiết kế thành các Command Class riêng biệt tại đây để Horizon/Worker xử lý.
Modified at 2026-03-30 11:46:30