# Похожие материалы

Модуль `related` подбирает для текущего документа другие опубликованные
документы. Он подходит не только товарам: профили можно настроить отдельно для
новостей, статей, записей блога, справочных страниц и любых собственных рубрик.

Модуль не навязывает карточку. Результат выводится собственными HTML-шаблонами
профиля либо передаётся в существующий запрос AVE.cms, где продолжают работать
обычные шаблоны полей и карточек сайта.

## Быстрый старт

1. Установите модуль и откройте **Модули → Похожие материалы**.
2. На вкладке **Индекс** нажмите **Переиндексировать**.
3. Откройте созданный профиль `default` и выберите стратегию и рубрики.
4. Вставьте в шаблон рубрики, документ или блок:

```text
[mod_related:default]
```

5. Откройте реальный документ, содержащий ключевые слова или теги, и проверьте
   результат.

После начального построения индекс обновляется автоматически при сохранении и
удалении документа. Повторная полная индексация нужна после массового импорта
напрямую в БД или изменения правил уже у большого числа документов.

## Стратегии

| Стратегия | Как выбираются документы |
| --- | --- |
| Релевантность | По общим ключевым словам, тегам и, если включено, словам заголовка. |
| Кольцо | Следующие документы в заданном порядке; в конце списка подбор продолжается с начала. |
| Гибрид | Сначала релевантные документы, затем недостающее количество добирается кольцом. |

Активные ручные связи всегда идут первыми, если в профиле включено **Учитывать
ручные связи**. Они занимают места в общем лимите и не дублируются в
автоматической части результата.

### Релевантность и веса

Индекс хранит три независимых источника:

| Источник | Что индексируется | Когда полезен |
| --- | --- | --- |
| Ключевые слова | Фразы из `document_meta_keywords`, разделённые запятой, точкой с запятой или новой строкой. | Редактор явно описывает тему документа. |
| Теги | Значения `document_tags`. | На сайте уже есть единый тематический словарь. |
| Заголовок | Значимые слова длиной от четырёх символов после нормализации. | Ключевые слова и теги заполнены не у всех документов. |

Вес задаёт относительную силу источника от `1` до `20`. При совпадении источника
текущего документа и источника кандидата веса перемножаются. Например,
совпадение двух ключевых фраз с весом `8` сильнее случайного общего слова
заголовка с весом `2`.

Заголовок по умолчанию выключен: общие слова могут давать шум. Его разумно
включать для старого контента, где ключевые слова и теги заполнены не полностью.

### Кольцевой подбор

Кольцо не выбирает случайные документы. Оно идёт от текущего документа дальше
по одному из стабильных порядков:

- **Позиция документа** — ручная позиция, затем дата и ID;
- **Дата публикации** — от новых материалов к старым;
- **ID документа** — порядок создания.

Когда список заканчивается, модуль продолжает с его начала. Текущий документ и
уже выбранные записи исключаются. Такой режим заменяет старый кольцевой
системный блок и полезен для «Следующих материалов» или равномерной перелинковки.

## Область профиля

Пустой список рубрик разрешает в результате документы любых типов. Выбранные
рубрики ограничивают только похожие материалы, а исходный документ может
относиться к другой рубрике. Например, профиль с рубрикой «Статьи» можно
вставить в шаблон категории каталога и получать только полезные статьи.

Переключатель **Только текущая рубрика** дополнительно требует, чтобы кандидат
принадлежал той же рубрике, что и открытый документ. Это удобно для новостной
ленты. Для рекомендаций между разными типами контента оставьте его выключенным.

В подбор никогда не попадают текущий документ, удалённые, выключенные, ещё не
опубликованные и уже просроченные документы, а также системная страница 404.

## Ручные связи

На вкладке **Ручные связи** выбираются:

1. профиль;
2. исходный документ, на странице которого выполняется подбор;
3. похожий документ;
4. порядок;
5. активность связи.

Оба документа выбираются живым поиском по ID, названию или alias. Один документ
нельзя связать сам с собой, а одинаковая пара внутри одного профиля не
дублируется. Выключенная связь сохраняется, но не влияет на публичный результат.

## Теги вызова модуля

### Текущий документ

```text
[mod_related:default]
```

`default` — стабильный системный код профиля. Вместо кода допустим ID, однако
код лучше переносится между установками.

### Явный документ

```text
[mod_related:default:125]
```

Второй аргумент — ID исходного документа. Такой вызов полезен в блоке или
внешнем шаблоне, где нет текущего контекста страницы.

### Совместимость со старым модулем

```text
[mod_moredoc]
```

Legacy-тег вызывает профиль `default` для текущего документа. Это переходный
синоним: новые шаблоны следует писать через `[mod_related:default]`, поскольку
он явно фиксирует профиль.

## Способы вывода

### Встроенные шаблоны

В этом режиме профиль хранит оболочку списка, одну карточку и необязательный
HTML для пустого результата. AVE.cms не подключает публичный CSS модуля:
классы, сетку и адаптивность определяет тема конкретного сайта.

### Существующий запрос AVE.cms

