📖 HƯỚNG DẪN PHÁT TRIỂN DỰ ÁN

Công nghệ sử dụng

• Framework: Laravel 12
• Database: MySQL
• Authentication: JWT (tymon/jwt-auth)
• API: RESTful API cho Mobile App (Flutter)
• Web: Admin Panel + Public Website

Kiến trúc

• Service Pattern: Tất cả business logic đặt trong Services, Controllers chỉ gọi Services
• Response Format: Thống nhất format response cho tất cả API
• i18n: Hỗ trợ đa ngôn ngữ (Tiếng Việt và Tiếng Anh)

Cấu trúc hoàn chỉnh

LVTN_BE/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Api/              # API Controllers cho Mobile
│   │   │   ├── Admin/            # Admin Controllers
│   │   │   ├── Partner/          # Partner Controllers
│   │   │   └── Web/              # Public Web Controllers
│   │   ├── Middleware/
│   │   ├── Requests/             # Form Requests
│   │   ├── Resources/            # API Resources
│   │   └── Traits/
│   ├── Models/
│   ├── Services/                 # Service Layer
│   ├── Helpers/                  # Helper Classes
│   └── Providers/
├── bootstrap/
├── config/
├── database/
│   ├── migrations/
│   └── seeders/
├── doc/
│   ├── api/                      # API Documentation (Markdown)
│   ├── html/                     # API Documentation (HTML)
│   └── task/                     # Task Documentation
├── resources/
│   ├── lang/
│   └── views/
├── routes/
│   ├── api.php
│   └── web.php
└── ...

Mô tả các thư mục chính

• app/Http/Controllers/Api/: Controllers cho Mobile App API
• app/Http/Controllers/Admin/: Controllers cho Admin Panel
• app/Http/Controllers/Partner/: Controllers cho Partner Dashboard
• app/Http/Controllers/Web/: Controllers cho Public Website
• app/Http/Resources/: API Resources để format dữ liệu trả về
• app/Http/Middleware/: Custom Middleware
• app/Http/Requests/: Form Request Validation
• app/Services/: Business Logic Layer
• app/Models/: Eloquent Models
• app/Helpers/: Helper Classes
• doc/api/: API Documentation (Markdown) - File gốc
• doc/html/: API Documentation (HTML) - File HTML được convert từ Markdown để hiển thị trên web
• doc/task/: Task Documentation
• resources/lang/: i18n files

Schema chính

Database schema được định nghĩa trong file b.sql. Các bảng chính:

1. Phân quyền

• roles - Vai trò (admin, partner, customer)
• permissions - Quyền hạn
• role_permissions - Phân quyền cho từng role
• users - Người dùng (có role_id, avatar_id)

2. Media System

• media_folders - Thư mục media
• media_files - File media (ảnh, video)

3. Core Business

• movies - Phim
• cinemas - Rạp chiếu phim
• rooms - Phòng chiếu
• seats - Ghế ngồi
• showtimes - Suất chiếu
• bookings - Đặt vé
• booking_seats - Ghế đã đặt

4. Reviews & Favorites

• reviews - Đánh giá phim
• favorite_movies - Phim yêu thích

5. Vouchers

• vouchers - Mã giảm giá

Quy tắc khi tạo Migration

Ví dụ Migration đúng chuẩn

Schema::create('showtimes', function (Blueprint $table) {
    $table->id();
    $table->foreignId('movie_id')->constrained()->onDelete('restrict');
    $table->foreignId('room_id')->constrained()->onDelete('restrict');
    $table->date('date');
    $table->time('start_time');
    $table->time('end_time');
    $table->decimal('price', 10, 2);
    $table->enum('status', ['scheduled', 'ongoing', 'completed', 'cancelled'])->default('scheduled');
    $table->timestamps();
    $table->softDeletes();
    
    // Indexes BẮT BUỘC
    $table->index('movie_id');
    $table->index('room_id');
    $table->index('date');
    $table->index('status');
    $table->index(['date', 'start_time']);
    $table->index(['movie_id', 'date']);
    $table->index('deleted_at');
    
    // UNIQUE constraint
    $table->unique(['room_id', 'date', 'start_time']);
});

Headers bắt buộc

Middleware Order

Thứ tự middleware áp dụng:

LanguageMiddleware → ApiKeyMiddleware → JWT → Role → Permission

Format thống nhất

Response thành công:

{
  "success": true,
  "code": "USER_CREATED_SUCCESS",
  "message": "User created successfully",
  "data": {
    "id": 10,
    "name": "Nguyễn Văn A"
  }
}

Response lỗi:

{
  "success": false,
  "code": "EMAIL_EXISTS",
  "message": "The email has already been taken",
  "errors": {
    "email": "This email is already in use"
  }
}

Quy tắc

1. Luôn có code: Cả success và error đều phải có code
2. Message theo ngôn ngữ: Lấy từ resources/lang/{locale}/errors.php hoặc success.php
3. Không dùng text tự do: Tất cả message phải định nghĩa trong file lang

API Resources

• Đặt trong app/Http/Resources/
• Mỗi Model có 1 Resource tương ứng
• Resource format dữ liệu trước khi trả về

