# Интеграция Solana users sync в сервер SHiNE

Этот документ фиксирует серверную конфигурацию модуля синхронизации `shine_users`
и базовую инициализацию новой PostgreSQL runtime-схемы сервера.

## Что уже есть

- основной сервер запускает `SolanaUsersSyncStartupService` до продолжения startup;
- модуль синхронизации держит актуальными таблицы:
  - `solana_sync_state`
  - `solana_sync_tx_history`
  - `solana_user_pda_current`
  - `solana_user_pda_history`
- источник истины по пользовательским PDA: `solana_user_pda_current`.

## Что должно быть настроено в `application.properties`

```properties
solana.users.sync.enabled=true
solana.users.sync.rpcUrl=https://api.devnet.solana.com
solana.users.sync.wsUrl=wss://api.devnet.solana.com/
solana.users.sync.databaseUrl=jdbc:postgresql://127.0.0.1:5432/shine_server_db
solana.users.sync.dbUser=shine_server
solana.users.sync.dbPassword=CHANGE_ME
solana.users.sync.pollIntervalSeconds=300
```

Замечания:

- `solana.users.sync.enabled=true` обязателен, иначе сервер пропустит startup sync.
- `solana.users.sync.databaseUrl` должен указывать на ту же PostgreSQL БД, где создана серверная runtime-схема.
- `solana.users.sync.wsUrl` задаётся явно, автоматически из `rpcUrl` не строится.

## Как создать пустую PostgreSQL runtime БД

SQL-скрипт инициализации лежит в:

```text
SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql
```

Пример запуска:

```bash
psql \
  "postgresql://shine_server:CHANGE_ME@127.0.0.1:5432/shine_server_db" \
  -f SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql
```

Скрипт:

- создаёт таблицу версии схемы `db_schema_version`;
- ставит `schema_version = 1`;
- создаёт таблицы sync-модуля Solana users;
- создаёт server runtime tables;
- не создаёт удалённые legacy-таблицы старого runtime для пользователей и DM;
- использует `signed_messages` как единственную таблицу серверных DM.

## Как поднять PostgreSQL в Docker

Шаблоны лежат в:

```text
deploy/postgres/docker-compose.yml.example
deploy/postgres/.env.example
```

Минимальная последовательность:

```bash
mkdir -p /home/player/SHiNE/postgres
cp deploy/postgres/.env.example /home/player/SHiNE/postgres/.env
cp deploy/postgres/docker-compose.yml.example /home/player/SHiNE/postgres/docker-compose.yml
cd /home/player/SHiNE/postgres
docker compose up -d
```

После старта контейнера:

```bash
cp /path/to/SHiNE-product/application.properties ./application.properties
# задать db.url/db.user/db.password и запустить сервер
```

Сложность тут низкая:

- сам Docker Postgres поднимается просто;
- сервер сам создаёт runtime schema v1, если БД пустая и в ней нет `db_schema_version`;
- основная аккуратность нужна в паролях, bind-mount каталоге и backup;
- для SHiNE важно не открывать `5432` наружу, только `127.0.0.1:5432`.

## Что пока остаётся как есть

- `sync_servers` сервер по-прежнему загружает из server PDA в Solana;
- runtime-сервер уже работает только с PostgreSQL;
- дальнейшим отдельным шагом остаются зачистка legacy-документации, переименования и перенос оставшихся прямых SQL-запросов в DAO/service.