# =========================================================================== #
# NG CMS // Плагин "Автоматическая генерация ключевых слов" (AutoKeys)      #
# =========================================================================== #

## Что это такое?

Плагин автоматически извлекает ключевые слова из текста новости для заполнения
мета-тега keywords. Использует морфологический анализ для приведения слов к
начальной форме и подсчитывает частоту употребления.

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

✓ Автоматическое извлечение ключевых слов из заголовка и содержимого новости
✓ Морфологический анализ с помощью библиотеки Morphos (склонение к именительному падежу)
✓ Фильтрация стоп-слов (предлоги, союзы, частицы)
✓ Настройка минимальной/максимальной длины слов
✓ Настройка минимальной частоты встречаемости
✓ Приоритетные слова (всегда включаются в список)
✓ Черный список слов (всегда исключаются)
✓ Автоматическая активация при добавлении/редактировании новостей
✓ Логирование через ng-helpers для отслеживания работы

## Установка

1. Активируйте плагин в админ-панели
2. Откройте форму добавления/редактирования новости
3. Установите галочку "Автоматически сгенерировать ключевые слова"
4. Сохраните новость - ключевые слова будут сгенерированы автоматически

## Настройки в админ-панели

### Основные параметры

**Минимальная длина слова (символов)**
- По умолчанию: 5
- Рекомендуется: 4-6
- Слова короче будут игнорироваться (предлоги, союзы обычно короткие)

**Максимальная длина слова (символов)**
- По умолчанию: 100
- Рекомендуется: 20-30
- Защита от склеенных слов и мусора

**Минимальная частота встречаемости**
- По умолчанию: 2
- Рекомендуется: 2-3
- Слово должно встретиться в тексте не менее N раз, чтобы попасть в ключевые

**Количество ключевых слов**
- По умолчанию: 10
- Рекомендуется: 10-15
- Максимальное количество ключевых слов в результате

**Добавлять заголовок N раз**
- По умолчанию: 0 (не добавлять)
- Рекомендуется: 2-3
- Увеличивает вес слов из заголовка в общем списке ключевых слов

### Автоактивация

**Активировать при добавлении новости**
- Да - галочка "Сгенерировать ключевые слова" будет установлена по умолчанию
- Нет - пользователь должен сам ставить галочку

**Активировать при редактировании новости**
- Да - галочка будет установлена при открытии формы редактирования
- Нет - галочка не будет установлена

### Приоритетные слова

**Использовать список приоритетных слов**
- Да - слова из списка всегда будут в начале ключевых слов
- Нет - игнорировать список

**Список приоритетных слов**
Одно слово на строку. Эти слова всегда включаются в ключевые, независимо от частоты.

Пример:
```
технологии
разработка
программирование
дизайн
```

### Черный список

**Использовать черный список слов**
- Да - слова из списка будут исключены из ключевых
- Нет - игнорировать список

**Черный список слов**
Одно слово на строку. Эти слова никогда не попадут в ключевые слова.

Пример:
```
новость
сегодня
вчера
сказал
рассказал
```

### Источник шаблонов
- Из темы сайта - использует шаблоны из templates/[тема]/autokeys/
- Из плагина - использует встроенные шаблоны

## Как работает алгоритм

1. **Очистка текста**
   - Удаление HTML-тегов
   - Декодирование HTML-сущностей (&nbsp; → пробел)
   - Приведение к нижнему регистру
   - Удаление спецсимволов и лишних пробелов

2. **Разбивка на слова**
   - Текст разбивается по пробелам
   - Каждое слово проверяется на длину (min/max)

3. **Фильтрация**
   - Исключаются числа и слова, начинающиеся с цифры
   - Исключаются стоп-слова (предлоги, союзы, частицы)
   - Исключаются слова из черного списка

4. **Морфологический анализ**
   - С помощью Morphos слово приводится к именительному падежу единственного числа
   - Пример: "технологиями" → "технология", "разработчиков" → "разработчик"
   - Если слово не склоняется, используется исходная форма

5. **Подсчет частоты**
   - Подсчитывается, сколько раз каждое слово встречается в тексте
   - Слова с частотой < min_occur исключаются

6. **Сортировка и ограничение**
   - Слова сортируются по частоте (от частых к редким)
   - Приоритетные слова добавляются в начало списка
   - Берутся первые N слов согласно настройке "Количество ключевых слов"

