/**
 * @defgroup public_capital_level_up_notification_process Уведомление о переходе на новый уровень
 * @ingroup public_capital_processes
 * 
 * Процесс автоматического уведомления системы о достижении участником 
 * нового уровня в системе геймификации.
 * 
 * ## Назначение процесса
 * 
 * Когда энергия участника достигает 100%, происходит автоматический переход 
 * на следующий уровень. Система отправляет inline action уведомление, которое:
 * - Фиксирует факт перехода в истории блокчейна
 * - Может быть перехвачено контроллером для отправки push-уведомлений
 * - Содержит информацию о предыдущем и новом уровне для аналитики
 * 
 * \htmlonly
 * <div class="mermaid">
 * sequenceDiagram
 *     participant Contributor
 *     participant Capital_Contract
 *     participant External_System
 *     
 *     Note over Contributor: Вносит вклад в проект
 *     Contributor->>Capital_Contract: Действие приема результата
 *     Capital_Contract->>Capital_Contract: Обновление энергии
 *     
 *     alt Энергия >= 100%
 *         Capital_Contract->>Capital_Contract: level += 1<br/>energy = 0
 *         Capital_Contract->>Capital_Contract: inline action: lvlnotify
 *         Capital_Contract->>External_System: Уведомление о переходе уровня
 *         External_System->>Contributor: Push-уведомление<br/>"Поздравляем! Новый уровень!"
 *     end
 * </div>
 * \endhtmlonly
 * 
 * ## Пошаговое описание процесса
 * 
 * ### Шаг 1: Обнаружение перехода уровня
 * <b>Триггер:</b> Функция @ref Capital::Contributors::add_energy_and_check_levelup
 * 
 * При добавлении энергии система проверяет условие перехода:
 * ```cpp
 * if (energy >= 100.0) {
 *     level += 1;
 *     energy = 0.0;
 * }
 * ```
 * 
 * ### Шаг 2: Отправка inline action
 * <b>Действие:</b> @ref capital::lvlnotify "Уведомление о переходе уровня"
 * 
 * Система автоматически вызывает inline action с параметрами:
 * - `coopname` - кооператив участника
 * - `username` - имя участника
 * - `prev_level` - предыдущий уровень
 * - `new_level` - новый уровень
 * 
 * ### Шаг 3: Обработка внешними системами
 * <b>Интеграция:</b> Контроллер и система уведомлений
 * 
 * Внешние системы могут:
 * 1. Слушать действие `lvlnotify` в истории блокчейна
 * 2. Отправлять push-уведомления пользователям
 * 3. Обновлять статистику и достижения в интерфейсе
 * 4. Начислять дополнительные бонусы или награды
 * 
 * ## Данные уведомления
 * 
 * | Параметр | Тип | Описание |
 * |----------|-----|----------|
 * | `coopname` | name | Кооператив, в котором произошел переход |
 * | `username` | name | Участник, достигший нового уровня |
 * | `prev_level` | uint32_t | Предыдущий уровень участника |
 * | `new_level` | uint32_t | Новый достигнутый уровень |
 * 
 * ## Пример использования в контроллере
 * 
 * Контроллер может обрабатывать это событие следующим образом:
 * 
 * ```typescript
 * // Подписка на действие lvlnotify
 * contract.on('lvlnotify', async (data) => {
 *   const { coopname, username, prev_level, new_level } = data;
 *   
 *   // Отправка push-уведомления
 *   await notificationService.send(username, {
 *     title: '🎉 Поздравляем!',
 *     message: `Вы достигли ${new_level} уровня!`,
 *     type: 'level_up',
 *     data: { prev_level, new_level }
 *   });
 *   
 *   // Обновление достижений
 *   await achievementService.unlock(username, `level_${new_level}`);
 * });
 * ```
 * 
 * ## Когда происходит уведомление
 * 
 * Уведомление отправляется автоматически в следующих случаях:
 * 
 * 1. **При приеме результата проекта:**
 *    - Участник вносит результат интеллектуальной деятельности
 *    - Обновляются его рейтинги и вклады
 *    - Рассчитывается прирост энергии
 *    - Если энергия >= 100%, происходит переход уровня
 * 
 * ## Особенности реализации
 * 
 * 1. **Inline action:** Вызывается автоматически из контракта, 
 *    не требует отдельной транзакции.
 * 
 * 2. **Авторизация:** Требуется от аккаунта контракта (_capital), 
 *    не может быть вызвано извне напрямую.
 * 
 * 3. **Логирование:** Информация записывается в историю блокчейна 
 *    и доступна для аудита.
 * 
 * 4. **Асинхронность:** Обработка уведомления внешними системами 
 *    происходит асинхронно и не влияет на выполнение основного действия.
 * 
 * @post 
 *  - Отправлено уведомление о переходе уровня
 *  - Информация записана в историю блокчейна
 *  - Внешние системы могут обработать событие
 * 
 * @see Capital::Contributors::add_energy_and_check_levelup
 * @see Capital::Contributors::update_gamification_from_segment
 */

