Drivers Bot

Telegram mini app для учета расходов автовладельца: заправки, ремонты, обслуживание, жидкости, статистика стоимости владения и расхода топлива.

Состав

• app/ - FastAPI сервис. Через него работают и бот, и HTML5 mini app.
• bot/ - aiogram 3 бот, который регистрирует пользователя, открывает mini app и показывает быстрые команды.
• web/ - HTML5 Telegram WebApp фронт.
• alembic/ - миграции PostgreSQL.

Основные таблицы

• users - пользователь Telegram.
• cars - автомобили пользователя.
• fuel_entries - заправки: дата, одометр, литры, цена, стоимость, АЗС.
• service_entries - обслуживание, ремонты, жидкости, шины, страховка, налоги и прочие расходы.

Связи: users 1:N cars, cars 1:N fuel_entries, cars 1:N service_entries.

Запуск

1. Создай .env:

cp .env.example .env

2. Заполни BOT_TOKEN и WEBAPP_URL. Для Telegram mini app WEBAPP_URL должен быть HTTPS URL, доступный Telegram.

3. Подними сервисы:

docker compose up --build

API будет доступен на http://localhost:8000, документация - http://localhost:8000/docs.

Локальный запуск без Docker

python -m venv .venv
source .venv/bin/activate
pip install -e .
alembic upgrade head
uvicorn app.main:app --reload

В отдельном терминале:

python -m bot.main

API

Ключевые endpoint-ы:

• POST /api/users - создать или обновить пользователя Telegram.
• POST /api/cars, GET /api/cars?owner_id=... - автомобили.
• POST /api/fuel, GET /api/cars/{car_id}/fuel - заправки.
• POST /api/service, GET /api/cars/{car_id}/service - сервисные записи.
• GET /api/cars/{car_id}/stats - стоимость владения, топливо, пробег, расход л/100 км, цена 1 км.
• GET /api/cars/{car_id}/charts/expenses.png - график расходов через pandas/matplotlib.

Что дальше

Практичные следующие шаги: авторизация WebApp через проверку initData, CRUD редактирование записей, напоминания по next_due_date и next_due_odometer, экспорт в CSV/XLSX, валюта и единицы измерения на уровне пользователя.