# Advanced Captcha Plugin для NGCMS

Продвинутая локальная система защиты форм от ботов с несколькими типами капчи. Не требует внешних сервисов.

## 🎯 Возможности

### Типы капчи

1. **Математические примеры**
   - Простые примеры на сложение, вычитание, умножение
   - Числа от 1 до 30
   - Легко для человека, сложно для простых ботов

2. **Текстовая капча**
   - Искаженный текст на canvas
   - Случайные цвета и углы поворота символов
   - Линии помех и шум
   - Можно обновить изображение

3. **Вопросы-ответы**
   - База из 15+ вопросов на общие знания
   - "Сколько дней в неделе?", "Столица России?" и т.д.
   - Легко расширяется новыми вопросами

4. **Checkbox "Я не робот"**
   - Анализ движений мыши
   - Проверка времени взаимодействия
   - Отслеживание траектории курсора
   - Генерация токена безопасности

5. **Слайдер**
   - Перетаскивание ползунка до конца трека
   - Анализ плавности движений
   - Визуальная обратная связь (процент выполнения)
   - Проверка взаимодействий пользователя

### Защита от ботов

- **Honeypot поле** - скрытое поле, которое заполняют только боты
- **Минимальное время** - защита от мгновенной отправки формы
- **Таймаут сессии** - капча действительна ограниченное время
- **Ограничение попыток** - максимум 3 попытки по умолчанию
- **Анализ взаимодействий** - отслеживание движений мыши, кликов, времени
- **Случайный выбор типа** - бот не знает, какая капча появится

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

1. Убедитесь, что установлен плагин `ng-helpers`
2. Скопируйте папку `ng-advanced-captcha` в `engine/plugins/`
3. Активируйте плагин в админ-панели
4. Настройте параметры в разделе "Плагины" → "Advanced Captcha"

## ⚙️ Настройка

### Типы капчи

Включите/выключите нужные типы капчи:

- ✅ Математические примеры
- ✅ Текстовая капча
- ✅ Вопросы-ответы
- ✅ Checkbox "Я не робот"
- ✅ Слайдер

### Основные настройки

- **Только для гостей** - показывать капчу только неавторизованным пользователям
- **Случайный тип** - случайный выбор типа капчи при каждой загрузке
- **Таймаут сессии** - время жизни капчи (60-3600 сек, по умолчанию 300)

### Безопасность

- **Минимальное время** - минимум секунд перед отправкой (по умолчанию 2)
- **Максимум попыток** - количество попыток ввода (по умолчанию 3)
- **Использовать honeypot** - включить скрытое поле-ловушку

## 🎨 Интеграция с темами

Плагин автоматически добавляет виджет капчи в формы. Для ручной интеграции используйте переменную `{{ captcha_widget }}` в шаблонах.

### Пример для формы комментариев:

```twig
<form id="comment" method="post">
    <!-- Поля формы -->

    {{ captcha_widget|raw }}

    <button type="submit">Отправить</button>
</form>
```

## 🔧 Технические детали

### Структура плагина

```
ng-advanced-captcha/
├── src/
│   ├── AdvancedCaptcha.php (основной класс)
│   ├── Types/
│   │   ├── MathCaptcha.php
│   │   ├── TextCaptcha.php
│   │   ├── QuestionCaptcha.php
│   │   ├── CheckboxCaptcha.php
│   │   └── SliderCaptcha.php
│   ├── Filters/
│   │   ├── AdvancedCaptchaCommentsFilter.php
│   │   ├── AdvancedCaptchaCoreFilter.php
│   │   └── AdvancedCaptchaFeedbackFilter.php
│   └── Exceptions/
├── assets/
│   ├── captcha.css
│   └── captcha.js
├── tpl/
│   └── captcha-widget.tpl
└── lang/russian/
```

### Поддерживаемые формы

- ✅ Регистрация пользователей
- ✅ Комментарии
- ✅ Обратная связь (feedback)

### API

Плагин предоставляет внутренние маршруты:

- `?ng_captcha_generate` - генерация новой капчи
- `?ng_captcha_image` - получение изображения для текстовой капчи

## 📊 Логирование

Все проверки капчи логируются:

- Успешные проверки (уровень `info`)
- Неудачные попытки (уровень `warning`)
- Обнаружение ботов (уровень `warning`)
- Ошибки (уровень `error`)

## 🔐 Безопасность

Плагин использует несколько уровней защиты:

1. **Серверная валидация** - все проверки на стороне сервера
2. **Сессии PHP** - данные хранятся в $\_SESSION
3. **Токены безопасности** - для checkbox и slider
4. **Анализ поведения** - отслеживание взаимодействий
5. **Honeypot** - ловушка для простых ботов
6. **Временные ограничения** - минимальное время и таймауты

## 🆚 Преимущества перед стандартной капчей

| Характеристика        | Стандартная капча | Advanced Captcha                           |
| --------------------- | ----------------- | ------------------------------------------ |
| Типы проверок         | 1 (цифры)         | 5 (math, text, question, checkbox, slider) |
| Случайный выбор       | Нет               | Да                                         |
| Honeypot              | Нет               | Да                                         |
| Анализ поведения      | Нет               | Да (движения, время, клики)                |
| Ограничение попыток   | Нет               | Да                                         |
| Таймаут сессии        | Нет               | Да                                         |
| Минимальное время     | Нет               | Да                                         |
| Визуальное оформление | Базовое           | Современное (CSS3)                         |
| Логирование           | Нет               | Подробное                                  |

## 📝 Расширение

### Добавление новых вопросов

Отредактируйте `src/Types/QuestionCaptcha.php`:

```php
protected $questions = [
    ['q' => 'Ваш вопрос?', 'a' => 'ответ'],
    // ...
];
```

### Создание нового типа капчи

1. Создайте класс в `src/Types/YourCaptcha.php`
2. Реализуйте методы `generateChallenge()` и `getAnswer()`
3. Добавьте шаблон в `tpl/`
4. Зарегистрируйте в `AdvancedCaptcha.php`

## 🐛 Отладка

Для отладки проверьте логи:

```bash
tail -f engine/cache/logs/plugins.log
```

## 📋 Требования

- NGCMS 1.0.0+
- PHP 7.4+
- Плагин ng-helpers
- Включенные сессии PHP

## 🤝 Вклад

Если вы хотите добавить новые типы капчи или улучшения - welcome!

## 📄 Лицензия

MIT License - см. файл LICENSE

## 👥 Автор

NGCMS Team - https://ngcms.ru

---

**Примечание**: Плагин полностью локальный и не отправляет данные на внешние сервисы. Все проверки выполняются на вашем сервере.
