WealthLedger: документация системы

WealthLedger помогает частному инвестору понимать состав портфеля T-Bank, исполненные операции, полученный доход и будущие выплаты, а также вручную вести банковские карты и повседневные расходы. Здесь объясняются продукт, понятия, функции, взаимодействия и причины архитектурных решений. Основной текст можно читать без исходников; технические ссылки нужны для дальнейшей проверки и изменения системы.

Первое знакомство

1. Обзор продукта — задачи пользователя и границы приложения.
2. Глоссарий — пользователь, сессия, подключение, счёт, портфель, полученный доход и прогноз выплаты.
3. Контекст — WealthLedger и внешние системы.
4. Контейнеры — браузерное приложение, API, локальное хранение и обмен данными.
5. Портфель и его загрузка — как источник превращается в позиции, суммы и состояние свежести.

После этого читатель должен уметь объяснить происхождение финансового показателя и отличить данные брокера, расчёт сервера и сохранённый экран.

Предметные области

Папки областей группируют знания; они не объявляют отдельные сервисы.

Тема	Что здесь искать
Аутентификация	Регистрация, вход, восстановление и завершение сессии
Счета	Доступные счета, сводки и состояния каждого счёта
Банковские карты	Ручные остатки, операции, категории, возвраты, месячные сводки и исправления
Портфель	Позиции, остатки, суммы, структура и свежесть
Все счета	Общий портфель, происхождение строк и сводные разделы
Операции	Исполненные операции, фильтры и пагинация
Доход	Полученные купоны и дивиденды, периоды и состав расчёта
Будущие выплаты	Календарь по текущим позициям и ограничения прогноза
Скринер акций и облигации	Подбор акций по параметрам, поиск выпуска, рыночные показатели и личная история

Найти материал по задаче

Потребность	Маршрут
Разобраться в системе	Архитектура, нужная область выше, внешние интеграции
Найти точные сведения	Глоссарий, показатели портфеля, HTTP API
Разобрать расхождение в суммах	Диагностика портфеля
Понять ошибку или старые данные	Состояния интерфейса, свежесть данных
Понять визуальные роли и состояния	Визуальные принципы
Узнать причину архитектурного решения	Журнал ADR
Запустить, обновить или восстановить приложение	Контейнерная поставка

Границы знаний

Основные спецификации сохраняют согласованное проверяемое поведение, а OpenSpec changes — предложения, дизайн и задачи изменений. Фактический Store находится в specs/openspec/, основные требования — в specs/openspec/specs/. Docs объясняет систему; код, тесты, схемы и конфигурация задают конкретный механизм, а ADR сохраняют принятые решения. Локальные инструкции frontend и backend описывают изменение реализации и её проверки.

Эти источники дополняют друг друга. Найденный незавершённый change не доказывает реализованную функцию; расхождение кода и требования требует разбора. Итоги исследований входят в ADR, когда принято значимое решение, и в тематические страницы, когда уточняют знания о системе. Исходные исследовательские отчёты в docs не хранятся. История изменений остаётся в Git; документация описывает текущее устройство системы и причины архитектурных решений.

Правила изменения текста, диаграмм, ссылок и проверки docs-impact находятся в CONTRIBUTING.

Релизы

Репозиторий выпускается независимо. develop — интеграция, main — принятые релизы. Обычная работа: issue-linked ветка от актуального develop, PR в develop; общие правила — в Engineering Workflow по ссылке из AGENTS. PR сливается squash или rebase-merge; merge-коммит не используется. main обновляется только fast-forward из develop, поэтому история линейна:

<type>/<issue>-<slug> --squash--> develop --ff-only--> main --> tag vX.Y.Z

Инвариант: origin/main всегда предок origin/develop. Проверка:

git fetch -q origin
git merge-base --is-ancestor origin/main origin/develop && echo ok || echo BROKEN

Commits и PR titles — Conventional Commits со ссылкой на Issue (кроме release), включая spec:. Версии вручную не повышай.

1. Получи main, develop и теги: git fetch origin --tags. Проверь инвариант. Создай release/X.Y.Z от проверенного develop; nvm use --silent, npm ci.
2. На чистой ветке выполни npm run release:preview, просмотри версию/changelog, затем npm run release:prepare. Команда создаёт chore(release): X.Y.Z, обновляет manifest/lockfile/CHANGELOG; тег и push не выполняет. Не обходи guards ветки, чистого дерева, отсутствующих тегов или уже подготовленной версии.
3. Проверь diff и штатные gates этого репозитория. Отправь только release-ветку, открой PR в develop с заголовком chore(release): X.Y.Z. После зелёных verify, security, commits выполни fast-forward-only merge. Если develop изменился, обнови release-ветку и повтори проверки кандидата.
4. Открой PR develop → main с тем же заголовком и слей fast-forward-only.
5. Получи удалённый main, сравни его HEAD с проверенным release SHA и версией manifest/lockfile. Создай аннотированный vX.Y.Z именно на этом SHA: git tag -a vX.Y.Z <release-sha> -m "Release X.Y.Z", затем отправь только git push origin refs/tags/vX.Y.Z. Не запускай release-it повторно на main.

Обратная синхронизация не нужна: release-коммит попал в develop на шаге 3. Опубликованные теги не перемещай. При сбое после merge создай отсутствующий тег без нового bump; до merge исправь и проверь существующий кандидат без повторного повышения версии.

Freeze релиза не поддерживается: пока открыт релизный PR, develop не двигают. Срочный fix — обычная ветка fix/* от develop с последующим релизом; пути от main нет, он сделал бы main не-предком develop. Исключение требует явного решения: release/hotfix-<name> от main, PR в main, тег, затем merge main → develop для восстановления инварианта.

feat: повышает minor, fix:/perf: и прочие разрешённые типы — patch; !/BREAKING CHANGE: — major, включая версии до 1.0. chore(release): исключён из рекомендации и changelog. Конфигурация — .release-it.json. В Gitea для main/develop должны быть запрещены прямой/force push и обход администратором, включена блокировка устаревшей ветки, обязательны verify, security, commits; теги v* защищены. Линейность обеспечивают merge styles репозитория: merge-коммиты и rebase --no-ff выключены, доступны squash, rebase-merge и fast-forward-only; стиль по умолчанию — squash. Workflow сам не включает эти настройки. Отдельное review approval для одного владельца не требуется. Npm publishing, deploy и Gitea Releases не включены.