Ví dụ Resource

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'phone' => $this->phone,
            'address' => $this->address,
            'role' => new RoleResource($this->whenLoaded('role')),
            'avatar' => new MediaFileResource($this->whenLoaded('avatar')),
            'created_at' => $this->created_at?->toDateTimeString(),
            'updated_at' => $this->updated_at?->toDateTimeString(),
        ];
    }
}

Sử dụng trong Controller

use App\Http\Traits\ApiResponseTrait;
use App\Http\Resources\UserResource;

class AuthController extends Controller
{
    use ApiResponseTrait;
    
    public function register(Request $request)
    {
        // ... logic tạo user
        
        return $this->successResponse(
            'USER_CREATED_SUCCESS',
            new UserResource($user),
            'User created successfully'
        );
    }
    
    public function me()
    {
        $user = auth()->user();
        $user->load(['role', 'avatar']); // Eager load relationships
        
        return $this->successResponse(
            'USER_FETCHED_SUCCESS',
            new UserResource($user),
            'User fetched successfully'
        );
    }
}

Nguyên tắc

Cấu trúc thư mục

app/Services/
├── Auth/
│   └── AuthService.php
├── Movie/
│   ├── MovieService.php
│   └── MovieSearchService.php
├── Booking/
│   ├── BookingService.php
│   └── BookingValidationService.php
├── Cinema/
│   ├── CinemaService.php
│   ├── RoomService.php
│   └── SeatService.php
└── ...

Quy tắc viết Service

1. Service trực tiếp làm việc với Model (không dùng Repository pattern)
2. Mỗi Service class chỉ xử lý 1 domain cụ thể
3. Service methods phải có tên rõ ràng, mô tả đúng chức năng
4. Service trả về data, không trả về Response

Ví dụ Service

namespace App\Services\Movie;

use App\Models\Movie;
use Illuminate\Support\Facades\DB;

class MovieService
{
    public function getAllMovies(array $filters = [])
    {
        $query = Movie::query();
        
        if (isset($filters['status'])) {
            $query->where('status', $filters['status']);
        }
        
        if (isset($filters['search'])) {
            $query->where('title', 'like', '%' . $filters['search'] . '%');
        }
        
        return $query->with(['poster', 'trailer'])->paginate(15);
    }
    
    public function createMovie(array $data): Movie
    {
        return DB::transaction(function () use ($data) {
            return Movie::create($data);
        });
    }
}

1. Models

Relationships

• Định nghĩa đầy đủ relationships
• Sử dụng $fillable, $casts, $hidden phù hợp
• Eager loading để tránh N+1 queries

2. Controllers

Quy tắc

• Chỉ gọi Service, không có business logic
• Sử dụng ApiResponseTrait để trả về response
• Validation sử dụng Form Requests
• Tên method rõ ràng: index, store, show, update, destroy

3. Form Requests

Validation

• Tạo Form Request cho các endpoint quan trọng
• Validation rules rõ ràng
• Custom messages nếu cần

4. Middleware

Đăng ký Middleware trong Config Files

// config/api.php
return [
    'middleware' => [
        'api.key' => \App\Http\Middleware\ApiKeyMiddleware::class,
    ],
];

// config/api.php
use App\Http\Middleware\ApiKeyMiddleware;

return [
    'middleware' => [
        'api.key' => ApiKeyMiddleware::class,
    ],
];

Quy tắc:

• Luôn dùng use statement ở đầu file config
• Sử dụng class name thay vì full namespace string
• Code rõ ràng, dễ đọc và maintain hơn

API Documentation

Task Documentation

Sau khi hoàn thành 1 task, ghi lại trong doc/task/:

Format: YYYY-MM-DD-[tên-task].md

Ví dụ: 2024-01-15-implement-authentication-api.md

• Tạo Migration với đầy đủ indexes
• Tạo Model với relationships đầy đủ
• Tạo API Resource trong app/Http/Resources/ để format dữ liệu
• Tạo Service với business logic
• Tạo Controller sử dụng Service và Resource
• Tạo Form Request cho validation (nếu cần)
• Sử dụng ApiResponseTrait cho response
• Message lấy từ file lang (errors.php/success.php)
• Eager load relationships trước khi trả về Resource
• Đăng ký routes với middleware phù hợp
• Viết API documentation trong doc/api/ (theo format chuẩn với bảng Request Parameters và Response Fields)
• Convert documentation sang HTML và lưu vào doc/html/ (dark theme, format đẹp)
• Test API với Postman
• Ghi lại task trong doc/task/ (theo format chuẩn)
• Nếu có gửi email: Truyền locale từ Controller → Service → Mail, set locale trong email view

• Code bằng tiếng Anh trực tiếp trong Blade
• Sử dụng __('Text') để dịch (chuẩn Laravel)
• Thêm bản dịch vào resources/lang/vi/vi.json và resources/lang/en/en.json nếu cần
• Sử dụng use statement trong config files, không dùng full namespace string
• Test với cả 2 locale (en và vi)

• Laravel Documentation: https://laravel.com/docs
• JWT Auth: https://jwt-auth.readthedocs.io/
• Database Schema: Xem file b.sql

1. Luôn tập trung vào vấn đề chính, tránh viết code lan man
2. Tái sử dụng code qua Service pattern
3. Thống nhất format response cho tất cả API
4. Viết documentation sau mỗi API
5. Test kỹ trước khi commit