# SHiNE — инструкция для агента: демонстрационный социальный граф 250 **Область действия:** только `scripts/dev/test-graph-250/` и отдельная **тестовая** PostgreSQL SHiNE. Перед изменениями читать корневой `AGENTS.md`, `SHiNE-server/AGENTS.md`, `deploy/AGENTS.md`, `deploy/TEST_SERVERS.md` и текущие `migration_v31.sql`, `migration_v33.sql`, `migration_v36.sql`, `migration_v37.sql`, `migration_v40.sql`. Всё пояснять на русском. ## Назначение Это **SQL-фикстура read model**, а не регистрация пользователей. Создаёт `testuser001@free`–`testuser250@free` в `user_identity_current`, параметры (`first_name`, `last_name`, `gender`, `shine`, `account_role`, `about`) в `users_params`, связи (10/14/70/80) в `connections_state`. Вызовы `shine_refresh_user_profile` и `shine_refresh_user_stats` обновляют производные таблицы. В актуальной схеме v40 связи используют `login`, `rel_type`, `to_login`, `to_block_number` и `to_block_hash`. **Нет реальных Free-сертификатов, подписанных HEADER/POST-блоков, действительных ключей, аватаров Arweave, регистрации в Solana/Arweave и права входа под этими пользователями.** Их данные видны через API, читающий PostgreSQL; синхронизация из цепочки их не восстановит. `about` перечисляет условные сообщества текстом; каналы SHiNE не создаются. Пользователям не добавляются публикации. Нельзя представлять их настоящими зарегистрированными аккаунтами. **Никогда не выполняйте SQL на production (`shineup.me`, `server2.shineup.me`), не отправляйте их в публичную сеть и не добавляйте эту фикстуру в миграции сервера.** На тестовых t1–t4 подтвердите текущие реквизиты базы; сведения `deploy/TEST_SERVERS.md` могут устареть. Не получать секреты из Git и не писать их в файлы проекта. ## Файлы - `generate.py` — детерминированная генерация (Python 3, stdlib; seed 20261111). - `test_generator.py` — автономные тесты взаимности, размеров групп, распределений, прав подтверждения и синтаксических требований SQL. - `seed.sql` — атомарная загрузка / повторная загрузка **всех 250** фикстур. - `remove.sql` — атомарное удаление **всех 250**; если найдены реальные связанные данные — прекращает транзакцию. - `verify.sql` — только SELECT, подсчёты после загрузки. - `users.csv` — список логинов, имён, сообществ, описаний, статистики. - `README.md` — короткая инструкция оператора. ## До запуска 1. Выберите *именно тестовую* БД с применёнными миграциями >=40 и существующим namespace `free`. **Не production и не копию production с ценными записями.** 2. Проверьте `SELECT current_database();` и сделайте резервную копию выбранной базы. 3. Убедитесь, что `testuser001@free`–`testuser250@free` не заняты реальными пользователями. При наличии старого графа **200** с маркером `SHINE_DEV_GRAPH_200_` сперва отдельно удалите его прежним скриптом. Новый генератор намеренно откажется от конфликта логинов. 4. Выполните офлайн-проверку: `python3 scripts/dev/test-graph-250/test_generator.py`. 5. В командах ниже используйте имя именно своей тестовой БД в **обоих** местах: строка подключения и `-v expected_db=...`. SQL дополнительно требует `PGOPTIONS` и проверяет имя базы по шаблону dev/test. ## Установка из корня репозитория ```bash # Пример для тестовой базы t1, предварительно настройте соединение локально. export DATABASE_URL='postgresql://DEV_USER@127.0.0.1:5432/shine_t1_db' psql -X "$DATABASE_URL" -c 'SELECT current_database();' # Сначала backup тестовой базы! PGOPTIONS='-c shine.allow_test_graph=yes' psql -X -v ON_ERROR_STOP=1 \ -v expected_db=shine_t1_db "$DATABASE_URL" \ -f scripts/dev/test-graph-250/seed.sql psql -X -v ON_ERROR_STOP=1 "$DATABASE_URL" -f scripts/dev/test-graph-250/verify.sql ``` Если `psql` имеется только **в контейнере** PostgreSQL тестового сервера (согласно `deploy/TEST_SERVERS.md` — `shine-test-postgres`), на **проверенном тестовом хосте** из корня проекта: ```bash # Пример t1; сначала убедитесь в правильном контейнере, БД и роли. docker exec -e PGOPTIONS='-c shine.allow_test_graph=yes' -i shine-test-postgres \ psql -X -v ON_ERROR_STOP=1 -U shine_t1 -d shine_t1_db \ -v expected_db=shine_t1_db < scripts/dev/test-graph-250/seed.sql docker exec -i shine-test-postgres \ psql -X -v ON_ERROR_STOP=1 -U shine_t1 -d shine_t1_db \ < scripts/dev/test-graph-250/verify.sql ``` Не угадывайте адреса, имя контейнера, роль или пароль: перед действием сверяйте окружение. В PostgreSQL журнале операций не должно быть ошибок (используется `ON_ERROR_STOP`). ## Удаление всех 250 ```bash PGOPTIONS='-c shine.allow_test_graph=yes' psql -X -v ON_ERROR_STOP=1 \ -v expected_db=shine_t1_db "$DATABASE_URL" \ -f scripts/dev/test-graph-250/remove.sql psql -X -v ON_ERROR_STOP=1 "$DATABASE_URL" -f scripts/dev/test-graph-250/verify.sql ``` Если используется Docker, замените `seed.sql` на `remove.sql` в приведённой выше команде `docker exec` с теми же флагами. **Защита:** обе операции работают в `BEGIN … COMMIT`, при ошибке откатываются; проверяют подтверждённое имя БД, v40+, маркер `SHINE_DEV_GRAPH_250_`, отсутствие чужих связей/блоков/сертификатов. Удаление дополнительно ищет записи во всех таблицах с одноколоночными внешними ключами на `user_identity_current` (кроме разрешённых read-моделей) и прекращается при обнаружении зависимостей. Если удаление запрещено, **не отключать защиту автоматически** — выяснить причину и сохранить данные. Повторный `seed.sql` удаляет только помеченные старые связи этой же версии и восстанавливает фиксированные тестовые данные; он не накапливает дубликатов. ## Проверка через SHiNE После установки найдите `testuser001@free` в поиске SHiNE, откройте «Связи» и проверьте V1/V2/V3. `testuser001@free` имеет **ровно 50 исходящих друзей**; `testuser052@free` — 55; `testuser112@free` — 60. Остальные сообщества различны и связаны мостами. В V3 после повторной загрузки фикстуры откройте `⋮ → Очистить кэш`: клиент кэширует список связей до 24 часов. **Если профиль не найден**, проверить отдельно, что UI подключён к нужному тестовому серверу/БД; `free` namespace существует; сервис поднят с нужным конфигом; вызывается `GetUserConnectionsGraph` на этом сервере. Не маскировать проблему созданием фальшивых on-chain блоков. **Полноценный запуск SQL на живой PostgreSQL требует отдельно выполнить шаги на тестовом сервере**; офлайн-тесты Python проверяют только данные и статическую форму SQL. ## Поддержка и изменения При изменении распределений править `generate.py`, выполнять `python3 generate.py` в этой папке и `python3 test_generator.py`. Коммитить вместе **все** обновлённые `seed.sql`, `remove.sql`, `users.csv`, а также документацию и тесты. Не править вручную большие сгенерированные SQL. Не создавать `free_registration_certificate` и `blocks_store` для фикстур: это уже отдельная задача интеграционного тестирования с подписанными блоками.