Всем привет! Я, как и многие здесь, не только разработчик, но и человек, увлеченный циклическими видами спорта. Я обожаю копаться в данных своих тренировок из Strava: анализировать мощность, пульсовые зоны, темп. Но мне всегда не хватало одной вещи — единой, понятной и, главное, прозрачной метрики, которая бы отвечала на простой вопрос: "А насколько я сейчас в хорошей форме?".

Конечно, есть VO2max, есть Fitness & Freshness от Strava, есть GFR у Garmin. Но мне всегда хотелось создать что-то свое. Метрику, которую я бы понимал от и до, от первой строчки кода до финальной цифры на экране.

Так в рамках моего pet-проекта The Peakline это платформы для аутдор-энтузиастов родилась идея PeakLine Score (PLS). Это моя попытка создать комплексную оценку производительности, которая учитывает не только твою скорость, но и сложность маршрута, по которому ты ехал.

В этой статье я расскажу, как устроен этот механизм "под капотом". Мы погрузимся в логику на Python, посмотрим, как она интегрируется в общий анализатор активностей и как результат подается пользователю в простом и понятном виде.

Важный дисклеймер: Весь проект, от идеи до кода, я делаю один в свободное от основной работы время. Он далек от идеала, и я буду очень благодарен за конструктивную критику и свежий взгляд.

Приглашаю вас изучить сам проект:

• Основной проект The Peakline: https://www.thepeakline.com/

• Репозиторий на GitHub: https://github.com/CyberScoper/peakline-peakline-score

• Демо страницы со Score: https://www.thepeakline.com/peakline-score (необходима авторизация в аккаунт Strava)

А теперь — к техническим деталям.

Архитектура: Python-мозг и HTML-лицо

Когда ты делаешь проект в одиночку, простота и четкое разделение ответственности — ключ к выживанию. Я не стал усложнять и построил архитектуру по классической схеме: бэкенд на Python (Flask) отвечает за всю логику, а фронтенд — это легковесный HTML, отрисованный с помощью серверного шаблонизатора Jinja2.

Чтобы не утонуть в коде, я разделил логику PLS на три четких, независимых компонента:

/folder1/
├── activity_analyzer.py  # "Интегратор"
└── peakline_score.py     # "Мозг" - вся математика здесь

/folder1/
└── peakline_score.html   # "Лицо" - представление данных

1. peakline_score.py (Мозг): Чистый Python-модуль, ядро всей системы. Он ничего не знает о Strava, веб-серверах или базах данных. Его задача — принять на вход числовые данные об активности и вернуть числовой балл. Максимально изолированный и тестируемый.

2. activity_analyzer.py (Интегратор): Этот модуль — дирижер оркестра. Он забирает "сырые" данные из Strava, проводит их через разные анализаторы (расчет зон мощности, пульса) и, в том числе, передает их в peakline_score.py для расчета PLS. Его задача — элегантно встроить новую фичу в существующий конвейер.

3. peakline_score.html (Лицо): Jinja2-шаблон. Он получает с бэкенда готовый словарь с данными PLS и отвечает только за то, чтобы красиво и понятно их показать пользователю.

Такой подход позволяет мне легко дорабатывать каждый компонент по отдельности.

peakline_score.py: Математика "супер-атлета"

Это сердце всей системы. Как объективно оценить результат? Проехать 100 км по плоской трассе за 3 часа — это одно, а проехать 70 км с набором высоты 2000 метров за то же время — совсем другое.

Идея проста: а что, если сравнить время пользователя со временем, которое показал бы на этом же маршруте гипотетический "идеальный" спортсмен?

Сначала я определил параметры этого "супер-атлета" — константный объект с показателями атлета мирового уровня.

# /utils/peakline_score.py
class PeakLineScoreCalculator:
    def __init__(self):
        self.SUPER_ATHLETE_PARAMS = {
            'ftp': 400,
            'max_speed_flat': 55,
            'climbing_power': 6.5,
            'weight': 70,
            # ... и другие параметры
        }

Затем я написал функцию calculateideal_time, которая оценивает, за сколько бы этот "супер-атлет" проехал маршрут. Логика учитывает два ключевых фактора: время на равнине и "штраф" за набор высоты.

# /utils/peakline_score.py (упрощенно)
def _calculate_ideal_time(self, distance_km: float, elevation_gain: float, activity_type: str):
    base_speed_kmh = self.SUPER_ATHLETE_PARAMS['max_speed_flat']
    climbing_penalty = 0.3  # минут на 100м набора высоты для велосипеда

    flat_time_hours = distance_km / base_speed_kmh
    elevation_penalty_hours = (elevation_gain / 100) * climbing_penalty / 60
    
    terrain_coefficient = self._get_terrain_coefficient(distance_km, elevation_gain)
    
    ideal_time = (flat_time_hours + elevation_penalty_hours) * terrain_coefficient
    return ideal_time

