# WealthLedger: документация проекта

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

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

1. Прочитайте [обзор системы](architecture/system-overview.md): пользователи,
   внешние системы, исполняемые части и движение данных.
2. Откройте [карту возможностей](features/README.md): выберите предметную
   область и найдите её поведение, ограничения и ответственность компонентов.
3. Сверяйте незнакомые понятия с [глоссарием](architecture/domain-glossary.md).
   Особенно важны различия между User, Session, подключением и брокерским
   счётом, между полученным доходом и прогнозом выплаты.
4. Изучите [локальное окружение](development/local-workspace.md) и один
   сценарий: вход → подключение T-Bank → счёт → портфель → доходы или события.

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

## Найти ответ по задаче

| Вопрос | Начать здесь |
| --- | --- |
| Как части проекта работают вместе? | [Обзор и схемы](architecture/system-overview.md) |
| Как устроена конкретная возможность и кто за неё отвечает? | [Карта возможностей](features/README.md) |
| Что означает термин или финансовый показатель? | [Глоссарий](architecture/domain-glossary.md) |
| Почему выбраны эти архитектурные ограничения? | [Решения ADR](adr/README.md) |
| Какие условия нужны для работы и как понимать локальные ошибки? | [Окружение и восстановление](development/local-workspace.md) |
| Где точные API-типы, статусы и правила изменения контракта? | [HTTP API](architecture/http-api.md) и [генерация контракта](development/runtime-openapi-verification.md) |
| Как проверяются согласованность и качество системы? | [Сопровождение](development/README.md) |
| Как обновлять знания вместе с кодом? | [Ведение документации](development/documentation.md) |

[Тематический индекс](AI_INDEX.md) связывает вопросы с соответствующими
объяснениями. Читать весь репозиторий для ответа на один вопрос не требуется.

## Какому источнику доверять

Документация объясняет текущее устройство и поведение системы. Точный публичный
HTTP-контракт публикует backend в OpenAPI; ADR сохраняют причины принятых решений.
Требования и предложения изменений могут отдельно согласовываться в OpenSpec,
но для понимания описанных сценариев доступ к нему не нужен.
[Карта владельцев фактов](development/documentation.md#владельцы-фактов)
помогает различать назначение этих знаний и разрешать расхождения.

Текущие объяснения находятся в `architecture` и `features`; руководства — в
`development`. [Исследования](research/README.md) содержат проверенные наблюдения
и варианты, [аудиты](audits/README.md) — исторические свидетельства.
Наличие рекомендации в исследовании или требования в старом change ещё не
означает, что возможность реализована. Статус каждого ADR указан в
[журнале решений](adr/README.md).

Основная документация читается самостоятельно, без исходников других
репозиториев. [Исторические свидетельства](development/README.md#исторические-свидетельства)
сохраняют исходные технические адреса своего времени и не являются
обязательным чтением для понимания системы. Документы используют Markdown,
схемы — Mermaid.