Files
SHiNE-server/scripts/dev/test-graph-250/AGENTS.md
T

83 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` для фикстур: это уже отдельная задача интеграционного тестирования с подписанными блоками.