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
@@ -7,10 +7,12 @@
 ## Requirements

 ### Requirement: User can retrieve upcoming events for an account
-Система MUST предоставлять аутентифицированному User read-only список известных будущих событий принадлежащего ему Brokerage Account от момента запроса до 30 календарных дней после него включительно. Ответ MUST содержать только события coupon, dividend, maturity и offer, отсортированные по дате по возрастанию, и момент расчёта прогноза.
+Система MUST предоставлять аутентифицированному User read-only список известных будущих событий открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection User, от момента запроса до 30 календарных дней после него включительно. Ответ MUST содержать только события coupon, dividend, maturity и offer, отсортированные по дате по возрастанию, и момент расчёта прогноза.
+
+Список будущих событий является прогнозом по текущему наблюдаемому состоянию счёта и MUST NOT означать, что WealthLedger хранит долговременное право владения Brokerage Account независимо от T-Bank connection.

 #### Scenario: Получение событий доступного счёта
- **WHEN** аутентифицированный User запрашивает будущие события принадлежащего ему Brokerage Account
+- **WHEN** аутентифицированный User запрашивает будущие события открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection
 - **THEN** система возвращает известные события на следующие 30 календарных дней и момент, на который был выполнен расчёт

 #### Scenario: Отсутствие событий в периоде
@@ -22,15 +24,17 @@
 - **THEN** система возвращает существующий ответ о недоступности счёта и не раскрывает события

 ### Requirement: Forecasts preserve event meaning and uncertainty
-Система MUST передавать для каждого события его календарную дату, тип, доступные идентификаторы и название инструмента, исходную валюту и, если она известна, прогнозную сумму до налогов. Прогнозная сумма MUST рассчитываться по текущему количеству бумаг на момент запроса. Дивиденд MUST обозначать переданную дату как дату реестра, а offer MUST передаваться без вымышленной суммы.
+Система MUST передавать для каждого события его календарную дату, тип, доступные идентификаторы и название Instrument, а также прогнозную сумму до налогов как Money, если она известна. Прогнозная сумма MUST рассчитываться по текущему количеству бумаг на момент запроса. Если денежные условия события неизвестны или неприменимы, прогнозная сумма MUST быть `null`, а не нулём и не парой разрозненных полей. Дивиденд MUST обозначать переданную дату как дату реестра, а offer MUST передаваться без вымышленной суммы.
+
+Instrument в Future Cash Event MUST иметь тот же доменный смысл, что и в Portfolio: это финансовый инструмент, к которому относится событие, даже если событие не является Portfolio Position.

 #### Scenario: Прогноз купона по текущей позиции
 - **WHEN** поддерживаемая облигация в текущей Portfolio Position имеет известный купон в пределах периода
- **THEN** система возвращает событие coupon с суммой до налогов в исходной валюте, рассчитанной по текущему количеству облигаций
+- **THEN** система возвращает событие coupon с прогнозной суммой до налогов как Money в исходной валюте, рассчитанной по текущему количеству облигаций

 #### Scenario: Прогноз дивиденда
 - **WHEN** поддерживаемая акция в текущей Portfolio Position имеет объявленный дивиденд с датой фиксации реестра в пределах периода
- **THEN** система возвращает событие dividend с датой, обозначенной как дата реестра (`record_date`), и суммой до налогов, равной `dividend_net` на одну бумагу, умноженной на текущее количество акций
+- **THEN** система возвращает событие dividend с датой, обозначенной как дата реестра (`record_date`), и прогнозной суммой до налогов как Money, равной `dividend_net` на одну бумагу, умноженной на текущее количество акций

 #### Scenario: Отменённый дивиденд не попадает в прогноз
 - **WHEN** запись дивиденда T-Bank имеет тип выплаты `Cancelled`
@@ -38,7 +42,7 @@

 #### Scenario: Отображение оферты без суммы
 - **WHEN** для поддерживаемой облигации известна оферта в пределах периода, но её денежные условия недоступны
