# Локальное окружение и восстановление

WealthLedger поставляется как локальное приложение: frontend работает
в браузере, backend обслуживает API и обращается к SQLite и внешним источникам.
Это описание предпосылок и ограничений работы, без привязки к устройству
исходного кода. Описано локальное окружение; production-топология по нему
не подтверждается.

## Подготовка backend

Локальная серверная среда использует Node 22 и SQLite. Для работы нужны:

| Параметр | Назначение и ограничение |
| --- | --- |
| Адрес локальной базы | Одинаковая база используется при подготовке схемы и работе приложения; относительный адрес зависит от рабочей директории процесса |
| Разрешённый origin frontend | Определяет browser-источник, которому разрешён доступ к API с credentials |
| Порт API | По умолчанию 3000 |
| Секрет подписи сессий | Секрет не короче 32 символов; отличается от ключа шифрования подключения |
| Ключ шифрования подключения | 32 байта в base64; требуется для чтения сохранённого T-Bank token |
| Параметры интеграции | Адрес T-Bank, лимит запросов и при необходимости доверенный CA; [ограничения](../integrations/tbank.md#конфигурация-и-ограничения) |

T-Bank token вводится пользователем через интерфейс после входа и не является
общим параметром окружения. Существующая база и её ключ шифрования сохраняются
при обновлении. До миграции необходима резервная копия; восстановление проверяется
на отдельной копии. Потеря или замена ключа не является безвредным сбросом:
прежнее подключение нельзя расшифровать новым ключом.

**Известное ограничение:** ранее была зафиксирована ошибка `Schema engine error`
на новой временной SQLite-базе до создания схемы. Условия проверки и пересмотра —
в [ограничении сквозной проверки](verification.md#известное-ограничение-сквозной-проверки).
Пользовательская база для такого воспроизведения не нужна; полный первый запуск
на чистой базе этим свидетельством не подтверждён.

В development доступна [локальная Swagger UI](http://localhost:3000/api/docs)
при стандартном порте API. Она показывает контракт, но не доказывает доступность
T-Bank и не используется frontend как источник данных во время работы.

## Подготовка frontend

Стандартные адреса: API `http://localhost:3000`, frontend `http://localhost:5173`.
Адрес API в клиенте должен совпадать с работающим сервером, а разрешённый origin
backend — с origin браузера. Смена порта требует согласованного изменения
адресов. Смесь `localhost` и `127.0.0.1` меняет границу browser cookie и CORS.

Локальный HTTP предполагает development-режим backend: в других режимах
refresh-cookie получает Secure flag и требует защищённого соединения.
Поведение сессии описано в [Authentication](../domains/authentication/overview.md).

## Первый сценарий

1. Пользователь регистрируется или входит. Новый профиль получает сессию;
   после перезагрузки приложение пытается её восстановить.
2. В настройках пользователь сохраняет собственный T-Bank Invest token.
   Успех означает проверенный доступ к брокеру и сохранённое подключение.
3. В разделе «Счета» доступны отдельный и общий портфель. Отсутствие доступных
   счетов является допустимым пустым результатом.
4. «Доходы» показывают полученные выплаты, «События» — будущие.
5. При выходе локальная сессия и её клиентский кэш очищаются.

Без T-Bank token доступны регистрация, вход и состояние отсутствующего
подключения. Это не подтверждает работу финансовых сценариев.

## Если запуск или сценарий не работает

| Симптом | Проверка и безопасное восстановление |
| --- | --- |
| Порт занят | Адрес действующего процесса или выбранный свободный порт должен совпадать с настройками клиента и разрешённым origin |
| Ошибка CORS или сессия теряется после reload | Согласованность адресов, hostname и режима cookie проверяется на стороне browser и backend |
| Ошибка подготовки базы | Установленный blocker не устраняется удалением пользовательской базы или обходом миграций; сохраняются версия среды и текст ошибки |
| `TBANK_NOT_CONNECTED` | Подключение создаётся в настройках текущего пользователя |
| `INVALID_TBANK_TOKEN` | После проверки token и прав у брокера подключение заменяется через настройки |
| `TBANK_UNAVAILABLE`, TLS или rate limit | Проверяются сеть, лимиты и доверенный CA; проверка TLS сохраняется |
| НКР/MOEX недоступен при работающих остальных секциях | Состояние источника и повторная попытка относятся к конкретной секции; недоступность не означает отсутствия рейтинга |
| Подключение не читается после смены ключа | Восстанавливается прежний ключ из защищённой копии; если он утрачен, собственный token вводится заново через настройки |

HTTP-запросы связываются с безопасными журналами через `X-Request-ID`.
Пароли, cookies, Authorization и broker token не включаются в диагностический
отчёт. Ограничения журналирования — [ADR 008](../adr/008-pino-backend-logging.md).

## Проверка первого изменения

Успешная сборка, запуск и прохождение сценария — разные доказательства.
Границы [проверок системы](verification.md) и
[HTTP-контракта](runtime-openapi-verification.md) рассматриваются отдельно.
Завершённость результата учитывает фактические проверки и остающиеся ограничения.