7. **Форматирование результата**
   - Слова объединяются через запятую с пробелом
   - Результат записывается в поле keywords новости

## Встроенные стоп-слова

Плагин автоматически исключает следующие стоп-слова:

```
это, как, так, для, что, или, его, все, уже, был, быть, она, при, даже,
если, под, еще, ещё, может, мне, вас, нас, они, тот, эта, эти, тем, чем,
без, где, над, про, раз, там, зачем, потом, того, чтобы, можно, было, были,
будет, была, этот, этой, этом, этих, через, после, перед, между, около,
более, менее, очень, также, тоже, только, лишь, ведь, вот, вообще, всегда
```

Вы можете дополнить этот список через "Черный список слов" в настройках.

## Примеры использования

### Пример 1: Техническая статья

**Исходный текст:**
```
Новые технологии искусственного интеллекта позволяют создавать продвинутые
системы машинного обучения. Разработчики используют нейронные сети для
анализа больших данных. Нейронные сети показывают отличные результаты в
задачах распознавания образов.
```

**Сгенерированные ключевые слова:**
```
нейронные сети, технологии, искусственный интеллект, машинное обучение,
разработчики, данные, анализ, распознавание, система
```

### Пример 2: С приоритетными словами

**Настройки:**
- Приоритетные слова: `технологии`, `разработка`

**Результат:**
```
технологии, разработка, нейронные сети, искусственный интеллект,
машинное обучение, анализ, данные
```

### Пример 3: С увеличением веса заголовка

**Заголовок:** "Искусственный интеллект в медицине"
**Настройка:** Добавлять заголовок 3 раза

Слова "искусственный", "интеллект", "медицина" встретятся в тексте +3 раза,
что повысит их приоритет при сортировке по частоте.

## Интеграция с ng-helpers

Плагин использует функции из ng-helpers v0.2.0:
- `logger()` - логирование операций и времени выполнения
- `sanitize()` - очистка входных данных
- `cache_get()` / `cache_put()` - (готов к использованию кэша)

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

При включенном логировании ng-helpers записываются события:
- Инициализация парсера: длина текста, настройки
- Извлечение ключевых слов: количество, время выполнения
- Финальный результат: количество и длина строки

Пример лога:
```
[autokeys] AutoKeyword init: length=1500 chars, minLen=5, maxLen=100
[autokeys] parse_words: extracted 12 keywords, time=45.23ms
[autokeys] Add news: generated 10 keywords
```

## Производительность

**Оптимизации:**
- Использование mb_strlen() вместо strlen() для Unicode
- Минимальное количество регулярных выражений
- Освобождение памяти после обработки (unset)
- Логирование времени выполнения для мониторинга

**Типичное время обработки:**
- Текст 500 слов: ~20-40 мс
- Текст 1000 слов: ~40-80 мс
- Текст 2000 слов: ~80-150 мс

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

- **NG CMS:** 0.9.2+
- **PHP:** 7.0+ (для Morphos требуется PHP 7.0+)
- **Библиотека:** Morphos (включена в плагин)
- **ng-helpers:** 0.2.0+ (опционально, но рекомендуется для логирования)
- **Расширение:** mbstring (для корректной работы с UTF-8)

## Известные ограничения

1. Морфология работает только для русского языка
2. Составные слова могут обрабатываться некорректно
3. Имена собственные приводятся к нарицательным формам
4. Аббревиатуры и англицизмы могут пропускаться

## Рекомендации по настройке

**Для новостного сайта:**
- Минимальная длина: 4
- Минимальная частота: 2
- Количество слов: 10-12
- Добавлять заголовок: 2-3 раза

**Для технического блога:**
- Минимальная длина: 5
- Минимальная частота: 2
- Количество слов: 12-15
- Добавлять заголовок: 3 раза
- Использовать приоритетные слова для терминов

**Для SEO-оптимизации:**
- Количество слов: не более 10-12 (Google рекомендует)
- Использовать приоритетные слова для целевых запросов
- Добавлять заголовок 2-3 раза для повышения релевантности

## Поддержка

Версия: 2.0 (с ng-helpers и Morphos)
Совместимость: NG CMS 0.9.2+

По вопросам работы плагина обращайтесь на форум https://ngcms.org
