104 lines
12 KiB
Markdown
104 lines
12 KiB
Markdown
# CarPass
|
||
|
||
CarPass — цифровой паспорт автомобиля в Telegram. Он помогает владельцу видеть реальную стоимость владения, вести сервисную историю и аккуратно собирать данные, которые повышают доверие к автомобилю.
|
||
|
||
## Для автовладельца
|
||
|
||
- Все автомобили в одном гараже.
|
||
- Заправки, ТО, ремонт, страховка, налоги, штрафы, парковки, мойки и другие расходы.
|
||
- Стоимость владения за период, стоимость 1 км и прогноз ближайших расходов.
|
||
- Разделение расходов на фиксированные и переменные: топливо, ремонт, страховка, налоги, штрафы, кредит и другие категории.
|
||
- Кредитный калькулятор: ежемесячный платеж, проценты, переплата и влияние кредита на стоимость владения.
|
||
- Расход топлива по корректным интервалам между полными баками и мягкие предупреждения, если запас хода резко снизился.
|
||
- Мягкий прогресс заполнения профиля авто: VIN, госномер, пробег, масло, параметры обслуживания.
|
||
- Бейджи качества истории без игровых очков и токсичных рейтингов.
|
||
- Напоминания о ТО, страховке и важных событиях.
|
||
- Автоматические рекомендации ТО по пробегу и времени, включая замену масла.
|
||
- Онлайн-запись в проверенное СТО: выбор услуги, свободного окна, комментарий и согласование времени.
|
||
- Мои записи: статусы requested, confirmed, proposed_new_time, cancelled, completed.
|
||
- OCR чеков и разбор свободного текста: пользователь проверяет найденные данные перед сохранением.
|
||
- История одометра: пробег обновляется из записей, а спорные значения требуют подтверждения.
|
||
|
||
## Для СТО
|
||
|
||
- Регистрация автосервиса через Mini App.
|
||
- Заявка на проверку и статус модерации.
|
||
- Модерация заявок: approved, rejected, needs changes, suspended.
|
||
- Публичная карточка СТО после подтверждения.
|
||
- Каталог СТО показывает только подтвержденные сервисы, город, специализации, рейтинг и ближайшее свободное окно.
|
||
- Кабинет СТО: подключенные авто, новые заявки, подтвержденные записи, активные заказ-наряды, выручка и предупреждения.
|
||
- Настройка графика: рабочие дни, часы, обед, праздники, длительность слота, параллельные записи и онлайн-запись.
|
||
- Календарь записей: заявки клиентов, подтверждение, отклонение, предложение нового времени.
|
||
- Создание заказ-наряда из подтвержденной записи на базе существующего `ServiceVisit`.
|
||
- Отзывы, рейтинг и ответы сервиса.
|
||
- Запрос доступа к конкретному автомобилю только с подтверждением владельца.
|
||
- Добавление визитов, работ и рекомендаций с аудитом действий.
|
||
|
||
## Запись и обслуживание
|
||
|
||
Если автомобиль уже привязан к СТО, владелец может открыть карточку авто и записаться сразу в календарь этого сервиса. Если привязки нет, пользователь выбирает СТО из каталога, смотрит свободные окна и создает заявку.
|
||
|
||
СТО получает уведомление о новой заявке, подтверждает время, отклоняет запись или предлагает другое окно. Когда запись подтверждена, она появляется в календаре СТО. После этого сервис создает заказ-наряд, добавляет работы, товары, жидкости, запчасти, комментарии и при необходимости отправляет заказ-наряд владельцу на согласование.
|
||
|
||
После закрытия заказ-наряда CarPass атомарно создает сервисную запись, расход автомобиля, историю одометра, рекомендации следующего ТО и уведомление владельцу. Завершенная работа появляется в истории автомобиля, а стоимость попадает в стоимость владения без двойного учета.
|
||
|
||
## Заказ-наряды СТО
|
||
|
||
Заказ-наряд хранит номер, СТО, автомобиль, владельца, сотрудника, пробег, жалобу клиента, диагностику, работы, материалы, рекомендации, комментарии, файлы, суммы работ и товаров, скидку, итог и статус. Поддержаны статусы `draft`, `diagnosis`, `waiting_owner_approval`, `approved_by_owner`, `rejected_by_owner`, `in_progress`, `completed`, `cancelled`, `archived`.
|
||
|
||
Завершенные заказ-наряды нельзя редактировать обычным способом. Если после согласования изменилась сумма, заказ-наряд возвращается на согласование владельцу.
|
||
|
||
## Рекомендации ТО
|
||
|
||
CarPass создает рекомендации обслуживания из данных автомобиля и истории работ. Сейчас базово поддержана плановая замена масла по интервалу пробега и времени, ручные рекомендации владельца и связь рекомендации с записью в СТО. Просроченные и близкие рекомендации получают приоритет, но формулируются мягко: пользователь видит действие “записаться”, а не тревожную ошибку.
|
||
|
||
## Уведомления
|
||
|
||
В системе создаются внутренние уведомления и, если настроен Telegram Bot Token, отправляются сообщения в Telegram:
|
||
|
||
- СТО получает новую заявку на запись, отмену клиента и решение по предложенному времени.
|
||
- Владелец получает подтверждение, отклонение или предложение нового времени.
|
||
- Владелец получает уведомления о создании заказ-наряда, ожидании согласования и завершении работы.
|
||
- Рекомендации ТО фиксируются в истории уведомлений.
|
||
|
||
Уведомления имеют статусы `pending`, `processing`, `sent`, `failed`, `retrying`, `abandoned`, `read`, счетчик повторов и idempotency key, чтобы не плодить дубли.
|
||
|
||
Telegram-уведомления являются основным каналом закрытого пилота. Browser push уже умеет сохранять подписки в Mini App и принимать push-события в service worker, но серверная Web Push-доставка помечена как beta и не считается критическим каналом пилота.
|
||
|
||
## Администрирование
|
||
|
||
Admin Control Center доступен по `/admin.html` и через команды бота `/admin`, `/admin_stats`, `/admin_users`, `/admin_sto`, `/admin_pending_sto`, `/admin_alerts`.
|
||
|
||
Админка включает dashboard сервиса, admin notifications, очередь заявок СТО, пользователей, автомобили, записи, заказ-наряды, audit log, экспорт и безопасный Data Explorer без произвольного SQL. Подробности по ролям, privacy, env и API описаны в [ADMIN.md](ADMIN.md).
|
||
|
||
## Безопасность данных
|
||
|
||
CarPass не раскрывает историю автомобиля по одному VIN или госномеру. СТО видит только разрешенный владельцем объем данных: базовую карточку, историю обслуживания или полный доступ. Любые чувствительные изменения, включая VIN, номер, пробег и технические параметры, проходят подтверждение владельца.
|
||
|
||
Чувствительные действия ограничены rate limiting: OCR, VIN/номер, запросы доступа к автомобилю, записи в СТО, приглашения сотрудников и отзывы. В production лимиты работают через Redis, а локально могут падать обратно на in-memory режим.
|
||
|
||
## Telegram Mini App
|
||
|
||
Mini App открывается через кнопку внутри Telegram-бота. Так Telegram передает защищенную авторизацию, а гараж привязывается к аккаунту пользователя. Если страницу открыть напрямую в браузере, CarPass покажет понятное приглашение открыть приложение через Telegram.
|
||
|
||
## Deploy
|
||
|
||
Production/pilot deploy описан в [DEPLOY.md](DEPLOY.md). Основной путь обновления сервера: git clone/pull, Docker Compose, Alembic migrations и `/ready` health check. Admin bootstrap выполняется через `ADMIN_TELEGRAM_IDS`, без hardcoded Telegram ID в миграциях.
|
||
|
||
Production-контур включает Redis-backed rate limiting, security headers, `/health`, `/ready`, Prometheus-ready `/metrics`, cleanup jobs, backup/restore скрипты и CI-шаблон для lint/tests/migrations/docker build.
|
||
|
||
## Команды бота
|
||
|
||
- `/start` и `/menu` — правильный вход в Mini App.
|
||
- `/garage` — список автомобилей.
|
||
- `/add_car` — быстрое добавление авто.
|
||
- `/fuel`, `/service`, `/insurance`, `/tax`, `/fine` — быстрые записи текстом.
|
||
- `/analytics` — стоимость владения и расход.
|
||
- `/sto`, `/register_sto` — каталог и регистрация СТО.
|
||
- `/appointments` — записи владельца в СТО.
|
||
- `/sto_bookings` — краткий отчет по заявкам и календарю СТО.
|
||
|
||
## Почему это полезно
|
||
|
||
Для владельца CarPass превращает хаотичные чеки и заметки в понятную картину расходов и обслуживания. Для сервиса это аккуратный канал взаимодействия с клиентом, подтвержденная история работ и доверие без лишнего доступа к персональным данным.
|