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/...).
• По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
• Для операций git push использовать токен из переменной окружения $GITEA_TOKEN.
• Деплой 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*.

Недопроверенные фичи (обязательно)

• Папка для учёта недопроверенных фич: Dev_Docs/Pending_Features/.
• По каждой новой доработке, которая требует ручной проверки, добавлять отдельный markdown-файл в Dev_Docs/Pending_Features/.
• Рекомендуемый формат имени файла: YYYY-MM-DD_HHMM_<short-feature-name>.md.
• Внутри файла обязательно указывать:
  • краткое описание фичи;
  • что именно проверять;
  • ожидаемый результат;
  • статус (например: pending, in_progress, done).
• После подтверждения, что фича проверена и работает корректно, соответствующий файл удалять.
• В Dev_Docs/Pending_Features/README.md вести краткий регламент и поддерживать актуальность.

Коммуникация в начале нового чата

• В начале каждого нового чата (в первом ответе пользователю) дополнительно сообщать, сколько сейчас недопроверенных фич лежит в Dev_Docs/Pending_Features/ (без учёта README.md).
• В том же первом ответе обязательно уточнять у пользователя, проверил ли он эти фичи и можно ли пометить их как завершённые (удалить соответствующие файлы).

Коммуникация по новым задачам (обязательно)

• При получении нового задания сначала кратко пересказать задачу своими словами.
• До начала реализации задать недостающие уточняющие вопросы (если они есть).
• Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать.
• Добавлять краткую оценку фичи (насколько это полезно/удачно по мнению исполнителя).
• После этого обязательно запросить подтверждение от пользователя, что задача понята верно, и только после подтверждения переходить к реализации.
• Если вопросов нет, явно написать в формате: «Я всё понял, начинаю делать?» и ждать подтверждения.
• Без подтверждения пользователя реализацию не начинать.