docs: make project documentation self-contained

development/local-workspace.md

@@ -0,0 +1,84 @@
+# Локальное окружение и восстановление
+
+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; [ограничения](../features/tbank-connection.md#конфигурация-и-ограничения) |
+
+T-Bank token вводится пользователем через интерфейс после входа и не является
+общим параметром окружения. Существующая база и её ключ шифрования сохраняются
+при обновлении. До миграции необходима резервная копия; восстановление проверяется
+на отдельной копии. Потеря или замена ключа не является безвредным сбросом:
+прежнее подключение нельзя расшифровать новым ключом.
+
+**Известное ограничение:** проверка новой временной SQLite-базы 12 сентября
+2026 года под Node 22 воспроизвела `Schema engine error` до создания схемы.
+Полный первый запуск на чистой базе пока не подтверждён; пользовательская база
+в этой проверке не использовалась. Условия пересмотра —
+[проверка backend](backend-workflow.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](../features/authentication.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).
+
+## Проверка первого изменения
+
+Успешная сборка, запуск и прохождение сценария — разные доказательства.
+Границы проверки описаны для [frontend](frontend-workflow.md),
+[backend](backend-workflow.md) и [HTTP-контракта](runtime-openapi-verification.md).
+Завершённость результата учитывает фактические проверки и остающиеся ограничения.