132 lines
12 KiB
Markdown
132 lines
12 KiB
Markdown
# 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 или rebase-merge; merge-коммит не используется. `main`
|
||
обновляется только fast-forward из `develop`, поэтому история линейна:
|
||
|
||
```text
|
||
<type>/<issue>-<slug> --squash--> develop --ff-only--> main --> tag vX.Y.Z
|
||
```
|
||
|
||
Инвариант: `origin/main` всегда предок `origin/develop`. Проверка:
|
||
|
||
```bash
|
||
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 не включены.
|