# Zilant / VOLK — Telegram poster и подписки

**Версия:** 1.0.4 ([`VERSION`](VERSION))

Автоматическая публикация постов и событий в Telegram-канал, веб-редактор, бот подписок с сезонными deep link.

## Режимы

| `WORKMODE` | Описание |
|------------|----------|
| `ZILANT` | VK + Zilant JSON → канал (основной пайплайн) |
| `VOLK` | VOLK API → категории и события → канал |

Подробнее: [`docs/volk-mode.md`](docs/volk-mode.md).

## Быстрый старт (сервер)

```bash
# Deploy через Woodpecker → rsync + post-deploy.sh
# Сервисы:
sudo systemctl status testbot-git.service   # бот :5005
sudo systemctl status testedit-git.service  # UI  :5006
sudo systemctl status runner.timer          # hourly pipeline
```

Конфигурация — скопируйте [`.env.example`](.env.example) в `.env` и заполните значения
(файл `.env` в git не коммитится). Ключевые переменные: `WORKMODE`, `RELAY_URL`, `WEBHOOK_URL`, `SEASON`, `MDB_*`.
Генерация секретов: `python tools/ops/genkey.py`.

## Пайплайн (ZILANT)

`runner.sh` по расписанию:

`vk_load` → `zk_load` → `db_update_shortname` → `tg_publish` → `evtg_publish`

Настройка timer: [`docs/runner-setup.md`](docs/runner-setup.md).

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

| Документ | О чём |
|----------|--------|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Компоненты, карта файлов, deploy |
| [`docs/volk-mode.md`](docs/volk-mode.md) | Режим VOLK |
| [`docs/telegram-messaging.md`](docs/telegram-messaging.md) | API отправки сообщений пользователям |
| [`docs/runner-setup.md`](docs/runner-setup.md) | Systemd timer / cron для runner |
| [`docs/CHANGELOG.md`](docs/CHANGELOG.md) | История версий |
| [`tools/README.md`](tools/README.md) | Вспомогательные и legacy-скрипты |

## Версионирование

SemVer в [`VERSION`](VERSION). При изменениях обновлять `VERSION` и [`docs/CHANGELOG.md`](docs/CHANGELOG.md).

## Структура каталогов

```
├── tg_mainbot.py, wsgi_bot.py      # responder-бот
├── db_edit.py, wsgi_edit.py        # веб-UI
├── tg_publish.py, evtg_publish.py  # публикация (ZILANT)
├── volk_load.py, volk_cat_publish.py  # VOLK
├── runner.sh, backupdb.sh
├── services/                       # systemd units, post-deploy
├── templates/                      # HTML UI
├── docs/                           # документация
└── tools/
    ├── ops/                        # genkey, register_tg_webhook, copy_databases
    ├── dev/                        # send_telegram_example, volk_*_testing
    └── legacy/                     # evt_prefetch
```