x0gp/server/PLAN.md

# x0gp — Server Plan (Go)

Документ фиксирует серверную архитектуру: транспорт, модули, протокол,
хранение, биллинг, деплой.

Дата фиксации архитектурных решений: 2026-06-18.
Дата обновления (домашний сервер для PoC и MVP): 2026-06-18.
Дата обновления v2 (Orange Pi 5 Pro + Coolify + статический IP): 2026-06-18.

Архитектурные выборы, на которых основан план:
1. Транспорт клиент-сервер: **WebSocket + бинарный protobuf**.
2. Управление машинками: **Wi-Fi, ESP32-S3 агент**.
3. Модель доверия: **authoritative server + client-side prediction**.
4. Позиционирование: **IR-магнитные секторы + overhead-CV (гибрид)**.

---

## 1. Цели и не-цели

### 1.1. Цели

- Round-trip "команда на экране -> отклик машинки" в худшем случае 200 мс,
  в типичном 80-120 мс.
- Поддержка одновременно 50-100 активных заездов на 1 Edge-инстанс.
- Устойчивость к обрывам связи (клиент теряет сеть на 0.5-2 с без потери
  состояния).
- Anti-cheat: защита от подмены телеметрии, авто-команд, грязного руления.
- Биллинг заездов и турниров (ЮKassa для РФ, Stripe для остального).
- Горизонтальное масштабирование (stateless API, sticky-сессии на WS).

### 1.2. Не-цели (для MVP)

- Физика шин (скорость не считаем, считаем положение с CV).
- Запись/воспроизведение VR-реплеев.
- Полноценный matchmaking с ELO (только базовый лобби).
- Мобильное приложение (только Web, мобилка во второй очереди).

---

## 2. Высокоуровневая архитектура

```
                +----------------------+
                | React (Web client)   |
                | React Native (mobile)|
                +----------+-----------+
                           |
                     WebSocket (binary protobuf)
                           |
                +----------v-----------+
                |   Edge / API Gateway |
                |   (Go, stateless)    |
                +----+------+-----+----+
                     |      |     |
       +-------------+      |     +-------------+
       |                    |                   |
+------v------+    +--------v-------+    +------v------+
| Race Engine |    | Realtime Hub   |    | REST API    |
| (stateful)  |    | (WS fan-out)   |    | (chi/echo)  |
+-------------+    +----------------+    +-------------+
       |                   |                    |
       +---------+---------+                    |
                 |                              |
        +--------v--------+                     |
        |     Redis       |  pub/sub, state    |
        +-----------------+                    |
                 |                              |
        +--------v--------+                     |
        |  Postgres / TS  |<-------------------+
        +-----------------+
```

**Edge / API Gateway** — единая точка входа, TLS, rate-limit, auth, маршрутизация.
**Race Engine** — authoritative state гонки, tick 60 Hz.
**Realtime Hub** — WebSocket-концентратор, fan-out игрокам, сериализация.
**REST API** — управление пользователями, лобби, платежами, история.

---

## 3. Транспорт

### 3.1. WebSocket (основной)

- Библиотека: **gorilla/websocket** или **nbio** (последняя — non-blocking,
  лучше для тысяч соединений).
- Формат кадров: **бинарный protobuf** (для latency) + опционально JSON для
  не-real-time сообщений (чат лобби).
- Subprotocol: `x0gp.v1`.
- Ping/pong: каждые 5 с, читаем RTT для диагностики.

### 3.2. Альтернатива на будущее

- WebRTC DataChannel — если потребуется суб-50 мс jitter.
- Собственный UDP+KCP — если появится конкурентная потребность.
- В плане не реализуем, но держим "port" в протоколе для миграции.

### 3.3. REST API

- HTTP/2, chi router.
- OpenAPI 3.1 спецификация, кодогенерация клиента.
- Авторизация: JWT (access 15 мин) + refresh token (30 дней).
- Idempotency-Key для платёжных эндпоинтов.

---

## 4. Структура Go-модулей

