# Madagascar Tours - Backend API & CMS

Полнофункциональный PHP backend для туристического агентства "Madagascar Tours" с REST API, CMS и админ-панелью.

## 📋 Архитектура

```
backend/
├── src/
│   ├── api/              # REST API контроллеры
│   ├── admin/            # Админ-панель контроллеры
│   ├── models/           # Модели данных
│   ├── controllers/      # Бизнес-логика
│   ├── middleware/       # Middleware (Auth, CORS и т.д.)
│   ├── config/           # Конфигурация (DB, Settings)
│   ├── database/         # Миграции БД
│   └── utils/            # Утилиты (Response, Validation и т.д.)
├── public/
│   ├── index.php         # API entry point
│   └── .htaccess         # URL rewriting
├── storage/
│   ├── uploads/          # Загруженные файлы
│   └── temp/             # Временные файлы
├── composer.json         # PHP зависимости
└── openapi.yaml          # API документация
```

## 🗄️ База данных

### Основные таблицы:

- **users** - Пользователи админ-панели (admin, editor)
- **tours** - Туры с SEO и метаданными
- **tour_schedules** - Расписание туров с доступными местами
- **news** - Новости с категориями
- **articles** - Внутренние статьи (не выводятся на сайте)
- **pages** - Статические страницы (About, Contact и т.д.)
- **categories** - Категории для туров, новостей, статей
- **menu** - Навигационное меню с поддержкой иерархии
- **sliders** - Слайдеры для страниц
- **settings** - Глобальные настройки сайта
- **files** - Файловый менеджер с метаданными
- **bookings** - Бронирования туров от клиентов
- **audit_logs** - Журнал всех действий админов

## 🔌 REST API Endpoints

### Туры
```
GET    /api/v1/tours              - Получить все туры
GET    /api/v1/tours/{slug}       - Получить тур по slug
GET    /api/v1/tours/region/{name} - Получить туры по регионам
POST   /api/v1/tours              - Создать тур (admin)
PUT    /api/v1/tours/{id}         - Обновить тур (admin)
DELETE /api/v1/tours/{id}         - Удалить тур (admin)
```

### Новости
```
GET    /api/v1/news               - Получить все новости
GET    /api/v1/news/{slug}        - Получить новость по slug
POST   /api/v1/news               - Создать новость (admin)
PUT    /api/v1/news/{id}          - Обновить новость (admin)
DELETE /api/v1/news/{id}          - Удалить новость (admin)
```

### Страницы
```
GET    /api/v1/pages/{slug}       - Получить страницу
```

### Меню
```
GET    /api/v1/menu               - Получить меню навигации
```

### Настройки
```
GET    /api/v1/settings           - Получить настройки сайта
PUT    /api/v1/settings           - Обновить настройки (admin)
```

### Бронирования
```
POST   /api/v1/bookings           - Создать бронирование
GET    /api/v1/bookings           - Получить бронирования (admin)
PUT    /api/v1/bookings/{id}      - Обновить статус (admin)
```

### Файлы
```
GET    /api/v1/files              - Получить файлы (admin)
POST   /api/v1/files              - Загрузить файл (admin)
DELETE /api/v1/files/{id}         - Удалить файл (admin)
```

### Аутентификация
```
POST   /api/v1/auth/login         - Вход в админ-панель
POST   /api/v1/auth/logout        - Выход
GET    /api/v1/auth/me            - Информация о текущем пользователе
```

## 🚀 Установка

### Requirements
- PHP 7.4+ или 8.0+
- MySQL 5.7+
- Composer

### Шаги установки

1. **Клонировать репозиторий**
```bash
git clone <repo>
cd madagascar-tours/backend
```

2. **Установить зависимости**
```bash
composer install
```

3. **Создать базу данных**
```sql
# Импортировать SQL схему
mysql -u root -p < src/database/migrations/001_init_schema.sql
```

4. **Настроить конфиг** (если требуется)
- Отредактировать `src/config/Config.php`
- Установить переменные окружения (DB_HOST, DB_NAME и т.д.)

5. **Запустить локальный сервер**
```bash
composer serve
# API будет доступен на: http://localhost:8000/api/v1
```

## 📚 API Документация

OpenAPI/Swagger документация доступна в файле `openapi.yaml`

Для просмотра:
1. Скопировать содержимое `openapi.yaml`
2. Открыть [Swagger Editor](https://editor.swagger.io/)
3. Вставить содержимое

## 🔐 Аутентификация

API использует JWT (JSON Web Tokens) для защиты админ endpoints.

### Получить токен:
```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@madagascar-tours.com",
    "password": "admin123"
  }'
```

### Использовать токен:
```bash
curl http://localhost:8000/api/v1/tours \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 📦 Встраивание в фронтенд

Фронтенд приложение (в папке `frontend/`) обращается к API только через HTTP запросы.

Пример на JavaScript:
```javascript
// Получить все туры
fetch('http://localhost:8000/api/v1/tours')
  .then(res => res.json())
  .then(data => console.log(data.data));

// Получить конкретный тур
fetch('http://localhost:8000/api/v1/tours/diego-suarez-getaway')
  .then(res => res.json())
  .then(data => console.log(data.data));

// Создать бронирование
fetch('http://localhost:8000/api/v1/bookings', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Doe',
    email: 'john@example.com',
    tour_id: 1,
    adults: 2,
    children: 1
  })
})
.then(res => res.json())
.then(data => console.log(data));
```

## 🔒 CORS конфигурация

API автоматически обрабатывает CORS для разрешённых источников:
- http://localhost:5500 (фронтенд)
- http://localhost:8000-8001 (локальная dev)

Для добавления новых источников отредактировать `src/config/Config.php`:
```php
public const ALLOWED_ORIGINS = [
    'http://localhost:5500',
    'https://your-frontend-domain.com'
];
```

## 📝 Примеры ответов API

### Успешный ответ (200):
```json
{
  "success": true,
  "message": "Tours retrieved successfully",
  "data": [
    {
      "id": 1,
      "title": "Diego Suarez Getaway",
      "slug": "diego-suarez-getaway",
      "price": 299,
      "duration_days": 5,
      "region": "north",
      "is_active": true
    }
  ]
}
```

### Ошибка валидации (422):
```json
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "email": "Email is required",
    "adults": "Adults must be at least 1"
  }
}
```

### Ошибка авторизации (401):
```json
{
  "success": false,
  "message": "Unauthorized"
}
```

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

```bash
# Запустить тесты
composer test

# С coverage
vendor/bin/phpunit --coverage-html ./coverage
```

## 🛠️ Следующие шаги

- [ ] Внедрить полную CRUD логику для всех эндпоинтов
- [ ] Написать модели данных (Tour, News, Page и т.д.)
- [ ] Добавить валидацию входных данных
- [ ] Внедрить систему кэширования
- [ ] Добавить систему ролей и прав доступа
- [ ] Создать админ-панель на Vue.js или React
- [ ] Добавить логирование и мониторинг
- [ ] Написать юнит-тесты

## 📞 Контакты

Поддержка: support@madagascar-tours.com

## 📄 Лицензия

MIT License