baton/docs/backend_spec.md

# Backend Spec: Baton PWA

**Версия:** 1.1
**Дата:** 2026-03-20
**Статус:** Approved (Architect)

---

## 1. API Contracts

### POST /api/register

Регистрирует UUID→имя пользователя. **Идемпотентен**: повторный вызов с тем же UUID возвращает существующую запись.

**Request:**
```http
POST /api/register
Content-Type: application/json

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Алиса"
}
```

| Поле | Тип | Ограничения |
|------|-----|-------------|
| uuid | string | UUID v4, обязателен |
| name | string | 1–100 символов, обязателен |

**Response 200 OK:**
```json
{
  "user_id": 42,
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Status codes:**

| Код | Причина |
|-----|---------|
| 200 | Успешно (новый или существующий) |
| 422 | Ошибка валидации Pydantic |
| 500 | Внутренняя ошибка сервера |

---

### POST /api/signal

Принимает сигнал тревоги от PWA. Сохраняет в SQLite, добавляет в очередь агрегатора Telegram.

**Request:**
```http
POST /api/signal
Content-Type: application/json

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1742478000000,
  "geo": {
    "lat": 55.7558,
    "lon": 37.6173,
    "accuracy": 15.0
  }
}
```

| Поле | Тип | Ограничения |
|------|-----|-------------|
| user_id | string | UUID v4 пользователя, обязателен |
| timestamp | int | Unix ms, > 0, обязателен |
| geo | object \| null | Необязателен; если передан — все три поля lat/lon/accuracy обязательны |
| geo.lat | float | -90.0 … 90.0 |
| geo.lon | float | -180.0 … 180.0 |
| geo.accuracy | float | > 0, метры |

**Response 200 OK:**
```json
{
  "status": "ok",
  "signal_id": 123
}
```

**Status codes:**

| Код | Причина |
|-----|---------|
| 200 | Сигнал принят |
| 422 | Ошибка валидации |
| 500 | Внутренняя ошибка |

---

### POST /api/webhook/telegram

Входящие обновления от Telegram Bot API. Регистрируется через `setWebhook` при старте сервера.

**Headers:**
```
X-Telegram-Bot-Api-Secret-Token: <WEBHOOK_SECRET>
```

**Request body:** стандартный Telegram Update object (JSON от Telegram).

**Обрабатываемые команды:**

| Команда | Действие |
|---------|----------|
| `/start` | Регистрация пользователя через Telegram (INSERT OR IGNORE в users с Telegram user_id как UUID) |

**Response:**
```json
{"ok": true}
```

**Status codes:**

| Код | Причина |
|-----|---------|
| 200 | Обновление обработано |
| 403 | Неверный или отсутствующий X-Telegram-Bot-Api-Secret-Token |
| 422 | Невалидный JSON |

---

## 2. DB Schema (SQLite WAL)

```sql
-- WAL mode + защита от write-lock (решения #1005, #1002)
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;
PRAGMA synchronous=NORMAL;

CREATE TABLE IF NOT EXISTS users (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid       TEXT UNIQUE NOT NULL,
    name       TEXT NOT NULL,
    created_at TEXT DEFAULT (datetime('now'))
);

CREATE TABLE IF NOT EXISTS signals (
    id               INTEGER PRIMARY KEY AUTOINCREMENT,
    user_uuid        TEXT NOT NULL REFERENCES users(uuid),
    timestamp        INTEGER NOT NULL,
    lat              REAL DEFAULT NULL,
    lon              REAL DEFAULT NULL,
    accuracy         REAL DEFAULT NULL,
    created_at       TEXT DEFAULT (datetime('now')),
    telegram_batch_id INTEGER DEFAULT NULL
);

CREATE TABLE IF NOT EXISTS telegram_batches (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    message_text  TEXT DEFAULT NULL,
    sent_at       TEXT DEFAULT NULL,
    signals_count INTEGER DEFAULT 0,
    status        TEXT DEFAULT 'pending'
);

-- Индексы
CREATE UNIQUE INDEX IF NOT EXISTS idx_users_uuid         ON users(uuid);
CREATE INDEX IF NOT EXISTS        idx_signals_user_uuid  ON signals(user_uuid);
CREATE INDEX IF NOT EXISTS        idx_signals_created_at ON signals(created_at);
CREATE INDEX IF NOT EXISTS        idx_batches_status     ON telegram_batches(status);
```

**Инвариант:** все три PRAGMA применяются при каждом подключении. Пропуск любой — нарушение решений #1005, #1002.

---

## 3. Telegram Aggregator Design

### Принцип работы

```
[POST /signal] ──► add_signal(user_name, ts, geo)
                        │
                   [in-memory buffer]
                        │
             asyncio background task (run loop)
                        │
                   sleep(10 sec)
                        │
                   if buffer not empty:
                        │
                   ──► flush()
                        │
                   формат сообщения
                        │
                   send_message()
```

### Буфер и окно

- **Хранение:** список `list[dict]` в памяти, защищённый `asyncio.Lock()`
- **Интервал сброса:** 10 секунд (скользящее окно)
- **Rate limit:** максимум 20 сообщений/минуту в группу, 1 сообщение/секунду (#1014)
  - Реализация: `asyncio.sleep(1)` после каждого успешного `send_message`

### Формат сообщения

```
🚨 Получено N сигналов [HH:MM:SS—HH:MM:SS]
Пользователи: name1, name2, name3
📍 С геолокацией: K из N
```

Если имя пользователя неизвестно — показывать первые 8 символов UUID.

### Обработка ошибок Telegram

| Код ответа | Действие |
|-----------|---------|
| 200 OK | Успех, обновить telegram_batch status = 'sent' |
| 429 Too Many Requests | Прочитать `retry_after` из тела ответа, `await asyncio.sleep(retry_after)`, повторить |
| 400 Bad Request | Логировать ошибку, сигналы не теряются (остаются в SQLite) |
| 5xx | Логировать, повторить через 30 сек (1 попытка) |

### Запись batch в SQLite

После успешной отправки:
```sql
INSERT INTO telegram_batches (message_text, sent_at, signals_count, status)
VALUES (?, datetime('now'), ?, 'sent');

UPDATE signals SET telegram_batch_id = ? WHERE id IN (...);
```

---

## 4. Middleware & Security

### CORS

```python
CORSMiddleware(
    allow_origins=[config.FRONTEND_ORIGIN],  # env var FRONTEND_ORIGIN
    allow_methods=["POST"],
    allow_headers=["Content-Type"],
)
```

`FRONTEND_ORIGIN` обязателен в `.env`. Не использовать `allow_origins=["*"]` в продакшне.

### Webhook Secret Validation

Middleware проверяет заголовок `X-Telegram-Bot-Api-Secret-Token` **только** для маршрута `POST /api/webhook/telegram`.

```
Входящий запрос на /api/webhook/telegram
  └── if header != config.WEBHOOK_SECRET → 403 Forbidden (немедленно)
  └── else → передать в обработчик
```

Реализация: Starlette `BaseHTTPMiddleware` или dependency в роуте (предпочтительно dependency — проще тестировать).

### Input Validation

Все входящие тела запросов валидируются через Pydantic v2 models. FastAPI возвращает 422 автоматически при ошибке валидации.

### Secrets Management

Все секреты исключительно через переменные окружения (`.env` + `python-dotenv`). Ни один секрет не должен логироваться (особенно `WEBHOOK_SECRET` и `BOT_TOKEN`).

---

## 5. Startup / Shutdown

### Startup (lifespan event)

```
1. init_db()
   └── PRAGMA journal_mode=WAL
   └── PRAGMA busy_timeout=5000
   └── PRAGMA synchronous=NORMAL
   └── CREATE TABLE IF NOT EXISTS ... (users, signals, telegram_batches)
   └── CREATE INDEX IF NOT EXISTS ...

2. set_webhook(url=config.WEBHOOK_URL, secret=config.WEBHOOK_SECRET)
   └── POST https://api.telegram.org/bot{TOKEN}/setWebhook
   └── WEBHOOK_URL ОБЯЗАН быть HTTPS (#1011)
   └── Если ошибка → залогировать и завершить старт с исключением

3. aggregator = SignalAggregator(interval=10)
   asyncio.create_task(aggregator.run())
```

### Shutdown (lifespan event)

```
1. aggregator.stop()           — установить флаг остановки
2. await aggregator.flush()    — отправить оставшиеся сигналы из буфера
3. Закрыть все aiosqlite соединения
```

---

## 6. Файловая структура

```
baton/
├── backend/
│   ├── main.py          # FastAPI app, роуты, lifespan events, CORS
│   ├── db.py            # SQLite init (WAL), CRUD: register_user, save_signal, get_user_name
│   ├── models.py        # Pydantic v2: RegisterRequest/Response, SignalRequest/Response, GeoData
│   ├── telegram.py      # send_message, set_webhook, SignalAggregator
│   ├── config.py        # Settings через python-dotenv: BOT_TOKEN, CHAT_ID, DB_PATH,
│   │                    #   WEBHOOK_SECRET, WEBHOOK_URL, FRONTEND_ORIGIN
│   └── middleware.py    # WebhookSecretValidator (или FastAPI dependency)
├── tests/
│   ├── conftest.py      # Фикстуры: in-memory SQLite, AsyncClient, respx mock
│   ├── test_register.py
│   ├── test_signal.py
│   ├── test_telegram.py
│   ├── test_webhook.py
│   └── test_db.py
├── docs/
│   ├── backend_spec.md  # Этот файл
│   └── backend_review.md  # Создаётся reviewer после имплементации
├── requirements.txt         # fastapi, uvicorn[standard], aiosqlite, httpx, python-dotenv, pydantic>=2.0
├── requirements-dev.txt     # pytest, pytest-asyncio, httpx, respx
└── .env.example
```

---

## 7. .env.example

```env
# Telegram
BOT_TOKEN=your_telegram_bot_token_here
CHAT_ID=-1001234567890
WEBHOOK_SECRET=your_random_secret_here
WEBHOOK_URL=https://yourdomain.com/api/webhook/telegram

# Database
DB_PATH=baton.db

# CORS
FRONTEND_ORIGIN=https://yourdomain.com
```

---

## 8. Соответствие решениям

| Решение | Статус | Реализация |
|---------|--------|-----------|
| #999: HTTPS для PWA/Geolocation | ✅ | WEBHOOK_URL обязан быть HTTPS; задокументировано в constraints |
| #1001: Background Sync fallback | ✅ | Не касается бэкенда; offline паттерн — на фронте |
| #1002: SQLite write-lock | ✅ | busy_timeout=5000 при каждом подключении |
| #1003: Требования не понижать | ✅ | Все 3 эндпоинта обязательны |
| #1004: bcrypt через run_in_executor | ✅ | UUID auth — без bcrypt; если добавится — только run_in_executor |
| #1005: WAL + busy_timeout + synchronous | ✅ | Все три PRAGMA вместе в init_db() |
| #1009: setWebhook vs getUpdates | ✅ | ТОЛЬКО setWebhook при старте; getUpdates запрещён |
| #1010: webhook secret validation | ✅ | Middleware/dependency на /api/webhook/telegram |
| #1011: HTTPS для webhook | ✅ | WEBHOOK_URL в .env.example — HTTPS |
| #1013: UUID v4 stateless auth | ✅ | register принимает UUID из localStorage |
| #1014: Telegram rate limit 20/min | ✅ | SignalAggregator: 10-сек окно, sleep(1) между отправками |

---

## 9. Открытые вопросы (для Director/PM)

1. **CORS origin** — какой домен фронтенда? (Определяется Infra-отделом)
2. **Количество uvicorn workers** — один процесс (aggregator в памяти) vs несколько (aggregator должен быть shared via Redis/SQLite)
   - **Рекомендация:** один uvicorn worker в продакшне для MVP (aggregator в памяти корректен)
3. **Команды Telegram-бота** — только `/start` для регистрации, или нужны другие команды?
4. **Telegram message format** — показывать реальные имена или UUID?