/**

 * @defgroup public_capital_allocate_process Аллокация программных инвестиций
 * @ingroup public_capital_processes
 * 
 * Процесс, при котором кооператив аллоцирует инвестиции из программы "Благорост" в конкретный проект
 * для использования в выдаче ссуд и возврате себестоимости вложений создателям, авторам и координаторам.
 *  
 * @pre <b>Обязательные условия:</b>
 * - Положительный баланс свободных инвестиционных средств в программе "Благорост"
 * - Существующий и активный проект
 * - Авторизация от имени кооператива
 * 
 * \htmlonly
 * <div class="mermaid">
 * sequenceDiagram
 *     participant К as Кооператив
 *     participant Контракт as Capital Contract
 *     participant П as Программа благороста
 *     participant Пр as Проект
 *     
 *     К->>Контракт: 1. Запрос аллокации средств
 *     Note over Контракт: Проверка существования проекта
 *     Контракт->>П: 2. Получение баланса программы
 *     Note over П: Проверка наличия средств
 *     Контракт->>Пр: 3. Аллокация средств в проект
 *     Note over Пр: Обновление пула инвестиций проекта
 * </div>
 * \endhtmlonly
 * 
 * ## Пошаговое описание процесса
 * 
 * ### Шаг 1: Инициация аллокации средств
 * <b>Действие:</b> @ref capital::allocate "Аллокация инвестиций"
 * 
 * Кооператив инициирует процесс аллокации средств из программы "Благорост" в конкретный проект.
 * Это необходимо для использования средств в выдаче ссуд и возврате себестоимости вложений.
 * 
 * @note Авторизация требуется от аккаунта кооператива, подтверждая его
 * право распоряжаться средствами программы благороста
 * 
 * ### Шаг 2: Проверка существования проекта
 * <b>Действие:</b> Валидация целевого проекта
 * 
 * Система проверяет, что проект существует и доступен для аллокации средств.
 * Проект должен быть активным и принимать инвестиции (обладать установленным планом).
 * 
 * ### Шаг 3: Валидация суммы инвестиций
 * <b>Действие:</b> Проверка корректности суммы
 * 
 * Система проверяет, что сумма инвестиций корректна и соответствует требованиям:
 * - Сумма должна быть положительной
 * - Сумма не должна превышать доступный баланс программы
 * - Сумма должна соответствовать символу кооператива
 * 
 * ### Шаг 4: Аллокация средств в проект
 * <b>Действие:</b> Перевод средств из программы в проект

Система аллоцирует средства из глобального пула программных инвестиций в проект:
- Средства переводятся из кошелька программы благороста
- Средства зачисляются в пул инвестиций проекта
- Обновляется баланс программы благороста

@note Распределение аллоцированных средств между пулом расходов и инвестиционным пулом проекта определяется в конфигурации кооператива. Если у проекта есть плановые непокрытые расходы, то в накопительный пул расходов выделяется процент от аллоцированной суммы, который установлен в конфигурации контракта параметром @c expense_pool_percent. Например, если у кооператива установлено значение 20% для пула расходов, то при аллокации средств в размере 10000 руб, в пул расходов пойдет 2000 руб, а оставшиеся 8000 руб пойдут в инвестиционный пул для обеспечения себестоимости затрат участников. При этом, если плановый пул расходов уже достаточно покрыт, то вся сумма может пойти в инвестиционный пул.

 * ### Шаг 5: Активация использования средств
 * <b>Действие:</b> Интеграция в систему проекта
 * 
 * После аллокации средства становятся доступны для использования в проекте:
 * - Для выдачи ссуд участникам проекта
 * - Для возврата себестоимости вложений создателям, авторам и координаторам
 * 
 * @post После завершения процесса:
 * 1. Средства аллоцированы в проект
 * 2. Баланс программы благороста уменьшен
 * 3. Пул инвестиций проекта пополнен
 * 4. Средства доступны для использования в проекте
 * 
 */