FuelRadar

PWA-система независимой агрегации данных о наличии топлива на АЗС (пилот — Краснодар).

Собственный мастер-каталог АЗС из нескольких источников; отделение факта существования станции от факта наличия топлива; честное различие «нет» и «не знаю»; достоверность каждого статуса с объяснением; очереди и ETA; уведомления по правилам пользователя.

Стек: FastAPI (Python) + SQLite (dev) / PostgreSQL+PostGIS (prod) + Next.js (React, TypeScript, Tailwind) + MapLibre GL.

История изменений по версиям — CHANGELOG.md. Установщик desktop-приложения и автообновление — на странице последнего релиза.

Возможности

• Карта и список АЗС с честными статусами: «нет» ≠ «не знаю», у каждого статуса достоверность с объяснением и разбором FuelRadar Score
• Очереди с ETA; поиск АЗС вдоль маршрута — коридор и дорожный маршрут по улицам
• История цены на карточке станции: спарклайн «Цена во времени» с подписями мин/макс (каждая цена со своей валютой) и честным пропуском записей без цены
• Внешний маршрут с выбором навигатора: Яндекс.Карты / 2ГИС / Google Maps — выбор запоминается и восстанавливается между запусками
• Отчёты «Сообщить» с ценой и статусом; уведомления по правилам (зоны мониторинга, избранное) — in-app, Web Push и Telegram-дайджест
• PWA с офлайн-режимом и desktop-приложение (Windows) с автообновлением

Быстрый старт на новой машине (Windows)

powershell -ExecutionPolicy Bypass -File .\setup.ps1

Или просто дважды кликнуть setup.cmd. Создаст venv и .env/frontend/.env.local, поставит все зависимости, нальёт демо-каталог АЗС (офлайн, без сети) и запустит backend (новое окно) и frontend (текущее окно) — откроется на http://localhost:3000. Тот же скрипт безопасно перезапускать позже для обновления (git pull + зависимости).

Команды

Команда	Что делает
make install	Установить зависимости (backend pip + frontend npm)
make dev	Запустить API локально (uvicorn, http://localhost:8000)
make test	Прогнать тесты backend + typecheck frontend
make lint	Линт backend (ruff)
make e2e	Браузерные E2E (Playwright/Chromium) критических сценариев
make compose-up	Поднять dev-окружение в Docker (api, worker, frontend)
make compose-prod	Поднять prod-профиль (+PostGIS, Redis, reverse proxy)

Переменные окружения — cp .env.example .env, секреты заполняются пользователем (R68).

Доступ и Telegram-подписка

Пользователей и входа в приложении нет: всё — карта, админка, настройки — доступно тому, кто его запустил. Защита от случайных клиентов — лимиты запросов и проверка Origin на изменяющих операциях, все админ-действия пишутся в журнал.

Подписка на события через Telegram: укажите токен бота в настройках интерфейса (вкладка «Настройки → Telegram» или TELEGRAM_BOT_TOKEN в .env), напишите боту любое сообщение — чат определится автоматически, задайте интервал в минутах — и приложение само пришлёт сводку о доступности топлива, изменениях и дефиците.

Источники данных

Каталог строится из нескольких источников (OSM/Overpass, файловый импорт списков сетей, пользовательские отчёты; HTTP-адаптер сетевых списков — network_lists — ждёт настройки NETWORK_LISTS_URLS). Как подключить новый источник — от адаптера до включения через админку: docs/new-source.md.

Production-запуск пилота

Чек-лист перевода проекта в эксплуатацию — секреты и конфигурация, деплой и периметр, источники и качество каталога, роли, мониторинг, бэкапы и критерии готовности: docs/pilot-readiness.md.

Состояние roadmap

Завершены T01–T15: каталог и дедупликация, Confidence Engine, публичный API, воркер, уведомления, frontend, Route Mode, прогноз/heatmap/BI, цена топлива end-to-end, realtime/Web Push и браузерные E2E.

T13 добавляет nullable цену с временем/источником, POST /reports с ценой вместе со статусом, фильтр fuel + price_max и честное «нет данных» в UI. Секреты и внешние источники цен не подставляются автоматически: отсутствующая цена остаётся отсутствующей.

Границы объёма MVP (R90)

Намеренно не строим в первом MVP: нативные приложения, микросервисы, Kubernetes, ML/LLM на каждый запрос, платный routing API. Heatmap, прогноз, route-corridor и реальные цены реализованы в расширенной волне T11–T13; полный список оставшихся ограничений — в .autopilot/fuelradar/spec.md.

Дорожный маршрут (R22.1) строится по улицам через OSRM-совместимый роутер с бесплатным профилем driving: односторонние улицы и запреты поворотов учитывает граф OSM, адрес роутера — в ROUTING_BASE_URL (пусто → честная прямая линия).

Структура

backend/app/        модульный монолит (FastAPI): core, db, api, sources, worker, …
frontend/app/       Next.js (App Router), карта — MapLibre GL через абстракцию
.autopilot/         бриф, манифест, спецификация, таски, дашборд

Подробная архитектура, API-контракты и инварианты — .autopilot/fuelradar/tickets/interfaces.md.