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

docs/telegram-messaging.md

@@ -0,0 +1,94 @@
+# Отправка сообщений через Telegram бота
+
+## Описание
+
+В проект добавлена возможность отправки сообщений пользователям Telegram через бота по их ID. Функциональность включает:
+
+1. **API endpoint** для отправки сообщений из других скриптов
+2. **Интерфейс в веб-приложении** для отправки сообщений через браузер
+3. **Обработку ошибок** и логирование всех операций
+
+## Архитектура системы
+
+Система состоит из двух основных компонентов:
+
+- **Веб-интерфейс** (`db_edit.py`) - работает на порту **5006** (WEBCTRL_PORT)
+- **Telegram бот** (`tg_mainbot.py`) - работает на порту **5005** (WEBHOOK_PORT)
+
+API endpoint `/send_message` находится в Telegram боте, поэтому все запросы должны отправляться на порт **5005**.
+
+### Конфигурация портов
+
+Порты и URL настраиваются в файле `.env`:
+
+- `RELAY_URL` - базовый URL **internal_relay** (все исходящие вызовы Bot API идут только через него)
+- `WEBHOOK_PORT` - порт для Telegram бота (по умолчанию 5005)
+- `WEBHOOK_URL` - URL доставки апдейтов от internal_relay к боту
+- `WEBCTRL_PORT` - порт для веб-интерфейса (по умолчанию 5006)
+
+## Использование через веб-интерфейс
+
+В заголовке страницы добавлены поля **ID пользователя**, **Сообщение** и кнопка **Отправить**.
+
+## Использование через API
+
+### Endpoint
+
+```
+POST /send_message
+POST {WEBHOOK_PATH}/send_message
+```
+
+### Заголовки
+
+```
+Content-Type: application/json
+X-API-Secret-Token: <WEBHOOK_SECRET>
+```
+
+### Тело запроса
+
+```json
+{
+    "user_id": 123456789,
+    "message": "Текст сообщения"
+}
+```
+
+### Пример (Python)
+
+```python
+import requests
+
+def send_telegram_message(user_id, message):
+    url = "http://192.168.0.109:5005/testbot/send_message"
+    headers = {
+        "Content-Type": "application/json",
+        "X-API-Secret-Token": "ваш_секретный_токен",
+    }
+    response = requests.post(url, json={"user_id": user_id, "message": message}, headers=headers)
+    return response.json()
+```
+
+### Пример (curl)
+
+```bash
+curl -X POST http://localhost:5005/testbot/send_message \
+  -H "Content-Type: application/json" \
+  -H "X-API-Secret-Token: ваш_секретный_токен" \
+  -d '{"user_id": 123456789, "message": "Привет!"}'
+```
+
+Опционально: CLI-скрипт `tools/dev/send_telegram_example.py`.
+
+## Коды ошибок API
+
+- `INVALID_TOKEN`, `NO_DATA`, `NO_USER_ID`, `NO_MESSAGE`, `INVALID_USER_ID`
+- `TELEGRAM_ERROR`, `INTERNAL_ERROR`
+
+## Требования
+
+- Бот запущен (webhook через `wsgi_bot.py`)
+- Пользователь начал диалог с ботом (`/start`)
+
+См. также [`ARCHITECTURE.md`](ARCHITECTURE.md).