/**

 * @defgroup public_capital_debt_process Выдача ссуды
 * @ingroup public_capital_processes
 * 
 * Процесс выдачи беспроцентных ссуд Участникам проекта на основании их трудовых
 * и иных вкладов. Ссуды ограничены provisional_amount сегмента и погашаются
 * автоматически при внесении результата в кооператив.
 * 
 * ## Назначение процесса
 * 
 * Система ссуд обеспечивает Участникам компенсацию трудозатрат в процессе работы над проектом:
 * - Участники получают средства до завершения проекта
 * - Размер ссуды ограничен фактическими вкладами и привлечёнными инвестициями
 * - Ссуды беспроцентные, что стимулирует активное участие
 * - Ссулы автоматически погашаются при внесении результата исключает проблемы с возвратом
 * 
 * ## Математические основы расчёта ссуд
 * 
 * ### Базовая формула доступной себестоимости
 *  Доступная себестоимость - это себестоимость труда, которую участник может использовать для получения ссуды. 
 *
 * ``` cpp
 * provisional_amount = (creator_base + author_base + coordinator_base) × (return_base_percent / 100)
 * ``` 
 *
 * где:
 * - creator_base - стоимость коммитов создателя
 * - author_base - авторская себестоимость (61.8% от создателей)  
 * - coordinator_base - координаторская премия от привлечённых инвестиций
 * - return_base_percent - коэффициент доступности средств (зависит от количества инвестиций)
 * 
 * ### Ограничения на выдачу
 * - Долг Участника по проекту меньше доступной себестоимости (debt_amount < provisional_amount)
 * - Участник находится в одной из или нескольких ролях: автор, исполнитель или координатор
 *
 * ## Диаграмма процесса
 * 
 * \htmlonly
 * <div class="mermaid">
 * sequenceDiagram
 *     participant P as Участник
 *     participant C as Capital Contract
 *     participant S as Soviet Contract
 *     participant G as Gateway Contract
 *     participant L as Loan Contract
 *     
 *     P->>C: 1. createdebt(заявление на ссуду)
 *     Note over C: Проверка лимитов
 *     Note over C: debt_amount + amount ≤ provisional_amount
 *     Note over C: Увеличение debt_amount в сегменте участника
 *     
 *     C->>S: 2. soviet::create_approval
 *     
 *     alt Предварительное одобрение председателем
 *         S->>C: 3. approvedebt()
 *         C->>S: 4. soviet::create_agenda
 *         
 *         alt Решение совета
 *             S->>C: 5. debtauthcnfr(решение совета)
 *             C->>G: 6. Gateway::create_outcome(платёж)
 *             
 *             alt Успешная оплата
 *                 G->>C: 7. debtpaycnfrm()
 *                 C->>L: 8. Создание записи о долге
 *                 Note over C: Долг зафиксирован
 *             else Отказ оплаты
 *                 G->>C: 7. debtpaydcln()
 *                 Note over C: Уменьшение debt_amount
 *             end
 *             
 *         else Отклонение советом
 *             S->>C: 5. declinedebt()
 *             Note over C: Уменьшение debt_amount
 *         end
 *         
 *     else Отклонение председателем
 *         S->>C: 3. declinereg()
 *         Note over C: Уменьшение debt_amount
 *     end
 *     
 *     Note over P,L: Погашение при внесении результата
 *     P->>C: 9. pushrslt(с суммой долга)
 * </div>
 * \endhtmlonly
 * 
 * ## Пошаговое описание
 * 
 * ### Шаг 1: Создание заявления на получение ссуды
 * 
 * Участник подаёт заявление на получение беспроцентной ссуды через действие @ref capital::createdebt.
 * 
 * @pre Предварительные условия:
 * - Проект находится в активном статусе
 * - Участник имеет активный сегмент в проекте  
 * - Общий долг Участника плюс запрашиваемая сумма меньше или равна сумме доступной себестоимости
 * - Сумма доступной себестоимости больше нуля (есть вклады, обеспеченные инвестициями)
 * 
 * @note Доступная себестоимость (provisional_amount) представляет собой себестоимость вкладов Участника, 
 * скорректированную на коэффициент возврата. Этот коэффициент показывает, какая часть базовых 
 * затрат обеспечена привлечёнными в проект инвестициями. Чем больше инвестиций привлечено, 
 * тем выше коэффициент и тем больше средств доступно для выдачи в виде ссуд. 
 * Коэффициент возврата себестоимости не превышает 100% от себестоимости затрат Участников. 
 * При превышении количества инвестиций суммы затрат, у инвесторов уменьшается коэффициент использования инвестиций, и они получат часть средств назад при закрытии проекта. 
 * 
 * <b>Входящие параметры:</b>
 * - amount - запрашиваемая сумма ссуды
 * - repaid_at - планируемая дата погашения ссуды
 * - statement - заявление на получение ссуды
 * 
 * @post Результат выполнения:
 * - 📄 Создаётся заявление в таблице Capital::debts
 * - Резервируется сумма долга в сегменте Участника, что не позволяет повторно отправлять заявления
 * 
 * ### Шаг 2: Одобрение заявки председателем
 * 
 * Председатель или доверенное им лицо принимает предварительное решение через действие @ref capital::approvedebt.
 * 
 * @pre Предварительные условия:
 * - 📄 Заявление создано и ожидает рассмотрения
 * 
 * @post Результат выполнения:
 * - 📄 При одобрении заявление передаётся в совет для получения протокола решения
 * - При отклонении заявка закрывается с указанием причин
 * 
 * @note Председатель оценивает обоснованность запроса, проверяет финансовое состояние проекта 
 * и подтверждает корректность расчётов перед передачей в совет. Председатель может делегировать эти полномочия доверенному Администратору. 
 * 
 * ### Шаг 3: Авторизация советом
 * 
 * Совет принимает решение о выдаче ссуды через действие @ref capital::debtauthcnfr. 
 * 
 * @pre Предварительные условия:
 * - 📄 Заявление одобрено председателем
 * 
 * @post Результат выполнения:
 * - При положительном решении инициируется исходящий платёж через контракт @ref public_gateway "Шлюза"
 * - При отклонении заявка закрывается
 * 
 * @note Совет рассматривает целесообразность выдачи, оценивает риски для проекта 
 * и утверждает выдачу ссуды по заявлению участника или отклоняет его. 
 * 
 * ### Шаг 4: Подтверждение оплаты
 * Лицо, обладающее доступом к расчётному счёту кооператива совершает исходящий платеж и отмечает его выполненным. 
 * Контракт @ref public_gateway "Шлюза" подтверждает успешное перечисление средств Участнику через действие @ref capital::debtpaycnfrm. 
 * 
 * @pre Предварительные условия:
 * - 📄 Совет авторизовал выдачу ссуды
 * - Gateway инициировал платёж
 
 * @post Результат выполнения:
 * - 📄 Фиксируется факт получения средств Участником
 * - Создаётся запись в контракте @ref public_loan "Ссуд"
 * - Увеличивается общий долг Участника в системе
 * - Участник получает средства на свой банковский счёт
 * 
 * @note Создание записи о долге в контракте loan фиксирует обязательство Участника 
 * по возврату полученных средств, информация о котором доступна в том числе и в других контрактах. 
 * 
 * ### Альтернативные пути: Отклонение и отказы
 * 
 * #### Отказ в оплате Gateway
 * 
 * При техническом сбое или неверных реквизитах администратор платежей через контракт @ref public_gateway "Шлюза" отклоняет платёж действием @ref capital::debtpaydcln.
 * 
 * @post Результат выполнения:
 * - Заявка удаляется из системы
 * - Размер долга в сегменте уменьшается
 * - Участник может подать заявку повторно
 * 
 * #### Отклонение заявки
 * 
 * Отклонение может произойти на любом этапе рассмотрения через действие @ref capital::declinedebt.
 * 
 * @post Результат выполнения:
 * - Указывается причина отказа
 * - Освобождается зарезервированная сумма долга в сегмента
 * 
 * ### Шаг 5: Погашение ссуды
 * 
 * Ссуды погашаются автоматически при внесении результата через действие @ref capital::pushrslt.
 * 
 * @pre Предварительные условия:
 * - Участник вносит результат через pushrslt
 * - Указывается сумма долга для погашения
 * 
 * @post Результат выполнения:
 * - Сумма долга вычитается из стоимости результата после его внесения
 * - Производится зачёт через контракт @ref public_loan
 * - Списывается долг в контракте @ref public_loan
 * - Уменьшаются обязательства Участника
 * 
 * @note Автоматическое погашение обеспечивает защиту от рисков невозврата средств.
 * 
 * ## Примеры расчёта доступных ссуд
 * 
 * ### Пример 1: Исполнитель с коммитами
 * - Себестоимость работы создателя = 100,000 рублей (50 часов × 2000 рублей/час)
 * - Коэффициент возврата = 80% (инвестиции покрывают 80% себестоимости затрат)
 * - Обеспеченная сумма = 100,000 × 0.8 = 80,000 рублей
 * - <b>Доступная ссуда: до 80,000 рублей</b>
 * 
 * ### Пример 2: Автор проекта
 * - Авторская себестоимость = 61,800 рублей (61.8% от 100,000 рублей создателей)
 * - Коэффициент возврата = 80%
 * - Обеспеченная сумма = 61,800 × 0.8 = 49,440 рублей
 * - <b>Доступная ссуда: до 49,440 рублей</b>
 * 
 * ### Пример 3: Координатор
 * - Координаторская премия = 6,400 рублей (4% от привлечённых 160,000 рублей)
 * - Коэффициент возврата = 80%
 * - Обеспеченная сумма = 6,400 × 0.8 = 5,120 рублей
 * - <b>Доступная ссуда: до 5,120 рублей</b>
 * 
 * @note В примерах показано, как размер доступной ссуды зависит от фактических вкладов Участника и 
 * коэффициента обеспеченности инвестициями. Чем больше Участник вложил и чем больше инвестиций 
 * привлечено в проект, тем больше средств доступно для получения в виде ссуды.
 * 
 * ## Влияние на конвертацию сегмента
 * 
 * Полученные ссуды влияют на доступные для конвертации суммы. Доступная часть себестоимости после 
 * погашения долга рассчитывается как общая стоимость сегмента результата минус размер долга.
 * 
 * @note Чем больше ссуда, тем меньше средств остаётся для конвертации в главный кошелёкёк, кошелёк проект или кошелёк программы. 
 * Премиальная часть не затрагивается и полностью доступна для конвертации в программу благороста или для конвертации в кошелёк проекта.
 * 
 *
 ## Эффекты процесса
 @include{doc} debtpaycnfrm-effect.dox

 ## Документы процесса
  @include{doc} debt-process-docs.dox
 *
 * ## Связанные процессы
 * 
 * - @ref public_capital_project_investment_process "Инвестиции в проект" - инвестиции обеспечивают ссуды
 * - @ref public_capital_result_process "Приём результата" - ссуды погашаются при внесении результата
 * - @ref public_capital_conversion_process "Конвертация взносов" - учитывает выданные и погашенные ссуды

 */