- **THEN** система возвращает событие offer без прогнозной суммы
+- **THEN** система возвращает событие offer с прогнозной суммой `null`

 #### Scenario: Неподдерживаемое частичное погашение
 - **WHEN** источник не предоставляет расписание будущих частичных погашений или амортизации облигации
@@ -60,7 +64,7 @@
 - **THEN** система трактует ответ как отсутствие данных по инструменту и не завершает запрос ошибкой

 ### Requirement: Account page presents an upcoming events list
-Страница Brokerage Account MUST предоставлять действие перехода на отдельную страницу «Будущие события». Эта страница MUST показывать все полученные события компактным списком без фильтров, пагинации и суммарного итога, с датой, типом, инструментом и суммой в исходной валюте, если она известна. Страница MUST объяснять, что прогноз основан на текущей позиции, указан до налогов и может быть неполным из-за доступности данных источника.
+Страница Brokerage Account MUST предоставлять действие перехода на отдельную страницу «Будущие события». Эта страница MUST показывать все полученные события компактным списком без фильтров, пагинации и суммарного итога, с датой, типом, инструментом и прогнозной суммой в исходной валюте, если она известна. Страница MUST объяснять, что прогноз основан на текущей позиции, указан до налогов и может быть неполным из-за доступности данных источника.

 #### Scenario: Просмотр ближайших событий
 - **WHEN** User открывает «Будущие события» из обзора Brokerage Account
@@ -7,7 +7,9 @@
 ## Requirements

 ### Requirement: Список активных брокерских счетов
-Система SHALL предоставлять авторизованному User `GET /api/v1/brokerage-accounts`, возвращающий массив его открытых поддерживаемых инвестиционных счетов T-Bank в порядке, полученном от T-Bank. Каждый элемент MUST содержать стабильный `id`, непустое `name`, нормализованный `type` (`BROKERAGE`, `INDIVIDUAL_INVESTMENT`, `INVEST_BOX` или `MONEY_MARKET_FUND`) и nullable `openedOn` в формате `YYYY-MM-DD`. Система MUST включать только счета T-Bank типов «брокерский счёт», «ИИС», «Инвесткопилка» и «фонд денежного рынка»; банковские и неизвестные типы MUST NOT возвращаться. Система MUST удалить внешние пробелы из имени и при пустом результате использовать непустое название соответствующего типа.
+Система SHALL предоставлять авторизованному User `GET /api/v1/brokerage-accounts`, возвращающий массив открытых поддерживаемых инвестиционных счетов T-Bank, доступных через текущий T-Bank connection User, в порядке, полученном от T-Bank. Каждый элемент MUST содержать стабильный `id`, непустое `name`, нормализованный `type` (`BROKERAGE`, `INDIVIDUAL_INVESTMENT`, `INVEST_BOX` или `MONEY_MARKET_FUND`) и nullable `openedOn` в формате `YYYY-MM-DD`. Система MUST включать только счета T-Bank типов «брокерский счёт», «ИИС», «Инвесткопилка» и «фонд денежного рынка»; банковские и неизвестные типы MUST NOT возвращаться. Система MUST удалить внешние пробелы из имени и при пустом результате использовать непустое название соответствующего типа.
+
+Список Brokerage Account является результатом наблюдения текущего брокерского подключения и MUST NOT создавать ожидание, что WealthLedger хранит долговременное право владения счётом независимо от T-Bank connection.

 #### Scenario: Поддерживаемые счета возвращаются в upstream-порядке
 - **WHEN** User с действующим T-Bank connection запрашивает список, а T-Bank возвращает открытые брокерский счёт, ИИС и неподдержанный дебетовый счёт
@@ -7,18 +7,20 @@
 ## Requirements

 ### Requirement: Получение Portfolio выбранного Brokerage Account
