Встроить синхронизацию Solana users в сервер

2026-07-23 23:49:39 +04:00
parent 4704f8485b
commit 5df69d73c7
24 changed files with 6243 additions and 1 deletions
@@ -0,0 +1,116 @@
+# Интеграция синхронизации `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.