# WealthLedger: документация системы WealthLedger помогает частному инвестору понимать состав портфеля T-Bank, исполненные операции, полученный доход и будущие выплаты, а также вручную вести банковские карты и повседневные расходы. Здесь объясняются продукт, понятия, функции, взаимодействия и причины архитектурных решений. Основной текст можно читать без исходников; технические ссылки нужны для дальнейшей проверки и изменения системы. ## Первое знакомство 1. [Обзор продукта](overview.md) — задачи пользователя и границы приложения. 2. [Глоссарий](glossary.md) — пользователь, сессия, подключение, счёт, портфель, полученный доход и прогноз выплаты. 3. [Контекст](architecture/context.md) — WealthLedger и внешние системы. 4. [Контейнеры](architecture/containers.md) — браузерное приложение, API, локальное хранение и обмен данными. 5. [Портфель](domains/portfolio/overview.md) и [его загрузка](domains/portfolio/flows/portfolio-loading.md) — как источник превращается в позиции, суммы и состояние свежести. После этого читатель должен уметь объяснить происхождение финансового показателя и отличить данные брокера, расчёт сервера и сохранённый экран. ## Предметные области Папки областей группируют знания; они не объявляют отдельные сервисы. | Тема | Что здесь искать | | --- | --- | | [Аутентификация](domains/authentication/overview.md) | Регистрация, вход, восстановление и завершение сессии | | [Счета](domains/accounts/overview.md) | Доступные счета, сводки и состояния каждого счёта | | [Банковские карты](domains/cards/overview.md) | Ручные остатки, операции, категории, возвраты, месячные сводки и исправления | | [Портфель](domains/portfolio/overview.md) | Позиции, остатки, суммы, структура и свежесть | | [Все счета](domains/portfolio/all-accounts.md) | Общий портфель, происхождение строк и сводные разделы | | [Операции](domains/operations/overview.md) | Исполненные операции, фильтры и пагинация | | [Доход](domains/income/overview.md) | Полученные купоны и дивиденды, периоды и состав расчёта | | [Будущие выплаты](domains/income/upcoming-events.md) | Календарь по текущим позициям и ограничения прогноза | | [Скринер акций](domains/instruments/stocks.md) и [облигации](domains/instruments/bonds.md) | Подбор акций по параметрам, поиск выпуска, рыночные показатели и личная история | ## Найти материал по задаче | Потребность | Маршрут | | --- | --- | | Разобраться в системе | [Архитектура](architecture/README.md), нужная область выше, [внешние интеграции](integrations/README.md) | | Найти точные сведения | [Глоссарий](glossary.md), [показатели портфеля](domains/portfolio/data-reference.md), [HTTP API](architecture/http-api.md) | | Разобрать расхождение в суммах | [Диагностика портфеля](domains/portfolio/how-to/investigate-discrepancy.md) | | Понять ошибку или старые данные | [Состояния интерфейса](architecture/cross-cutting/ui-resilience.md), [свежесть данных](architecture/cross-cutting/data-freshness.md) | | Понять визуальные роли и состояния | [Визуальные принципы](design/overview.md) | | Узнать причину архитектурного решения | [Журнал ADR](adr/README.md) | | Запустить, обновить или восстановить приложение | [Контейнерная поставка](architecture/deployment.md) | ## Границы знаний [Основные спецификации](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/AI_INDEX.md) сохраняют согласованное проверяемое поведение, а OpenSpec changes — предложения, дизайн и задачи изменений. Фактический Store находится в `specs/openspec/`, основные требования — в `specs/openspec/specs/`. Docs объясняет систему; код, тесты, схемы и конфигурация задают конкретный механизм, а [ADR](adr/README.md) сохраняют принятые решения. Локальные инструкции [frontend](https://git.personal.ksv741.ru/WealthLedger/frontend/src/commit/9f7e342333b80bfacfd5bc394a2dcd0613d33ff3/AGENTS.md) и [backend](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/AGENTS.md) описывают изменение реализации и её проверки. Эти источники дополняют друг друга. Найденный незавершённый change не доказывает реализованную функцию; расхождение кода и требования требует разбора. Итоги исследований входят в ADR, когда принято значимое решение, и в тематические страницы, когда уточняют знания о системе. Исходные исследовательские отчёты в docs не хранятся. История изменений остаётся в Git; документация описывает текущее устройство системы и причины архитектурных решений. Правила изменения текста, диаграмм, ссылок и проверки docs-impact находятся в [CONTRIBUTING](CONTRIBUTING.md). ## Релизы Репозиторий выпускается независимо. `develop` — интеграция, `main` — принятые релизы. Обычная работа: issue-linked ветка от актуального `develop`, PR в `develop`; общие правила — в Engineering Workflow по ссылке из AGENTS. Обычные PR допускают squash; release и обратная синхронизация сохраняют историю. Commits и PR titles — Conventional Commits со ссылкой на Issue (кроме release), включая `spec:`. Версии вручную не повышай. 1. Получи `main`, `develop` и теги: `git fetch origin --tags`. Убедись, что `develop` содержит последний релиз. Создай `release/` от проверенного `develop`; `nvm use --silent`, `npm ci`. Hotfix начинается от `main` в `release/hotfix-` и проходит тот же процесс. 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 в `main` с заголовком `chore(release): X.Y.Z`. После зелёных `verify`, `security`, `commits` выполни fast-forward-only merge. Если `main` изменился, согласуй историю и повтори проверки кандидата. 4. Получи удалённый `main`, сравни его HEAD с проверенным release SHA и версией manifest/lockfile. Создай аннотированный `vX.Y.Z` именно на этом SHA: `git tag -a vX.Y.Z -m "Release X.Y.Z"`, затем отправь только `git push origin refs/tags/vX.Y.Z`. Не запускай release-it повторно на `main`. 5. Верни release-коммит через PR `main → develop` без squash/rebase; проверь, что `develop` содержит тег. Опубликованные теги не перемещай. При сбое после merge создай отсутствующий тег без нового bump; до merge исправь и проверь существующий кандидат без повторного повышения версии. `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*` защищены. Workflow сам не включает эти настройки. Отдельное review approval для одного владельца не требуется. Npm publishing, deploy и Gitea Releases не включены.