69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# 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, валюта и единицы измерения на уровне пользователя.
|