/**

 * @defgroup public_capital_project_investment_process Инвестиции в проект
 * @ingroup public_capital_processes

 * Процесс привлечения денежных средств от участников в конкретный проект.
 * Инвестиции распределяются между инвестиционным пулом и пулом расходов
 * в соответствии с настройками кооператива. Процесс включает создание заявки
 * на инвестицию и автоматическое распределение средств по пулам проекта.

 * @note КРИТИЧЕСКИ ВАЖНО: Чистые инвесторы (только роль инвестора) НЕ вносят результат через pushrslt.
 * После завершения проекта они конвертируют свой сегмент напрямую через convertsegm.

 * ## Диаграмма процесса

 * \htmlonly
 * <div class="mermaid">
 * sequenceDiagram
 *     participant Инвестор
 *     participant Контракт благороста
 *     participant Контракт кошелька

 *     Инвестор->>Контракт благороста: 1. Подача заявления на инвестицию
 *     Note over Контракт благороста: Списание с доступного остатка кошелька программы
 *     Note over Контракт благороста: Расчёт доли координатора (если есть)
 *     Контракт благороста->>Контракт кошелька: 2. Списание с кошелька программы и зачисление на кошелёк программы благороста (заблокировано)
 *     Note over Контракт благороста: Распределение по пулам:
 *     Note over Контракт благороста: - Часть на расходы (expense_pool_percent)
 *     Note over Контракт благороста: - Остаток в инвестиционный пул
 *     Note over Контракт благороста: Расчёт координаторской премии
 *     Note over Контракт благороста: Обновление коэффициентов проекта
 *     Note over Контракт благороста: ВЗНОС ИНВЕСТОРА ЗАВЕРШЕН
 *     Note over Инвестор: Чистый инвестор НЕ вносит результат через pushrslt
 * </div>
 * \endhtmlonly

 * ## Пошаговое описание

 * ### Шаг 1: Создание инвестиции в проект
 * @ref capital::createinvest "Создание инвестиции в проект"

 * Инвестор подаёт заявку на инвестирование в проект, которая автоматически обрабатывается:

 * <b>Входящий документ:</b> Заявление на зачёт части паевого взноса с доступного остатка кошелька программы на проект

 * <b>Предварительные условия:</b>
 * - Проект открыт для инвестиций
 * - На кошельке программы благороста достаточно средств в доступном остатке
 * - Инвестор подписал приложение к договору УХД для данного проекта

 * <b>Немедленные действия:</b>
 * @post ➖🔓 Списать сумму с доступного остатка на кошельке программы благороста

 * <b>Производится расчёт координаторского вклада, если у инвестора указан координатор</b>
 * @note Координатор получает вознаграждение только в случае, если привлек инвестиции, зарегистрировав инвестора по реферальной ссылке за период, меньший чем установленный в конфигурации кооператива (по умолчанию 30 дней). Координатор получает возможность совершить вклад в результат на 4% (по умолчанию) от суммы инвестиций только пока инвестор инвестирует в течение этого периода. После истечения периода координатор не получает вознаграждение.

 * <b>Проводки по кошелькам:</b>
 * @post ➕🔒 Зачислить сумму заблокированными на кошелёк программы благороста

 * <b>Распределение по пулам проекта:</b>
 * - <b>На расходы:</b> часть средств направляется в пул расходов проекта
 * - <b>В инвестиционный пул:</b> остаток средств направляется в инвестиционный пул

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

 * <b>Обновление показателей проекта:</b>
 * @post увеличение накопленного пула расходов проекта
 * @post увеличение инвестиционного пула проекта
 * @post увеличение общих полученных инвестиций проекта

 * <b>Перерасчёт коэффициентов:</b>
 * @post пересчет процента возврата базовых средств
 * @post пересчет процента использования инвестиций

 * <b>Обновление сегментов:</b>
 * - Инвестор: увеличение суммы инвестиций, пересчёт предварительной суммы, установка флага is_investor
 * - Координатор (если есть): увеличение базовой суммы координатора, пересчёт предварительной суммы

 * @note ВАЖНО: Инвестиция является ПОЛНЫМ взносом инвестора в проект. Чистые инвесторы (без других ролей)
 * НЕ должны вносить результат через pushrslt, так как их взнос уже учтен. После завершения проекта
 * чистый инвестор может сразу конвертировать свой сегмент через convertsegm.

 * ### Шаг 2: Возврат неиспользованных инвестиций
 * @ref capital::returnunused "Возврат неиспользованных инвестиций"

 * После завершения проекта инвестор может вернуть неиспользованные средства:

 * <b>Предварительные условия:</b>
 * - Проект завершен (статус COMPLETED)
 * - Инвестор является участником проекта
 * - Есть неиспользованные средства для возврата

 * <b>Проводки:</b>
 * @post 🔓 Добавить доступный баланс в главный кошелек
 * @post уменьшение заблокированного баланса в кошельке проекта

 * <b>Обновление показателей:</b>
 * @post увеличение суммы возвращенных инвестиций проекта
 * @post корректировка фактически использованной суммы инвестиций

 ## Эффекты процесса
 @include{doc} createinvest-effect.dox

 ## Документы процесса
  @include{doc} project-investment-docs.dox
 *


 * ## Связанные процессы

 * - @ref public_capital_planning_process "Планирование проекта" - план определяет потребность в инвестициях
 * - @ref public_capital_debt_process "Управление ссудами" - инвестиции обеспечивают ссуды
 * - @ref public_capital_unused_return_process "Возврат неиспользованных средств" - возврат неиспользованной части
 * - @ref public_capital_result_process "Приём результата" - инвестиции участвуют в благороста

 */