docs(specs): archive domain money contract change

2026-08-25 22:30:38 +03:00
parent 6898732dd8
commit 039b72eed3
13 changed files with 538 additions and 16 deletions
@@ -0,0 +1,68 @@
+## Why
+
+После нескольких итераций вокруг счетов, Portfolio, операций и будущих
+денежных событий в модели появились близкие, но не полностью согласованные
+формулировки. Одни документы говорят о принадлежности Brokerage Account User,
+другие — о доступности счёта через текущее подключение брокера. Денежные
+значения в части потоков описаны как единый Money, а в будущих событиях
+разделены на сумму и валюту. Валютная позиция инструмента и Cash Balance также
+легко смешиваются в чтении, хотя в поведении системы они имеют разные роли.
+
+Эти расхождения уже затрагивают публичное понимание продукта: разработчик,
+агент или downstream consumer может по-разному интерпретировать доступность
+счёта, свежесть Portfolio, денежные прогнозы и связь Instrument с событиями.
+Исправить это стоит сейчас, пока область T-Bank-инвестиций ещё компактна и до
+следующих расширений по операциям, прогнозам и аналитике.
+
+## What Changes
+
+- Согласовать канонический язык вокруг Brokerage Account: система описывает
+  счёт как доступный User через его текущее подключение брокера, не как
+  долговременно принадлежащий User объект внутри WealthLedger.
+- Согласовать денежные значения во всех инвестиционных read-моделях вокруг
+  единого Money-представления с явной валютой и отсутствующим значением как
+  неизвестностью, а не нулём.
+- Уточнить различие между Currency Instrument Position и Cash Balance: первая
+  является позицией по торгуемому инструменту, вторая — денежным остатком на
+  счёте.
+- Сделать язык Portfolio Snapshot явным там, где речь идёт о результате
+  наблюдения Portfolio на конкретный момент с признаком свежести.
+- Расширить доменный смысл Instrument так, чтобы он охватывал не только
+  Portfolio Position, но и связанные события по инструменту.
+- Структурировать domain glossary так, чтобы доменные термины не смешивались с
+  runtime/cache-механизмами, сохранив последние как технические ограничения
+  текущего поведения.
+- **Non-goals:** не менять физическую модульную структуру приложения, не
+  вводить новое долговременное хранение Portfolio, событий или счетов, не
+  переименовывать массово существующие пользовательские маршруты и не менять
+  брокерскую интеграцию сверх необходимого согласования observable contract.
+
+## Capabilities
+
+### New Capabilities
+
+_Нет._
+
+### Modified Capabilities
+
+- `brokerage-accounts`: требования к счетам должны использовать единый язык
+  доступности через текущее подключение брокера и не создавать ложное
+  ожидание долговременного владения счётом внутри WealthLedger.
+- `portfolio-view`: требования к Portfolio должны явно различать Portfolio
+  Snapshot, Cash Balance и позиции по валютным инструментам, а также
+  согласованно описывать Money и Instrument.
+- `brokerage-account-upcoming-events`: требования к будущим событиям должны
+  использовать тот же язык доступности счёта, Money и Instrument, что и
+  Portfolio.
+- `project-documentation`: glossary и durable documentation должны закрепить
+  единый доменный язык и отделить его от runtime/cache терминов.
+
+## Impact
+
+Затрагиваются пользователи и разработчики, которые читают инвестиционные
+экраны, API contract, OpenSpec requirements и as-built документацию по
+T-Bank-счетам, Portfolio и будущим денежным событиям. Изменение является
+контрактным для финансовых read-моделей и потребует синхронного обновления
+SDD, backend contract, frontend consumer types, пользовательских состояний и
+документации. Долговременная модель хранения User, Session и T-Bank connection
+не расширяется.