# ВДНХ Афиша API (Тестовое задание)

Бэкенд-приложение для фильтрации и вывода афиши событий Выставки (ВДНХ) на основе предоставленного технического задания.

## 🛠 Стек технологий
- **PHP:** 8.2 / 8.3
- **Framework:** Laravel 12.x
- **Database:** MySQL / PostgreSQL
- **API Specification:** Postman (коллекция в корне проекта)

---

## 📋 Постановка задачи
Разработать JSON API для Афиши событий (https://vdnh.ru/) со следующими требованиями:
1. Метод API для фильтрации событий по нескольким категориям и промежутку дат.
2. Реализация пагинации для списка событий.
3. Наличие сидеров (Database Seeding) для наполнения тестовыми данными.
4. Публикация на GitHub + предоставление коллекции для Postman.

## 🚀 Развертывание проекта

Выполните последовательно следующие команды в терминале:

1. **Клонирование репозитория и установка зависимостей:**
   ```bash
   composer install
   ```

2. **Настройка окружения:**
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```
   *Отредактируйте файл `.env`, указав ваши доступы к базе данных (`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`).*

3. **Миграции и наполнение базы (Сидинг):**
   ```bash
   php artisan migrate:fresh --seed
   ```
   > 💡 **Что произойдет:** Команда полностью пересоздаст структуру БД и запустит сидеры, которые сгенерируют **11 реальных категорий** и **40 тестовых событий** со случайными датами для удобной проверки фильтрации.

4. **Пользователи:**
   - В базе уже есть сгенерирован "test@example.com" с паролем "password".
   - Чтобы использовать другие методы, находящиеся под защитой Sanctum, необходимо вызвать метод [/api/login](#1. Авторизация (Получение токена)) и получить токен, который сохранится в переменную token в [POSTMAN](#Тестирование в Postman).
   - Для генерации нового пользователя или изменения его пароля/токена можно воспользоваться консольными командами, описанными ниже.

## 💻 Консольные команды (CLI)

Для удобства управления пользователями и токенами добавлены кастомные Artisan-команды:

1. **Создание пользователя и генерация API-токена:**
   ```bash
   php artisan user:create-api-user "Ivan Ivanov" ivan@example.com "secret123"
   ```
   *Команда регистрирует нового пользователя в базе данных и сразу генерирует для него первый Sanctum-токен.*

2. **Сброс пароля и выдача нового токена:**
   ```bash
   php artisan user:reset-password ivan@example.com "new_secret123"
   ```
   *Команда находит пользователя по email, обновляет его пароль и выводит в консоль новый рабочий Sanctum-токен.*


## 📡 Документация API (Эндпоинты)

*Для всех запросов обязательно передавайте заголовки:*
- `Accept: application/json`
- `Content-Type: application/json`

### 1. Авторизация (Получение токена)

*   **URL:** `/api/login`
*   **Метод:** `POST`

#### Тело запроса (JSON):
```json
{
    "email": "user@example.com",
    "password": "your_password"
}
```

### 2. Выход из системы (Logout)
*   **URL:** `/api/logout`
*   **Метод:** `POST`
*   **Описание:** Деактивирует и удаляет текущий API-токен Sanctum, с которым был выполнен запрос. Заговоловок Authorization c токеном обязателен.

---

*В ответе возвращаются  данные пользователя и его `access_token` для авторизации в защищенных эндпоинтах.*

### 2. Получение списка событий с фильтрацией и пагинацией

*   **URL:** `/api/gigs`
*   **Метод:** `GET`
*   **Описание:** для метода необходим заголовок Authorization: Bearer {{token}}, который можно получить методом /login.

#### Параметры запроса (Query Parameters):
| Параметр | Тип | Обязательный | Описание | Пример / Значение |
| :--- | :--- | :--- | :--- | :--- |
| `categories` | `array` | Нет | Массив ID или слагов категорий | `categories[]=1&categories[]=2` |
| `date_from` | `string` | Нет | Начало диапазона дат (`YYYY-MM-DD`) | `2026-05-01` |
| `date_to` | `string` | Нет | Конец диапазона дат (`YYYY-MM-DD`) | `2026-05-31` |
| `page` | `integer` | Нет | Номер страницы пагинации | `2` |
| `per_page` | `integer` | Нет | Количество элементов на страницу | `15` *(По умолчанию: `10`)* |


#### Пример запроса:
`GET /api/gigs?categories[]=1&categories[]=4&date_from=2026-02-01&date_to=2026-05-31`

---

## 🧪 Тестирование в Postman

В корне репозитория находится файл коллекции для быстрого тестирования всех эндпоинтов: **`gigs_api_collection.json`**.