```
server/
  cmd/
    api-gateway/           # REST + WS, stateless
    race-engine/           # stateful, authoritative tick
    agent-linker/          # запускается в помещении (на gateway-ПК)
    indexer/               # пишет телеметрию в Timescale
    replay-recorder/       # (опц.) пишет replay в S3
  internal/
    auth/                  # JWT, сессии, refresh, MFA
    billing/               # ЮKassa/Stripe, биллинг сессий
    race/                  # сессии, круги, DNF, рестарты, секторы
    realtime/              # WS hub, fan-out, per-client очереди
    transport/             # protobuf-схемы, кодеки
    control/               # приём команд, rate-limit, prediction snapshots
    prediction/            # client-side prediction серверные корректировки
    telemetry/             # агрегация, пересылка в TS
    anti_cheat/            # эвристики: sanity check, повторы, geo
    tournament/            # bracket, лэддер, регистрация
    storage/
      postgres/            # sqlx/pgx, миграции
      redis/               # сессии, pub/sub, лобби
      timescale/           # телеметрия
    obs/                   # логирование, метрики, трейсы
  proto/
    client_server.proto    # команды, телеметрия для игрока
    server_agent.proto     # команды и состояние для машинки
  api/
    openapi.yaml
  migrations/              # SQL
  deploy/
    docker-compose.yml     # dev
    helm/                  # prod
  scripts/
    loadtest/              # 100 виртуальных гонщиков
```

---

## 5. Протокол (protobuf)

### 5.1. Клиент -> Сервер

- `ClientHello { version, token, locale }`
- `JoinRace { raceId, carClass }`
- `LeaveRace {}`
- `InputState { seq, tsMs, steering (-1..1), throttle (0..1), brake (0..1), gear (-1..0..1), buttons }` (60-120 Hz)
- `ChatMessage { text }` (rate-limited)
- `Ping { tsMs }`

### 5.2. Сервер -> Клиент

- `ServerHello { sessionId, raceTick, config }`
- `RaceSnapshot { tick, tsMs, cars: [{id, x, y, heading, speed, lap, sector, lastLapMs}], leaderboard }` (30-60 Hz)
- `InputAck { seq, appliedAtMs }`
- `Correction { deltaSteering, deltaThrottle, reason }` (редко, при расхождении)
- `RaceEvent { type: START|LAP|SECTOR|DNF|END, payload }`
- `TournamentUpdate { ... }`
- `Pong { tsMs }`

### 5.3. Сервер -> Бортовой агент

- `AgentCommand { carId, steering, throttle, brake, gear, flags, expiresAtMs }` (60-120 Hz)
- `AgentConfig { maxSteeringRate, maxThrottleRate, rampLimits }`

### 5.4. Бортовой агент -> Сервер

- `AgentHello { carId, fwVersion, hwId, rssi }`
- `AgentTelemetry { carId, tsMs, steeringActual, throttleActual, rpm, voltage, current, tempEsc, tempMotor, imu: {ax, ay, az, gx, gy, gz}, irSensor: {front, rear}, batteryPct }` (10-30 Hz)
- `Heartbeat { tsMs, uptimeSec, errors }` (1 Hz)
- `AgentLog { level, msg }`

### 5.5. Gateway-агент -> Edge-сервер

- `TrackHello { trackId, hwId, publicKey, version }`
- `CarFrame { carId, tsMs, position: {x,y,z}, heading, velocity, confidence }` (из CV, 30-60 Hz)
- `SectorEvent { carId, sector, tsMs, lap }`
- `ReplayChunk { raceId, tsMs, jpegBytes }` (по запросу)
- `LocalCommand { carId, payload }` (forwarded from server)

---

## 6. Race Engine (authoritative tick)

### 6.1. Tick

- Фиксированный шаг: **16.67 мс (60 Hz)**.
- На каждом тике:
  1. Принять все InputState от игроков за последние N мс (батч).
  2. Применить к authoritative state машинок (с учётом ramp limits).
  3. Сформировать команды бортовым агентам.
  4. Отправить команды агенту в помещении.
  5. Через ~33 мс получить телеметрию и CV-обновления.
  6. Скорректировать state.
  7. Сформировать RaceSnapshot для клиентов.

### 6.2. Client-side prediction

- Клиент хранит последний применённый state и локально симулирует физику
  между snapshot-ами.
- При получении Snapshot клиент сверяет, если расхождение > порога — плавная
  коррекция (lerp 100-200 мс), без "телепорта".
- Сервер шлёт `Correction` только если расхождение > критического.

### 6.3. Anti-cheat эвристики

- Sanity check входящих команд (steering/throttle в допустимом диапазоне,
  скорость изменения не выше физического предела).
- Сравнение CV-позиции с заявленной (на сервере) — если расходятся > N метров,
  пометка DQF.
- Повторы replay: после заезда сверяем логгированные команды с CV-треком.
- Device fingerprint + поведенческий профиль.
- Rate limit: > 200 Hz InputState = бан.

