first commit

README.md

@@ -0,0 +1,68 @@
+# 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`:
+
+```bash
+cp .env.example .env
+```
+
+2. Заполни `BOT_TOKEN` и `WEBAPP_URL`. Для Telegram mini app `WEBAPP_URL` должен быть HTTPS URL, доступный Telegram.
+
+3. Подними сервисы:
+
+```bash
+docker compose up --build
+```
+
+API будет доступен на `http://localhost:8000`, документация - `http://localhost:8000/docs`.
+
+## Локальный запуск без Docker
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+alembic upgrade head
+uvicorn app.main:app --reload
+```
+
+В отдельном терминале:
+
+```bash
+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, валюта и единицы измерения на уровне пользователя.