diff --git a/AGENTS.md b/AGENTS.md index 5c0f56b..4b2efc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,13 @@ ## Назначение и authority -Этот репозиторий хранит durable as-built документацию WealthLedger. Canonical OpenSpec store — `wealth-ledger-specs` в `../specs/openspec`; OpenSpec commands, читающие или изменяющие change, всегда выполняются с `--store wealth-ledger-specs`. Proposal, Delta Specs, Design, Tasks и другие versioned planning artifacts вне canonical store запрещены, включая `superpowers/plans`; `../references/**` read-only. +Этот репозиторий хранит durable as-built документацию WealthLedger. Shared SDD +policy, common reading pointers, audit routing и `../references/**` policy +задаёт root `AGENTS.md`. + +Canonical SDD authority находится в `wealth-ledger-specs`, физически в +`../specs/openspec` от этого репозитория. Любая OpenSpec command, читающая или +изменяющая change, должна использовать `--store wealth-ledger-specs`. Docs обновляется до фактического проверенного состояния affected change и не представляет planned behavior как поставленное. Artifact ownership и Completion Evidence определены в [`development/engineering-governance.md`](development/engineering-governance.md); audit-derived работа начинается с [`development/audit-remediation.md`](development/audit-remediation.md). @@ -16,11 +22,12 @@ npm run verify ``` Gate non-mutating и запускает runtime preflight, committed Markdown rules и `git diff --check`. Auto-fix и network/browser link checking в gate не входят; local links affected documentation проверяются scoped review. +Актуальные scripts проверять в `package.json`/`npm run`. ## Boundaries - `architecture/` — текущее устройство, `features/` — поставленное поведение, `adr/` — устойчивые решения, `development/` — процесс и Completion Evidence, `audits/` — immutable snapshots. -- Перед изменением current state сверяться с [`architecture/system-overview.md`](architecture/system-overview.md) и [`architecture/domain-glossary.md`](architecture/domain-glossary.md); indexes должны вести к новым документам. +- Indexes должны вести к новым документам. - Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks. - Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts. diff --git a/architecture/domain-glossary.md b/architecture/domain-glossary.md index d8e0a2c..bbf083a 100644 --- a/architecture/domain-glossary.md +++ b/architecture/domain-glossary.md @@ -1,5 +1,30 @@ # Глоссарий домена +## User + +Локальный владелец данных WealthLedger, идентифицируемый `id` и +нормализованным email. User владеет Session, T-Bank connection и видит только +свои Brokerage Accounts. + +_Не использовать_: клиент T-Bank, инвестор T-Bank. + +## Session + +Локальная authenticated-сессия User: короткоживущий access token в браузере и +server-side refresh token rotation через cookie. Session не является +T-Bank connection и не подтверждает доступ к Brokerage Account без текущего +Bearer token. + +_Не использовать_: T-Bank сессия, browser session. + +## Money + +Денежная сумма в одной ISO-валюте, передаваемая как `{ currency, value }`, где +`value` — decimal string без экспоненциальной записи. Backend выполняет точные +операции, frontend форматирует Money для отображения. + +_Не использовать_: number amount, MoneyDto как доменный термин. + ## T-Bank connection Единственное принадлежащее User подключение к T-Bank Invest, содержащее @@ -17,7 +42,8 @@ _Не использовать_: счёт T-Bank, банковский счёт. ## Investment Account Type Нормализованная категория Brokerage Account, независимая от upstream enum -T-Bank. +T-Bank: `BROKERAGE`, `INDIVIDUAL_INVESTMENT`, `INVEST_BOX` или +`MONEY_MARKET_FUND`. _Не использовать_: тип аккаунта T-Bank, protobuf type. @@ -35,6 +61,14 @@ _Не использовать_: общий портфель, баланс сч _Не использовать_: валютная позиция, виртуальная позиция. +## Portfolio Position Type + +Нормализованный display type Portfolio Position, полученный из upstream +instrument type: `STOCK`, `BOND`, `FUND`, `CURRENCY`, `FUTURE`, `OPTION`, +`STRUCTURED_NOTE`, `DIGITAL_FINANCIAL_ASSET` или `OTHER`. + +_Не использовать_: upstream instrument type как доменный enum. + ## Instrument Ценная бумага или иной торгуемый актив T-Bank, на который ссылается Portfolio @@ -56,7 +90,7 @@ _Не использовать_: аватар актива, иконка бум ## Cash Balance Ненулевой доступный денежный остаток Portfolio в одной валюте; не является -Portfolio Position. +Portfolio Position и передаётся отдельно от `positions` в `cashBalances`. _Не использовать_: валютная позиция, заблокированные средства. @@ -87,10 +121,19 @@ _Не использовать_: история Portfolio, баланс счёт Нормализованное представление одной операции T-Bank в Account Ledger; хранит исходные суммы и доступные детали операции, не создавая синтетических записей -для комиссии сделки. +для комиссии сделки. API/code сохраняют legacy names `BrokerageOperationDto`, +`BrokerageOperationsPageDto` и `/operations`; в доменной документации primary +term — Ledger Entry. _Не использовать_: проводка, рассчитанная операция. +## Operation Category + +Нормализованная категория Ledger Entry для фильтрации и отображения: +`trade`, `income`, `tax`, `fee`, `transfer` или `other`. + +_Не использовать_: upstream operation type как category. + ## Ledger Page Cache Кэш страницы Account Ledger, отделённый от кэша отдельных операций. @@ -124,6 +167,15 @@ _Не использовать_: активный refresh token, признак Прогнозируемое на ближайший период денежное или связанное корпоративное событие одного Brokerage Account, рассчитанное по текущей Portfolio Position; -не является исполненной Ledger Entry. +не является исполненной Ledger Entry. API/code сохраняют legacy names +`UpcomingEventDto`, `UpcomingEventsDto`, `/events` и frontend `BrokerageEvent`; +в доменной документации primary term — Future Cash Event. _Не использовать_: будущая операция, гарантированная выплата. + +## Future Cash Event Type + +Нормализованный тип Future Cash Event: `coupon`, `dividend`, `maturity` или +`offer`. + +_Не использовать_: upstream dividend type, MOEX row name. diff --git a/features/brokerage-account-ledger.md b/features/brokerage-account-ledger.md index 13092f3..58aef80 100644 --- a/features/brokerage-account-ledger.md +++ b/features/brokerage-account-ledger.md @@ -31,6 +31,6 @@ sequenceDiagram - Запрашиваются только исполненные операции T-Bank. - Полный журнал фильтруется по периоду и категориям, а изменение фильтра сбрасывает cursor-пагинацию. - Полный журнал не показывает цену, количество, НКД и комиссию записи. -- Backend хранит в памяти процесса до 100 страниц Account Ledger: свежая страница живёт до 30 секунд, а при переполнении вытесняется давно не использовавшаяся страница (LRU). Ключ включает пользователя, счёт, нормализованные период и categories, cursor и limit; отсутствующий `to` приводится к текущему 30-секундному bucket. Проверка подключения и доступа к счёту выполняется до выдачи кэшированной страницы. Операции не сохраняются и не синхронизируются локально. +- Backend хранит в памяти процесса до 100 страниц Account Ledger: свежая страница живёт до 30 секунд, а при переполнении вытесняется давно не использовавшаяся страница (LRU). Ключ включает пользователя, счёт, нормализованные период и categories, cursor и limit; отсутствующий `to` приводится к текущему 30-секундному bucket. Проверка подключения и доступа к счёту выполняется до выдачи кэшированной страницы. Ключ не включает версию T-Bank token, поэтому после успешной замены T-Bank connection для того же User, Brokerage Account и query уже сохранённая страница может оставаться видимой до истечения 30-секундного TTL. Операции не сохраняются и не синхронизируются локально. - Журнал не рассчитывает остаток после операции, суммарные доходы или налоги, историческую стоимость Portfolio, конвертацию валют и рыночные изменения цены. - `409 TBANK_NOT_CONNECTED`, `400 INVALID_TBANK_TOKEN`, `404` недоступного счёта и `503 TBANK_UNAVAILABLE` используют существующую семантику ошибок T-Bank.