# Интеграция синхронизации `shine_users` в основной сервер

Этот документ описывает, что нужно для встраивания Solana sync-модуля пользовательских PDA в основной SHiNE-server.

Основной архитектурный документ:

- [docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md](/home/ai/work/SHiNE/SHiNE-server-sha256/SHiNE-product/docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md)

## Что уже готово

Отдельный модуль `sync-solana` уже умеет:

- подключаться к Solana RPC и WebSocket;
- вычислять `users_economy_config_pda`;
- хранить checkpoint синхронизации в PostgreSQL;
- читать историю через `getSignaturesForAddress(users_economy_config_pda)`;
- поддерживать realtime через websocket;
- выполнять страховочный periodic poll раз в 5 минут;
- хранить:
  - `solana_sync_state`
  - `solana_sync_tx_history`
  - `solana_user_pda_current`
  - `solana_user_pda_history`
- блокировать дальнейший startup до входа в `READY`.

## Что нужно перенести в основной сервер

Из `sync-solana` в сервер нужно перенести рабочие классы:

- `sync-solana/src/main/java/sync-solana/config/`
- `sync-solana/src/main/java/sync-solana/service/`
- `sync-solana/src/main/java/sync-solana/source/`
- `sync-solana/src/main/java/sync-solana/source/rpc/`
- `sync-solana/src/main/java/sync-solana/storage/postgres/`
- `sync-solana/src/main/java/sync-solana/codec/`
- `sync-solana/src/main/java/sync-solana/model/`
- `sync-solana/src/main/java/sync-solana/util/`

`Main.java` нужен только как reference для bootstrap и как отдельный `main` в сервере уже не понадобится.

Рекомендуемый вариант:

- оформить это как отдельный Gradle submodule внутри `SHiNE-server`;
- запускать его из server startup как lifecycle-сервис.

## Порядок запуска в сервере

При старте основного сервера последовательность должна быть такой:

1. прочитать общий server config;
2. создать Solana users sync service;
3. вызвать `start()`;
4. вызвать `awaitReady()`;
5. только после этого продолжать остальной startup сервера:
   - синхронизацию с другими нодами;
   - запуск WS/HTTP;
   - остальную серверную инициализацию.

Если Solana initial sync не дошёл до `READY`, startup сервера должен считаться неуспешным.

## Переменные окружения сервера

На сервере должны быть доступны:

```text
SOLANA_RPC_URL=
SOLANA_WS_URL=
SOLANA_PROGRAM_ID=SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6
SYNC_POLL_INTERVAL_SECONDS=300
```

Для PostgreSQL sync-модуль может использовать уже существующую server PostgreSQL-конфигурацию, если сервер уже предоставляет:

```text
DATABASE_URL=
PGUSER=
PGPASSWORD=
```

Если в сервере используется другая схема конфигов, нужно сделать адаптер на уровне server config, а не менять саму логику sync.

## Логи

Sync-модуль должен писать в общие server logs через тот же `slf4j/logback`, что и основной сервер.

Минимум, который должен быть виден в логах:

- старт sync-модуля;
- вход в `READY`;
- realtime sync;
- periodic poll;
- reconnect websocket;
- fallback на full snapshot;
- ошибки RPC/WS/DB.

## Что потребуется по deploy

Отдельных deploy-скриптов для sync-модуля не требуется, если он встроен в основной server jar.

По deploy нужно:

- обновить server env/override-конфиг новыми переменными `SOLANA_*` и `SYNC_POLL_INTERVAL_SECONDS`;
- убедиться, что на сервере доступен PostgreSQL, в который модуль будет писать свои таблицы;
- при необходимости описать новые env в документации конкретного server-контура.

## Что ещё проверить после интеграции

После встраивания в основной сервер нужно отдельно проверить:

- startup сервера с ожиданием `awaitReady()`;
- создание таблиц в server PostgreSQL;
- initial sync после пустой БД;
- restart recovery после уже существующего checkpoint;
- realtime update через websocket;
- periodic poll без новых транзакций;
- fallback на full snapshot при потере history anchor.