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

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

Структура пяти независимых Git-репозиториев, команды получения checkout и безопасные границы root tracking описаны в workspace README. Корень — репозиторий WealthLedger/main; frontend, backend, docs и specs клонируются внутрь него отдельно.

Версия Node

Все локальные проверки используют Node 24 LTS; .nvmrc в frontend, backend и docs фиксирует 24.21.0. Specs использует frontend .nvmrc. По официальному расписанию Node поддержка Node 24 завершается 30.04.2028. В каждом npm-репозитории выполните nvm install, nvm use --silent и npm ci; в backend затем npm run build для генерации Prisma client. Поставляемый npm 11.19 запускает dependency install scripts только по allowScripts в package.json; разрешения привязаны к версиям сборочных зависимостей и пересматриваются при их обновлении. После смены major обязательна переустановка native modules через npm ci. Для отката верните прежние runtime/package/lockfile-конфигурации, выберите Node 22 и повторите npm ci и backend build. Сам переход Node не меняет схему или данные.

Подготовка backend

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

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

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

После подготовки зависимостей и конфигурации примените штатные migrations: из backend после nvm use --silent выполните npx prisma migrate deploy. Для существующей базы сначала сохраните согласованный backup. На Node 22.21.0 / Prisma 7.9.1 обнаружена зависимость fresh migration от унаследованного RUST_LOG=warn/error. Backend Prisma config исключает эту переменную из процесса CLI; назначать RUST_LOG=info больше не требуется. Условия и доказательство — в сквозной проверке.

В development доступна локальная Swagger UI при стандартном порте 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.

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

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

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

Сохранение данных и откат

Перед обновлением сохраняется согласованный SQLite backup; ключ шифрования T-Bank хранится отдельно. Для работающей базы используется SQLite backup API, который учитывает WAL. Несогласованное копирование файлов базы и WAL не является резервной копией. Восстановление сначала проверяется на отдельном файле.

Банковская миграция добавляет таблицы, сохраняя User, Session и TbankConnection. При необходимости отката приложения сначала прекращаются новые записи и сохраняется актуальный снимок. Затем возвращается совместимая предыдущая версия backend при сохранении расширенной схемы. Старый backup не восстанавливается поверх новой истории: это удалило бы введённые банковские операции.

Совместимость проверена с исходной версией backend 8ec172f48eefa2237dc0c16919fbb2e726b39a65: она выполняла вход с расширенной схемой, а новая версия после возврата читала прежние карты и операции. Отдельно проверены перезапуск, служебные данные защиты повторов и приложение на восстановленной SQLite-копии. Это подтверждение конкретной пары версий, а не гарантия совместимости любого будущего изменения схемы.

Проверка воспроизводится через процессный сценарий с каталогом отдельно собранного baseline: после активации backend .nvmrc выполнить node test/bank-cards-durability.cjs <baseline-directory>. Сценарий создаёт собственные временные базы и вымышленные данные. Migrations и HTTP/DB-ограничения описаны в проверке системы.

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

Симптом	Проверка и безопасное восстановление
Порт занят	Адрес действующего процесса или выбранный свободный порт должен совпадать с настройками клиента и разрешённым origin
Ошибка CORS или сессия теряется после reload	Согласованность адресов, hostname и режима cookie проверяется на стороне browser и backend
Ошибка подготовки базы	Сохранить версию среды и текст ошибки; использовать backend Prisma config, не удалять пользовательскую базу и не обходить migrations
`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.

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

Успешная сборка, запуск и прохождение сценария — разные доказательства. Границы проверок системы и OpenAPI contract flow рассматриваются отдельно. Завершённость результата учитывает фактические проверки и остающиеся ограничения.

13 KiB Raw Blame History Unescape Escape