103 lines
6.4 KiB
Markdown
103 lines
6.4 KiB
Markdown
# 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.
|