Перенести документацию в docs и добавить социальный граф

2026-07-13 12:58:41 +04:00
parent c9cfb394d7
commit af12d7b954
91 changed files with 653 additions and 2 deletions
@@ -0,0 +1,38 @@
+# Поддержать проект Сияние
+
+Статус: `pending`
+
+## Кратко
+
+В `shine-UI/js/pages/wallet-view.js` добавлен новый раздел `Поддержать проект Сияние` с тремя входами:
+
+1. купить билет;
+2. посмотреть билет по номеру;
+3. сгенерировать новую пару ключей.
+
+## Что проверить
+
+1. Открыть `Кошелёк`.
+2. Перейти в `Поддержать проект Сияние`.
+3. Проверить экран покупки:
+   - виден коэффициент;
+   - виден остаток лимита очереди 1;
+   - виден расчет в SOL;
+   - кнопка `Справка` открывает отдельный экран;
+   - покупка блокируется, если сумма больше остатка лимита.
+4. Проверить экран просмотра:
+   - `12` ищется как билет очереди 1;
+   - `2-5` и `3 8` ищутся как билеты очередей 2 и 3;
+   - показываются статус, количество билетов до него и уже выплаченные значения.
+5. Проверить генератор ключей:
+   - генерируется новая пара ключей;
+   - публичный и секретный ключи показываются;
+   - можно скопировать и скачать результат;
+   - дополнительный текст в поле необязателен.
+
+## Ожидаемый результат
+
+- Экран раздела поддержки открывается из `wallet-view`.
+- Покупка билета выполняется по текущему курсу и с допуском 3%.
+- По номеру билета показывается понятная сводка по очереди.
+- Генерация ключей использует безопасный браузерный рандом и не требует сохранения секретного ключа.
@@ -0,0 +1,20 @@
+# Promo-логины через продавцов в Solana
+
+- краткое описание:
+  - в `shine_users` добавлена поддержка PDA продавцов красивых логинов, promo-подписи `shine_promo_v1:<login>` и отдельная автономная страница `shine-UI/promo-code-generator.html` для генерации promo-кода через браузерный кошелёк или через ручной ввод Base58 seed 32 bytes;
+- что проверять:
+  - admin-транзакцией создать или обновить `promo_seller_pda`;
+  - сгенерировать promo-код на странице `promo-code-generator.html` в режиме wallet extension;
+  - сгенерировать promo-код на той же странице в режиме ручного Base58 seed;
+  - открыть HTML локально как отдельный файл без сервера и убедиться, что генерация в режиме Base58 seed продолжает работать;
+  - зарегистрировать короткий/premium логин по promo-коду;
+  - убедиться, что без promo-кода тот же логин не проходит `shine_login_guard`;
+  - убедиться, что после успешной регистрации `remaining_sales` уменьшается на 1;
+  - проверить отказ при исчерпанной квоте, неверной подписи и логине короче `min_login_length`;
+- ожидаемый результат:
+  - promo-регистрация проходит только при валидной подписи продавца и соблюдении лимитов;
+  - обычная регистрация без promo-кода продолжает работать как раньше;
+  - страница генерации выдаёт строку формата `1seller-signatureBase58` в обоих режимах;
+  - single-file HTML работает локально оффлайн минимум в режиме ручного Base58 seed;
+- статус:
+  - `pending`
@@ -0,0 +1,51 @@
+# Синхронизация mainnet-адресов Solana по UI/серверу/ESP32
+
+- статус: `pending`
+
+## Кратко
+
+Во все основные клиентские и серверные точки проекта протянуты актуальные mainnet-адреса программ:
+
+- `shine_login_guard`: `SHiGxGsXGioQYCYhchQ5R7KWoxN5UjFAFsucPf6sfnh`
+- `shine_users`: `SHiNEPr1APdAgNBteUyBXcNovaHctpSjUu8oH2ZJdN6`
+- `shine_payments`: `SHiPmXbM9Fs9khzRUW3TGKsS2W84aqaXTxs3ZkajW9v`
+
+Также по умолчанию переключены основные RPC defaults на `https://api.mainnet-beta.solana.com` там, где это нужно для рабочего mainnet-сценария.
+
+## Что проверять
+
+1. Основной UI:
+   - отображение и использование новых program id;
+   - регистрация/чтение Solana PDA в mainnet;
+   - экран кошелька и покупка лимита.
+
+2. Server UI:
+   - создание server PDA в mainnet;
+   - чтение PDA;
+   - обновление PDA;
+   - корректная блокировка devnet-автопополнения при mainnet endpoint.
+
+3. Browser plugin wallet:
+   - резолв `user_pda` и `server PDA` через mainnet RPC.
+
+4. Web UI `shine_payments`:
+   - чтение очередей;
+   - покупка билета;
+   - admin/manager/dao tools открываются с новыми program id и mainnet RPC.
+
+5. ESP32 homeserver UI:
+   - отображаются новые program id;
+   - дефолтный Solana RPC теперь mainnet.
+
+6. Временный режим регистрации:
+   - в основном UI логины длиной 5-7 символов без временного кода не проходят;
+   - в основном UI логины длиной 5-7 символов с временным кодом проходят локальную проверку;
+   - в основном UI любой другой временный код отклоняется сразу;
+   - ESP32 и прямой on-chain вызов `shine_users` полагаются на текущий временный `shine_login_guard`, то есть валидные логины длиной от 5 символов допускаются без словарной классификации.
+
+## Ожидаемый результат
+
+- Во всех перечисленных поверхностях используются новые mainnet program id.
+- Запросы по умолчанию идут в mainnet, кроме явно devnet-утилит.
+- Нет обращений к старым devnet program id.
+- Временный UI-барьер для коротких логинов работает так, как задумано, и не ломает обычную регистрацию для логинов от 8 символов.
@@ -0,0 +1,42 @@
+# Временный режим коротких логинов
+
+- статус: `pending`
+
+## Кратко
+
+Временно упрощён `shine_login_guard`:
+
+- on-chain допускаются любые валидные логины длиной от `5` символов;
+- словарная premium/trademark-классификация временно отключена.
+
+Поверх этого основной UI вводит временное ограничение:
+
+- логины длиной `8+` проходят обычную проверку;
+- логины длиной `5..7` допускаются только при вводе временного кода;
+- любой другой код отклоняется сразу.
+
+ESP32 в этом временном режиме не ограничивается UI-кодом и использует только on-chain правила.
+
+## Что проверять
+
+1. Основной UI:
+   - логин длиной `4` символа отклоняется;
+   - логин длиной `5..7` без временного кода отклоняется;
+   - логин длиной `5..7` с корректным временным кодом проходит локальную проверку;
+   - логин длиной `5..7` с любым другим кодом отклоняется;
+   - логин длиной `8+` проходит без временного кода.
+
+2. Solana on-chain:
+   - `shine_login_guard` возвращает `CLASS_FREE` для валидных логинов длиной от `5`;
+   - `shine_login_guard` возвращает `CLASS_PREMIUM` для логинов короче `5` или с невалидными символами.
+
+3. ESP32 / прямой вызов:
+   - валидный логин длиной `5+` регистрируется без временного кода;
+   - логин короче `5` не регистрируется.
+
+## Ожидаемый результат
+
+- Основной UI удерживает обычных пользователей от коротких логинов без временного кода.
+- Свои пользователи могут временно регистрировать короткие логины через UI-код.
+- ESP32 продолжает работать без отдельной промо-логики.
+- On-chain логика остаётся простой и компактной.
@@ -0,0 +1,39 @@
+# 4 тестовых SHiNE-сервера на одном VPS (`178.208.90.249`)
+
+- статус: `pending`
+
+## Кратко
+
+Поднят отдельный тестовый стенд:
+- `t1.shineup.me`
+- `t2.shineup.me`
+- `t3.shineup.me`
+- `t4.shineup.me`
+
+Каждый домен ведёт на свой SHiNE-инстанс под пользователем `player`, все инстансы работают через Solana `devnet`.
+
+## Что проверять
+
+- UI каждого домена открывается без ошибок:
+  - `https://t1.shineup.me`
+  - `https://t2.shineup.me`
+  - `https://t3.shineup.me`
+  - `https://t4.shineup.me`
+- регистрация/логин клиента может работать через каждый из этих серверов
+- WebSocket-подключение реально идёт на свой инстанс, а не в соседний
+- чтение PDA и server-ui формы по умолчанию используют `devnet`
+- межсерверный sync после ручных тестов действительно использует `access_servers/sync_servers`
+- не происходит путаницы данных между `t1/t2/t3/t4`
+
+## Ожидаемый результат
+
+- каждый домен работает независимо
+- у каждого инстанса своя БД и свои локальные данные
+- `Caddy` корректно проксирует `/ws` на `7101..7104`
+- серверы не падают после старта
+- если devnet RPC временно даёт `429`, последовательный рестарт по одному инстансу позволяет подтянуть `sync_servers`
+
+## Примечание
+
+Подробная схема размещения описана в:
+- [Dev_Docs/deploy/test-server/178.208.90.249_quad_devnet.md](/home/ai/work/SHiNE/SHiNE-server-sha256/Dev_Docs/deploy/test-server/178.208.90.249_quad_devnet.md)
@@ -0,0 +1,17 @@
+# Итог звонка как DM от инициатора
+
+- краткое описание фичи:
+  Вместо локальных `call-tech` записей итог звонка теперь отправляется как обычное DM-сообщение только от стороны, которая инициировала звонок.
+
+- что именно проверять:
+  1. Успешный звонок: после завершения инициатор отправляет в чат DM вида `Звонок: 37с` или `Звонок: 2м 14с`.
+  2. Неуспешный звонок без ответа: инициатор отправляет `Звонил, но недозвонился: нет ответа`.
+  3. Неуспешный звонок, когда у адресата нет доставленных сессий: инициатор отправляет `Звонил, но недозвонился: абонент не в сети`.
+  4. Неуспешный звонок при проблеме соединения: инициатор отправляет `Звонил, но недозвонился: не удалось установить соединение`.
+  5. Старые локальные `call-tech` bubble про итог звонка больше не появляются ни у инициатора, ни у принимающей стороны.
+
+- ожидаемый результат:
+  Итог звонка виден обеим сторонам как обычное DM-сообщение от инициатора, а локальные служебные записи про итог звонка больше не используются.
+
+- статус:
+  pending
@@ -0,0 +1,23 @@
+## Краткое описание
+
+Сервер перестал валидировать внутреннюю crypto-структуру `body` у контентных DM `type=1/2`.
+UI теперь не отбрасывает такие сообщения: если сообщение не удалось расшифровать, вместо текста показывается заглушка `Неудалось расшифровать сообщение`.
+
+## Что проверять
+
+- Отправка и приём обычных DM между штатными клиентами продолжают работать как раньше.
+- Сообщение с незнакомым форматом `body` у `type=1/2` принимается сервером и доходит до клиента.
+- В UI такое сообщение отображается в чате одной из ожидаемых заглушек:
+  - `Формат сообщения не поддерживается`
+  - `Не удалось расшифровать сообщение`
+  - `Сообщение повреждено`
+- После выхода из аккаунта и повторного входа backlog с такими сообщениями тоже отображается с той же заглушкой.
+- ACK доставки по сессии для такого сообщения не зацикливается и сообщение не приходит бесконечно повторно.
+
+## Ожидаемый результат
+
+Сервер выступает транспортом для opaque DM-body, а клиент при неудачной расшифровке показывает безопасный fallback вместо полного пропуска сообщения с различением основных причин.
+
+## Статус
+
+pending
@@ -0,0 +1,28 @@
+## Краткое описание
+
+В DM добавлен клиентский формат технических вставок в начале plaintext:
+
+- `<SHiNE:reply;v=1;id=...>`
+- `<SHiNE:call;v=1;status=...;...>`
+
+UI скрывает такие вставки из текста сообщения, а call-вставки отображает специальным человекочитаемым видом.
+Также добавлена защита от пользовательского текста, начинающегося с `<SHiNE:`, и исправлен безопасный рендер превью последнего сообщения в списке личных диалогов.
+
+## Что проверять
+
+- Если пользователь отправляет обычный текст, начинающийся с `<SHiNE:`, он уходит как `< SHiNE:` и отображается как обычный текст.
+- DM с `<SHiNE:call...>` показывается в чате как специальное call-сообщение, а не как сырой техтекст.
+- При исходящем звонке короче `5` секунд call-summary не отправляется вообще.
+- В списке личных сообщений превью такого сообщения показывает человекочитаемый итог звонка.
+- DM с `<SHiNE:reply...>Текст ответа` скрывает техблок и показывает только `Текст ответа`.
+- В меню любого DM первым пунктом есть `Ответить`, и отправка из этого режима реально добавляет `<SHiNE:reply...>` в начало plaintext.
+- Если reply-цель отсутствует, сообщение всё равно показывается как обычный текст ответа.
+- Текст вида `<script>alert(1)</script>` или похожие HTML-теги не исполняются ни в чате, ни в списке личных сообщений, ни в списке каналов.
+
+## Ожидаемый результат
+
+Технические SHiNE-вставки работают только как управляющие метаданные UI, а отображаемый пользователю текст и превью остаются безопасными и не рендерят HTML.
+
+## Статус
+
+pending
@@ -0,0 +1,20 @@
+# Недопроверенные фичи
+
+Эта папка хранит список доработок, которые уже реализованы, но ещё не подтверждены ручной проверкой.
+
+## Как использовать
+
+1. При каждом коммите с новыми пользовательскими фичами (если нужна ручная проверка) добавить новый файл:
+   - формат: `YYYY-MM-DD_HHMM_<short-feature-name>.md`
+   - название `<short-feature-name>` и текст файла по возможности писать на русском языке
+2. В файле указать:
+   - что сделано;
+   - как проверять;
+   - ожидаемый результат;
+   - текущий статус (`pending` / `in_progress` / `done`).
+3. После подтверждения работоспособности — удалить файл фичи из этой папки.
+
+## Важно
+
+- `README.md` не удаляется.
+- Количество недопроверенных фич = число файлов `*.md` в этой папке, кроме `README.md`.
@@ -0,0 +1,25 @@
+# Регистрация: FAQ и режим пароля из 12 слов
+
+- краткое описание:
+  - на экране регистрации добавлен блок частых вопросов с переходом на отдельный экран справки;
+  - добавлен альтернативный режим ввода пароля через 12 полей-слов в кошелёчном формате, которые склеиваются в одну строку без изменения API;
+  - такой же режим добавлен и на экран входа по логину и паролю.
+
+- что проверять:
+  - на стартовом экране открыть `Зарегистрироваться`;
+  - убедиться, что внизу экрана есть кнопки FAQ;
+  - открыть несколько вопросов и проверить возврат обратно на регистрацию;
+  - включить галочку `Представить пароль в виде 12 слов`;
+  - убедиться, что появляется сетка с нумерованными полями в 3 колонки;
+  - ввести часть слов, перейти дальше и проверить, что шаг подтверждения и генерация ключей работают;
+  - выключить галочку и проверить, что пароль остаётся собранным в одном поле;
+  - открыть экран входа по паролю и повторить те же проверки для режима `12 слов`;
+  - пройти регистрацию до шага оплаты без ошибок интерфейса.
+
+- ожидаемый результат:
+  - FAQ открывается отдельным экраном и содержит понятные ответы;
+  - режим `12 слов` не ломает регистрацию и вход и даёт тот же поток, что и обычный пароль;
+  - пароль не отправляется в новом формате, а продолжает использоваться как одна строка.
+
+- статус:
+  - pending
@@ -0,0 +1,25 @@
+# Временная бесплатная загрузка аватара в Arweave
+
+- краткое описание фичи:
+  Добавлены два временных `Test...` API для бесплатной загрузки маленьких аватаров в Arweave через серверный кошелёк с лимитом `3` загрузки на пользователя. В UI мастера смены аватара добавлен пункт `Залить аватар бесплатно`.
+
+- что именно проверять:
+  1. Пользователь с активной сессией открывает редактирование профиля.
+  2. По нажатию на аватар открывается мастер `Сменить аватар`.
+  3. В мастере есть пункт `Залить аватар бесплатно`.
+  4. До первой загрузки UI показывает остаток `3 из 3`.
+  5. Маленький JPEG/PNG/WebP после уменьшения до файла <= `128 KB` успешно уходит через `TestUploadFreeAvatar`.
+  6. После загрузки приходит `txId`, и аватар сохраняется в профиль как `avatar.ar`.
+  7. Остаток уменьшается: `2`, `1`, `0`.
+  8. На четвёртой попытке сервер отвечает понятной ошибкой про исчерпанный бесплатный лимит.
+  9. Если итоговый уменьшенный файл всё ещё > `128 KB`, UI не отправляет его и показывает понятную ошибку.
+  10. Если серверный Arweave JWK/path не настроен, UI получает понятную ошибку временной функции.
+
+- ожидаемый результат:
+  - первые 3 маленькие аватарки загружаются через серверный Arweave-кошелёк;
+  - после каждой успешной загрузки `ava` в профиле указывает на новый `txId`;
+  - после исчерпания лимита дальнейшая бесплатная загрузка блокируется без записи в профиль;
+  - обычная загрузка через свой Arweave-кошелёк продолжает работать отдельно.
+
+- статус:
+  pending
@@ -0,0 +1,28 @@
+# Общий список каналов без stories
+
+- Краткое описание:
+  вкладка `Каналы` переведена на единый список без разделения на "мои" и "подписки".
+  Название канала в списке теперь показывается как `login_владельца/название_канала`.
+  Служебный канал `stories` скрыт из списка каналов, поиска, подписки и связанных UI-сценариев.
+
+- Что проверять:
+  1. Открыть вкладку `Каналы`.
+  2. Убедиться, что сразу показывается один общий список.
+  3. Проверить, что свои и чужие каналы отображаются вместе.
+  4. Проверить формат названий: `ownerLogin/channelName`.
+  5. Открыть свой канал и убедиться, что внутри сохраняется UI владельца.
+  6. Открыть чужой канал и убедиться, что внутри сохраняется UI подписчика.
+  7. Проверить, что `stories` не отображается:
+     - в общем списке;
+     - в поиске каналов;
+     - в подписке на канал;
+     - в списках выбора канала для репоста.
+
+- Ожидаемый результат:
+  - вкладка `Каналы` больше не делится на два режима;
+  - все видимые каналы идут единым списком;
+  - `stories` нигде не виден и не предлагается пользователю;
+  - переход в канал сохраняет корректный UI в зависимости от владельца.
+
+- Статус:
+  `pending`
@@ -0,0 +1,47 @@
+# Crash-safe запись обычного `AddBlock` через `tmp_bch`
+
+## Кратко
+
+Обычный `AddBlock` переведён на схему:
+
+1. сборка `<blockchainName>.tmp_bch`;
+2. запись sidecar `<blockchainName>.write_check` с `blockNumber` и `blockHash`;
+3. создание пустого marker `<blockchainName>.write_pending`;
+4. SQL-транзакция;
+5. атомарная подмена `tmp -> main`;
+6. удаление временных файлов.
+
+## Что проверить
+
+1. Обычный `AddBlock` на свежей цепочке.
+2. Падение до SQL-commit:
+   - должны остаться только временные файлы;
+   - на старте они должны быть удалены.
+3. Падение после SQL-commit, но до `atomicReplaceBlockchainFile(...)`:
+   - на старте recovery должен довести swap до конца.
+4. Падение после `atomicReplaceBlockchainFile(...)`, но до удаления marker/sidecar:
+   - на старте recovery должен просто подчистить хвост.
+5. Сценарий без marker:
+   - `tmp_bch` / `write_check` считаются мусором и удаляются.
+
+## Ожидаемый результат
+
+- БД и файловая версия цепочки остаются согласованными.
+- Повторный старт сервера не ломает chain и не требует ручной правки файлов.
+- `BlockchainTmpRecoveryOnStartup` корректно обрабатывает и живые остатки, и мусор.
+
+## Статус
+
+`pending`
+
+## Что уже сделано
+
+- В коде есть `tmp_bch`, `write_check` и `write_pending`.
+- `BlockchainWriter` пишет обычный `AddBlock` через временные артефакты.
+- `BlockchainTmpRecoveryOnStartup` умеет добивать или чистить незавершённую запись.
+
+## Что ещё перепроверить
+
+- ручной crash-test на тестовом сервере;
+- совместимость с уже существующими `resync_pending` marker-файлами;
+- отсутствие ложных срабатываний на старых временных файлах.
@@ -0,0 +1,29 @@
+# Проверка аварийных остановок на разных этапах
+
+## Кратко
+
+Нужно отдельно проверить, как сервер восстанавливается после внезапной остановки:
+
+1. во время обычного `AddBlock` / `tmp_bch`-pipeline;
+2. во время `full resync` цепочки;
+3. во время startup recovery, если остановка произошла на предыдущем запуске;
+4. при обычном апгрейде сервиса без явного crash-сценария.
+
+## Что проверять
+
+1. Остановка сервиса до `commit` БД.
+2. Остановка сервиса после `commit`, но до замены `main.bch`.
+3. Остановка сервиса во время `BlockchainResyncCleanupDAO`.
+4. Остановка сервиса во время повторной загрузки цепочки по `GetBlockchainBlock`.
+5. Поведение при обычном `systemctl restart`, когда сервер сам должен добить recovery.
+
+## Ожидаемый результат
+
+- после старта сервер либо дочищает временные артефакты, либо завершает незаконченный `resync`;
+- не остаётся битых `.tmp_bch`, `.write_check`, `.write_pending`, `.resync_pending`;
+- БД и файлы цепочки остаются согласованными;
+- обычная работа сервера не стартует поверх незавершённого recovery.
+
+## Статус
+
+`pending`