SHiNE-server/shine-solana/shine/AGENTS.md

AGENTS.md

Documentation Rule

В проекте есть два обязательных класса документов:

1. Документы по программам в doc/programs/:
   • shine_users.md
   • shine_login_guard.md
   • shine_payments.md
2. Документы по форматам в doc/formats/:
   • shine-user-pda-format-v.1.0.md

Эти документы должны быть достаточными для повторной реализации программ и форматов с нуля.

Если меняется формат записи, сериализация, правила подписи, prev_hash, экономика лимитов, правила очередей, правила CPI, seed PDA или связанные ограничения create/update, соответствующую документацию в doc/ нужно обновлять в том же изменении.

Language Rule

Во всем проекте использовать русский язык:

• комментарии в коде;
• тексты в файлах настроек и справочных файлах;
• сообщения и описания в коммитах;
• сопроводительные технические заметки.

Rule: Logic and Docs

Если меняется бизнес-логика смарт-контрактов, сериализация PDA, правила переводов или экономика:

1. Обновить соответствующий документ в doc/programs/ и/или doc/formats/ в том же изменении.
2. Если документ сразу обновить нельзя, обязательно явно согласовать это с пользователем в чате и зафиксировать план обновления.

Отдельное обязательное правило:

1. Документы по программам и документ формата PDA должны всегда совпадать с кодом программ.
2. Перед любым изменением кода нужно явно проверять, затрагивает ли оно поведение, PDA, поля, проверки, экономику или формат.
3. Если затрагивает, документ обновляется обязательно.
4. Нельзя сознательно оставлять код и документы в рассинхроне без отдельной явной договоренности с пользователем.

Rule: Git Push

Для push в удаленный репозиторий использовать токен из переменной окружения:

• GITEA_TOKEN

Push выполнять через http.extraHeader (Authorization) без вывода токена в логи.

Rule: Commit Messages

Текст commit message писать на русском языке. Это обязательное правило для всех новых коммитов в этом репозитории.

Rule: UI Deploy

Деплой UI Shine Payments выполнять через Gradle из папки shine:

1. gradle deployUi
2. gradle checkUiRemote

Где смотреть детали (пути деплоя, путь Caddy, рабочие URL):

• комментарии в build.gradle (в корне shine/).

Назначение этого UI:

• это временные тестовые сайты для shine_payments;
• использовать их для ручной проверки сценариев покупки билетов, менеджерских лимитов и пошаговых выплат.

Известное предупреждение сборки

При cargo build / anchor build для Solana-программ может регулярно появляться предупреждение вида:

• A function call in method ... driftsort_main ... overwrites values in the frame

Для текущего проекта это известное предупреждение toolchain/stdlib. Если:

1. сборка завершается успешно;
2. anchor deploy проходит успешно;
3. целевой сценарий реально работает в devnet/localnet,

то это предупреждение считать допустимым и не блокирующим само изменение.

Дополнительное правило для рабочих отчётов:

1. предупреждение именно про driftsort_main / overwrites values in the frame считать уже зафиксированным;
2. при обычных успешных сборках и проверках не выносить его отдельно пользователю как новую проблему;
3. упоминать его только если пользователь сам спрашивает про него отдельно или если есть признаки, что изменился характер предупреждения.

Rule: Dictionary Growth Reporting

Если пользователь просит увеличить количество слов в словарях shine_login_guard:

1. Увеличивать словарь в первую очередь в явно указанных пользователем категориях/файлах.
2. Если в конкретной категории добавлять новые уместные слова уже затруднительно, прямо сообщать об этом и предлагать соседние категории для расширения.
3. После каждого такого изменения выводить количество слов по каждому файлу словаря:
   • src/dictionaries/premium/*.txt
   • src/dictionaries/trademarks/*.txt
4. В отчете дополнительно кратко оценивать заполненность категорий (где есть смысл расширять, где уже близко к насыщению).
5. В конце каждого увеличения словаря обязательно выводить итог:
   • общее число слов для premium;
   • общее число слов для trademarks.