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

9.9 KiB
Raw Blame History

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.

Установка из корня репозитория

# Пример для тестовой базы 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), на проверенном тестовом хосте из корня проекта:

# Пример 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

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 для фикстур: это уже отдельная задача интеграционного тестирования с подписанными блоками.