/**
 * @defgroup public_capital_refresh_contributor_process Обновление энергии участника
 * @ingroup public_capital_processes
 * 
 * Процесс обновления энергии участника с учетом естественного снижения (decay) 
 * в системе геймификации "Уровень и Энергия".
 * 
 * ## Назначение процесса
 * 
 * Энергия участника естественным образом снижается со временем, стимулируя 
 * регулярную активность в кооперативе. Данный процесс обновляет текущее значение 
 * энергии участника на основе:
 * - Времени с последнего обновления
 * - Настроенной скорости снижения энергии (energy_decay_rate_per_day)
 * 
 * Процесс не добавляет энергию - прирост энергии происходит автоматически 
 * при внесении вкладов через другие операции контракта.
 * 
 * \htmlonly
 * <div class="mermaid">
 * sequenceDiagram
 *     participant Кооператив
 *     participant Capital_Contract
 *     participant Contributor_Table
 *     
 *     Кооператив->>Capital_Contract: 1. Запрос обновления энергии
 *     Note over Capital_Contract: Проверка авторизации
 *     Capital_Contract->>Contributor_Table: 2. Получение данных участника
 *     Capital_Contract->>Capital_Contract: 3. Расчет decay
 *     Note right of Capital_Contract: days_passed = (current_time - last_update) / 86400<br/>decay = days_passed × decay_rate_per_day
 *     Capital_Contract->>Contributor_Table: 4. Обновление энергии
 *     Note right of Contributor_Table: energy = max(0, energy - decay)<br/>last_energy_update = current_time
 *     Capital_Contract-->>Кооператив: Энергия обновлена
 * </div>
 * \endhtmlonly
 * 
 * ## Пошаговое описание процесса
 * 
 * ### Шаг 1: Авторизация кооператива
 * <b>Действие:</b> Проверка авторизации от имени кооператива
 * 
 * Только кооператив может обновлять энергию участников. Это централизованная 
 * операция обслуживания системы геймификации.
 * 
 * ### Шаг 2: Получение данных участника
 * <b>Действие:</b> @ref capital::refreshcontr "Обновление энергии участника"
 * 
 * Система загружает текущее состояние участника из таблицы contributors,
 * включая:
 * - Текущий уровень энергии (energy)
 * - Время последнего обновления (last_energy_update)
 * 
 * ### Шаг 3: Расчет естественного снижения (decay)
 * <b>Формула расчета:</b>
 * 
 * 1. Рассчитывается количество прошедших дней:
 * \f[
 * days\_passed = \frac{current\_time - last\_energy\_update}{86400}
 * \f]
 * 
 * 2. Применяется decay на основе настроенной скорости:
 * \f[
 * decay = days\_passed \times energy\_decay\_rate\_per\_day
 * \f]
 * 
 * 3. Обновляется энергия:
 * \f[
 * new\_energy = max(0.0, current\_energy - decay)
 * \f]
 * 
 * ### Шаг 4: Сохранение обновленного состояния
 * <b>Действие:</b> Запись в таблицу @ref Capital::contributor
 * 
 * Система сохраняет:
 * - Новое значение энергии
 * - Текущее время как last_energy_update
 * 
 * ## Параметры геймификации
 * 
 * Процесс использует следующие параметры из конфигурации:
 * 
 * | Параметр | По умолчанию | Описание |
 * |----------|--------------|----------|
 * | `energy_decay_rate_per_day` | 1.11% | Скорость снижения энергии в день |
 * 
 * **Примеры настройки:**
 * - **1.11%** - энергия снизится до 0 за 90 дней (3 месяца) без активности
 * - **2.0%** - более агрессивное снижение за 50 дней
 * - **0.5%** - мягкое снижение за 200 дней
 * 
 * ## Взаимосвязь с другими процессами
 * 
 * **Прирост энергии:**
 * Энергия увеличивается автоматически при:
 * - @ref public_capital_result_process "Приёме результата в кооператив"
 * 
 * В этих процессах после обновления рейтингов вызывается 
 * @ref Capital::Contributors::update_gamification_from_segment, 
 * который рассчитывает прирост энергии от вкладов.
 * 
 * **Переход на новый уровень:**
 * Когда энергия достигает 100%, участник автоматически переходит 
 * на следующий уровень и получает уведомление через действие 
 * @ref capital::lvlnotify "lvlnotify".
 * 
 * ## Примечания по использованию
 * 
 * 1. **Регулярность обновления:** Рекомендуется вызывать это действие 
 *    периодически (например, раз в день) для всех активных участников.
 * 
 * 2. **Автоматизация:** Может быть реализовано через планировщик задач 
 *    на стороне контроллера.
 * 
 * 3. **Оптимизация:** Обновление не требуется, если участник недавно 
 *    вносил вклады - в этом случае энергия уже актуальна.
 * 
 * @post 
 *  - Энергия участника обновлена с учетом прошедшего времени
 *  - Время последнего обновления установлено в текущее время
 *  - Энергия не может быть меньше 0
 * 
 */

