# SHiNE ESP32 Homeserver UI Spec

## Назначение

Этот документ описывает актуальный UI-прототип homeserver `SHiNE` для платы `Waveshare ESP32-S3-Touch-AMOLED-2.16`.
Актуальный основной Arduino-скетч лежит в `../main-device/shine_homeserver_main/`.

Документ является источником истины для Arduino-скетча:

- если меняется этот документ, должен меняться и скетч;
- если меняется скетч, должен обновляться и этот документ;
- экраны, кнопки, поля, статусы, переходы и тексты не должны расходиться.

## Текущий объём реализации

Текущая реализация является интерактивным прототипом экрана устройства, пригодным для ручной проверки на железе.

Что уже входит в прототип:

- локальный UI на тач-экране;
- хранение настроек и секретов во внутренней памяти `ESP32` через `NVS`;
- русский текст в логике интерфейса; в текущей временной сборке отображение на экране идёт через ASCII-транслитерацию, потому что `U8g2`-шрифты на устройстве временно не рисуются;
- экран пополнения с реальным `solana:` URI и рисованием QR-кода через `LVGL`;
- реальное подключение к `Wi-Fi` по сохранённым `SSID/паролю`;
- реальная проверка доступности `API`, `RPC` и `WS`-адресов;
- реальное чтение баланса кошелька из `Solana RPC`;
- проверка обязательных условий перед регистрацией;
- живая on-chain регистрация серверного `user_pda` в `shine_users` по нажатию кнопки на главном экране;
- прототип входящих запросов с подтверждением и отклонением;
- PIN-блокировка (в текущей временной сборке вход по PIN отключён, устройство открывает `HOME` сразу после старта);
- базовые настройки, статус и главный экран;
- сохранение `PDA` и `tx signature` после успешной регистрации.
- создание и возобновление серверной сессии `SHiNE` через WebSocket с `sessionType = 100` и `clientPlatform = "ESP32"`.

Что пока считается именно прототипом, а не финальной интеграцией:

- приём реальных входящих запросов на вход/подпись пока не подключён к живой сети;
- входящие запросы пока демонстрационные, чтобы можно было проверить UX и логику подтверждения.

## Основная идея устройства

Устройство работает как отдельный homeserver:

- хранит секрет на самом устройстве;
- позволяет ввести логин, секрет и имя homeserver;
- показывает адрес кошелька устройства;
- позволяет пополнить баланс перед регистрацией;
- после выполнения условий даёт зарегистрировать устройство как homeserver;
- после регистрации может принимать входящие запросы на вход и на подпись.

`SD`-карта не нужна для постоянного хранения секрета в этом прототипе.
Основное сохранение идёт во внутреннюю flash-память через `NVS`.

## Данные, которые хранятся на устройстве

Прототип хранит:

- `PIN`;
- `Wi-Fi SSID`;
- `Wi-Fi password`;
- `login`;
- `session/homeserver name`;
- `master secret`;
- `wallet address`;
- `user pda address`;
- `registration signature`;
- `balance`;
- `server api url`;
- `server rpc url`;
- `server ws url`;
- флаги:
  `wifiReady`, `serversReady`, `secretReady`, `registered`, `online`.

## Правило серверной сессии SHiNE

При подключении к серверу `SHiNE` устройство должно авторизовываться как homeserver-сеанс:

- `sessionType = 100`
- `clientPlatform = "ESP32"`
- `clientInfo = "ESP32 homeserver"`

Это относится и к `CreateAuthSession`, и к `SessionLogin`.

## Правила готовности к регистрации

Кнопка регистрации доступна только если одновременно выполнены условия:

1. настроен и подтверждён `Wi-Fi`;
2. заполнены и подтверждены серверные адреса;
3. задан логин;
4. сгенерирован или введён секрет;
5. баланс кошелька не меньше `0.20 SOL`;
6. устройство ещё не зарегистрировано.

Если хотя бы одно условие не выполнено, главный экран показывает, чего именно не хватает.

## Экранная модель

В прототипе используются следующие экраны:

1. `LOCK`
2. `HOME`
3. `STATUS`
4. `CONNECTION`
5. `WIFI_EDIT`
6. `SERVERS`
7. `ACCOUNT`
8. `WALLET`
9. `WALLET_QR`
10. `REQUESTS`
11. `REQUEST_DETAIL`
12. `SETTINGS`
13. `PIN_EDIT`
14. `TEXT_INPUT`
15. `CONFIRM`
16. `REGISTER_ACCOUNT_CONFIRM`
17. `REGISTER_ACCOUNT_RESULT`

## Общие правила интерфейса

- Верхняя строка всегда показывает краткий статус устройства:
  `PIN`, `Wi-Fi`, `сервер`, `регистрация`.
