реструктуризация файлов проекта

2026-08-30 10:08:43 +03:00
parent adc49c285c
commit 251fa0be11
21 changed files with 619 additions and 333 deletions
@@ -0,0 +1,153 @@
+# Архитектура проекта
+
+Версия: см. [`VERSION`](../VERSION). История изменений: [`docs/CHANGELOG.md`](CHANGELOG.md).
+
+## Назначение
+
+Система загружает посты и события из внешних источников, хранит их в MariaDB, публикует анонсы в Telegram-канал и даёт веб-интерфейс для редактирования и управления подписками через responder-бота.
+
+Поддерживаются два режима работы (`WORKMODE` в `.env`):
+
+| Режим | Источники данных | Публикация |
+|-------|------------------|------------|
+| **ZILANT** | VK (`vk_load.py`), JSON Zilant (`zk_load.py`) | `tg_publish.py`, `evtg_publish.py` |
+| **VOLK** | VOLK API (`volk_load.py`) | `volk_cat_publish.py` |
+
+Подробнее о VOLK: [`docs/volk-mode.md`](volk-mode.md).
+
+## Компоненты runtime
+
+```
+┌─────────────────┐     rsync      ┌──────────────────┐
+│  Woodpecker CI  │ ─────────────► │  /opt/testbot-git │
+└─────────────────┘                └────────┬─────────┘
+                                            │
+         ┌──────────────────────────────────┼──────────────────────────┐
+         ▼                                  ▼                          ▼
+  runner.timer                    testbot-git.service           testedit-git.service
+  → runner.sh                     gunicorn :5005                gunicorn :5006
+    vk_load, zk_load,               wsgi_bot → tg_mainbot         wsgi_edit → db_edit
+    db_update_shortname,
+    tg_publish, evtg_publish
+```
+
+### Responder-бот (подписки)
+
+- **`tg_mainbot.py`** — Flask + webhook, обработка `/start`, callback-кнопок подписки.
+- **`wsgi_bot.py`** — точка входа gunicorn; однократная регистрация webhook с file lock.
+- **`season_links.py`** — сезонные payload (`zk2026_post_*`, `subscribe_zk2026_*` и т.д.).
+- Старые ссылки без префикса сезона → сообщение «сезон завершён» + кнопка в канал.
+
+### Poster (публикация в канал)
+
+- **`tg_publish.py`** — посты VK → Telegram.
+- **`evtg_publish.py`** — события → Telegram.
+- **`volk_cat_publish.py`** — категории VOLK → Telegram (режим VOLK).
+- Все исходящие вызовы Bot API — через **`telegram_relay.py`** (`RELAY_URL`).
+
+### Веб-интерфейс
+
+- **`db_edit.py`** — CRUD постов/событий, кнопки рескана, публикации, «Назвать» (AI shortname).
+- **`db_update_shortname.py`** — генерация коротких названий через RouterAI.
+- **`test_tg_poster.py`** — тестовый пост в канал (кнопка «Тест» в UI).
+- Шаблоны: `templates/`.
+
+### База данных
+
+- **`ensure_db.py`** — создание/миграция схемы (вызывается из loader-скриптов).
+- **`backupdb.sh`** — дамп БД при deploy (`post-deploy.sh`).
+
+## Пайплайн runner.sh (ZILANT)
+
+Порядок выполнения (systemd timer `runner.timer`):
+
+1. `vk_load.py` — загрузка постов из VK
+2. `zk_load.py` — загрузка событий из JSON
+3. `db_update_shortname.py` — AI shortname для новых записей
+4. `tg_publish.py` — публикация постов
+5. `evtg_publish.py` — публикация событий
+
+> **`tools/legacy/evt_prefetch.py`** раньше стоял перед `evtg_publish.py`; с 1.0.0 снят с пайплайна.
+
+## Deploy
+
+- **`.woodpecker.yml`** — rsync на сервер, затем `services/post-deploy.sh`.
+- **`post-deploy.sh`** — venv, pip, backup БД, обновление systemd units, restart сервисов.
+
+## Конфигурация (.env)
+
+| Переменная | Назначение |
+|------------|------------|
+| `WORKMODE` | `ZILANT` или `VOLK` |
+| `SEASON` | Префикс сезона для deep link (`zk2026`) |
+| `RELAY_URL` | Internal relay для Bot API |
+| `WEBHOOK_URL`, `WEBHOOK_SECRET` | Доставка апдейтов боту |
+| `MDB_*`, `MDBASE` | MariaDB |
+| `POSTER_BOT_TOKEN`, `RESPONDER_BOT_TOKEN` | Токены ботов |
+
+## Карта файлов
+
+### Ядро (runtime)
+
+| Файл | Роль |
+|------|------|
+| `tg_mainbot.py` | Responder-бот, webhook |
+| `wsgi_bot.py` | Gunicorn entry (бот) |
+| `db_edit.py` | Веб-UI |
+| `wsgi_edit.py` | Gunicorn entry (UI) |
+| `tg_publish.py` | Публикация постов |
+| `evtg_publish.py` | Публикация событий |
+| `vk_load.py` | Загрузка VK |
+| `zk_load.py` | Загрузка Zilant JSON |
+| `volk_load.py` | Загрузка VOLK (режим VOLK) |
+| `volk_cat_publish.py` | Публикация VOLK (режим VOLK) |
+| `db_update_shortname.py` | AI shortname |
+| `formatter.py` | Форматирование текста постов/событий |
+| `ensure_db.py` | Схема БД |
+| `telegram_relay.py` | Relay для Bot API |
+| `season_links.py` | Сезонные ссылки и callback |
+| `test_tg_poster.py` | Тестовая публикация (UI) |
+| `runner.sh` | Пайплайн по расписанию |
+| `backupdb.sh` | Бэкап БД |
+| `gunicorn_bot.conf.py` | Stub-конфиг gunicorn (бот) |
+
+### Инфраструктура
+
+| Путь | Роль |
+|------|------|
+| `services/testbot-git.service` | systemd: бот :5005 |
+| `services/testedit-git.service` | systemd: UI :5006 |
+| `services/runner.service`, `runner.timer` | systemd: hourly runner |
+| `services/post-deploy.sh` | Post-deploy |
+| `.woodpecker.yml` | CI deploy |
+
+### Вспомогательные (`tools/`)
+
+| Путь | Роль |
+|------|------|
+| `tools/ops/genkey.py` | Генерация секретов |
+| `tools/ops/register_tg_webhook.py` | Ручная регистрация webhook |
+| `tools/ops/copy_databases.sh` | Клонирование MariaDB |
+| `tools/dev/send_telegram_example.py` | CLI-пример `/send_message` |
+| `tools/dev/volk_telegram_testing.py` | Отладка публикации в Telegram |
+| `tools/dev/volk_category_testing.py` | Отладка загрузки категории VOLK |
+| `tools/legacy/evt_prefetch.py` | Legacy: prefetch событий |
+
+См. [`tools/README.md`](../tools/README.md).
+
+### Документация
+
+| Файл | Содержание |
+|------|------------|
+| `README.md` | Быстрый старт |
+| `docs/ARCHITECTURE.md` | Этот файл |
+| `docs/volk-mode.md` | Режим VOLK |
+| `docs/telegram-messaging.md` | API `/send_message` |
+| `docs/runner-setup.md` | Настройка runner timer |
+| `docs/CHANGELOG.md` | История версий |
+
+## Версионирование
+
+- Версия в корне: **`VERSION`** (SemVer: `MAJOR.MINOR.PATCH`).
+- При каждом значимом изменении обновлять `VERSION` и запись в `docs/CHANGELOG.md`.
+- Правило для агентов: `.cursor/rules/version-and-docs.mdc`.