-Система SHALL предоставлять авторизованному User `GET /api/v1/brokerage-accounts/:accountId/portfolio`. Она MUST возвращать нормализованный полный Portfolio только для открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection User. Ответ MUST содержать `lastSuccessfulAt` в RFC 3339 UTC без миллисекунд, boolean `isStale`, `totalsByCurrency`, `positions` и `cashBalances`.
+Система SHALL предоставлять авторизованному User `GET /api/v1/brokerage-accounts/:accountId/portfolio`. Она MUST возвращать нормализованный полный Portfolio Snapshot только для открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection User. Ответ MUST содержать `lastSuccessfulAt` в RFC 3339 UTC без миллисекунд, boolean `isStale`, `totalsByCurrency`, `positions` и `cashBalances`.
+
+Portfolio Snapshot является результатом наблюдения Portfolio на конкретный момент. Он MUST NOT означать, что WealthLedger хранит Portfolio как долговременный агрегат или подтверждает доступность Brokerage Account вне текущего T-Bank connection.

 #### Scenario: Получение текущего Portfolio
 - **WHEN** User запрашивает Portfolio доступного Brokerage Account, а обязательные upstream-данные успешно получены
- **THEN** система отвечает `200` полным нормализованным Portfolio с `isStale: false` и временем успешного получения финансового снимка
+- **THEN** система отвечает `200` полным нормализованным Portfolio Snapshot с `isStale: false` и временем успешного получения финансового снимка

 #### Scenario: Недоступный Brokerage Account
 - **WHEN** `accountId` не принадлежит User, закрыт, неподдерживаем или больше не доступен через текущий T-Bank connection
- **THEN** система отвечает `404` без Portfolio
+- **THEN** система отвечает `404` без Portfolio Snapshot

 ### Requirement: Нормализованный состав Portfolio
-Система MUST возвращать только обычные Portfolio Position с ненулевым количеством и доступные Cash Balance с ненулевой суммой. Cash Balance MUST быть отдельным от Portfolio Position элементом и агрегироваться до одного значения на валюту. Порядок Portfolio Position и Cash Balance MUST соответствовать upstream-порядку; система MUST NOT сортировать или объединять Portfolio Position с одинаковым FIGI. Виртуальные позиции и заблокированные денежные остатки MUST NOT входить в Portfolio.
+Система MUST возвращать только обычные Portfolio Position с ненулевым количеством и доступные Cash Balance с ненулевой суммой. Cash Balance MUST быть отдельным от Portfolio Position элементом и агрегироваться до одного значения на валюту. Portfolio Position с типом `CURRENCY` MUST означать позицию по торгуемому валютному Instrument и MUST NOT смешиваться с Cash Balance. Порядок Portfolio Position и Cash Balance MUST соответствовать upstream-порядку; система MUST NOT сортировать или объединять Portfolio Position с одинаковым FIGI. Виртуальные позиции и заблокированные денежные остатки MUST NOT входить в Portfolio.

 Каждая Portfolio Position MUST содержать нормализованный тип `STOCK`, `BOND`, `FUND`, `CURRENCY`, `FUTURE`, `OPTION`, `STRUCTURED_NOTE`, `DIGITAL_FINANCIAL_ASSET` либо `OTHER`, строковое `quantity`, nullable `currentValue`, nullable `averagePurchasePrice`, nullable `absoluteReturn`, nullable `isin` и nullable `logoName` — имя файла логотипа бренда инструмента. Имя файла логотипа MUST заполняться из metadata инструмента, когда upstream предоставляет бренд с непустым именем файла логотипа; во всех остальных случаях оно MUST быть `null`. Логотип является presentation metadata: он не влияет на количество, стоимость, агрегаты, успешность или свежесть Portfolio Snapshot. Система MUST искать metadata по instrument UID при его наличии, затем по FIGI. Отображаемый идентификатор MUST предпочитать name, затем ticker, а при недоступности metadata использовать FIGI, не скрывая финансовые значения.