### 6.4. Состояния гонки

- `LOBBY` -> `COUNTDOWN` (3..1) -> `RACING` -> `FINISHED`.
- DNF по: таймаут без input 5 с, потеря связи с агентом > 3 с, флаг
  администратора.
- RESTART: только на LoBBY или между раундами.

---

## 7. Realtime Hub

- Один WS-коннект на игрока.
- Подписки: `race:{raceId}`, `tournament:{id}`, `user:{id}`.
- Fan-out: при Snapshot race-движок публикует в Redis pub/sub, Hub читает
  и шлёт подписанным клиентам.
- Backpressure: если клиент не успевает читать — дропаем старые Snapshot,
  шлём только последний.
- Sticky-сессии: cookie `x0gp_sticky` при балансировке на L7.

---

## 8. Хранение

### 8.1. PostgreSQL (relational)

Таблицы (основные):
- `users` (id, email, phone, password_hash, created_at, locale)
- `sessions` (id, user_id, refresh_hash, ip, ua, expires_at)
- `wallets` (user_id, balance, currency)
- `payments` (id, user_id, provider, ext_id, amount, status, created_at)
- `races` (id, track_id, class, started_at, ended_at, winner_id, replay_url)
- `race_results` (race_id, user_id, car_id, lap_times[], best_lap, dnf_reason)
- `tournaments` (id, name, format, entry_fee, prize_pool, status)
- `tournament_entries` (tournament_id, user_id, seed, eliminated_at)
- `cars` (id, hw_id, model, fw_version, status, last_seen)
- `tracks` (id, name, layout_id, geo_city, status)

Миграции: `golang-migrate/migrate`.

### 8.2. Redis

- `session:{token}` -> userId (TTL 15 мин)
- `refresh:{token}` -> userId (TTL 30 дн)
- `race:{id}:state` -> serialized race state (TTL 1 час)
- `lobby:{id}` -> set of userIds
- `ratelimit:{user}:{op}` -> token bucket
- pub/sub channel `race_events`

### 8.3. TimescaleDB (time-series)

- hypertable `telemetry` (ts, race_id, car_id, field, value)
- 7 дней горячих данных, потом cold в S3.
- continuous aggregates для "лучший круг на треке", "топ-скорости".

---

## 9. Биллинг

### 9.1. Провайдеры

- **ЮKassa** — для РФ.
- **Stripe** — для остального мира (фаза 3).

### 9.2. Сценарии

- Пополнение кошелька (one-time payment).
- Списание за заезд (раз в N минут или за сессию).
- Входной взнос в турнир.
- Призовые начисления победителям.

### 9.3. Идемпотентность и реконсиляция

- Каждый платёж имеет `Idempotency-Key` на стороне клиента и `ext_id` от
  провайдера.
- Webhook-эндпоинт `/webhooks/yookassa` с проверкой подписи.
- Ежедневный job сверяет балансы с провайдером.

---

## 10. Авторизация

- Email + password (argon2id) — базовый сценарий.
- OAuth Yandex / VK / Google — для удобства.
- MFA TOTP — обязательно для админов и pro-игроков.
- JWT: HS256 в PoC, RS256 в проде.
- Refresh-token rotation, device-binding.

---

## 11. Anti-cheat

Уровни:
1. **Sanity** — диапазоны, скорости, ramp limits (всегда).
2. **CV-check** — расхождение с overhead-камерой > 1 м -> пометка.
3. **Replay verify** — после заезда можно пересчитать (асинхронно).
4. **Behavioral** — паттерны (слишком "идеальные" круги = подозрительно).
5. **Manual review** — оператор смотрит replay при споре.

---

## 12. Observability

- Логи: `slog` (stdlib) в JSON, отправка в Loki.
- Метрики: `prometheus/client_golang`, экспорт `/metrics`.
- Трейсы: OpenTelemetry, OTLP в Jaeger/Tempo.
- Ключевые метрики:
  - `ws_connections_total`
  - `rtt_ms_p50/p95/p99` (по `(clientSendTs - serverRecvTs)`)
  - `tick_lag_ms` (если тик опаздывает > 5 мс — алерт).
  - `input_rate_per_client`
  - `dropped_snapshots_per_client`
  - `gateway_online{trackId}` (heartbeat агенты в помещении).

---

## 13. Деплой и инфраструктура

**Базовое решение: PoC и MVP крутятся на Orange Pi 5 Pro через Coolify.**
Перенос на облако/VPS — когда появится коммерческая нагрузка и SLA обязательства.

