79 lines
8.1 KiB
Markdown
79 lines
8.1 KiB
Markdown
# 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
|
||
- Все документы и заметки по деплою хранить в папке `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`).
|
||
- В том же первом ответе обязательно уточнять у пользователя, проверил ли он эти фичи и можно ли пометить их как завершённые (удалить соответствующие файлы).
|
||
|
||
## Коммуникация по новым задачам (обязательно)
|
||
- При получении нового задания сначала кратко пересказать задачу своими словами.
|
||
- До начала реализации задать недостающие уточняющие вопросы (если они есть).
|
||
- Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать.
|
||
- Добавлять краткую оценку фичи (насколько это полезно/удачно по мнению исполнителя).
|
||
- После этого обязательно запросить подтверждение от пользователя, что задача понята верно, и только после подтверждения переходить к реализации.
|
||
- Если вопросов нет, явно написать в формате: «Я всё понял, начинаю делать?» и ждать подтверждения.
|
||
- Без подтверждения пользователя реализацию не начинать.
|