Синхронизировать изменения проекта

2026-07-05 18:18:03 +04:00
parent 0240db59ee
commit 81bef1e1cc
36 changed files with 573 additions and 335 deletions
@@ -1,6 +1,6 @@
 # Программа `shine_login_guard`

-Документ описывает целевое поведение программы классификации логинов SHiNE.
+Документ описывает текущее временное поведение программы классификации логинов SHiNE.

 Задача программы:

@@ -12,11 +12,12 @@

 `shine_login_guard` — маленькая служебная программа, которую вызывает `shine_users` через CPI до регистрации пользователя.

-Она отвечает только на вопрос:
+В текущем временном режиме она отвечает только на вопрос:

- можно ли зарегистрировать логин автоматически;
- является ли логин premium;
- является ли логин trademark/company.
+- является ли логин допустимым для автоматической регистрации;
+- нужно ли отклонить слишком короткий или некорректный логин.
+
+UI может накладывать дополнительные временные ограничения поверх этой логики, но сама программа про них не знает.

 ## 2. Program ID

@@ -28,34 +29,9 @@

 У программы нет PDA-состояний и persistent storage.

-Она опирается на статически сгенерированные словари, встроенные в бинарник на этапе сборки.
+Программа полностью stateless и не опирается на словари при классификации.

-## 4. Внешние артефакты
-
-Словари хранятся в:
-
- `src/dictionaries/premium/**/*.txt`
- `src/dictionaries/trademarks/**/*.txt`
-
-На этапе build:
-
- все `.txt` файлы рекурсивно собираются;
- слова нормализуются;
- дубль-слова детектятся и логируются как warning;
- итоговые массивы слов вшиваются в generated Rust file.
-
-## 5. Нормализация словаря
-
-Слово словаря считается валидным, если:
-
- не пустое;
- длина не больше `20`;
- содержит только ASCII-буквы и цифры;
- после `trim()` и `lowercase()` остаётся валидным.
-
-Символ `_` в словарных словах не допускается.
-
-## 6. Единственная инструкция
+## 4. Единственная инструкция

 Инструкция:

@@ -73,9 +49,9 @@

 - аккаунты не требуются

-Подпись транзакции для самой классификации не имеет бизнес-смысла. Если вызов идёт через CPI из `shine_users`, программа `shine_login_guard` не требует signer-аккаунтов вообще.
+Если вызов идёт через CPI из `shine_users`, программа `shine_login_guard` не требует signer-аккаунтов.

-## 7. Выходные классы
+## 5. Выходные классы

 Программа возвращает `u32` через `set_return_data`:

@@ -83,7 +59,14 @@
 - `1` — `CLASS_PREMIUM`
 - `2` — `CLASS_TRADEMARK`

-## 8. Правила нормализации логина
+Сейчас фактически используются только:
+
+- `CLASS_FREE`
+- `CLASS_PREMIUM`
+
+`CLASS_TRADEMARK` сохранён для совместимости ABI, но временная логика его не возвращает.
+
+## 6. Правила нормализации логина

 Перед классификацией логин нормализуется:

@@ -97,50 +80,51 @@

 - логин считается `CLASS_PREMIUM`.

-Это намеренно жёсткое поведение: сомнительный логин не должен автоматически попадать в free-класс.
+Это означает, что `shine_users` не пустит такой логин в обычную регистрацию.

-## 9. Правила классификации
+## 7. Временные правила классификации

-Алгоритм:
+Текущий временный алгоритм:

 1. Нормализовать логин.
-2. Попробовать разрезать его на `1..3` слов из словарей.
-3. Если среди найденных частей есть trademark-слово, вернуть `CLASS_TRADEMARK`.
-4. Если есть только premium-слова, вернуть `CLASS_PREMIUM`.
-5. Если словарное совпадение не найдено и длина нормализованного логина `<= 7`, вернуть `CLASS_PREMIUM`.
-6. Иначе вернуть `CLASS_FREE`.
+2. Если нормализованный логин короче `5` символов, вернуть `CLASS_PREMIUM`.
+3. Иначе вернуть `CLASS_FREE`.

-## 10. Разбиение на слова
+То есть on-chain программа в этом режиме:

-Максимум слов в логине:
+- пропускает любые валидные логины длиной от `5` символов;
+- не использует premium-словари;
+- не использует trademark-словари;
+- не выполняет словарную сегментацию логина.

- `3`
+## 8. Граница ответственности

-Алгоритм разбиения:
+Важно разделять уровни:

- DFS/backtracking по префиксам строки;
- на каждом шаге берётся префикс длиной `1..20`;
- если префикс найден в premium или trademark словаре, поиск продолжается на остатке строки;
- если найден хотя бы один путь с trademark-словом, итог = `CLASS_TRADEMARK`;
- если найден путь только с premium-словами, итог = `CLASS_PREMIUM`.
+1. `shine_login_guard`
+   - проверяет только базовую валидность и минимальную длину `5`.

-## 11. Инварианты
+2. UI
+   - может вводить дополнительные временные ограничения;
+   - например, пускать логины длиной `5..7` только по временному коду.

-Должно быть сохранено при переписи:
+3. `shine_users`
+   - остаётся финальной on-chain точкой регистрации;
+   - дополнительно проверяет общий формат логина в собственной логике.

- тот же способ нормализации логина;
- та же семантика классов `0/1/2`;
- тот же лимит `MAX_WORDS_PER_LOGIN = 3`;
- тот же fallback `len <= 7 => premium`, если словарь ничего не нашёл;
- тот же порядок приоритета `TRADEMARK > PREMIUM > FREE`.
+## 9. Совместимость

-## 12. Что не обязано сохраниться при переписи
+Сохранено:

-Можно менять без изменения бизнес-логики:
+- тот же ABI инструкции;
+- тот же формат `return_data`;
+- те же значения классов `0/1/2`;
+- тот же `Program ID`.

- build pipeline словарей;
- структуру хранения слов внутри бинарника;
- способ поиска слов, если сохраняется тот же результат;
- техническую форму возврата, если внешний контракт для `shine_users` останется совместимым.
+Изменено относительно полной словарной версии:

-Но если меняется именно интерфейс `return_data` или классы, это уже требует обновления `shine_users` и документации.
+- нет словарной классификации;
+- нет разделения на premium/trademark по содержимому логина;
+- короткий порог временно снижен до `5`.
+
+При возврате к полной модели нужно будет обновить этот документ снова синхронно с кодом.