### 13.1. Orange Pi 5 Pro (PoC и MVP)

**Платформа: Orange Pi 5 Pro** (Rockchip RK3588S, ARM64). Уже есть в наличии.

**Характеристики:**
- CPU: 8 cores (4× Cortex-A76 @ 2.4 GHz + 4× Cortex-A55 @ 1.8 GHz)
- RAM: 4 / 8 / 16 / 32 GB LPDDR4x (зависит от версии)
- GPU: Mali-G610 MP4
- **NPU: 6 TOPS** (RKNN) — для CV-инференса (YOLO/ByteTrack) **на борту**
- Сеть: 2× 2.5 GbE (один WAN, один LAN с трассой — **физическая изоляция**)
- Wi-Fi 6 (резерв)
- USB 3.0 × 2, PCIe 2.1 x1, SATA
- ОС: Ubuntu (уже стоит, с **Coolify**)

**Coolify как платформа деплоя:**
- Self-hosted PaaS, уже развёрнут.
- UI для управления сервисами, доменами, SSL, env-vars.
- Push-to-deploy из Git-репо (GitHub/Gitea).
- Сервисы = Docker Compose под капотом, но с UI и без боли.
- Встроенные: PostgreSQL, Redis, MinIO (S3-совместимое), Plausible, Uptime Kuma.
- Версионирование деплоев, rollback в 1 клик.

**Доступ из интернета (статический IP уже есть):**
- **Основной вариант**: Caddy reverse proxy + Let's Encrypt напрямую.
  Coolify умеет провизить LE-сертификаты из коробки.
- Подходит, т.к. провайдер даёт статический IP, 443/tcp открыт на роутере
  через port-forward на Orange Pi.
- Cloudflare Tunnel не нужен (нет смысла добавлять лишний hop).
- WAF: Crowdsec через Coolify (опц., можно отложить).

**Архитектура:**
```
+---------------- ORANGE PI 5 PRO (Ubuntu + Coolify) ----------------+
|                                                                       |
|  Coolify (docker compose orchestration)                               |
|    +-- api-gateway        ------------------------------------+      |
|    +-- race-engine        ----------------------------------+      |
|    +-- postgres+timescale (через Coolify UI)                  |      |
|    +-- redis              -----------------------------------+      |
|    +-- caddy (LE)         -----------------------------------+      |
|    +-- prometheus+grafana -----------------------------------+      |
|    +-- minio (S3 replays) -----------------------------------+      |
|                                                                       |
|  Natively (systemd) - требуют прямой доступ к железу:               |
|    +-- agent-linker   (Wi-Fi к машинкам)                            |
|    +-- cv-tracker     (USB камеры, NPU RKNN)                        |
|    +-- node_exporter  (мониторинг)                                  |
|                                                                       |
+---------------------------------------------------------------------+
   2.5 GbE #1 (WAN, к роутеру)         2.5 GbE #2 (LAN к трассе)
        |                                       |
        vv
   +--------------+                   +---------------------+
   | Internet     |                   | Switch (или точка-  |
   | (clients)    |                   | точка)              |
   +--------------+                   +----------+----------+
                                                 |
                                          +------v------+
                                          | x0gp-track  |
                                          | AP + камеры |
                                          +-------------+
```

**Изоляция сети трассы:**
- LAN-порт Orange Pi → выделенный коммутатор (или напрямую к точке доступа
  x0gp-track).
- В этой сети только машинки и камеры — никаких домашних устройств.
- AP настраивается на изолированный SSID / VLAN.
- Это даёт предсказуемый latency (нет соседского трафика) и безопасность.

**Использование NPU RK3588S:**
- RKNN Toolkit 2 для конвертации моделей (PyTorch → ONNX → RKNN).
- Поддерживаются YOLOv8/v9, ByteTrack через onnxruntime-rknn.
- Целевой инференс: 60-120 FPS на одной камере 1080p (с запасом).
- Если NPU не подходит — fallback на CPU ARM A76.
- Альтернативный inference-сервер: Ultralytics + onnxruntime-rknn.

**ARM64-специфика:**
- Docker-образы должны быть `linux/arm64` или `multi-arch`.
- Postgres+TimescaleDB, Redis, Caddy, Prometheus, Grafana — есть для arm64.
- Go-сервисы — `GOARCH=arm64` при сборке (по умолчанию если собирать на
  Orange Pi).
- CV-инференс на Python — pin версии onnxruntime-rknn под aarch64.

