# Локальное окружение и восстановление 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#известное-ограничение-сквозной-проверки). На Node 22.21.0 / Prisma 7.9.1 подтверждено три последовательных применения миграций к новым временным базам с `RUST_LOG=info` вне sandbox. Без этой переменной ошибка воспроизводится. Пользовательская база для воспроизведения не нужна; успешная миграция сама по себе не подтверждает полный первый запуск. В 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 доступны регистрация, вход, состояние отсутствующего подключения и [ручной банковский учёт](../domains/cards/overview.md). Банковский сценарий не подтверждает доступность инвестиционных поставщиков. ## Сохранение данных и откат Перед обновлением сохраняется согласованный SQLite backup; ключ шифрования T-Bank хранится отдельно. Для работающей базы используется SQLite backup API, который учитывает WAL. Несогласованное копирование файлов базы и WAL не является резервной копией. Восстановление сначала проверяется на отдельном файле. Банковская миграция добавляет таблицы, сохраняя User, Session и TbankConnection. При необходимости отката приложения сначала прекращаются новые записи и сохраняется актуальный снимок. Затем возвращается совместимая предыдущая версия backend при сохранении расширенной схемы. Старый backup не восстанавливается поверх новой истории: это удалило бы введённые банковские операции. Совместимость проверена с исходной версией backend `8ec172f48eefa2237dc0c16919fbb2e726b39a65`: она выполняла вход с расширенной схемой, а новая версия после возврата читала прежние карты и операции. Отдельно проверены перезапуск, служебные данные защиты повторов и приложение на восстановленной SQLite-копии. Это подтверждение конкретной пары версий, а не гарантия совместимости любого будущего изменения схемы. Проверка воспроизводится через [процессный сценарий](../../backend/test/bank-cards-durability.cjs) с каталогом отдельно собранного baseline: после активации backend `.nvmrc` выполнить `node test/bank-cards-durability.cjs `. Сценарий создаёт собственные временные базы и вымышленные данные. Migrations и HTTP/DB-ограничения описаны в [проверке системы](verification.md). ## Если запуск или сценарий не работает | Симптом | Проверка и безопасное восстановление | | --- | --- | | Порт занят | Адрес действующего процесса или выбранный свободный порт должен совпадать с настройками клиента и разрешённым 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) рассматриваются отдельно. Завершённость результата учитывает фактические проверки и остающиеся ограничения.