Функция getterrain_coefficient дополнительно классифицирует маршрут (flat, rolling, hilly, mountain) и вводит небольшой повышающий коэффициент для более сложного рельефа.

Теперь, имея actual_time и ideal_time, формула расчета балла становится элементарной:

pls_points = (ideal_time / actual_time) * 1000

Если проехал как "супер-атлет" — получаешь 1000 баллов. Вдвое медленнее — 500. Просто и прозрачно.

activity_analyzer.py: Интеграция без боли

Новая фича не должна ломать старую логику. У меня уже был большой модуль activity_analyzer.py, который выполнял полный анализ тренировки: запрашивал данные из Strava, считал зоны мощности, пульса, получал погоду. Задача — встроить расчет PLS в этот процесс, не создавая хаоса.

Я решил эту задачу с помощью небольшой вспомогательной функции add_pls_to_activity_analysis. Она работает как последний шаг в конвейере анализа.

# /utils/activity_analyzer.py
from .peakline_score import add_pls_to_activity_analysis

async def analyze_activity(activity_id: str, strava_user_id: int):
    # ... здесь происходит весь основной анализ ...
    # ... получение данных из Strava, расчет зон и т.д. ...
    
    # В конце, когда все данные собраны в analysis_results:
    set_cached_analysis(int(activity_id), strava_user_id, analysis_results)
    
    # Добавляем PeakLine Score к анализу
    analysis_results = add_pls_to_activity_analysis(analysis_results)
    
    logger.info(f"Analysis for activity {activity_id} completed successfully.")
    return analysis_results

Сама функция-обертка add_pls_to_activity_analysis просто извлекает уже посчитанные данные из общего объекта анализа, передает их в наш калькулятор PeakLineScoreCalculator и добавляет результат в новый ключ peakline_score.

# /utils/peakline_score.py
def add_pls_to_activity_analysis(analysis_data: Dict[str, Any]) -> Dict[str, Any]:
    # ... проверка, что данные существуют ...
    
    details = analysis_data['details']
    activity_data = {
        'distance': details.get('distance', 0),
        'moving_time': details.get('moving_time', 0),
        'total_elevation_gain': details.get('total_elevation_gain', 0),
        # ... и другие необходимые поля
    }
    
    pls_data = calculate_peakline_score_for_activity(activity_data)
    
    if pls_data:
        analysis_data['peakline_score'] = pls_data
    
    return analysis_data

Такой подход "декоратора" позволил добавить новую сложную логику, практически не изменяя основной код анализатора.

peakline_score.html: От цифр к эмоциям

Сухие цифры на бэкенде — это лишь полдела. Важно было подать их пользователю так, чтобы это мотивировало, а не расстраивало. Здесь в игру вступает шаблонизатор Jinja2.

Бэкенд передает в шаблон один большой объект pls_data. А дальше магия происходит прямо в HTML. Например, главный балл выводится одной строкой:

<div class="pls-score-display">{{ pls_data.overall_pls_score }}</div>
<div class="pls-level">{{ pls_data.performance_level }}</div>

Таблица с лучшими результатами генерируется в цикле, что делает код чистым и лаконичным:

    {% for score in pls_data.top_scores %}
    
        
            <a class="activity-link" href="/activity/{{ score.activity_id }}">
                {{ score.activity_name }}
            </a>
        
        {{ score.date[:10] }}
        
            {% if score.terrain_type == 'hilly' %}
                <span class="terrain-icon">⛰️</span>{{ T.pls_terrain_hilly }}
            {% else %}
                ...
            {% endif %}
        
        <strong>{{ score.pls_points }}</strong>
    
    {% endfor %}

А блок с рекомендациями использует простую if/elif/else логику, чтобы давать разные советы в зависимости от уровня пользователя. Это делает страницу "живой" и персонализированной.

<div class="improvement-tip">
    <h3>{{ T.pls_recommendations_title }}</h3>
    {% if pls_data.overall_pls_score &lt; 600 %}
        <p><strong>{{ T.pls_recommendations_tips_title }}</strong></p>
        <ul>...</ul>
    {% elif pls_data.overall_pls_score &lt; 800 %}
        <p><strong>{{ T.pls_recommendations_excellent_title }}</strong></p>
        <ul>...</ul>
    {% else %}
        <p><strong>{{ T.pls_recommendations_great_job }}</strong></p>
    {% endif %}
