# 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) |
| Проверить условия локальной работы | [Окружение и восстановление](development/local-workspace.md) |
| Понять ошибку или старые данные | [Состояния интерфейса](architecture/cross-cutting/ui-resilience.md), [свежесть данных](architecture/cross-cutting/data-freshness.md) |
| Найти визуальные роли и примеры | [Дизайн-система](development/design-system.md), [UI-каталог](development/ui-catalog.md) |
| Узнать причину архитектурного решения | [Журнал ADR](adr/README.md) |
| Изменить или проверить систему | [Сопровождение](development/README.md), затем инструкции нужного репозитория |

Практический tutorial первого инвестиционного сценария пока не подготовлен:
он требует подключения брокера, а запуск на новой базе имеет известное
ограничение. Маршрут первого знакомства выше — чтение, не учебный запуск.
UI-каталог содержит безопасные вымышленные примеры и поясняет границы их использования.

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

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

Эти источники дополняют друг друга. Найденный незавершённый change не доказывает
реализованную функцию; расхождение кода и требования требует разбора.
Итоги исследований входят в ADR, когда принято значимое решение, и в тематические
страницы, когда уточняют знания о системе. Исходные исследовательские отчёты
в docs не хранятся. [Исторические свидетельства](development/README.md#исторические-свидетельства)
сохраняют результаты своего времени и не заменяют текущее описание системы.

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