- Основной язык прототипа: русский.
- Для вывода текста в текущей временной сборке используется стандартный шрифт `Arduino_GFX`.
- Русские строки на экране временно показываются в ASCII-транслитерации.
- Кнопки крупные, с тач-ориентированным размером.
- Опасные действия подтверждаются отдельным диалогом.
- После изменения данных конфигурация сразу сохраняется в `NVS`.

## Экран LOCK

Назначение:

- экран блокировки предусмотрен в UI, но в текущей временной сборке после запуска пропускается;
- вход по PIN временно отключён для отладки остальных экранов.

Отображается:

- заголовок `SHiNE Device`;
- статус `Устройство заблокировано`;
- поле ввода PIN в виде маски;
- кнопки цифровой клавиатуры;
- кнопки `Стереть` и `Открыть`.

Поведение:

- если PIN введён верно, открывается `HOME`;
- если PIN неверный, показывается ошибка `Неверный PIN`;
- в текущей временной сборке этот экран не показывается автоматически при старте.

## Экран HOME

Это основной экран устройства.

Показывает:

- крупный статус регистрации;
- имя логина;
- имя homeserver;
- строку `Wi-Fi: <SSID> connected|disconnected`;
- строку `SHiNE: <server address> connected|unavailable`;
- короткий статус баланса.

Особенности верхнего блока:

- зелёный/контурный статусный кружок аккаунта расположен слева от строки логина;
- блок `STATUS` поднят выше относительно предыдущей версии;
- если состояние хорошее, слово `connected` в строках `Wi-Fi` и `SHiNE` показывается зелёным.

В зоне баланса:

- основная кнопка показа/обновления баланса занимает примерно 80% строки;
- текст на кнопке баланса выровнен левее центра;
- справа от неё стоит отдельная кнопка `QR`;
- после старта устройства баланс пытается загрузиться автоматически, если уже есть секрет и `Wi-Fi`;
- нажатие на кнопку `QR` открывает экран `WALLET_QR`.

Нижние кнопки:

- `Статус`
- `Подключение`
- `Аккаунт`
- `Кошелёк`
- `Запросы`
- `Настройки`

Дополнительная большая кнопка:

- `REGISTER ACCOUNT`
- либо жёлтая `ADD HOMESERVER`
- либо жёлтая `FIX HOMESERVER PASSWORD`

Если регистрация уже сделана:

- если пользователь создан, но в `PDA` ещё нет сессии текущего homeserver, показывается жёлтая кнопка `ADD HOMESERVER`;
- если в `PDA` есть homeserver с тем же именем, но с другим ключом, показывается жёлтая кнопка `FIX HOMESERVER PASSWORD`;
- если и пользователь, и homeserver-сессия уже корректны, вместо призыва к регистрации показывается статус `Homeserver активен`.
- две нижние кнопки внизу экрана не прилегают вплотную друг к другу, между ними есть небольшой зазор.

## Экран REGISTER_ACCOUNT_CONFIRM

Показывает предварительную проверку перед отправкой транзакции регистрации.

Отображается:

- повторный `login`;
- сообщение о том, что логин свободен или уже занят;
- баланс кошелька с проверкой порога `0.020 SOL`;
- имя homeserver;
- пометка, если используется стандартное значение `homeserver1`;
- отдельное предупреждение, если `Wi-Fi` не подключён.

Кнопки:

- `ЗАРЕГИСТРИРОВАТЬ В СИЯНИИ`
- `BACK`

Поведение:

- если `Wi-Fi` не подключён, на экране прямо показывается уведомление об этом и кнопка регистрации недоступна;
- если `login` уже занят в `shine_users`, регистрация недоступна;
- если баланс меньше `0.020 SOL`, на экране показывается соответствующая ошибка;
- если все проверки пройдены, кнопка регистрации активна и запускает on-chain регистрацию.

## Экран REGISTER_ACCOUNT_RESULT

Показывает результат отправки регистрации.

Отображается:

- текст успеха или ошибки;
- подробное сообщение;
- при успехе краткий `user_pda`;
- при успехе краткий `tx signature`.

Кнопки:

- `BACK HOME`
- `ACCOUNT`

Поведение:

- после успешной регистрации данные `user_pda` и `tx signature` сохраняются в `NVS`;
- при ошибке на экране показывается причина отказа;
- если ошибку вернул `sendTransaction`, экран старается показать не только общий текст, но и детали `RPC`/preflight/simulate-логов.

## Экран HOMESERVER_PDA_CONFIRM

Показывает, что именно не так с homeserver-секцией уже существующей пользовательской `PDA`.

Отображается:

