kin: BATON-ARCH-012 Добавить WEBHOOK_ENABLED флаг для локальной разработки

README.md

@@ -0,0 +1,131 @@
+# Baton — Экстренный сигнал
+
+PWA-приложение для отправки экстренных сигналов с геолокацией через Telegram-бота.
+
+## Стек
+
+- **Backend:** Python 3.12+, FastAPI, aiosqlite, httpx
+- **Frontend:** Vanilla JS PWA (Service Worker, Web Push)
+- **База данных:** SQLite (WAL mode)
+- **Уведомления:** Telegram Bot API
+
+## Запуск
+
+```bash
+# Зависимости
+pip install -r requirements.txt
+
+# Переменные окружения (см. .env.example)
+cp .env.example .env
+
+# Запуск
+uvicorn backend.main:app --host 0.0.0.0 --port 8000
+```
+
+## Переменные окружения
+
+| Переменная | Обязательна | Описание |
+|---|---|---|
+| `BOT_TOKEN` | да | Токен Telegram-бота |
+| `CHAT_ID` | да | ID чата для уведомлений |
+| `WEBHOOK_SECRET` | да | Секрет для верификации Telegram webhook |
+| `WEBHOOK_URL` | да | Публичный URL `/api/webhook/telegram` |
+| `DB_PATH` | нет | Путь к SQLite-файлу (по умолчанию `baton.db`) |
+| `FRONTEND_ORIGIN` | нет | Разрешённый origin для CORS (по умолчанию `http://localhost:3000`) |
+| `WEBHOOK_ENABLED` | нет | Регистрировать webhook при старте (по умолчанию `true`) |
+| `APP_URL` | нет | Публичный URL приложения для keep-alive (например `https://baton.fly.dev`) |
+
+## API
+
+| Метод | Путь | Описание |
+|---|---|---|
+| `GET` | `/health` | Health check: `{"status": "ok", "timestamp": <unix_ts>}` |
+| `POST` | `/api/register` | Регистрация пользователя |
+| `POST` | `/api/signal` | Отправка экстренного сигнала |
+| `POST` | `/api/webhook/telegram` | Telegram webhook |
+
+## Hosting & Keep-Alive
+
+### Проблема cold start
+
+На бесплатных хостингах (Render, fly.io free tier, Railway и подобных) приложение **засыпает** после периода неактивности (обычно 15–30 минут). Следующий входящий запрос ждёт пока процесс поднимется заново — **cold start занимает 3–5 секунд**. Для экстренного приложения это критично.
+
+### Решения по вариантам хостинга
+
+| Вариант | Стоимость | Cold start | Рекомендация |
+|---|---|---|---|
+| **fly.io Hobby** | $5/мес | Нет (всегда активен) | Оптимально для прода |
+| **fly.io free tier** | Бесплатно | 3–5 сек | Только для разработки |
+| **Render free** | Бесплатно | 3–5 сек | Только для разработки |
+| **Самохостинг (VPS)** | От $3–5/мес | Нет | Полный контроль |
+
+> **Финальный выбор хостинга зависит от решения по OQ-004** (открытый вопрос по бюджету и масштабированию проекта).
+
+### Keep-alive механизм (asyncio background task)
+
+Приложение запускает фоновый asyncio-таск, который каждые **10 минут** пингует собственный `/health` endpoint. Это предотвращает засыпание на платформах, которые реагируют на активность процесса.
+
+**Активация:** установите переменную `APP_URL`:
+
+```bash
+APP_URL=https://your-app.fly.dev
+```
+
+Без `APP_URL` таск не запускается (keep-alive отключён).
+
+**Ограничение:** self-ping работает пока процесс жив. Если платформа убивает процесс при нулевом трафике — нужен внешний пингер (см. ниже).
+
+### Keep-alive для самохостинга (cron / systemd timer)
+
+Если приложение на VPS и нужен мониторинг извне:
+
+**Вариант 1 — crontab:**
+
+```bash
+# Редактируем cron
+crontab -e
+
+# Добавляем запись (каждые 10 минут):
+*/10 * * * * curl -sf https://your-app.example.com/health > /dev/null
+```
+
+**Вариант 2 — systemd timer:**
+
+Создайте два файла:
+
+`/etc/systemd/system/baton-keepalive.service`:
+```ini
+[Unit]
+Description=Baton keep-alive ping
+
+[Service]
+Type=oneshot
+ExecStart=curl -sf https://your-app.example.com/health
+```
+
+`/etc/systemd/system/baton-keepalive.timer`:
+```ini
+[Unit]
+Description=Run Baton keep-alive every 10 minutes
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=10min
+
+[Install]
+WantedBy=timers.target
+```
+
+Активация:
+```bash
+systemctl daemon-reload
+systemctl enable --now baton-keepalive.timer
+systemctl list-timers baton-keepalive.timer
+```
+
+## Тесты
+
+```bash
+pip install -r requirements-dev.txt
+pytest
+```