Выберите **Существующий запрос** и укажите запрос с готовыми карточками. Модуль
передаёт ему уже выбранные ID в рассчитанном порядке. Условия запроса повторно
не выбирают документы; используются его основной шаблон, шаблон элемента,
поля, системные блоки и карточки текущей темы.

Если запрос удалён или недоступен, модуль безопасно использует встроенный
шаблон профиля.

## Теги шаблона контейнера

| Тег | Значение |
| --- | --- |
| `[tag:id]` | Числовой ID профиля. |
| `[tag:code]` | Стабильный системный код профиля. |
| `[tag:title]` | Название профиля, например «Похожие статьи». |
| `[tag:description]` | Описание профиля. Спецсимволы экранируются. |
| `[tag:count]` | Фактическое количество карточек. |
| `[tag:items]` | Склеенный HTML всех карточек. Этот тег нужно оставить в оболочке. |

Пример:

```html
<section class="related-content" data-profile="[tag:code]">
	<h2>[tag:title]</h2>
	<div class="related-content__grid">[tag:items]</div>
</section>
```

## Теги шаблона карточки

| Тег | Значение |
| --- | --- |
| `[tag:index]` | Номер карточки от `1` в текущем результате. |
| `[tag:docid]` | ID найденного документа. |
| `[tag:rubric-id]` | ID его рубрики. |
| `[tag:url]` | Публичный URL документа. |
| `[tag:title]` | Название документа, экранированное для HTML. |
| `[tag:description]` | Meta description; при его отсутствии используется тизер. HTML удаляется. |
| `[tag:date]` | Дата публикации в формате `дд.мм.гггг`. |
| `[tag:datetime]` | Дата публикации в формате `гггг-мм-дд` для `<time datetime>`. |
| `[tag:views]` | Внутренний счётчик просмотров документа. |
| `[tag:image]` | Готовый `<img>` разрешённого размера либо пустая строка. |
| `[tag:image-url]` | URL первого исходного изображения документа. |
| `[tag:thumb]` | URL превью из выбранного системного пресета. |
| `[tag:score]` | Числовой вес релевантности; для ручной связи имеет высокий служебный приоритет, для кольца равен `0`. |
| `[tag:matches]` | Количество общих нормализованных признаков. |
| `[tag:source]` | Источник результата: `manual`, `relevance` или `ring`. |

`[tag:image]` удобен для обычной карточки. Если тема использует `picture`,
соберите его самостоятельно из `[tag:image-url]` и `[tag:thumb]`.

Пример:

```html
<article class="related-card" data-source="[tag:source]">
	<a href="[tag:url]">[tag:image]</a>
	<div>
		<time datetime="[tag:datetime]">[tag:date]</time>
		<h3><a href="[tag:url]">[tag:title]</a></h3>
		<p>[tag:description]</p>
	</div>
</article>
```

## JSON API

```http
GET /api/v1/related/{profile}/{document}
```

Пример:

```text
/api/v1/related/default/125
```

Ответ использует общий контракт `{success, data}`. В `data` находятся профиль,
ID исходного документа и массив `items`. Элемент имеет
`document_id`, `rubric_id`, `title`, `url`, `description`, `published_at`,
`views`, `image`, `thumb`, `score`, `matches` и `source`. API использует те же
ограничения публикации и порядок, что серверный тег, но не возвращает HTML
шаблона.

## Хуки

### `related.results.resolved`

Вызывается после подбора и загрузки данных документов, до HTML:

```php
array(
	'profile' => $profile,
	'document' => $currentDocument,
	'items' => $items,
)
```

Обработчик может отфильтровать, дополнить или переупорядочить `items`, затем
должен вернуть весь массив контекста.

### `related.rendering`

Вызывается после встроенного шаблона или существующего запроса:

```php
array(
	'profile' => $profile,
	'document_id' => $documentId,
	'items' => $items,
	'html' => $html,
)
```

Изменяйте `html`, если модулю-интеграции нужно обернуть результат или полностью
заменить представление.

## Кеш и индекс

Результат профиля для документа кешируется на 15 минут. Кеш целиком очищается
при сохранении или удалении документа, изменении профиля, ручной связи и полной
переиндексации. Поэтому устаревшая карточка не должна оставаться после работы в
панели.

Индекс хранит только нормализованные признаки, ID и рубрику. Полные данные
карточки читаются из актуальных документов при разрешении результата. Uninstall
модуля удаляет профили, индекс и ручные связи полностью.

## Практические профили

### Похожие новости

- стратегия: **Гибрид**;
- рубрика: «Новости»;
- только текущая рубрика: включено;
- ключевые слова `8`, теги `6`, заголовок выключен;
- лимит: `4`.

### Продолжить чтение

- стратегия: **Кольцо**;
- рубрики: «Статьи» и «Блог»;
- только текущая рубрика: выключено;
- порядок: дата публикации;
- лимит: `3`.

### Товарные аналоги

- стратегия: **Релевантность**;
- товарные рубрики;
- ключевые слова и теги;
- ручные связи включены для точного закрепления аналогов;
- вывод через запрос с эталонной карточкой товара.