- причина (`homeserver` отсутствует в `PDA` или ключ не совпадает с локальным секретом);
- `login`;
- имя `homeserver`;
- короткое пояснение, что именно будет сделано.

Кнопки:

- `ADD HOMESERVER` или `FIX HOMESERVER PASSWORD`
- `BACK`

Поведение:

- если `Wi-Fi` не подключён, действие недоступно;
- экран не создаёт нового пользователя, а запускает `update_user_pda`;
- при `ADD HOMESERVER` в блок `sessions` добавляется запись `session_type=100`;
- при `FIX HOMESERVER PASSWORD` обновляется публичный ключ уже существующей записи `homeserver`.

## Экран HOMESERVER_PDA_RESULT

Показывает результат обновления `sessions` в пользовательской `PDA`.

Отображается:

- успех или ошибка;
- короткое сообщение;
- при успехе краткий `tx signature`.

Кнопки:

- `BACK HOME`
- `ACCOUNT`

Поведение:

- при ошибке текст ошибки сохраняется в ту же USB/NVS-диагностику, что и регистрация;
- после успешного обновления выполняется повторная проверка `PDA`, и основной экран должен перейти в состояние `ok`.

## Экран STATUS

Показывает сводку:

- логин;
- homeserver;
- есть ли секрет;
- зарегистрировано ли устройство;
- подключён ли Wi-Fi;
- доступны ли серверы;
- хватает ли баланса;
- находится ли устройство онлайн;
- краткий отпечаток `PDA` или `tx`.

Кнопки:

- `Назад`
- `Обновить статус`

`Обновить статус` в прототипе не делает сеть, а просто перерисовывает текущие вычисленные состояния.

## Экран CONNECTION

Показывает:

- `Wi-Fi`: готов / не готов;
- `Серверы`: готовы / не готовы;
- `Онлайн`: да / нет.

Кнопки:

- `Wi-Fi`
- `Серверы`
- `Подключить`
- `Отключить`
- `Назад`

Поведение:

- `Подключить` переводит устройство в `online=true`, если `Wi-Fi` реально подключён и серверы реально проверены;
- `Отключить` переводит устройство в `online=false`.

## Экран WIFI_EDIT

Поля:

- `SSID`
- `Пароль`

Кнопки:

- `Изменить SSID`
- `Изменить пароль`
- `Проверить`
- `Сбросить`
- `Назад`

Поведение:

- `Проверить` делает реальную попытку подключения к `Wi-Fi`;
- `Сбросить` очищает обе строки и ставит `wifiReady=false`.

## Экран SERVERS

Поля:

- `API URL`
- `RPC URL`
- `WS URL`

Кнопки:

- `Изменить API`
- `Изменить RPC`
- `Изменить WS`
- `Проверить`
- `Тестовые`
- `Назад`

Поведение:

- `Тестовые` подставляет дефолтные тестовые значения;
- `Проверить` делает реальные сетевые проверки:
  - `API URL` должен отвечать по `HTTP/HTTPS`;
  - `RPC URL` должен отвечать на `Solana JSON-RPC`;
  - `WS URL` должен принимать `TCP/TLS`-соединение.

## Экран ACCOUNT

Показывает:

- логин;
- имя homeserver;
- статус секрета;
- короткий отпечаток секрета;
- статус регистрации;
- короткий отпечаток `PDA` или `tx`.

Кнопки:

- `Изменить логин`
- `Секрет`
- `Имя homeserver`
- `Сгенерировать`
- `Очистить`
- `Назад`

Поведение:

- `Сгенерировать` создаёт новый `master secret` и пересчитывает из него `device`-кошелёк;
- `Очистить` удаляет секрет, адрес кошелька, `PDA`, `tx`, регистрацию и онлайн-статус;
- логин приводится к нижнему регистру и trim.
- после успешной регистрации на экране сохраняются и отображаются краткие отпечатки `PDA` и `TX`.

## Экран WALLET

Показывает:

- адрес кошелька устройства;
- баланс в `SOL`;
- минимально рекомендуемую сумму для регистрации;
- статус `Хватает / Не хватает`.

Кнопки:

- `QR и URI`
- `+0.10 SOL`
- `+0.25 SOL`
- `-0.10 SOL`
- `Проверить`
- `Назад`

Поведение:

- кнопки пополнения/уменьшения нужны для теста сценариев;
- `Проверить` читает реальный баланс из `Solana RPC`;
- адрес кошелька должен совпадать с `device key`, вычисленным из сохранённого `master secret`;
- отрицательный баланс не допускается.

## Экран WALLET_QR

Экран показывает:

- крупный реальный `QR` для строки `solana:<wallet_address>`;
- снизу крупный текст самого адреса кошелька.

Поведение:

