Stsezhka

Appearance

Use Case #UC-027.3: Обслуживание, Аварийные оповещения и Корректировка пробега 🛠️ ​

1. Жизненная ситуация (Боль пользователя) ​

Представь: Велосипедист использует дорогую амортизационную вилку Fox 36. Производитель требует проводить базовое обслуживание (замену масла в штанах) каждые 50 часов налета, а полное обслуживание с заменой сальников — каждые 125 часов. При этом общий срок службы вилки до списания составляет десятки тысяч километров. Также бывает ситуация, когда пользователь забыл включить запись поездки на телефоне, или наоборот, прокатился на другом байке с этим же измерителем мощности. Ему нужно вручную скорректировать пробег детали, добавив или отняв "лишние" километры.

Как он мучается сейчас: Обычные трекеры позволяют только "сбросить" пробег детали до нуля. Пользователь не может сделать регулярное ТО (которое сбрасывает сервисный интервал), сохранив общий пробег детали за все годы службы. А ручная корректировка пробега отдельных деталей вообще невозможна: приходится вручную пересчитывать пробеги в уме.

Мечта юзера: Видеть два независимых трекера на карточке детали: "Срок службы" (Lifespan) и "Межсервисный интервал" (Service). Обслужил вилку? Нажал одну кнопку — сервисный интервал обнулился, а общий пробег остался нетронутым. Проехал тренировку без записи? Открыл модальное окно и ввел: +120 км. Все счетчики обновились автоматически.

2. Как это ДОЛЖНО работать у тебя (UX-Магия) ​

Интуитивно понятные шкалы износа и мгновенные действия.

Сценарий (Что видит юзер):

  1. На карточке каждого компонента в гараже отображаются две красивые полосы прогресса:
    • Lifespan (Толстая шкала): Общий ресурс детали (например, 4500 / 5000 км).
    • Service (Тонкая шкала): Ресурс до следующего ТО (например, 80 / 100 часов).
  2. Умный выбор приоритета шкал: Если деталь отслеживает и километры, и часы (например, вилка), шкала автоматически рассчитывает износ по обоим параметрам и показывает тот, который ближе к критическому порогу 100% (по принципу "где тоньше, там и рвется").
  3. Цветовая палитра износа (HSL-логика):
    • Зеленый (Безопасно): От 0% до 74.9% — деталь свежая.
    • Желтый (Внимание): От 75% до 89.9% — скоро потребуется обслуживание.
    • Красный (Критично): >= 90% — износ превышен, требуется срочное вмешательство.
  4. В контекстном меню детали (три точки ⋮) доступны два быстрых действия:
    • 💧 [ Провести обслуживание ]: Обнуляет текущий сервисный пробег/часы с красивой анимацией успеха.
    • ⚖️ [ Скорректировать пробег ]: Открывает модальное окно для ввода положительной или отрицательной корректировки пробега (deltaKm, deltaHours).

3. СЕКРЕТ ДЛЯ ПРОГРАММИСТА (Интервалы, шкала и математическое ограничение) ​

Обработка ручных действий и расчеты производятся с помощью специализированных Hono API эндпоинтов:

  1. 💧 Сброс сервисного интервала (POST /api/components/:id/service):

    • Устанавливает поля currentServiceKm и currentServiceHours в 0.
    • Обновляет дату последнего обслуживания lastServiceDate на текущее время.
    • Важно: Поля currentLifespanKm и currentLifespanHours остаются абсолютно нетронутыми!

  2. ⚖️ Корректировка пробега (POST /api/components/:id/adjust):

    • Принимает тело запроса { deltaKm?: number, deltaHours?: number }.
    • Значения дельт могут быть как положительными, так и отрицательными (для скручивания ошибочно начисленного износа).
    • Прибавляет deltaKm одновременно к двум счетчикам километров (currentLifespanKm и currentServiceKm).
    • Прибавляет deltaHours одновременно к двум счетчикам часов (currentLifespanHours and currentServiceHours).

4. Защита от "дурака" (Математическое ограничение пробега не ниже 0) ​

Ловушка: "Отрицательный пробег" ​

Проблема: Если пользователь скорректирует пробег на -500 км при текущем пробеге цепи 300 км, математическое сложение выдаст -200 км. Отрицательный износ сломает логику шкал прогресса и может вызвать падение рендеринга на клиенте. Решение:

  • Защитный зажим (Clamping): На бэкенде в эндпоинте /adjust после прибавления дельты результат математически зажимается встроенной функцией Math.max(0, newValue). Износ детали физически никогда не может опуститься ниже ровно 0.0.

Эпики и Задачи (Epics & Tasks) ​

Epic 1: Действия над компонентами на Бэкенде (apps/api) ​

  • Task 1.1: Реализовать эндпоинт /service для сброса сервисных счетчиков.
  • Task 1.2: Реализовать эндпоинт /adjust с поддержкой отрицательных дельт и жестким ограничением Math.max(0, value).

Epic 2: Визуальный движок износа и Шкалы (apps/web) ​

  • Task 2.1: Разработать универсальный математический модуль расчета наихудшего износа (Tie-Breaker Km/Hours).
  • Task 2.2: Создать динамический генератор цветов шкал прогресса на основе процентных порогов (Зеленый 75% -> Желтый 90% -> Красный).
  • Task 2.3: Сверстать двойные шкалы износа (Lifespan + Service) на карточке детали.

Epic 3: Модальные окна действий ​

  • Task 3.1: Интегрировать действие "Провести обслуживание" с оптимистичным обновлением состояния во фронтенд-хранилище.
  • Task 3.2: Разработать модальное окно корректировки пробега с удобными полями ввода дельт.

Epic 4: Тестирование и надежность ​

  • Task 4.1: Написать юнит-тесты на модуль расчета цвета и приоритета шкал (Tie-Breaker).
  • Task 4.2: Покрыть тестами бэкенд-математику корректировок износа (особенно зажим на нулевом пробеге).