137 lines
13 KiB
Markdown
137 lines
13 KiB
Markdown
# Локальное окружение и восстановление
|
||
|
||
WealthLedger поставляется как локальное приложение: frontend работает
|
||
в браузере, backend обслуживает API и обращается к SQLite и внешним источникам.
|
||
Это описание предпосылок и ограничений работы, без привязки к устройству
|
||
исходного кода. Описано локальное окружение; production-топология по нему
|
||
не подтверждается.
|
||
|
||
Структура пяти независимых Git-репозиториев, команды получения checkout и
|
||
безопасные границы root tracking описаны в [workspace README](../../README.md).
|
||
Корень — репозиторий `WealthLedger/main`; frontend, backend, docs и specs
|
||
клонируются внутрь него отдельно.
|
||
|
||
## Версия Node
|
||
|
||
Все локальные проверки используют Node 24 LTS; `.nvmrc` в frontend, backend
|
||
и docs фиксирует 24.21.0. Specs использует frontend `.nvmrc`.
|
||
По [официальному расписанию Node](https://github.com/nodejs/Release#release-schedule)
|
||
поддержка 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; [ограничения](../integrations/tbank.md#конфигурация-и-ограничения) |
|
||
|
||
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` больше не требуется.
|
||
Условия и доказательство — в
|
||
[сквозной проверке](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 доступны регистрация, вход, состояние отсутствующего
|
||
подключения и [ручной банковский учёт](../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 <baseline-directory>`.
|
||
Сценарий создаёт собственные временные базы и вымышленные данные. Migrations
|
||
и HTTP/DB-ограничения описаны в [проверке системы](verification.md).
|
||
|
||
## Если запуск или сценарий не работает
|
||
|
||
| Симптом | Проверка и безопасное восстановление |
|
||
| --- | --- |
|
||
| Порт занят | Адрес действующего процесса или выбранный свободный порт должен совпадать с настройками клиента и разрешённым 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](../adr/008-pino-backend-logging.md).
|
||
|
||
## Проверка первого изменения
|
||
|
||
Успешная сборка, запуск и прохождение сценария — разные доказательства.
|
||
Границы [проверок системы](verification.md) и
|
||
[OpenAPI contract flow](runtime-openapi-verification.md) рассматриваются отдельно.
|
||
Завершённость результата учитывает фактические проверки и остающиеся ограничения.
|