@@ -26,6 +28,10 @@
 - **WHEN** upstream возвращает обычную ненулевую позицию с нераспознанным типом инструмента
 - **THEN** система возвращает её в исходном порядке с типом `OTHER`

+#### Scenario: Позиция валютного инструмента не является денежным остатком
+- **WHEN** upstream возвращает ненулевую Portfolio Position валютного инструмента и ненулевой Cash Balance той же валюты
+- **THEN** система возвращает Portfolio Position с типом `CURRENCY` отдельно от Cash Balance и не объединяет их между собой
+
 #### Scenario: Позиция без metadata инструмента
 - **WHEN** lookup metadata по FIGI не дал ticker или name либо временно недоступен
 - **THEN** система возвращает позицию с FIGI как fallback-идентификатором и всеми доступными финансовыми значениями
@@ -63,7 +69,7 @@
 - **THEN** система отвечает `200` с пустыми `positions`, `cashBalances` и `totalsByCurrency`

 ### Requirement: Точные значения и валютные агрегаты
-Все количества и финансовые значения в Portfolio MUST передаваться десятичными строками без экспоненциальной записи и без незначащих завершающих нулей. Денежное значение MUST содержать ISO-код валюты. Система MUST корректно нормализовать отрицательные целую и дробную части upstream-значений. Отсутствующее значение MUST передаваться как `null`, а не как ноль.
+Все количества и финансовые значения в Portfolio Snapshot MUST передаваться десятичными строками без экспоненциальной записи и без незначащих завершающих нулей. Денежное значение MUST быть единым Money-значением с ISO-кодом валюты и десятичной строкой значения. Система MUST корректно нормализовать отрицательные целую и дробную части upstream-значений. Отсутствующее значение MUST передаваться как `null`, а не как ноль.

 `currentValue` Portfolio Position MUST быть точным произведением количества на текущую цену при наличии валидных множителей и валюты цены. `absoluteReturn` MUST быть точной величиной `(currentPrice - averagePurchasePrice) * quantity` только когда обе цены имеют одинаковую известную валюту. Позиция без вычислимой текущей стоимости MUST оставаться в ответе, но MUST NOT входить в агрегаты. `totalsByCurrency` MUST содержать точную сумму currentValue позиций и Cash Balance в каждой валюте без валютной конвертации.

@@ -78,15 +78,24 @@ MUST предоставлять index поставленных фич и MUST NO
 Brokerage Accounts, Portfolio, Account Ledger или Future Cash Events как
 отложенные.

+Канонический domain glossary MUST закреплять различие между Brokerage Account,
+доступным через текущее T-Bank connection, Portfolio Snapshot, Portfolio
+Position, Currency Instrument Position, Cash Balance, Money, Instrument, Ledger
+Entry и Future Cash Event. Runtime/cache-термины MUST быть отделены от
+доменных терминов так, чтобы документация не представляла технический механизм
+как бизнес-сущность.
+
 #### Scenario: Новый участник находит поставленную систему
 - **WHEN** новый участник открывает устойчивую документацию
 - **THEN** он может перейти из index к system overview, glossary, документам
  поставленных фич и соответствующему development workflow

 #### Scenario: Участник различает близкие доменные понятия
- **WHEN** участнику нужно описать cached portfolio data или account operation
- **THEN** канонический glossary различает Client Cached Snapshot и Portfolio
-  Snapshot, а также Future Cash Event и Ledger Entry
+- **WHEN** участнику нужно описать cached portfolio data, валютную позицию,
+  денежный остаток или account operation
+- **THEN** канонический glossary различает runtime/cache-механизмы, Portfolio
+  Snapshot, Currency Instrument Position, Cash Balance, Future Cash Event и
+  Ledger Entry

 ### Requirement: README репозиториев являются компактными onboarding entrypoints
 Репозитории frontend и backend SHALL предоставлять русскоязычные README