ave-cms/help/modules/crossposting.md

Кросспостинг

Модуль crossposting отправляет документы AVE.cms в Telegram, сообщества VK, Дзен через внешний шлюз и любые сервисы с HTTPS webhook. Публикация выполняется в фоне, поэтому недоступная площадка не мешает редактору сохранить документ.

Быстрый запуск

1. Установите и включите модули Планировщик и Кросспостинг.
2. Откройте Модули → Кросспостинг → Каналы.
3. Добавьте канал, сохраните его и нажмите кнопку проверки соединения.
4. На вкладке Шаблоны создайте текст публикации.
5. На вкладке Правила выберите рубрику, шаблон, каналы и момент отправки.
6. Опубликуйте тестовый документ и проверьте вкладки Очередь и Попытки.

Кнопка Новая публикация позволяет отправить отдельный документ без автоматического правила. Пустая дата означает отправку сейчас; заполненная дата создаёт отложенное задание.

Каналы

Telegram

Создайте бота через BotFather, добавьте его администратором канала и разрешите публиковать сообщения. В настройках канала укажите токен и @username канала или его числовой ID. Токен хранится в локальном хранилище секретов и после сохранения больше не показывается.

VK

Укажите ID сообщества и токен с правом публикации на стене. Положительное значение ID автоматически преобразуется в формат владельца сообщества.

Дзен

Способ прямой публикации Дзена может зависеть от типа канала и доступного партнёрского интерфейса. Поэтому AVE.cms не привязывает очередь к закрытому или недокументированному API. Канал Дзен через шлюз передаёт подготовленный материал вашему HTTPS bridge. Замена bridge не требует менять правила, шаблоны и документы.

Универсальный webhook

Webhook получает JSON с событием crossposting.publish, update, status или test. Заголовок Idempotency-Key стабилен для одной публикации. Если задан секрет, тело подписывается заголовком:

X-AVE-Signature: sha256=<HMAC-SHA256 raw JSON body>

Ответ шлюза может содержать:

{
  "accepted": true,
  "status": "published",
  "id": "remote-123",
  "url": "https://service.example/posts/remote-123"
}

Шаблоны

Базовые теги:

Тег	Значение
[tag:document:title]	название документа
[tag:document:excerpt]	тизер или анонс
[tag:document:url]	абсолютная публичная ссылка
[tag:document:published]	дата публикации
[tag:document:tags]	теги документа
[tag:document:meta_description]	meta description
[tag:field:alias]	значение поля рубрики по системному alias

Поле изображения задаётся отдельным alias. Поддерживается одиночное изображение и первый кадр множественного media-поля. Кнопка Предпросмотр собирает публикацию на реальном документе до сохранения шаблона.

Формат Обычный текст безопасно экранирует символы разметки. Формат Безопасный HTML сохраняет поддерживаемое площадкой оформление; Telegram принимает жирный, курсив, подчёркивание, зачёркивание, код и ссылки.

Правила и обновления

Правило применяется только к выбранной рубрике:

• Только вручную — автоматические задания не создаются;
• Сразу после публикации — задание доступно немедленно;
• По дате публикации документа — будущая дата создаёт отложенное задание.

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

Шаблон со значением Для всех можно использовать в разных каналах. Если для Telegram, VK и Дзена нужны разные тексты или изображения, создайте отдельный шаблон и правило для каждой площадки. Так оформление одного канала не влияет на остальные.

Статусы и защита от дублей

Одна строка очереди соответствует одному документу в одном канале. Для задания строится уникальный ключ из документа, редакции, правила, канала и времени. Повторное сохранение, двойной клик или параллельный cron не создают дубль.

Статус Опубликовано означает, что площадка приняла публикацию и вернула её ID. Проверено означает, что шлюз дополнительно нашёл удалённую запись. Прочтение публикации подписчиками Telegram и VK не является статусом доставки и модулем не выдумывается.

Планировщик каждую минуту запускает задачу crossposting.publish. Ошибки повторяются с увеличивающейся задержкой, а после исчерпания попыток остаются в журнале для ручного повтора. Неисправимые публикации также появляются в уведомлениях панели.

Новый шлюз в модуле

Дополнительный модуль регистрирует шлюз из своего services.php:

use App\Modules\Crossposting\GatewayRegistry;

GatewayRegistry::register('my_channel', function (array $settings, array $secrets) {
    return new MyGateway($settings, $secrets);
}, array(
    'title' => 'Мой канал',
    'icon' => 'ti ti-send',
    'fields' => array(
        array('name' => 'endpoint_url', 'label' => 'URL', 'type' => 'url', 'required' => true),
        array('name' => 'token', 'label' => 'Токен', 'type' => 'secret', 'required' => true),
    ),
    'capabilities' => array('publish', 'update', 'verify'),
));

Класс реализует GatewayInterface. Сетевые запросы выполняются только через OutboundHttpClient, секреты получает отдельно от обычных настроек.