**Бэкапы:**
- Ежедневный `pg_dump` (cron в Coolify или отдельный scheduled task).
- Backup в MinIO (S3-совместимое) внутри Coolify.
- Опционально off-site: rclone → Backblaze B2 / Yandex Object Storage.
- Retention: 14 дней локально, 30 дней off-site.

**Безопасность:**
- SSH: только ключи, fail2ban.
- Coolify UI: за reverse proxy с basic auth или Cloudflare Access.
- Порты наружу: 80/tcp + 443/tcp (для Caddy/LE).
- Postgres и Redis слушают только 127.0.0.1 внутри Coolify.
- UPS для Orange Pi (microSD карты не любят внезапные отключения).

### 13.2. Production (после MVP, когда появится коммерческая нагрузка)

- VPS в Москве и СПб (2 региона) — Selectel / Yandex Cloud / Timeweb.
- Managed Postgres + Redis (для снятия с Orange Pi задач бэкапа и HA).
- Kubernetes (Yandex Cloud / Selectel / AWS) — HPA по метрикам
  ws_connections, tick_lag.
- Redis Cluster, Postgres с read-replica.
- CDN для статики (CloudFront / Cloudflare).
- WAF (CrowdSec).
- Orange Pi остаётся как **gateway-агент + CV-инференс** в помещении с
  трассой (NPU продолжаем использовать для позиционирования).
- Edge-сервер (Go) переезжает на VPS, к которому подключаются несколько
  Orange Pi из разных помещений.

---

## 14. Производительность и SLO

| Метрика | Цель |
|---|---|
| API p99 latency | < 100 мс |
| WS input->ack | < 30 мс на Edge |
| Tick stability | 60 Hz +/- 2 мс |
| Один race-engine | 100 активных гонок |
| Один api-gateway | 5000 WS-клиентов |
| Доступность | 99.5% (PoC), 99.9% (prod) |

---

## 15. Roadmap (server)

| Фаза | Срок | Что делаем |
|---|---|---|
| **S0: PoC моно-сервис** | 1-2 нед | Один Go-бинарь: WS + REST + race state in-memory + локальный agent-linker. SQLite. Без биллинга. |
| **S1: MVP модульный** | 4-6 нед | Разделение на api-gateway / race-engine / agent-linker. Postgres + Redis. Auth, JWT, лобби. |
| **S2: CV + телеметрия** | 8-10 нед | Интеграция с overhead-CV. TimescaleDB. Replay recorder (S3-совместимое). |
| **S3: Биллинг** | 10-12 нед | ЮKassa, кошелёк, сессии под оплатой. Webhooks. Админка. |
| **S4: Турниры** | 14-18 нед | Bracket, лэддер, призовые. Анти-чит уровня 2-3. |
| **S5: Продакшн** | 4-6 мес | K8s, мульти-регион, SLO, on-call. Stripe для остального мира. Мобильное приложение. |

---

## 16. Открытые вопросы

- **Стек frontend**: React + Vite, какие библиотеки для WS (reconnect,
  backoff)? Кандидаты: `reconnecting-websocket`, `socket.io-client` (overkill,
  но быстро), свой тонкий клиент на `WebSocket` API.
- **Cloudflare Tunnel vs WireGuard vs статический IP** — что выберем для
  доступа к домашнему серверу? Дефолт: Cloudflare Tunnel (проще, есть
  free-tier, базовый WAF). Уточним после тестов latency.
- **Бэкапы Postgres на NAS** — есть ли дома NAS или использовать внешнее
  S3-совместимое (Backblaze B2 / Yandex Object Storage) для off-site бэкапов?
- **CDN/streaming для replay** — Mux / Cloudflare Stream / своё? Out of scope
  для MVP, но в плане держим "порт".
- **Интеграция со стриминговыми платформами (Twitch)** — out of scope для
  MVP, но в плане держим "порт".
- **Язык CV-сервиса**: Go (gocv) или Python (быстрее итерация, ONNX-рантайм)?
  Дефолт: Python на PoC для скорости итераций, Go для prod-инференса
  (меньше ресурсов, проще деплой).
- **Конкретные характеристики домашнего сервера** (CPU/RAM/диск/ОС) — нужно
  для оценки, сколько одновременных гонок он потянет. В PLAN.md пока заложен
  разумный минимум (4 CPU / 16 GB / 500 GB SSD).
- **ЮKassa-аккаунт** — есть ли уже ИП/ООО для приёма платежей, или
  регистрировать при переходе на биллинг?