Skip to content

workflows.md

Latest commit

 

History

History
123 lines (101 loc) · 8.6 KB

workflows.md

File metadata and controls

123 lines (101 loc) · 8.6 KB
Raw

Пользовательские сценарии

Первый вход в Mi Fitness

  1. Открыть портал (/) — без сохранённого состояния Mi Fitness синхронизация будет падать с ошибкой авторизации.
  2. Ввести email и пароль Xiaomi через POST /api/auth/login (portal/routers/auth.py:41).
  3. При обычном логине сервер сразу получает passToken и serviceToken и сохраняет их в MI_FITNESS_STATE_PATH (auth.json).
  4. Если Xiaomi требует капчу, push-подтверждение в приложении или двухшаговую проверку — login вернёт {"success": false, "action": "captcha" | "verification" | "step2", "verification_url": ...} (format_auth_error, portal/routers/auth.py:70); подтверждение нужно пройти вне портала (по verification_url) и повторить логин.

Синхронизация пробежек

  1. Вручную — кнопка «↻ Синхронизировать» в навигации (POST /api/sync), либо автоматически по расписанию (AUTO_SYNC_INTERVAL_HOURS, MORNING_SYNC_TIME).
  2. Портал запрашивает у Mi Fitness активности с даты последней сохранённой пробежки (при пустой БД — за последние 90 дней), отфильтровывает не-бег и дистанции короче 300 м.
  3. Каждая активность сохраняется (INSERT OR REPLACE) — новые учитываются в added, уже существующие — в updated.
  4. Если serviceToken/passToken истёк (Xiaomi отвечает 401), портал один раз пробует обновить сессию: сначала «тихим» рефрешем passToken, а если MI_FITNESS_PASSWORD задан в .env — ещё и повторным логином по паролю (refresh_auth_state, portal/sync.py:170). Без пароля в .env истёкшую сессию нужно обновлять вручную через /api/auth/login.
  5. Если за синхронизацию добавилась ровно одна новая пробежка — её детали (GPS-трек, посекундные пульс/темп) подгружаются сразу же. Если добавилось несколько — детали остаются недогруженными до ручного действия.
  6. Если после синхронизации что-то реально изменилось (added > 0 или updated > 0) и ошибок не было — портал сразу пересчитывает «ответ на сегодня».

Просмотр дашборда

/ показывает (каждая карточка включается/выключается в /settings):

  • Ответ на сегодня — последняя сохранённая рекомендация AI-тренера, с кнопками «промпт» (посмотреть использованный текст) и «обновить» (пересчитать без ожидания синхронизации).
  • Ключевые метрики, Прогресс формы (Efficiency Factor по неделям + scatter «темп vs пульс» в модалке), Цель на месяц с прогрессом и статусом (on_track / slightly_behind / behind), Дистанции последних 20 пробежек, Последние пробежки — постраничная таблица.

Загрузка деталей пробежки вручную

Кнопка «Загрузить все детали» на дашборде вызывает POST /api/activities/details/load-all: находит все активности без сохранённых деталей и последовательно догружает их одну за другой (portal/routers/activities.py:215). Долгая операция — выполняется синхронно в теле запроса, без прогресс-бара на бэкенде (только счётчик loaded/failed в ответе).

Просмотр детальной страницы пробежки

/activity/{activity_id}:

  1. Показывает сохранённые метрики и (если детали ещё не загружены) кнопку «Загрузить детали», вызывающую GET /api/activities/{id}/detail.
  2. График «Пульс и скорость по времени» переключается на «по дистанции» (chart-mode-toggle), плюс полоска Efficiency Factor по ходу тренировки.
  3. Пульсовые зоны — по длительностям hrm_*_duration.
  4. Карточка «AI тренер» — кнопка «Получить анализ» запускает потоковый (SSE) разбор конкретной пробежки; готовый разбор кэшируется и переоткрывается мгновенно при следующем визите, кнопка «Пересчитать анализ» форсирует новый запрос.

Получение цели на месяц

  1. GET /api/goals/monthly — текущая цель (если задана) и прогресс.
  2. GET /api/goals/monthly/suggest — просит AI (или, при сбое, эвристику по истории) предложить km_goal/runs_goal вместе с консервативным и амбициозным вариантом.
  3. POST /api/goals/monthly — сохраняет выбранную (или отредактированную вручную) цель на конкретный year/month.

Ведение журнала состояния

/health — список записей с периодом действия (started_at, опционально ended_at) и свободным текстовым описанием. Записи можно добавлять, редактировать и удалять (POST/PUT/DELETE /api/health-states...). Последние три активные/недавние записи автоматически попадают во все три AI-промпта — отдельно подтверждать это на каждом экране не нужно.

Обновление авторизации Claude CLI

Когда AI-функции начинают падать с истёкшей OAuth-сессией CLI, дашборд показывает ошибку с кнопкой «Войти в Claude», ведущей на /claude-auth:

  1. Через логин-URL — POST /api/claude-auth/login-url запускает claude auth login как subprocess, вычитывает из его stdout OAuth-ссылку и возвращает session_id + login_url; после перехода по ссылке и получения кода — POST /api/claude-auth/login-code дописывает код в stdin того же процесса и завершает вход.
  2. Вручную — POST /api/claude-auth с готовым claudeAiOauth токеном напрямую перезаписывает ~/.claude/.credentials.json (запасной путь, если первый способ недоступен).

Подробности потоков и рисков — в docs/ai-assistant.md.

Изменение настроек

/settings — редактирование двух из трёх prompt-шаблонов (для «ответа на сегодня» и для разбора пробежки; шаблон предложения цели на месяц не редактируется через UI), целевой пульсовой зоны для графика детальной страницы и видимости карточек дашборда. Сохранение — POST /api/settings, применяется к следующей генерации промпта, уже сгенерированные и закэшированные ответы не пересчитываются автоматически.