SHiNE-server/AGENTS.md

AGENTS

Язык проекта

• По умолчанию использовать русский язык во всех пользовательских текстах и технических пояснениях.
• Пояснения к коммитам, PR и merge-запросам писать на русском языке.
• Комментарии в коде, встроенные справки, документацию и инструкции писать по возможности на русском языке.

Примечание

• Если внешний инструмент/интеграция требует английский формат, допускается английский, но рядом желательно дать краткое пояснение на русском.

Документация блокчейна

• Актуальная документация по форматам блокчейна находится в Dev_Docs/Blockchain/README.md.
• Это точка входа (оглавление), рядом расположены детальные файлы по форматам, типам каналов и командным сообщениям.
• При любом изменении кода, связанного с блокчейном (формат блока, типы каналов, правила чтения/записи, команды), обязательно обновлять соответствующие документы в Dev_Docs/Blockchain/.
• Дополнительно обязательно вести Dev_Docs/Blockchain/CHANGELOG.md: дописывать изменения построчно с указанием даты/времени и хэша коммита, после которого внесено изменение.

Версионирование

• Единый файл версий проекта: VERSION.properties (в корне репозитория).
• Перед каждым новым коммитом обязательно увеличивать версии в VERSION.properties:
• client.version — версия клиентского UI.
• server.version — версия серверной части.
• Базовое правило инкремента: +1 по последнему числовому сегменту (patch), если не оговорено иное.

Deploy

• Все документы и заметки по деплою хранить в папке Deploy Server/.
• Для сервера VPS-05 (45.136.124.227) доступ выполнять через пользователя player.
• Базовый целевой хост для деплоя по умолчанию: player@45.136.124.227.
• Базовый путь на сервере для SHiNE: /home/player (проекты SHiNE размещать в /home/player/SHiNE/...).
• По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
• Деплой UI выполнять только в один целевой контур за запуск: либо prod (основной), либо один выбранный тестовый (ui_1, ui_2, ui_3, ui_drygmira, ui_milana, ui_aidar).
• Если из запроса неясно, куда деплоить, обязательно сначала спросить пользователя, какой именно целевой контур нужен.
• По умолчанию сначала деплой и проверка на тестовом контуре; на основной (prod) деплоить только после явного подтверждения пользователя, что версия проверена и готова.
• При уточняющем вопросе отдельно предупреждать: деплой на основной выполнять только если точно подтверждена корректная работа.

Логи звонков (установка соединения)

• Специальный поток диагностики установки звонков идёт через CallDeliveryReport (клиент → сервер).
• На проде специальный файл для звонков:
• /home/player/SHiNE/shine-server/logs/call-delivery-events.log
• Общий серверный лог (и ротации) на проде:
• /home/player/SHiNE/shine-server/logs/app.log
• /home/player/SHiNE/shine-server/logs/app.YYYY-MM-DD.log
• Для анализа причин недозвона в первую очередь фильтровать записи по ключам:
• CallDeliveryReport
• call_connected
• outgoing_failed
• incoming_failed
• call_busy
• call_declined
• unknown_error
• В этих записях искать поля reason, failureStage, pcConnectionState, pcIceConnectionState, routeLabel, configuredTurnHosts*, reachableTurnHosts*.