SHiNE-server/AGENTS.md

AGENTS

Язык проекта

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

Примечание

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

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

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

Документация личных сообщений (DM)

• Актуальная документация по логике личных сообщений находится в Dev_Docs/Personal_Messages/README.md.
• При любом изменении кода, связанного с личными сообщениями (формат подписанного DM-блока, типы DM-сообщений, правила доставки/ACK/read-receipt, роутинг по сессиям, UI-логика чатов), обязательно обновлять Dev_Docs/Personal_Messages/README.md.
• Логика личных сообщений в коде должна всегда соответствовать Dev_Docs/Personal_Messages/README.md.
• Документ по личным сообщениям обязан поддерживаться в актуальном состоянии.

Известная проблема (временная пометка)

• Мнения по связям пользователя (known_person, shine_confirmed, shine_seen) в UI могут отображаться нестабильно.
• Требуется отдельная доработка и финальная проверка end-to-end: запись мнения в блокчейн → обновление connections_state → ответ GetUserConnectionsGraph → отображение в UI.
• До фикса считать эту часть функционала незавершённой и обязательно перепроверять вручную после каждого деплоя.

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

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

Deploy

• Все документы и заметки по деплою хранить в папке Dev_Docs/deploy/.
• Базовый целевой хост для деплоя по умолчанию: player@93.170.12.154 (shineup.me).
• Базовый путь на сервере для SHiNE: /home/player (проекты SHiNE размещать в /home/player/SHiNE/...).
• По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
• Для операций git push использовать токен из переменной окружения $GITEA_TOKEN.
• Для серверного деплоя использовать один gradle task: ./gradlew deployServer.
• Для UI деплоя использовать один gradle task: ./gradlew deployUI.
• Для локального запуска использовать ./gradlew startLocal (или startLocalWithBuild).
• Сначала предлагать локальную проверку, а деплой на сервер выполнять по запросу пользователя.

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

• Специальный поток диагностики установки звонков идёт через 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).
• В том же первом ответе обязательно уточнять у пользователя, проверил ли он эти фичи и можно ли пометить их как завершённые (удалить соответствующие файлы).

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

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