- отдельная текстовая подсказка возврата не показывается;
- возврат на главный экран выполняется обычным тапом по экрану.

Показывает:

- QR-код для строки вида:
  `solana:<wallet>`;
- мелкую подпись с полным адресом кошелька под QR.

Поведение:

- QR должен быть сканируемым, а не декоративным;
- адрес кошелька берётся из `device key`, вычисленного из сохранённого `master secret`;
- нажатие в любую точку экрана возвращает пользователя на `HOME`.

## Экран REQUESTS

Показывает список демонстрационных запросов:

- `Вход в сессию`
- `Подпись сообщения`

Для каждого запроса:

- тип;
- источник;
- короткий статус.

Кнопки:

- `Открыть запрос 1`
- `Открыть запрос 2`
- `Назад`

## Экран REQUEST_DETAIL

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

- тип запроса;
- кто запросил;
- время;
- описание;
- отпечаток/идентификатор.

Кнопки:

- `Разрешить`
- `Отклонить`
- `Назад`

Поведение:

- после разрешения или отклонения запрос помечается обработанным;
- экран списка отражает новый статус.

## Экран SETTINGS

Показывает:

- текущий PIN;
- базовые флаги безопасности;
- технические действия прототипа.

Кнопки:

- `Сменить PIN`
- `Сбросить онлайн`
- `Полный сброс`
- `Назад`

`Полный сброс` очищает весь локальный конфиг и возвращает устройство к стартовому состоянию.

## Экран PIN_EDIT

Используется для ввода нового PIN.

Правила:

- допустимы только цифры;
- длина PIN: 4..8 символов;
- после сохранения новый PIN немедленно пишется в `NVS`.

## Экран TEXT_INPUT

Это общий экран редактирования текстовых полей.

Используется для:

- `SSID`
- `Пароль Wi-Fi`
- `Логин`
- `Имя homeserver`
- `API URL`
- `RPC URL`
- `WS URL`

Состав экрана:

- заголовок поля;
- текущее значение;
- программная клавиатура;
- кнопки `Стереть`, `OK`, `Отмена`.

## Экран CONFIRM

Это модальный экран подтверждения.

Используется для:

- регистрации;
- очистки секрета;
- полного сброса.

Кнопки:

- `Подтвердить`
- `Отмена`

## Сценарий первой настройки

Ожидаемый путь пользователя:

1. открыть устройство сразу после старта; экран PIN временно не требуется;
2. открыть `Подключение -> Wi-Fi`;
3. ввести `SSID` и пароль, нажать `Проверить`;
4. открыть `Подключение -> Серверы`;
5. проверить или задать серверные адреса;
6. открыть `Аккаунт`;
7. ввести логин;
8. задать имя homeserver;
9. сгенерировать секрет;
10. открыть `Кошелёк`;
11. при необходимости пополнить баланс;
12. вернуться на `HOME`;
13. нажать `REGISTER ACCOUNT`;
14. на экране проверки ещё раз увидеть `login`, статус свободного `PDA`, баланс, `homeserver1` и при необходимости сообщение о неподключённом `Wi-Fi`;
15. нажать `ЗАРЕГИСТРИРОВАТЬ В СИЯНИИ`;
16. после завершения увидеть либо экран успеха с `user_pda` и `tx signature`, либо подробную ошибку;
17. после успешной регистрации увидеть статус `Homeserver активен`.

Примечание:

- устройство реально отправляет `create_user_pda` в `shine_users`, а после подтверждения сохраняет `PDA` и `tx signature`.

## Сценарий входящего запроса

1. открыть `Запросы`;
2. выбрать один из запросов;
3. прочитать детали;
4. нажать `Разрешить` или `Отклонить`;
5. убедиться, что статус запроса изменился.

## Временный режим текста

В текущей диагностической версии:

- строковые литералы в коде остаются русскими и в `UTF-8`;
- перед выводом на экран они временно транслитерируются в ASCII;
- рендер выполняется стандартным шрифтом `Arduino_GFX`;
- это обходной режим, пока `U8g2`-шрифты на устройстве не начнут рисоваться стабильно.

## Критерии ручной проверки

Минимально нужно проверить:

1. устройство загружается и сразу открывает `HOME`; экран блокировки временно отключён;
2. текст отображается читаемо хотя бы в ASCII-транслитерации;
3. ввод по экранной клавиатуре работает;
4. после перезагрузки сохранённые поля остаются в памяти;
5. секрет и адрес кошелька сохраняются на устройстве;
6. экран `QR и URI` рисует читаемый QR-код;
7. регистрация блокируется, пока условия не выполнены;
8. после выполнения условий регистрация становится доступной;
9. список запросов и экран подтверждения работают;
10. полный сброс действительно очищает сохранённое состояние.
