chore: база

src/Telegram/README.md

@@ -9,3 +9,55 @@
 Смена интерфейса бота в админке переключает поведение бота в рантайме.
 
 В первой итерации нужно реализовать поддержку создания интерфейсов чат-ботов. Которые сообщениями отвечают на сообщения. И поддержку приватных сообщений только. Но мы подразумеваем что в будущем это приложение может быть расширено.
+
+## Как устроено
+
+Зависимости: Django и pyTelegramBotAPI. Приложение ничего не знает о других приложениях проекта: оно предоставляет базовый класс интерфейса, а приложения регистрируют свои интерфейсы сами.
+
+- `models.py` - `Bot`, `User`, `Chat` (у каждого чата состояние диалога `state` и данные `data`), `Message`.
+- `interfaces.py` - базовый класс `Interface`, декораторы `command`, `text`, `state` и реестр `register`.
+- `context.py` - `Context`, который получает обработчик: текст, команда, собеседник, состояние, `reply()`.
+- `messages.py` - `send()` для отправки сообщения в чат вне обработчика, например уведомления из фоновой задачи.
+- `dispatcher.py` - разбор обновления: сохраняет пользователя, чат, сообщение и передает его интерфейсу бота.
+- `runner.py` - long polling: по потоку на каждый опубликованный бот, супервизор сверяется с базой каждые 5 секунд.
+
+## Интерфейс бота
+
+```python
+from Telegram.interfaces import Interface, command, register, state, text
+
+
+@register
+class Shop(Interface):
+	title = 'Магазин'
+
+	@command('start')
+	@text('главное меню')
+	def menu(self, ctx):
+		ctx.reset()
+		ctx.reply('Привет', keyboard=[['адрес']])
+
+	@text('адрес')
+	def ask_address(self, ctx):
+		ctx.state = 'await_address'
+		ctx.reply('Пришли адрес', keyboard=[['главное меню']])
+
+	@state('await_address')
+	def address(self, ctx):
+		ctx.data['address'] = ctx.text
+		ctx.state = ''
+		ctx.reply('Сохранил')
+
+	def fallback(self, ctx):
+		ctx.reply('Не понял')
+```
+
+Порядок разбора сообщения: команда, текст кнопки, состояние диалога, `fallback`. Модуль с интерфейсом нужно импортировать при старте, например в `AppConfig.ready()`.
+
+## Запуск
+
+1. В админке добавить бота с токеном и выбрать интерфейс.
+2. Действие "Опубликовать" проверяет токен, подтягивает имя бота и включает бота. "Отозвать" выключает.
+3. `make tg_run` запускает раннер. Смена интерфейса, публикация и отзыв применяются без перезапуска.
+
+`TELEGRAM_API_URL` направляет бота на свой Bot API сервер (сервис `telegram` в `docker-compose.yaml`).