</div>

Под капотом "Общего рейтинга": Как из хаоса тренировок рождается единый балл

Самая интересная часть — это не оценка одной тренировки, а вычисление общего рейтинга атлета. Ведь одна случайная супер-успешная гонка не должна определять весь его уровень. Здесь я подсмотрел идею у Garmin с их GFR Score, но реализовал ее по-своему.

Алгоритм в функции calculate_user_pls_score состоит из пяти простых шагов:

1. Анализ: Скрипт перебирает все доступные тренировки пользователя.

2. Расчет: Для каждой вычисляется индивидуальный PLS-балл.

3. Сортировка: Все результаты сортируются по убыванию — от лучших к худшим.

4. Выборка: Из всего списка берутся только 6 лучших результатов. Это позволяет отсеять неудачные или восстановительные тренировки, которые не отражают пиковую форму.

5. Усреднение: Итоговый PeakLine Score — это простое среднее арифметическое этих шести лучших показателей.

Вот как это выглядит в коде:

# /utils/peakline_score.py
def calculate_user_pls_score(self, user_activities: List[Dict[str, Any]]):
    if not user_activities:
        return None
    
    pls_scores = []
    for activity in user_activities:
        score_data = self.calculate_score(activity)
        if score_data:
            pls_scores.append({ ... }) # Собираем все результаты
    
    if not pls_scores:
        return None
    
    # 3. Сортируем по баллам (лучшие сначала)
    pls_scores.sort(key=lambda x: x['pls_points'], reverse=True)
    
    # 4. Берем топ-6 результатов
    top_scores = pls_scores[:6]
    
    if not top_scores:
        return None
        
    # 5. Рассчитываем средний балл
    average_pls = sum(score['pls_points'] for score in top_scores) / len(top_scores)
    
    return {
        'overall_pls_score': round(average_pls, 1),
        'performance_level': self._get_performance_level(int(average_pls)),
        'top_scores': top_scores,
        'total_activities_analyzed': len(pls_scores),
    }

Этот подход показался мне наиболее сбалансированным. Он отражает реальный потенциал, но при этом достаточно стабилен и не скачет от одной неудачной тренировки.

Трудности на пути соло-разработчика

Когда ты один на один с проектом, проблемы приобретают особый вкус.

1. Подбор коэффициентов. Самым сложным было найти "правильные" цифры для SUPER_ATHLETE_PARAMS и "штрафов" за рельеф. Я потратил несколько вечеров, сравнивая свои результаты с результатами профессионалов на известных сегментах Strava. Это была настоящая исследовательская работа, чтобы добиться адекватной и правдоподобной оценки.

2. "Грязные" данные из API. Не у всех активностей есть данные о наборе высоты. Иногда GPS-трек может быть неточным. Пришлось заложить в код множество проверок вроде details.get('total_elevation_gain', 0), чтобы одна "сломанная" тренировка не обрушила весь анализ пользователя.

3. Сделать фичу мотивирующей. Изначально шкала была слишком жесткой, и большинство пользователей получали бы "обидные" 300-400 баллов. Я понял, что продукт должен вдохновлять. Поэтому я доработал формулу и добавил текстовые уровни ('Elite', 'Excellent', 'Good'), а также тот самый блок с рекомендациями, чтобы система не просто ставила оценку, а подсказывала, как стать лучше.

Что дальше? Планы развития

PeakLine Score — это только начало. У меня в планах:

• Учет большего числа факторов: Добавить в формулу влияние погоды (ветер, температура), данные о которой я уже получаю для детального анализа активности.

• Динамика во времени: Строить график изменения PLS, чтобы пользователь видел свой прогресс наглядно.

• Разделение по видам спорта: Создать отдельные рейтинги для бега и велоспорта, так как сравнивать их напрямую некорректно.

Заключение и призыв к действию

Создание своей собственной аналитической метрики — это увлекательнейшее путешествие на стыке программирования и предметной области (в моем случае — спорта). PeakLine Score — это моя первая попытка сделать что-то подобное, и я уверен, что формулу еще можно и нужно улучшать.

И здесь мне очень нужна ваша помощь.

Призыв №1: Оцените идею. Как вам сама концепция? Какие факторы вы бы добавили в расчет? Может, у вас есть идеи, как сделать оценку еще точнее и полезнее?

Призыв №2: Поделитесь своим мнением. Мне очень важно услышать ваше мнение о проекте The Peakline в целом. Нужны ли такие нишевые инструменты для спортсменов-любителей?

Спасибо, что дочитали эту длинную статью. Буду рад любому фидбэку в комментариях!