chore(release): 1.0.0

test: prove reads finish before source synchronization
Block synthetic upstream with an explicit barrier instead of comparing total HTTP batch time with a two-second timer. Keep the 500 ms server p95 gate and RPC assertions unchanged.
2026-09-26 22:33:48 +03:00 · 2026-09-26 21:45:50 +03:00 · 2026-09-26 21:29:15 +03:00 · 2026-09-19 16:25:12 +03:00 · 2026-09-19 16:24:08 +03:00 · 2026-09-19 15:07:57 +03:00
264 changed files with 28107 additions and 10359 deletions
@@ -1,24 +0,0 @@
 # Backend router
 Объединяй triggers из смысла задачи, путей и обнаруженных boundaries.
 Читай выбранные guides до решения; якорь допускает чтение только нужного раздела.
 Просто backend-файл не требует всех conventions.
 | Решение / сигнал | Читать |
 | --- | --- |
 | Новый module/provider/service; бизнес-логика; перенос responsibility | [Architecture](conventions/backend-architecture.md) |
 | Controller, DTO, route/status, validation/exception, публичная HTTP-семантика | [HTTP API](conventions/backend-http-api.md) |
 | Prisma/schema/query/persistence, transaction, migration, atomic write | [Data](conventions/backend-data.md) |
 | Тесты или behavior с testing risk | [Testing](conventions/backend-testing.md) |
 | JWT, cookie, login/refresh/logout, guard/access, token encryption, sensitive logs | [Security](conventions/security-auth.md) |
 | T-Bank/gRPC/proto, upstream retry/rate limit/cache, MoexClient | [Integrations](conventions/backend-integrations.md) |
 | Logging/request context без изменения secrets/auth | [Logging](conventions/backend-architecture.md#logging) |
 | Новый abstraction/dependency, refactor, неясный scope | [Общий выбор реализации](../../docs/development/engineering-governance.md#выбор-реализации) |
 | Изменение request/response/route/status/error shape или Swagger metadata | HTTP API + [общий contract workflow](../../docs/development/runtime-openapi-verification.md) |
 Новый endpoint обычно требует HTTP API + Testing; Architecture/Data/Security
 добавляются по новым ответственности, persistence или access rules.
 Изменение одного Prisma query без HTTP/auth границы не требует HTTP API/Security.
 Auth refresh активирует Security + Data + Testing; HTTP API добавляется, если
 меняется controller/HTTP contract. Exact docs/spec sources выбирай через SOURCES.
 Повтори routing при расширении diff, включая новые и unstaged файлы.
@@ -1,19 +0,0 @@
 # Источники backend
 | Что нужно установить | Владелец |
 | --- | --- |
 | Implementation decision и безопасный pattern | [CONVENTIONS](CONVENTIONS.md) |
 | HTTP errors, DTO semantics, public wire shape | [docs: HTTP API](../../docs/architecture/http-api.md); runtime OpenAPI из Nest — единственный editable source |
 | Auth/session, account access, token encryption | [Аутентификация](../../docs/domains/authentication/overview.md), [доступ к данным](../../docs/architecture/containers.md#хранимые-данные-и-границы-доступа), [подключение брокера](../../docs/integrations/tbank.md) |
 | Prisma schema/data ownership и migration context | [docs: Data](../../docs/architecture/containers.md#хранимые-данные-и-границы-доступа) |
 | T-Bank/gRPC/cache, logging | [T-Bank](../../docs/integrations/tbank.md), [свежесть данных](../../docs/architecture/cross-cutting/data-freshness.md), [наблюдаемость](../../docs/architecture/http-api.md#наблюдаемость) |
 | Money, account/position/income/cache meanings | [docs: Domain](../../docs/glossary.md) |
 | Поведение конкретной feature | [docs: Features](../../docs/README.md#предметные-области) |
 | Существующие behavioral requirements при необходимости | [specs index](../../specs/AI_INDEX.md) |
 | Versions/scripts и scope автоматических checks | package.json/lockfile, ESLint/TypeScript/Jest/Prisma configs |
 SOURCES — карта, не требование прочитать все ссылки. Code показывает реализацию,
 ADR — rationale, docs — текущие факты; старый пример не отменяет контракт.
 Исследование предлагает варианты, а actual source разрешает выбор. При missing
 или conflicting security/data facts сначала установи источник. Для обычной
 работы OpenSpec/SDD не требуется.
@@ -0,0 +1,262 @@
 # Backend architecture
 ## Устройство и data flow
 NestJS + TypeScript modular monolith. Composition root `AppModule` подключает
 бизнес-модули, validated configuration, Prisma и Pino. Общая `configureApp`
 задаёт `/api/v1`, CORS/cookies, validation, request logging и error filter.
 Точные versions/scripts — в [package.json](../package.json); source code
 определяет фактическую реализацию.
 ```text
 HTTP controller → application service/use case → pure domain rules
                            ↓
                repository/data access → Prisma → SQLite
                            ↓
                integration client → T-Bank gRPC / MOEX / NCR HTTP
 ```
 `modules/auth`, `modules/banking/bank-cards` и области `modules/investments`
 владеют пользовательскими возможностями. Сложные модули разделены на
 presentation/application/domain/infrastructure; компактные остаются плоскими.
 `*.module.ts` — Nest DI, `*.api.ts` — используемые cross-module exports.
 Application использует конкретные providers; обязательных ports на каждый
 класс нет.
 Stocks/bonds — slices одного instruments module: catalog владеет identity/cache,
 market — котировками, income — выплатами/личными позициями. Общая orchestration
 в `instruments/application` использует DTO/provider records и не становится pure
 domain из-за extraction в функцию. Boundary mappers преобразуют внешние records;
 чистые расчёты portfolio/banking остаются у domain owner.
 PrismaService владеет DB lifecycle. Самостоятельные use cases получают данные
 через concrete repositories; существующие связные CRUD/transaction services
 сохраняют прямые queries по [data convention](conventions/data.md).
 Money — currency + decimal string; расчёты используют точные общие helpers.
 Auth управляет identity/session; TbankAccessService проверяет доступ к счёту и
 connection generation. Integration clients владеют protocol/deadline/retry;
 provider records преобразуются перед чистыми domain calculations.
 Пользовательский `tbank-connection` не владеет низкоуровневым gRPC client.
 Nest DTO/metadata → `npm run openapi:generate` → игнорируемый Git `openapi.json`
 для публичных consumers.
 Problem Details фильтруются общей HTTP boundary; StructuredLogger добавляет
 request context и ограничивает поля событий. Jest unit tests, изолированные
 SQLite/HTTP suites и OpenAPI parity доказывают разные части поведения.
 Локальные источники выбираются через [Источники](../AGENTS.md#источники).
 ## Module-first organization
 Сначала выбери business owner в `modules/`, затем ответственность внутри него.
 ### Progressive structure
 Три уровня организации: business module → responsibility layer → technical grouping
 при реальной необходимости. Компактный module с понятными controller/DTO/service
 может оставаться плоским. Ориентир 5–7 файлов не является порогом: учитывай число
 ответственностей, наличие domain/repository/use cases и удобство просмотра каталога.
 Когда в module смешаны несколько services, transport, расчёты и persistence,
 группируй файлы по ответственности:
 ```text
 feature/
 ├── feature.module.ts
 ├── feature.api.ts          # только при существующих внешних потребителях
 ├── presentation/           # HTTP, DTO, guards
 ├── application/            # сценарии, orchestration, application input
 ├── domain/                 # чистые бизнес-правила и расчёты
 └── infrastructure/         # persistence, framework и boundary mapping
 ```
 Создавай только нужные слои. В корне сложного module оставляй composition и
 публичную boundary; production code и colocated tests размещай в слое владельца.
 Внутри business slice действует то же правило, без отдельного Nest module ради папок.
 `controllers/`, `dto/`, `services/`, `use-cases/`, `persistence/`, `mappers/`
 допустимы только внутри слоя, когда множество однотипных файлов мешает навигации.
 Для одного controller или пары DTO дополнительная поддиректория не нужна.
 Пустые папки, новые barrels, CQRS и interfaces не требуются для этой организации.
 ## Поиск и создание файла
 При работе над feature проходи владельцев в порядке:
 1. Найди business module.
 2. Прочитай его `*.module.ts` (для slice — composition родительского module).
 3. Проверь `presentation/`: controller и transport contract.
 4. Проследи вызовы в `application/`: сценарии и services.
 5. Проверь используемые правила в `domain/`.
 6. Проверь `infrastructure/`: repository и технические реализации.
 7. По обнаруженным зависимостям переходи в `integrations/` и `common/`.
 В плоском module классифицируй файлы по suffix и следуй их ответственности.
 Отсутствующий слой пропускай. Если business owner известен, начинай локально,
 а не с repository-wide search.
 **Rule of locality:** code that belongs to one business capability stays inside
 that capability unless it is cross-cutting. Например, расчёты карт принадлежат
 bank-cards/domain, даже если реализованы обычными функциями.
 Перед созданием файла определи:
 1. Какой business module владеет изменением? Сначала owner, затем common при
   подтверждённой общей потребности.
 2. Какова ответственность: HTTP/DTO/guard → presentation; сценарий/orchestration →
   application; чистое business rule/calculation → domain; persistence или
   module-specific technical implementation → infrastructure; внешний протокол → integrations.
 3. Какой approved suffix из таблицы соответствует этой ответственности?
 4. Какой слой владеет файлом? В компактном плоском module сохрани размещение рядом
   с owner; в слоистом используй соответствующий слой.
 5. Достаточно ли colocate файл рядом с существующими? Level 3 grouping создавай
   только при заметном улучшении навигации по множеству однотипных файлов.
 Если owner или роль не определены, сначала установи ответственность. Generic
 `utils.ts`, `helpers.ts`, `manager.ts`, `handler.ts` и arbitrary directory её не заменяют.
 ## Naming & File Suffix Convention
 Имена файлов — `kebab-case`. File suffix определяет responsibility, directory
 определяет architectural layer. Размещение в таблице предпочтительно для
 слоистого module; компактный плоский module сохраняет файлы в корне.
 Cross-module consumers во всех строках ограничены публичной границей ниже.
 | Suffix | Когда использовать | Где | Кто зависит | Когда не использовать |
 | --- | --- | --- | --- | --- |
 | `*.controller.ts` | HTTP endpoint / transport | presentation | Nest wiring | DB, расчёты, SDK, сложная оркестрация |
 | `*.dto.ts` | Request/response, validation, OpenAPI | presentation | Controller; application boundary при совпадении shape | Универсальная domain model |
 | `*.use-case.ts` | Один самостоятельный application scenario | application | Controller, другой orchestrator | Prisma queries, Request/Response, SDK implementation |
 | `*.service.ts` | Конкретная cohesive reusable capability | рядом с owner; application/domain/integration по роли | Сценарии и services; domain — только от чистого domain service | Свалка несвязанных сценариев |
 | `*.repository.ts` | Persistence queries и согласованные DB reads/writes | infrastructure | Application service/use case | Domain calculations, HTTP request, external transport |
 | `*.client.ts` | Низкоуровневый внешний HTTP/gRPC/SDK | integrations или infrastructure | Application orchestration, boundary mapper | Пользовательский lifecycle и domain rules |
 | `*.mapper.ts` | Meaningful conversion между моделями | обычно infrastructure у преобразуемой boundary | Код соответствующей boundary | Формальное копирование нескольких одинаковых полей |
 | `*.policy.ts` | Cohesive decision rule | domain/application/integration по входным данным | Владелец правила; domain — от чистой policy | Persistence, transport, generic strategy |
 | `*.guard.ts` | Nest guard | presentation | Nest/controller | Основная account authorization и финансовые правила |
 | `*.strategy.ts` | Framework strategy, например JWT | infrastructure | Framework wiring | Обычный service без strategy contract |
 | `*.module.ts` | Nest imports/providers/controllers/exports | module root | Composition root, importing module | Бизнес-логика |
 | `*.types.ts` | Малая группа связанных TS types | рядом с owner | Потребители модели на разрешённых слоях | Глобальные types всего module, runtime validation |
 | `*.api.ts` | Явный список публичных exports | root конкретного module/integration | Другие modules | DTO/client/service implementation или generic API logic |
 | `*-input.ts` | Application input: нормализация и проверка формы, отличающейся от wire DTO | application | Application code | Копия DTO под новым именем; вариант `*.input.ts` |
 | `*.calculations.ts`, `*.rules.ts` или предметное имя | Чистые бизнес-расчёты, value semantics | domain | Application и domain | Nest/Prisma/HTTP/SDK зависимости |
 | `*.spec.ts` | Существующая unit/component проверка поведения | рядом с owner/slice | Test runner | Архитектурные проверки папок и trivial wiring |
 `bank-card-input.ts` использует выбранный `*-input.ts`: переводит Money в
 копейки, нормализует значения и проверяет application input. DTO не дублируется
 отдельным Input type. `rub-money.ts` — domain-правила RUB; `bond-money.mapper.ts`
 — преобразование ответа клиента. Эти роли не определяются словом money в имени.
 Технические framework suffixes (`*.filter.ts`, `*.middleware.ts`,
 `*.decorator.ts`, `*.config.ts`, `*.validation.ts`) сохраняют соответствующие
 существующие роли в common/config. `tbank.crypto.ts` — локальная реализация
 шифрования токена; имя не является разрешением создавать generic crypto layer.
 HTTP/e2e naming и расположение — в [Testing](conventions/testing.md).
 Без зафиксированной необходимости не вводи `*.helper.ts`, `*.utils.ts`,
 `*.manager.ts`, `*.processor.ts`, `*.handler.ts`, `*.provider.ts`, `*.factory.ts`.
 Новая naming convention сначала получает конкретную роль и обоснование здесь.
 Для data access выбран только `*.repository.ts`, не persistence/store/dao.
 ## Публичные границы
 `*.module.ts` задаёт DI boundary; `*.api.ts` перечисляет используемые другими
 модулями providers, функции и типы. Внешний production import идёт через этот
 API или файл Nest module. Чистый `integrations/tbank/decimal.ts` — отдельный
 публичный вход для protobuf conversion: импорт арифметики не загружает DI/Prisma.
 Внутри модуля используй прямые локальные импорты.
 Tests могут импортировать внутренний owner для проверки поведения и mocks.
 Новый export требует текущего потребителя; controller и persistence остаются
 приватными. Не добавляй `index.ts` на каждом уровне.
 Circular dependencies устраняй изменением ownership/composition. `forwardRef()`
 не является стандартным исправлением boundaries; исключение требует конкретной
 неизбежной связи и проверки DI initialization.
 Каждый provider регистрируется у одного владельца. Потребители импортируют
 его module, а не повторяют provider: это сохраняет единственный кэш и лимитер.
 `AuthModule` экспортирует guard; наличие JWT не заменяет account access check.
 - `income` читает операции через `operations.api.ts`.
 - `instruments` получает личные позиции через `portfolio.api.ts`.
 - `tbank-connection` использует T-Bank integration и публичный сброс портфеля.
 - `portfolio` и другие инвестиционные модули используют `TbankModule`, который
  не зависит от business modules. Так управление подключением не образует цикл.
 - `investment-calendar.ts` и `account-reference.dto.ts` разделяются только
  инвестиционными областями; это не глобальная библиотека бизнес-правил.
 ## Ответственность и направление зависимостей
 | Владелец | Ответственность |
 | --- | --- |
 | Controller / presentation | Route, verified identity, transport DTO, validation, status/cookie; вызов сценария |
 | Use case / application service | Оркестрация, business validation, доступ и согласованность результата |
 | Domain | Чистые правила и расчёты; без NestJS, Prisma, HTTP/Swagger и внешних SDK |
 | Persistence / infrastructure | Запросы, транзакции, технические реализации границ |
 | `src/integrations/{tbank,moex,ncr}` | Внешние протоколы, декодирование, retry/deadline/cache; без зависимостей от HTTP DTO business modules |
 | `src/prisma` | Общий DB provider и lifecycle; не generic repository |
 Основной вызов: presentation → application → domain; application использует
 конкретные infrastructure providers, зарегистрированные module. Infrastructure
 может использовать application types/input и domain rules; новые interfaces
 ради инверсии зависимостей не обязательны. Domain не импортирует presentation или
 infrastructure. Существующие связные CRUD/transaction services могут сохранять прямые queries
 по [Data](conventions/data.md); use case получает данные через repository и сам
 Prisma queries не выполняет. Entity/interface на каждую таблицу не требуется.
 DTO остаются транспортными runtime classes; существующее использование DTO
 на application boundary допустимо по [HTTP API](conventions/http-api.md).
 Сохраняй существующий error contract: HTTP exceptions остаются на application/
 transport boundary. Чистому расчёту не нужен новый framework ошибок.
 Mapping и stable codes — по [Errors](conventions/error-handling.md).
 Точные ограничения — [HTTP](conventions/http-api.md), [Data](conventions/data.md),
 [Security](conventions/security-auth.md), [Integrations](conventions/integrations.md).
 ## Сценарии и размер сервисов
 Разделяй независимые операции, а не строки. Пример: `BankCardsService` владеет
 картами, `BankOperationsService` — журналом/переводами, `GetBankSummaryUseCase` —
 сводкой через repository и чистый расчёт. Не разрывай денежную transaction,
 общий cache/limiter или pending promises при extraction.
 Расширение abstractions — по [change scope](conventions/engineering.md#change-scope).
 ## Common
 `common` содержит общий error filter, logging, API decorators, тип `Money`,
 его HTTP `MoneyDto` и точную decimal-арифметику, используемые несколькими областями. Код одного
 модуля принадлежит этому модулю: например, RUB/kopecks rules — банковским картам,
 protobuf units/nano conversion — T-Bank integration. Domain использует
 `money.types.ts`, а не Swagger DTO; это общая форма денег для карт и портфеля.
 Давай функциям предметные имена; не создавай глобальные `utils.ts`/`helpers.ts`.
 ## Domain literals and magic values
 Общий выбор symbolic values и числовых policies —
 [Domain values](conventions/engineering.md#domain-values).
 Сохраняй strict TS и explicit boundary types. Для недоверенного input выбирай
 `unknown` + runtime narrowing; отключённый lint `no-explicit-any` не делает
 `any` нормой domain/application model. `declare` допустим для заполняемых извне
 DTO fields, не для сокрытия неинициализированного owned state.
 OpenAPI enum metadata и runtime validation должны читать тот же vocabulary,
 что application/domain. Например, `BankOperationKind` принадлежит bank-cards/domain,
 а DTO получает допустимые значения через `Object.values(BankOperationKind)`.
 Публичные enum values входят в OpenAPI artifact. Внешние/generated enums
 сохраняй; generated Prisma/protocol code вручную не меняй.
 `@typescript-eslint/no-magic-numbers` включён как error; базовое ESLint rule
 отключено в пользу TS-версии. Исключения для очевидных чисел и их bigint форм,
 индексов, default values, enum/type declarations и readonly properties заданы
 в ESLint config. Test fixtures/expected values остаются inline, остальные lint
 правила продолжают действовать. Numeric policy получает предметное имя и единицы;
 semantic magic strings проверяются conventions/review без нового инструмента.
 ## Logging
 События, levels, correlation и safe fields — по
 [Observability](conventions/observability.md).
 ## Проверка
 `npm run typecheck:app`, `npm run lint`, targeted Jest по изменённому use case.
 Смысл boundaries проверяется review: backend не имеет отдельного автоматического
 FSD/DI architecture checker. Existing tests и build не доказывают правильный owner.
@@ -1,53 +0,0 @@
 # Backend architecture
 ## Выбор владельца
 Найди существующий use case, его collaborators и tests до создания module/service.
 Сохрани ответственность в текущем module, если новая возможность относится к нему.
 Module — граница связного набора providers, а не папка для каждого endpoint.
 | Решение | Owner |
 | --- | --- |
 | Route, request/response mapping, status/cookie | Controller, [HTTP rules](backend-http-api.md) |
 | Business use case, orchestration, domain validation | Feature service |
 | Input shape/format | DTO + configured ValidationPipe |
 | Атомарность/DB query | Сервис use case через PrismaService, [Data](backend-data.md) |
 | Внешний protocol, deadline/retry/limiting | Existing client, [Integrations](backend-integrations.md) |
 | Чистое вычисление/mapper без lifecycle и DI | Обычная функция рядом с domain owner |
 | Bootstrap/config/global cross-cutting concern | AppModule, config, существующий common owner |
 **Безопасный путь:** расширь текущий owner; выделяй collaborator, когда он скрывает
 самостоятельный инвариант или координацию. Не вводи CQRS, generic repository,
 interface с одной реализацией или base controller только ради шаблона Nest.
 Не превращай common в хранилище бизнес-логики и не переноси frontend модели сюда.
 ## Существующие seams
 `TbankConnectionModule` уже объединяет счета, портфель, операции, доходы и события.
 Новый связанный use case обычно добавляется в него; создание отдельного module
 требует собственной ответственности, не только нового файла.
 - [BrokerageOperationsController](../../src/tbank/brokerage-operations.controller.ts) передаёт user/account/query в service, без финансовых вычислений в controller.
 - [TbankAccessService](../../src/tbank/tbank-access.service.ts) владеет connection/account access и generation; новые account use cases используют его вместо копирования guard/decrypt logic.
 - [decimal.ts](../../src/tbank/decimal.ts) — пример pure domain helper; Injectable и adapter для арифметики не нужны.
 Наличие guard подтверждает session, но не владение account. При пересечении
 access boundary добавь [Security](security-auth.md). Ошибка upstream не должна
 обходить общий HTTP filter или превращать чужой account в доступный.
 ## Logging
 Единственный logger — nestjs-pino; application events используют существующий
 [StructuredLogger](../../src/common/logging/structured-logger.service.ts) и
 request context. Выбирай стабильное имя события и разрешённые scalar fields.
 Wrapper отбрасывает неизвестные поля, но это не разрешение помещать secret
 в `message`/`stack`: review sensitive logging обязателен.
 Не добавляй второй logger или сырой request/body/error payload.
 Источник rationale — [ADR 008](../../../docs/adr/008-pino-backend-logging.md);
 при secrets/user data читай также Security.
 ## Проверка
 `npm run typecheck:app`, `npm run lint`, targeted Jest по изменённому use case.
 Смысл boundaries проверяется review: backend не имеет отдельного автоматического
 FSD/DI architecture checker. Existing tests и build не доказывают правильный owner.
@@ -1,52 +0,0 @@
 # Backend HTTP API
 ## Выбор boundary
 Сначала определи, меняется wire contract или только реализация существующего
 use case. Для route/request/response/status/error shape читай
 [HTTP semantics](../../../docs/architecture/http-api.md) и
 [общий contract workflow](../../../docs/development/runtime-openapi-verification.md).
 | Проверка | Где выполнять |
 | --- | --- |
 | Тип/формат/диапазон входа | Runtime DTO class с class-validator/class-transformer |
 | Согласованность полей, бизнес-ограничение | Feature service/domain helper |
 | Session и identity | Existing guard/strategy |
 | Доступ user к конкретному account | Existing access service |
 | HTTP envelope/безопасная ошибка | Общий HttpExceptionFilter |
 Controller объявляет contract и делегирует; не обращается напрямую к Prisma/gRPC
 ради обхода service. Request identity берётся из verified `request.user`, не из
 body/userId, предоставленного клиентом. Access rules активируют Security.
 ## DTO и errors
 DTO — runtime class: TS interface не предоставляет validation metadata.
 ValidationPipe уже настроен в `configureApp` (`transform`, `whitelist`).
 Не обещай rejection неизвестных fields: `forbidNonWhitelisted` не включён.
 Для query numbers/arrays выбирай явное преобразование и валидаторы, как в
 [operations DTO](../../src/tbank/brokerage-operation.dto.ts). Swagger metadata
 описывает те же required/optional/nullable/enum/range значения.
 Используй типизированные response DTO, `ApiOkResponse`/другой фактический status
 и существующий `ApiProblemResponses`. При новых ошибках задай публичный stable
 `code`; сообщение внутреннего exception не является UI contract. Не возвращай
 raw upstream error, Prisma record с secrets или stack. Текущая форма ошибок
 описана у HTTP owner; не добавляй поля RFC только потому, что они встречаются в tutorial.
 **Безопасный путь:** используй exception и общий filter, а не локальный
 `res.status(...).json(...)`. Исключение — транспортная операция вроде cookie;
 следуй существующему auth controller с `passthrough` и явно заданным status.
 ## Пример и проверка
 [Operations controller](../../src/tbank/brokerage-operations.controller.ts)
 показывает guard, user.sub, DTO query и service delegation.
 Для нового field обновляй canonical source и generated artifacts в определённом
 направлении; body type frontend не исправляется вручную.
 Проверь happy path и применимые invalid input/access/not-found/domain/upstream
 errors на boundary, где они возникают. Unit вызов controller не запускает pipes,
 guards или serialization. `npm run test:openapi-contract` проверяет schema parity,
 но не поведение invalid request; выбирай соответствующий test по
 [Testing](backend-testing.md). Финальный gate не заменяет semantic review ошибок.
@@ -1,47 +0,0 @@
 # Backend integrations
 ## Выбор boundary
 T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient. Сервисы use case
 получают нормализованный результат через эти clients. Frontend не вызывает
 T-Bank и не получает credentials/proto client. Reference source —
 [ADR 003](../../../docs/adr/003-tbank-server-side-grpc-boundary.md) и
 [connection behavior](../../../docs/integrations/tbank.md).
 Для нового account use case сначала используй TbankAccessService: access,
 connection generation и invalid-token translation не дублируются в callers.
 Чистый mapper финансового значения остаётся рядом с domain owner.
 ## Retry, cache и protocol
 Existing client уже владеет bounded FIFO queue, rate limit, deadline и retry
 классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop
 в service. Не отключай TLS verification ради окружения: используй документированный
 CA mechanism. Точные параметры и ограничения принадлежат
 [connection configuration](../../../docs/integrations/tbank.md#конфигурация-и-ограничения).
 При query/cache change установи key, user/account/generation ownership,
 freshness и поведение late response. Старый результат не может обслужить новую
 connection generation. Client Cached Snapshot frontend отличается от backend
 cache/stale policy; semantics конкретного use case читай через
 [feature index](../../../docs/README.md#предметные-области).
 Внешний auth failure и временная недоступность имеют разные public codes;
 raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService
 и общем HTTP boundary. Для HTTP error change читай HTTP API/Security по trigger.
 Vendor proto хранится в `src/tbank/proto/contracts`; для обновления сверяй
 официальный source и влияние на loader/DTO, не редактируй read-only references.
 Generated artifacts, если есть, создавай из source, без ручной подгонки вывода.
 ## Безопасный путь и проверка
 Сначала добавь нужный operation в существующий client и используй его из
 ответственного service. Отдельный abstraction/adapter оправдан новой
 ответственностью или несовместимым protocol, не только вторым методом.
 [TbankClient tests](../../src/tbank/tbank.client.spec.ts) — пример controlled
 upstream responses. Проверь queue/deadline/retry limit, token translation,
 cache isolation и late response для затронутых ветвей. Fixtures синтетические;
 реальная сеть, секреты и пользовательские accounts не нужны.
 Logging использует [existing logger](backend-architecture.md#logging).
@@ -1,46 +0,0 @@
 # Backend testing
 ## Выбор уровня
 Применяй [общие testing risks](../../../docs/development/engineering-governance.md#risk-based-testing).
 Тесты должны различать правильное и неправильное наблюдаемое поведение.
 | Что меняется | Проверка |
 | --- | --- |
 | Pure mapper/decimal/domain branch | Unit со значимыми edge cases |
 | Service orchestration/access/retry policy | Jest с mocks внешних boundaries и observable outcome |
 | Pipe/guard/cookie/status/HTTP error | Configured Nest HTTP boundary; прямого вызова метода controller недостаточно |
 | OpenAPI metadata/wire schema | `test:openapi-contract` + потребительский contract check |
 | DB constraint/CAS/transaction/migration | Integration с изолированной реальной DB |
 | Только DTO declarations/thin wiring | Existing contract/type/build без искусственного unit test |
 Unit specs colocated в `src/**/*.spec.ts`; HTTP/integration — `test/`.
 Мокируй T-Bank, время и нужную DB boundary, а не проверяемую business-функцию.
 Не зови реальный внешний account/API. Expected error/code, отсутствие запроса
 при недопустимом доступе и сохранение данных важнее private method call count.
 ## Случаи и примеры
 - [BrokerageAccountsService tests](../../src/tbank/brokerage-accounts.service.spec.ts): отсутствие connection не вызывает upstream, нормализация и точные суммы.
 - [AuthService tests](../../src/auth/auth.service.spec.ts): invalid/expired/superseded token и concurrent rotation; mock race test не является доказательством DB transaction.
 - [HTTP filter tests](../../src/common/filters/http-exception.filter.spec.ts): безопасный error envelope.
 - [OpenAPI integration](../../test/openapi-contract.e2e-spec.ts): configured app + frontend snapshot, без записи snapshot и без T-Bank.
 При bug сначала воспроизведи именно его исход, затем исправь responsible owner.
 Не создавай tests для каждой декларации, logs строки или поведения Prisma/Nest
 без собственного инварианта. Coverage не имеет общего threshold.
 ## Команды и ограничения
 Итерация: `npm test -- --runInBand <pattern>`, затем нужный typecheck/lint.
 Полный `npm run verify` включает lint, оба typecheck, Jest и build.
 `npm run test:openapi-contract` — отдельный required check при wire contract change.
 `npm run test:e2e` существует, но известный Prisma migration blocker описан в
 [ограничении сквозной проверки](../../../docs/development/verification.md#известное-ограничение-сквозной-проверки) и WL-P2-05
 [registry](../../../docs/development/audit-remediation.md). Скрипт использует
 фиксированную `/tmp/wealth-ledger-e2e.db`; не запускай его конкурентно как
 независимые DB tests. Для isolation выбери отдельную test DB и runner configuration.
 Если задаче нужна HTTP/DB proof, установи применимость blocker и выполни доступную
 изолированную проверку. Не объявляй покрытым то, что до tests не запустилось;
 сохрани точный failure и оставшуюся проверку. Unit/Swagger success не заменяет e2e.
@@ -9,12 +9,40 @@ PrismaService — существующий shared DB provider с lifecycle пр
 | Ситуация | Решение |
 | --- | --- |
-| Один query/write конкретного use case | Existing service + PrismaService |
+| Данные для use case | Concrete repository; use case не импортирует PrismaService/Prisma и не строит queries |
 | Несколько записей обязаны выполниться вместе | Database transaction вокруг инварианта |
 | Конкурентная смена одного значения | Atomic conditional update/constraint с проверкой результата |
 | Независимые reads | Не добавляй transaction ради внешнего вида |
 | Общая persistence abstraction | Только при реальной общей ответственности; generic repository для одной Prisma реализации не нужен |
 Размещение repository определяется [Architecture](../architecture.md):
 в слоистом module это `infrastructure/`.
 Repository — конкретный класс `*.repository.ts` у business owner, без обязательных
 interface/port/adapter. Он владеет queries, includes/filtering, DB mapping и
 согласованным чтением. Суффиксы `*.persistence.ts`, `*.store.ts`, `*.dao.ts`
 для той же роли не используем. Nest module регистрирует repository приватно.
 Новые business decisions (можно ли менять архивную карту, допустим ли перевод)
 принадлежат application/domain; repository сохраняет persistence и ownership
 ограничения. Existing checks/HTTP helpers в BankCardsRepository — migration
 candidate, не повод дублировать их при новом use case или разрывать transaction.
 `BaseRepository<T>`, `GenericRepository<T>` и RepositoryFactory поверх Prisma
 не нужны без отдельной общей ответственности.
 `BankCardsRepository.summaryData` проверяет владельца карты и получает операции
 с категориями в одной read transaction. `GetBankSummaryUseCase` выбирает период,
 вызывает repository, затем чистый `bankSummary` и формирует ответ. Prisma records
 не становятся domain entities: расчёт получает только нужные ему значения.
 Не создавай обёртку на каждый вызов Prisma. Существующие связные CRUD/transaction
 services (auth, lifecycle подключения, изменения карт/операций/категорий)
 сохраняют queries рядом с CAS и проверками инварианта, если их перенос требует
 лишь набора pass-through методов. Новая самостоятельная read/write capability
 получает repository method; самостоятельный use case не выполняет Prisma queries.
 `BankCardsRepository.write` сохраняет общую retry/transaction boundary для
 существующих banking services. Такой callback с Prisma transaction client —
 локальная техническая граница этих services, не API для domain или use cases.
 Выбирай только нужные данные, сохраняй user/account ownership в запросах и
 application checks. Предварительный lookup не заменяет unique constraint при race.
 Пример: AuthService обрабатывает P2002 и использует conditional `updateMany`
@@ -23,16 +51,16 @@ application checks. Предварительный lookup не заменяет
 Transaction не охватывает сетевой T-Bank вызов как будто это одна atomic DB
 операция. Планируй порядок и compensation по текущей задаче; не удерживай DB
 lock во время retry внешней сети. Access/cache generation semantics — у
-[T-Bank source](../../../docs/integrations/tbank.md#граница-финансового-кэша).
+[T-Bank integration](integrations.md#retry-cache-и-protocol).
 ## Деньги и точность
 Для денежных значений используй existing decimal helpers и строковый wire value,
 не JS floating-point арифметику для сумм. Currency — отдельная часть Money;
 разные валюты не складываются без явно заданного conversion contract.
-Источник: [Money](../../../docs/glossary.md#money),
+Источник формы — `src/common/money.types.ts`;
-пример: [decimal.ts](../../src/common/decimal.ts). UI formatting не меняет
+пример точной арифметики: [decimal.ts](../../src/common/decimal.ts).
-backend ownership расчётов и доменную семантику.
+Форматирование ответа не меняет доменную семантику и точность расчёта.
 ## Schema и migration
@@ -45,12 +73,12 @@ client обновляй из schema. Не переписывай уже прим
 **Безопасный путь:** additive изменение, заполнение/проверка данных и только затем
 удаление прежней формы, если задача этого требует. Примеры schema/migrations:
-[Prisma source](../../prisma/schema.prisma); исторический rationale —
+[Prisma source](../../prisma/schema.prisma). SQLite — embedded storage текущего
-[ADR 001](../../../docs/adr/001-prisma-sqlite-local-mvp.md), не текущий список таблиц.
+приложения; файл БД и encryption key требуют согласованного backup/restore.
 ## Проверка
 `npx prisma validate`; после schema change `npx prisma generate` и
 `npm run typecheck:app`. Invariants/atomicity/migration safety требуют tests
 на соответствующей boundary: mock Prisma не доказывает реальную transaction.
-Выбор integration/e2e и известные ограничения — в [Testing](backend-testing.md).
+Выбор integration/e2e и известные ограничения — в [Testing](testing.md).
@@ -0,0 +1,74 @@
 # Работа в репозитории
 ## Граница и порядок работы
 Репозиторий сам содержит инструкции, исходники, конфигурацию и входы своих
 проверок. Сборка, CI и обязательный маршрут чтения работают без соседних
 checkout. Внешний API задаётся предоставленным публичным контрактом;
 исходники или инструкции его реализации не являются зависимостью разработки.
 При нехватке требования сообщи, какое решение не определено, до его реализации.
 Начни с результата и affected areas. До edits проследи flow/invariants, найди
 owner и 1–3 примера. Код показывает механизм; случайный аналог не меняет контракт.
 Работай напрямую; OpenSpec/SDD lifecycle — только по явному запросу.
 Перед Node-командами активируй местную `.nvmrc`: `nvm use --silent`.
 Сохраняй чужие staged/unstaged/untracked изменения и read-only архивы.
 ## Change scope
 Сначала расширь существующего владельца. Иначе используй standard library,
 платформу или установленную dependency; небольшая новая реализация допустима
 при собственной ответственности. Не создавай helper/interface/wrapper ради
 возможного reuse. Общее имя не означает общую бизнес-ответственность.
 Сохраняй validation, authorization, atomicity, accessibility и migration safety.
 После diff выполни Boy Scout review: проверь новое дублирование, owner, callers,
 небольшие связанные legacy issues и соответствие local conventions. Исправляй
 непосредственно связанные low-risk проблемы; широкий cleanup — отдельная задача.
 ## Domain values
 Finite business vocabulary принадлежит одному domain/module/entity owner.
 Переиспользуй его symbols; для нового словаря без аналога — `as const` + union.
 Сохраняй wire values; generated/external enums не переписывай вручную.
 Numeric policy называй по смыслу и единицам. Индексы, `Math.max(value, 0)` и
 обычные labels не выноси в constants без semantic benefit.
 Локальный TypeScript/lint профиль определяет дополнительные ограничения.
 ## Dependencies
 Проверь аналоги и direct dependencies в местном manifest до добавления пакета.
 Новая dependency оправдана текущей потребностью и меньшей общей сложностью;
 оцени compatibility, runtime/bundle и maintenance/security. Импортируемый пакет
 объявляется напрямую; транзитивная установка не является контрактом.
 Сохраняй exact versions и lockfile; воспроизводимая установка — `npm ci`.
 Peer-конфликт решай совместимыми версиями без `--force`/`--legacy-peer-deps`.
 Используй существующий analyzer; не добавляй второй для той же проверки.
 ## Test Intent
 Перед нетривиальным тестом кратко определи наблюдаемый исход, regression risk,
 значимые edge/error/concurrency cases и самую дешёвую надёжную boundary.
 Отдельный artifact не нужен. Проверяй результат, а не private call order,
 декларации, тривиальные wrappers или поведение framework.
 При bug сначала воспроизведи исход. Mock race не доказывает DB atomicity.
 Уровни и runnable commands выбирай по местной testing convention.
 ## Проверки и завершение
 Code/dependency change: `npm ci`, полный `npm run verify` и дополнительные
 risk checks из местной testing convention. Targeted tests ускоряют итерацию,
 но не заменяют финальный gate. `lint:fix`/format — edits, не proof.
 Markdown-only: проверь новые/изменённые тексты, локальные ссылки/якоря, маршруты
 чтения и `git diff --check`; application build ради текста не нужен.
 Повтори routing по staged/unstaged/new files. Запиши краткие команды, результаты
 и ограничения. Зелёный lint не заменяет semantic/security review.
 ## Git и релизы
 Работа — в `codex/<task>` от актуального `develop`, затем PR в `develop`.
 Сохраняй чужие изменения; перед commit просмотри staged paths и diff.
 Commits и PR titles — Conventional Commits; допустим `spec:`. Каждый commit
 содержит одну связанную задачу. Root другого checkout не управляет этим repo.
 Прямой push в `main`, force-push и перенос опубликованных тегов не входят в
 обычную работу. Перед release/hotfix прочитай местный README, раздел «Релизы».
@@ -0,0 +1,40 @@
 # Backend errors
 ## Поток
 ```text
 application/domain outcome → application mapping → HttpExceptionFilter
                          → application/problem+json
 ```
 Сохраняй принятый профиль RFC 9457: `status`, стабильный публичный `code`,
 для validation — `errors: [{ pointer, detail }]`. Точный контракт и известное
 расхождение validation описаны в [HTTP API](http-api.md#источник-контракта).
 Не добавляй `type/title/instance` как обязательные поля без contract change.
 Чистый domain не импортирует Nest HTTP exceptions. Существующий application
 service может бросить подходящий `HttpException` с public code; не нужен новый
 error framework/registry. Если domain outcome требует HTTP interpretation,
 маппинг принадлежит application/transport boundary.
 ## Codes и безопасность
 - Используй existing code владельца, не сравнивай внутренние сообщения.
  Новое значение имеет один symbolic owner; metadata/validation и consumers
  согласуются по [domain values](engineering.md#domain-values).
 - Общий envelope, default status mapping и unexpected errors принадлежат
  [HttpExceptionFilter](../../src/common/filters/http-exception.filter.ts).
  Не дублируй `res.status().json()` в controllers/services.
 - Неожиданный exception → `500 / INTERNAL_SERVER_ERROR`, без message/stack,
  SQL, credentials или raw upstream payload в ответе.
 - External auth failure и временная недоступность имеют разные outcomes;
  translation выполняется на existing integration/access boundary.
 - Логи используют [observability](observability.md). Redaction не
  делает произвольное сообщение ошибки безопасным.
 ## Проверка
 Для изменённого кода проверь observable status/code и сохранность данных.
 Для validation нужен request через `configureApp`: fabricated `ValidationError`
 в unit test filter не доказывает форму, выходящую из реального ValidationPipe.
 OpenAPI parity проверяет schema, а не response pipeline; [Testing](testing.md).
@@ -0,0 +1,88 @@
 # Backend HTTP API
 ## Выбор boundary
 Сначала определи, меняется wire contract или только реализация существующего
 use case. Для route/request/response/status/error shape используй
 [локальный публичный контракт](#источник-контракта) и configured HTTP tests.
 | Проверка | Где выполнять |
 | --- | --- |
 | Тип/формат/диапазон входа | Runtime DTO class с class-validator/class-transformer |
 | Согласованность полей, бизнес-ограничение | Feature service/domain helper |
 | Session и identity | Existing guard/strategy |
 | Доступ user к конкретному account | Existing access service |
 | HTTP envelope/безопасная ошибка | Общий HttpExceptionFilter |
 Controller объявляет contract и делегирует; не обращается напрямую к Prisma/gRPC
 и не выполняет финансовые расчёты или сложную оркестрацию.
 Controller вызывает application use case/service. Identity берётся из verified
 `request.user`, не из body/userId, предоставленного клиентом. Access rules активируют Security.
 ## DTO и errors
 DTO — runtime class: TS interface не предоставляет validation metadata.
 `*.controller.ts` и `*.dto.ts` остаются около HTTP boundary, в root компактного
 module или presentation. DTO можно передать application boundary при совпадении
 формы; отдельный Input с теми же полями не нужен. Domain не импортирует DTO:
 например, чистые денежные расчёты используют `Money`, а Swagger — `MoneyDto`.
 Нормализованная форма input нужна только при смысловом отличии от wire contract;
 выбор suffix принадлежит [Architecture](../architecture.md).
 ValidationPipe уже настроен в `configureApp` (`transform`, `whitelist`).
 Не обещай rejection неизвестных fields: `forbidNonWhitelisted` не включён.
 Для query numbers/arrays выбирай явное преобразование и валидаторы, как в
 [operations DTO](../../src/modules/investments/operations/presentation/brokerage-operation.dto.ts). Swagger metadata
 описывает те же required/optional/nullable/enum/range значения.
 Используй типизированные response DTO, `ApiOkResponse`/другой фактический status
 и существующий `ApiProblemResponses`. Prisma model не является public contract:
 response выбирает поля явно. Stable codes, RFC 9457 профиль и mapping принадлежат
 [Errors](error-handling.md).
 **Безопасный путь:** используй exception и общий filter, а не локальный
 `res.status(...).json(...)`. Исключение — транспортная операция вроде cookie;
 следуй существующему auth controller с `passthrough` и явно заданным status.
 ## Пример и проверка
 Prefix `/api/v1` задаёт `configureApp`. Route/status/request/response/OpenAPI
 change — изменение публичного backend contract; несовместимое изменение требует
 согласованного перехода consumers, а не незаметной правки DTO. Новый API version
 не вводи для внутреннего refactor.
 Pagination сохраняет contract endpoint: operations использует opaque cursor,
 limit и DTO bounds. Не заменяй cursor offset/page и не добавляй global pagination
 helper ради первого endpoint. Новая pagination явно определяет порядок,
 границу страницы и end-of-list; reused cursor не должен менять filters/owner.
 [Operations controller](../../src/modules/investments/operations/presentation/brokerage-operations.controller.ts)
 показывает guard, user.sub, DTO query и service delegation.
 Для нового field обновляй Nest DTO/metadata и публикуемый OpenAPI artifact.
 Потребители получают публичный контракт независимо от внутреннего устройства API.
 Проверь happy path и применимые invalid input/access/not-found/domain/upstream
 errors на boundary, где они возникают. Unit вызов controller не запускает pipes,
 guards или serialization. `npm run test:openapi-contract` проверяет schema parity,
 но не поведение invalid request; выбирай соответствующий test по
 [Testing](testing.md). Финальный gate не заменяет semantic review ошибок.
 ## Источник контракта
 Nest DTO/controllers/Swagger metadata определяют публичный HTTP API.
 `npm run openapi:generate` собирает backend и записывает корневой `openapi.json`.
 Nest preview читает metadata без запуска HTTP-порта, провайдеров, БД и T-Bank;
 команда не требует deployment environment. Artifact исключён из Git.
 При изменении API обнови DTO/metadata и выполни генерацию. Потребители получают
 artifact отдельно; backend не читает их репозитории. `test:openapi-contract`
 сравнивает вывод генератора с runtime schema configured app во временном каталоге.
 Проверка подтверждает правильность генерации, но без versioned baseline не
 выявляет breaking change относительно предыдущего выпуска. Для такого изменения
 согласуй переход consumers и проверь relevant HTTP behavior.
 HTTP prefix — `/api/v1`; Swagger доступен согласно `src/config/swagger.config.ts`.
 Общий error response — `application/problem+json` со `status` и публичным `code`.
 Validation требует `400 / VALIDATION_ERROR` и `errors: [{ pointer, detail }]`.
 Известное ограничение: ValidationPipe сейчас формирует строковые сообщения,
 а filter ожидает структурированные field errors; schema parity не доказывает
 правильность `errors`. Изменение требует проверки реального HTTP pipeline.
@@ -0,0 +1,73 @@
 # Backend integrations
 ## Выбор boundary
 T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient; NCR ratings —
 NcrRatingsClient. Сервисы use case
 используют объявленные клиентом records; SDK clients, metadata и transport errors
 остаются внутри integration. Credentials и proto client не входят в публичный
 HTTP API. Connection lifecycle проверяется на границе соответствующего module
 и [Security](security-auth.md).
 `modules/investments/tbank-connection` — пользовательская capability чтения,
 создания/замены и удаления подключения. `integrations/tbank` — технические
 RPC, credentials/access и resilience. Эти владельцы не объединяются из-за имени
 поставщика; низкоуровневый client не зависит от пользовательского module.
 `*.client.ts` содержит transport и его retries; `*.api.ts` только перечисляет
 публичные exports. Все шесть `auth/operations/portfolio/tbank/moex/ncr.api.ts`
 имеют одинаковую роль программной границы, определённую в
 [Architecture](../architecture.md). Логика, DTO definitions и HTTP routes
 в эти файлы не помещаются. Type exports обозначаются `export type`.
 Преобразование provider records происходит на boundary: например,
 `tbank-portfolio.mapper.ts` и `bond-money.mapper.ts`; protobuf decimal helper
 остаётся отдельным чистым входом integration. Domain получает внутренние
 значения и не импортирует gRPC/SDK types. Не добавляй новый adapter на каждый
 client или mapper для простого копирования полей. Даты/units/nano разбираются
 на границе клиента/его mapping, а не становятся моделью чистых расчётов.
 Для нового account use case сначала используй TbankAccessService: access,
 connection generation и invalid-token translation не дублируются в callers.
 Mapper внешних финансовых значений остаётся внутри business capability,
 обычно в infrastructure по [Architecture](../architecture.md).
 ## Retry, cache и protocol
 Existing client уже владеет bounded FIFO queue, rate limit, deadline и retry
 классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop
 в service. Не отключай TLS verification ради окружения: используй документированный
 CA mechanism. Точные параметры и ограничения принадлежат
 [validated environment](../../src/config/env.validation.ts) и
 [TbankClient](../../src/integrations/tbank/tbank.client.ts).
 Эта queue/retry policy относится к T-Bank. MOEX/NCR HTTP clients используют
 собственный bounded timeout и безопасный unavailable outcome; не приписывай им
 gRPC retry policy. При изменении upstream сначала прочитай конкретный client.
 При query/cache change установи key, user/account/generation ownership,
 freshness и поведение late response. Старый результат не может обслужить новую
 connection generation. Успешная замена/deletion подключения меняет generation
 даже при сохранении прежнего token; ошибка оставляет прежнее подключение.
 Кэш конкретного use case принадлежит его service и tests. Не переноси
 сохранённый snapshot между пользователями или поколениями подключения.
 Внешний auth failure и временная недоступность имеют разные public codes;
 raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService
 и общем HTTP boundary. Для HTTP error change читай HTTP API/Security по trigger.
 Vendor proto хранится в `src/integrations/tbank/proto/contracts`; для обновления сверяй
 официальный source и влияние на loader/DTO, не редактируй read-only references.
 Generated artifacts, если есть, создавай из source, без ручной подгонки вывода.
 ## Безопасный путь и проверка
 Сначала добавь нужный operation в существующий client и используй его из
 ответственного service. Отдельный abstraction/adapter оправдан новой
 ответственностью или несовместимым protocol, не только вторым методом.
 [TbankClient tests](../../src/integrations/tbank/tbank.client.spec.ts) — пример controlled
 upstream responses. Проверь queue/deadline/retry limit, token translation,
 cache isolation и late response для затронутых ветвей. Fixtures синтетические;
 реальная сеть, секреты и пользовательские accounts не нужны.
 Logging использует [existing logger](../architecture.md#logging).
@@ -0,0 +1,22 @@
 # Observability
 - Единственный logger — nestjs-pino. Application events используют
  [StructuredLogger](../../src/common/logging/structured-logger.service.ts),
  стабильное имя события и разрешённые scalar fields. `console.log` и второй
  logger в production не используются.
 - `info` — значимый lifecycle/outcome; `debug` — подробности успешного RPC;
  `warn` — восстановимая проблема/retry; `error` — окончательный сбой.
  Не добавляй log на каждый вход/выход функции или дубликат HTTP completion.
 - RequestContextService и request middleware владеют correlation: серверный
  request ID возвращается как `X-Request-ID`, входящий client ID хранится отдельно.
  Передавай существующий context, не создавай собственный UUID в каждом service.
 - Wrapper ограничивает поля, Pino redacts request secrets. Не логируй passwords,
  tokens, cookie, Authorization, credentials, connection generation, raw body
  или upstream error. Secret в `message/stack` не становится безопасным из-за
  allowlist; правила [Security](security-auth.md) обязательны для sensitive data.
 - Для ошибки используй public code и безопасный context операции/попыток;
  [error mapping](error-handling.md) не отдаёт внутренние детали клиенту.
 Проверяй новые поля/redaction/correlation existing logging tests; не добавляй
 тест на каждую строку log. Existing ESLint не запрещает все вызовы `console`
 отдельным правилом: до настройки встроенного `no-console` это semantic review.
@@ -10,20 +10,23 @@ account access/connection generation — TbankAccessService; token crypto —
 TbankTokenService/TbankCrypto. Расширяй существующую boundary, не добавляй
 второй JWT middleware, decrypt helper или refresh coordinator.
-[Authentication](../../../docs/domains/authentication/overview.md) и
+Access проверяется JWT strategy; refresh передаётся httpOnly cookie.
-[ADR 006](../../../docs/adr/006-auth-session-policy.md)/[009](../../../docs/adr/009-concurrent-refresh-rotation-policy.md)
+Сроки token/session принадлежат auth source и configured HTTP tests.
-задают session semantics. Access хранится только в памяти frontend; refresh
+Source code конфигурации cookie —
-передаётся httpOnly cookie. Source code конфигурации cookie —
+[AuthController](../../src/modules/auth/presentation/auth.controller.ts); изменение flags/path требует
 [AuthController](../../src/auth/auth.controller.ts); изменение flags/path требует
 проверки browser/HTTP поведения, не только TypeScript.
 Refresh rotation атомарна: один победитель, проигравший/superseded token получает
 401, но сам по себе не отзывает session победителя. Не вводи replay history/grace
-или иной security contract без текущей задачи. Logout идемпотентен; in-memory
+или иной security contract без текущей задачи. Logout идемпотентен, отзывает
-frontend session/cache очищается и при network failure.
+сессию и очищает refresh cookie на HTTP-границе.
 ## Trust boundaries
 Клиентский интерфейс не является security boundary. DTO runtime validation выполняется
 server-side; whitelist не заменяет access checks. Environment/secret inputs
 проверяет existing config owner; реальные credentials не попадают в fixtures.
 Verified JWT не доказывает доступ к accountId из URL. Используй user.sub и
 existing account access policy; не доверяй userId/token из клиента как authority.
 Cross-user, invalid/expired/superseded token и concurrent requests — обязательные
@@ -32,13 +35,20 @@ cases для соответствующего изменения.
 T-Bank credentials остаются server-side и хранятся encrypted. Используй
 existing AES-256-GCM boundary с validated 32-byte key; не печатай plaintext,
 шифротекст, cookie, Authorization или connection generation в logs/errors/API.
-[Connection source](../../../docs/integrations/tbank.md) определяет
+Успешная замена/deletion меняет connection generation и инвалидирует её кэши;
-cache invalidation при замене/deletion и ограничение key rotation.
+ошибка сохраняет прежнее подключение. Ключ не ротируется автоматически:
 новый ключ не расшифрует сохранённые credentials. Нужен исходный ключ или
 повторное сохранение token пользователем; сохраняй ключ отдельно от backup БД.
 Не передавай Prisma User/Session целиком наружу; выбирай public DTO. Пароль
 обрабатывает существующий bcrypt flow. Не копируй требования о нормализации
 или длине из tutorial: сверяй runtime DTO, tests и feature source.
 Предпочитай Prisma query API. Raw SQL допускается только по конкретной нужде
 с параметризованными значениями; не конкатенируй untrusted input и не передавай
 его в `queryRawUnsafe`/`executeRawUnsafe`. Dynamic identifiers выбирай из
 закрытого server-owned набора. Проверка user ownership сохраняется и в SQL.
 ## Безопасный путь и проверка
 При неясной ownership/crypto/session семантике прочитай exact source до edits.
@@ -46,6 +56,6 @@ cache invalidation при замене/deletion и ограничение key ro
 фиктивным success или log. Logger allowlist/redaction не делает произвольный
 message безопасным.
-Targeted auth/access/crypto/logging tests + [Testing](backend-testing.md).
+Targeted auth/access/crypto/logging tests + [Testing](testing.md).
-Cookie/guard/HTTP changes требуют configured HTTP proof; frontend Bearer/retry
+Cookie/guard/HTTP changes требуют configured HTTP proof.
-проверяется MSW. Schema parity не доказывает отсутствие утечки secret.
+Schema parity не доказывает отсутствие утечки secret.
@@ -0,0 +1,55 @@
 # Backend testing
 Перед нетривиальными тестами сформулируй
 [общий Test Intent](engineering.md#test-intent); отдельный документ
 не требуется. Trivial low-risk изменения обходятся без него.
 ## Выбор уровня
 Проверяй риски доступа, денежных расчётов, целостности данных, конкурентных
 изменений, публичного контракта и подтверждённых регрессий.
 Тесты должны различать правильное и неправильное наблюдаемое поведение.
 | Что меняется | Проверка |
 | --- | --- |
 | Pure mapper/decimal/domain branch | Unit со значимыми edge cases |
 | Service orchestration/access/retry policy | Jest с mocks внешних boundaries и observable outcome |
 | Pipe/guard/cookie/status/HTTP error | Configured Nest HTTP boundary; прямого вызова метода controller недостаточно |
 | OpenAPI metadata/wire schema | `test:openapi-contract` + configured HTTP tests |
 | DB constraint/CAS/transaction/migration | Integration с изолированной реальной DB |
 | Только DTO declarations/thin wiring | Existing contract/type/build без искусственного unit test |
 Unit specs colocated в `src/**/*.spec.ts`; HTTP/integration — `test/`.
 Мокируй T-Bank, время и нужную DB boundary, а не проверяемую business-функцию.
 Не зови реальный внешний account/API. Expected error/code, отсутствие запроса
 при недопустимом доступе и сохранение данных важнее private method call count.
 ## Случаи и примеры
 - [BrokerageAccountsService tests](../../src/modules/investments/brokerage-accounts/brokerage-accounts.service.spec.ts): отсутствие connection не вызывает upstream, нормализация и точные суммы.
 - [AuthService tests](../../src/modules/auth/application/auth.service.spec.ts): invalid/expired/superseded token и concurrent rotation; mock race test не является доказательством DB transaction.
 - [HTTP filter tests](../../src/common/filters/http-exception.filter.spec.ts): безопасный error envelope.
 - [OpenAPI integration](../../test/openapi-contract.e2e-spec.ts): генератор без сервера + configured app; временный JSON, без versioned snapshot и без T-Bank.
 При bug сначала воспроизведи именно его исход, затем исправь responsible owner.
 Не создавай tests для каждой декларации, logs строки или поведения Prisma/Nest
 без собственного инварианта. Coverage не имеет общего threshold.
 ## Команды и ограничения
 Итерация: `npm test -- --runInBand <pattern>`, затем нужный typecheck/lint.
 Полный `npm run verify` включает lint, оба typecheck, Jest и build.
 `npm run test:openapi-contract` — отдельный required check при wire contract change.
 `npm run test:e2e` запускает все HTTP suites через изолированный SQLite runner;
 `npm run test:sqlite` — только auth/cards. Каждая suite получает новую временную
 базу со штатными migrations. Прямой Jest без runner отклоняется до DB-запросов.
 `prisma.config.ts` исключает влияние унаследованного `RUST_LOG=warn/error`
 на fresh migration; точная Prisma version принадлежит manifest/lockfile. Подробности и регрессия запуска —
 [Backend README](../../README.md#реальная-sqlite-и-сохранность-данных).
 HTTP suites требуют разрешения открывать локальные порты. Ошибка sandbox
 не считается успешным тестом; повторите проверку в подходящем окружении.
 Для schema/data changes дополнительно `npm run test:durability -- <baseline>`.
 Матрица рисков и подготовка совместимой предыдущей сборки — в том же README.
 Mock Prisma не заменяет доказательство реальной DB concurrency.
@@ -0,0 +1,13 @@
 **
 !package.json
 !package-lock.json
 !.nvmrc
 !nest-cli.json
 !tsconfig*.json
 !prisma.config.ts
 !prisma/
 !prisma/schema.prisma
 !prisma/migrations/
 !prisma/migrations/**
 !src/
 !src/**
@@ -0,0 +1,26 @@
 name: Conventional commits
 on:
  pull_request:
    types: [opened, synchronize, reopened, edited]
 jobs:
  commits:
    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: https://github.com/actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - run: npm ci --ignore-scripts
      - name: Check PR title and commits
        env:
          PR_TITLE: ${{ github.event.pull_request.title }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          printf '%s\n' "$PR_TITLE" | npm run commitlint -- --strict
          npm run commitlint -- --strict --from "$BASE_SHA" --to "$HEAD_SHA"
@@ -0,0 +1,59 @@
 name: Backend image
 on:
  push:
    tags: ['v*']
 concurrency:
  group: backend-image-publication
  cancel-in-progress: false
 jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      IMAGE: nexus.personal.ksv741.ru/docker-hosted/wealthledger/backend
      RELEASE_TAG: ${{ gitea.ref_name }}
      REVISION: ${{ gitea.sha }}
      DOCKER_CONFIG: ${{ runner.temp }}/wealthledger-backend-docker
    steps:
      - uses: https://github.com/actions/checkout@v4
      - uses: https://github.com/actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - name: Validate release version
        run: |
          node --input-type=commonjs -e 'const p = require("./package.json"); const l = require("./package-lock.json"); if (!/^v\d+\.\d+\.\d+$/.test(process.env.RELEASE_TAG) || process.env.RELEASE_TAG !== `v${p.version}` || l.version !== p.version || l.packages[""].version !== p.version) process.exit(1)'
          test "$(git rev-parse HEAD)" = "$REVISION"
          docker version
          docker buildx version
      - run: npm ci
      - run: npx --no-install prisma generate
      - run: npm run verify
      - run: npm run test:e2e
      - name: Login with dedicated Nexus writer
        env:
          REGISTRY_USERNAME: ${{ secrets.NEXUS_USERNAME }}
          REGISTRY_TOKEN: ${{ secrets.NEXUS_PASSWORD }}
        run: |
          test -n "$REGISTRY_USERNAME" && test -n "$REGISTRY_TOKEN"
          install -d -m 700 "$DOCKER_CONFIG"
          printf '%s' "$REGISTRY_TOKEN" | docker login nexus.personal.ksv741.ru --username "$REGISTRY_USERNAME" --password-stdin
      - name: Publish immutable release tag
        run: |
          VERSION="${RELEASE_TAG#v}"
          if docker manifest inspect "$IMAGE:$VERSION" >/dev/null 2>manifest-error.log; then
            echo 'Refusing to overwrite an existing release tag'; exit 1
          fi
          if ! grep -Eq 'manifest unknown|no such manifest' manifest-error.log; then
            echo 'Cannot prove tag absence; refusing publication'; exit 1
          fi
          docker buildx build --target production --build-arg VERSION="$VERSION" --build-arg REVISION="$REVISION" --tag "$IMAGE:$VERSION" --metadata-file image-metadata.json --push .
          DIGEST="$(node --input-type=commonjs -p 'require("./image-metadata.json")["containerimage.digest"]')"
          docker pull "$IMAGE@$DIGEST"
          test "$(docker image inspect "$IMAGE@$DIGEST" --format '{{index .Config.Labels "org.opencontainers.image.revision"}}')" = "$REVISION"
          npm run test:container -- "$IMAGE@$DIGEST"
          printf 'Backend image: %s@%s\n' "$IMAGE" "$DIGEST"
      - name: Remove registry session
        if: always()
        run: rm -rf "$DOCKER_CONFIG"
@@ -0,0 +1,31 @@
 name: Backend security
 on:
  push:
    branches:
      - '**'
  pull_request:
  schedule:
    - cron: '17 5 * * *'
 jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Record checked revision
        run: git rev-parse HEAD
      - name: Scan history with Gitleaks 8.30.1
        run: |
          curl --fail --location --silent --show-error https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz -o /tmp/gitleaks.tar.gz
          echo '551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  /tmp/gitleaks.tar.gz' | sha256sum --check
          mkdir -p /tmp/gitleaks-bin
          tar -xzf /tmp/gitleaks.tar.gz -C /tmp/gitleaks-bin gitleaks
          /tmp/gitleaks-bin/gitleaks git --log-opts=--all --redact=100 --no-banner
      - uses: https://github.com/actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - name: Audit runtime and development dependencies
        run: npm audit --include=dev --audit-level=low
@@ -0,0 +1,34 @@
 name: Backend verify
 on:
  push:
    branches: ['**']
  pull_request:
 jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: https://github.com/actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Record checked revision
        run: git rev-parse HEAD
      - uses: https://github.com/actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - run: npm ci
      - name: Generate Prisma client before typechecks
        run: npx --no-install prisma generate
      - name: Run all backend gates
        run: npm run verify
      - name: Run isolated SQLite and runtime OpenAPI suites
        run: npm run test:e2e
      - name: Analyze develop with SonarQube
        if: gitea.event_name == 'push' && gitea.ref == 'refs/heads/develop'
        # v2.3.0: same Docker-based scanner used for SonarQube 9.9.
        uses: https://github.com/SonarSource/sonarqube-scan-action@aecaf43ae57e412bd97d70ef9ce6076e672fe0a9
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          args: -Dsonar.qualitygate.wait=true
@@ -21,6 +21,7 @@ lerna-debug.log*
 # Tests
 /coverage
 /.scannerwork
 /.nyc_output
 # IDEs and editors
@@ -64,3 +65,6 @@ report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 /dev.db-*
 /prisma/*.db
 /prisma/*.db-*
 # Generated public API artifact
 /openapi.json
@@ -0,0 +1,19 @@
 # Reviewed historical false positives only; new commits remain scanned.
 # Test fixtures: base64 of the deterministic string 0123456789abcdef repeated twice.
 25d7c5780b60343fecb4f1ae9a30392776eb5aec:src/config/env.validation.spec.ts:generic-api-key:30
 31cbba8654f01adf11c52e12c2b286200d6cad7d:src/config/env.validation.spec.ts:generic-api-key:10
 31cbba8654f01adf11c52e12c2b286200d6cad7d:src/config/env.validation.spec.ts:generic-api-key:17
 31cbba8654f01adf11c52e12c2b286200d6cad7d:src/config/env.validation.spec.ts:generic-api-key:42
 31cbba8654f01adf11c52e12c2b286200d6cad7d:test/e2e-env.cjs:generic-api-key:4
 326fb67def9b3878d5447ef838ae96d50bf493d6:src/tbank/brokerage-operations.service.spec.ts:generic-api-key:15
 34c2b79e276c9575996604f3f862bc866cfe44e7:src/tbank/upcoming-events.service.spec.ts:generic-api-key:15
 c0a4a9388074bdce20138dd5649805ed24a9e9fa:src/tbank/brokerage-accounts.service.spec.ts:generic-api-key:12
 ce24a84b7fb48091d2b91836eb7b702a2f811c96:test/e2e-env.cjs:generic-api-key:16
 dfca11c81f7e6dadce3ca6f961d265c5e3f8ff8e:src/tbank/portfolio.service.spec.ts:generic-api-key:16
 # Historical .env.example JWT_SECRET is an explicit replace-with placeholder.
 4cbfc2621cfc54df3d09786905130c28a2323a04:.env.example:generic-api-key:4
 # Historical CircleCI badge copied verbatim from nestjs/typescript-starter README.
 # Verified against https://github.com/nestjs/typescript-starter/blob/master/README.md
 f8dcfb71c1767696a9aa6741ddaf6575416c901e:README.md:generic-api-key:5
 # Container smoke fixture: same deterministic 32-byte test key, never a runtime secret.
 1a6be432f24f757728a03415051392069112af1f:test/container-smoke.cjs:generic-api-key:14
@@ -0,0 +1 @@
 save-exact=true
@@ -1 +1 @@
-22
+24.21.0
@@ -0,0 +1,106 @@
 {
  "git": {
    "requireBranch": "release/*",
    "requireCleanWorkingDir": true,
    "requireUpstream": false,
    "requireCommits": true,
    "commitMessage": "chore(release): ${version}",
    "tagName": "v${version}",
    "tag": false,
    "push": false
  },
  "npm": {
    "publish": false
  },
  "github": {
    "release": false
  },
  "gitlab": {
    "release": false
  },
  "hooks": {
    "after:git:init": "node scripts/check-release.cjs"
  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "infile": "CHANGELOG.md",
      "preset": {
        "name": "conventionalcommits",
        "types": [
          {
            "type": "chore",
            "scope": "release",
            "effect": "hidden"
          },
          {
            "type": "feat",
            "section": "Features",
            "effect": "bump"
          },
          {
            "type": "fix",
            "section": "Bug Fixes",
            "effect": "bump"
          },
          {
            "type": "perf",
            "section": "Performance",
            "effect": "bump"
          },
          {
            "type": "docs",
            "section": "Documentation",
            "effect": "bump"
          },
          {
            "type": "spec",
            "section": "Specifications",
            "effect": "bump"
          },
          {
            "type": "refactor",
            "section": "Refactoring",
            "effect": "bump"
          },
          {
            "type": "build",
            "section": "Build",
            "effect": "bump"
          },
          {
            "type": "ci",
            "section": "CI",
            "effect": "bump"
          },
          {
            "type": "test",
            "section": "Tests",
            "effect": "bump"
          },
          {
            "type": "style",
            "section": "Styles",
            "effect": "bump"
          },
          {
            "type": "chore",
            "section": "Maintenance",
            "effect": "bump"
          },
          {
            "type": "revert",
            "section": "Reverts",
            "effect": "bump"
          }
        ]
      },
      "context": {
        "host": "https://git.personal.ksv741.ru",
        "owner": "WealthLedger",
        "repository": "backend",
        "linkReferences": true,
        "commit": "commit"
      }
    }
  }
 }
@@ -1,23 +1,38 @@
-# Backend
+# Backend router
-NestJS API; общие правила работы — в root `AGENTS.md`.
+Репозиторий самостоятельный: обязательные инструкции и проверки используют
-До backend-решения прочитай [router](.ai/CONVENTIONS.md) и
+только его файлы и предоставленные публичные контракты. Перед работой прочитай
-[sources](.ai/SOURCES.md), затем только применимые документы/разделы.
+[порядок работы](.ai/conventions/engineering.md#граница-и-порядок-работы), затем
 объединяй triggers задачи и путей; читай активированные темы до решения.
-## Проверка
+| Решение / сигнал | Читать |
 | --- | --- |
 | Устройство/data flow, module/layer/public API/DI/suffix, owner | [Architecture](.ai/architecture.md) |
 | TS vocabulary, domain literals, magic values | [Types/values](.ai/architecture.md#domain-literals-and-magic-values) |
 | Controller/DTO/validation, route/status/response, OpenAPI | [HTTP API](.ai/conventions/http-api.md) |
 | Application/domain/HTTP error, exception, code | [Errors](.ai/conventions/error-handling.md) |
 | Repository/Prisma/query, transaction, migration, atomic write | [Data](.ai/conventions/data.md) |
 | Tests или behavior с regression risk | [Testing](.ai/conventions/testing.md) |
 | JWT/cookie/session/guard/access, encryption, secrets | [Security](.ai/conventions/security-auth.md) |
 | External client/gateway/SDK/proto, retry/rate limit/cache | [Integrations](.ai/conventions/integrations.md) |
 | Logging/context/levels, sensitive logs | [Observability](.ai/conventions/observability.md); sensitive data также Security |
 | Изменение публичного wire contract / Swagger metadata | [HTTP API](.ai/conventions/http-api.md#источник-контракта) |
 | Helper/dependency/новый pattern, refactor/scope | [Change scope](.ai/conventions/engineering.md#change-scope), для пакета — [Dependencies](.ai/conventions/engineering.md#dependencies) |
 | Выбор gate, tooling, завершение | [Проверки](.ai/conventions/engineering.md#проверки-и-завершение) |
-Перед Node-командами: `nvm use --silent` по `.nvmrc`.
+Новый endpoint обычно требует HTTP API + Testing; Data/Security добавляются
-После lockfile install `npm ci` полный gate — `npm run verify`:
+по persistence/access trigger. Auth refresh активирует Security + Data + Testing.
-zero-warning ESLint, application/test TypeScript, Jest и build.
+Перед завершением повтори routing по новым и изменённым файлам. Для Git/release
-`lint:fix`/`format` пишут файлы и запускаются отдельно от доказательства проверки.
+прочитай [Git и релизы](.ai/conventions/engineering.md#git-и-релизы).
 `test:cov` — диагностика без общего threshold; scripts принадлежат `package.json`.
-HTTP contract changes дополнительно проходят общий
+## Источники
 [contract workflow](../docs/development/runtime-openapi-verification.md).
 Общий e2e имеет известный environment blocker; применимость и маршрут проверки
 описаны в [backend testing](.ai/conventions/backend-testing.md).
 Generated Prisma client не редактируется вручную. Credentials, авторизация
 доступа к счетам и внешние интеграции остаются server-side.
-ESLint/TypeScript не доказывают правильность domain boundaries, security или
+| Вопрос | Локальный источник |
-денежных вычислений: для них нужны semantic review и risk-based tests.
+| --- | --- |
 | HTTP errors/DTO/wire shape | [HTTP API](.ai/conventions/http-api.md), генерация `npm run openapi:generate`, configured HTTP tests |
 | Auth/session, account access, secrets | [Security](.ai/conventions/security-auth.md) и auth/access tests |
 | Prisma/data ownership | [Data](.ai/conventions/data.md), Prisma schema/migrations |
 | T-Bank/cache/logging | [Integrations](.ai/conventions/integrations.md), [Observability](.ai/conventions/observability.md) |
 | Money и финансовые расчёты | [Data](.ai/conventions/data.md#деньги-и-точность), domain source и tests владельца |
 | Поведение области | Module source и tests; неясное ожидание уточни до изменения |
 | Versions/scripts/check scope | Manifest/lockfile, ESLint/TypeScript/Jest/Prisma configs |
@@ -0,0 +1,138 @@
 # Changelog
 ## [1.0.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v0.2.3...v1.0.0) (2026-09-26)
 ### ⚠ BREAKING CHANGES
 * investment reads return data/meta resource envelopes and locally
  persisted snapshots; consumers must use the matching OpenAPI contract and explicit
  synchronization endpoints.
 ### Features
 * persist T-Bank data and synchronize reads ([d6e6c4a](https://git.personal.ksv741.ru/WealthLedger/backend/commit/d6e6c4ace553572ff9e9f635b7a4d21c8afbf97f))
 ### Tests
 * prove reads finish before source synchronization ([e423213](https://git.personal.ksv741.ru/WealthLedger/backend/commit/e4232138d04ad6a2aa8100a7d36fdcb2d7663fa8))
 ## [0.2.3](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v0.2.2...v0.2.3) (2026-09-19)
 ### Bug Fixes
 * correct Nexus routing and SonarQube host ([7c0150c](https://git.personal.ksv741.ru/WealthLedger/backend/commit/7c0150c56b2dab44347b55344e04c821689543e7))
 ## [0.2.2](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v0.2.1...v0.2.2) (2026-09-19)
 ### Bug Fixes
 * update Nexus registry host ([4c91682](https://git.personal.ksv741.ru/WealthLedger/backend/commit/4c916829eac23326a42c09873e32908cfc9f422c))
 ## [0.2.1](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v0.2.0...v0.2.1) (2026-09-18)
 ### Documentation
 * use shared Nexus account [#25](https://git.personal.ksv741.ru/WealthLedger/backend/issues/25) ([9437b6a](https://git.personal.ksv741.ru/WealthLedger/backend/commit/9437b6a311cd51230b8381c8643c6ea308454d38))
 ### CI
 * add backend SonarQube analysis [#23](https://git.personal.ksv741.ru/WealthLedger/backend/issues/23) ([1946192](https://git.personal.ksv741.ru/WealthLedger/backend/commit/1946192be975eeea75432ec39b27d19952742b15))
 * publish backend images to Nexus [#25](https://git.personal.ksv741.ru/WealthLedger/backend/issues/25) ([0ec7ae5](https://git.personal.ksv741.ru/WealthLedger/backend/commit/0ec7ae51af080288a31dc6e65a738a4bd6396436))
 ## [0.2.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v0.1.0...v0.2.0) (2026-09-16)
 ### Features
 * add backend container delivery ([1a6be43](https://git.personal.ksv741.ru/WealthLedger/backend/commit/1a6be432f24f757728a03415051392069112af1f))
 * generate OpenAPI without peer repositories ([32c12fb](https://git.personal.ksv741.ru/WealthLedger/backend/commit/32c12fb10d4f739c6af0ce32b8f2ea6e94c42090))
 ### Bug Fixes
 * allow reviewed container smoke fixture ([d7cb7e3](https://git.personal.ksv741.ru/WealthLedger/backend/commit/d7cb7e3e206c995ef2fa6f1ee61ef7e93599d88f))
 ### Documentation
 * refine backend conventions and routing ([9810d47](https://git.personal.ksv741.ru/WealthLedger/backend/commit/9810d47e42d9275cf2520556f517d411058ddcb3))
 * simplify conventions layout ([0167826](https://git.personal.ksv741.ru/WealthLedger/backend/commit/016782657acfd35ff3fd755462007938fac35156))
 ## 0.1.0 (2026-09-14)
 ### Features
 * add authorization ([4cbfc26](https://git.personal.ksv741.ru/WealthLedger/backend/commit/4cbfc2621cfc54df3d09786905130c28a2323a04))
 * add bond details, yields and credit ratings ([235c179](https://git.personal.ksv741.ru/WealthLedger/backend/commit/235c179ff813dac3312b849928d11734bccba823))
 * add brocker account list ([c0a4a93](https://git.personal.ksv741.ru/WealthLedger/backend/commit/c0a4a9388074bdce20138dd5649805ed24a9e9fa))
 * add logging ([25d7c57](https://git.personal.ksv741.ru/WealthLedger/backend/commit/25d7c5780b60343fecb4f1ae9a30392776eb5aec))
 * add manual bank card ledger ([e6f58ef](https://git.personal.ksv741.ru/WealthLedger/backend/commit/e6f58ef0eef3fbae079270a0d429afd17e4cd3ac))
 * add operations list ([326fb67](https://git.personal.ksv741.ru/WealthLedger/backend/commit/326fb67def9b3878d5447ef838ae96d50bf493d6))
 * add portfolio ([dfca11c](https://git.personal.ksv741.ru/WealthLedger/backend/commit/dfca11c81f7e6dadce3ca6f961d265c5e3f8ff8e))
 * add stock details and ticker resolution ([f24fd98](https://git.personal.ksv741.ru/WealthLedger/backend/commit/f24fd98fbcbbf952b11bb61f607ae0aec4456839))
 * add tbank tokens ([31cbba8](https://git.personal.ksv741.ru/WealthLedger/backend/commit/31cbba8654f01adf11c52e12c2b286200d6cad7d))
 * add агегку events ([34c2b79](https://git.personal.ksv741.ru/WealthLedger/backend/commit/34c2b79e276c9575996604f3f862bc866cfe44e7))
 * aggregate portfolio data across accounts ([eaf2f67](https://git.personal.ksv741.ru/WealthLedger/backend/commit/eaf2f67b34b2f8b45a9f5d53c544b91304b333d3))
 * **cards:** support inclusive date range queries ([3cf883e](https://git.personal.ksv741.ru/WealthLedger/backend/commit/3cf883efbc6fceddc889c5aadc3c8ffb410c6de5))
 * enrich ledger events with logo metadata ([84fabd2](https://git.personal.ksv741.ru/WealthLedger/backend/commit/84fabd264fa539dfefb1172e27a038870a30d845))
 * establish backend foundation ([ab21426](https://git.personal.ksv741.ru/WealthLedger/backend/commit/ab21426478233b1cdfc7571c796f76d347874501))
 * **events:** support date range filtering ([a79f59a](https://git.personal.ksv741.ru/WealthLedger/backend/commit/a79f59a468dd113147b6f1a04ed0efd9828046c6))
 * expose instrument brand logo name in portfolio positions ([5375e55](https://git.personal.ksv741.ru/WealthLedger/backend/commit/5375e5598a284238b995661dd2c0e9ce5901d190))
 * expose instrument isin in portfolio positions ([5aa9bd3](https://git.personal.ksv741.ru/WealthLedger/backend/commit/5aa9bd395a8e49e423764eb7c4a88afe56332ad4))
 * expose logos and ISINs for upcoming events ([33f703d](https://git.personal.ksv741.ru/WealthLedger/backend/commit/33f703d9a375e3d88e492fbb338e609d6c499d7f))
 * **income:** add account income analytics API ([7ba4da0](https://git.personal.ksv741.ru/WealthLedger/backend/commit/7ba4da0d1b49afcb0db3d1756254e5d5e04f0c35))
 * initial commit ([f8dcfb7](https://git.personal.ksv741.ru/WealthLedger/backend/commit/f8dcfb71c1767696a9aa6741ddaf6575416c901e))
 * **portfolio:** expose asset allocation by currency ([05747dc](https://git.personal.ksv741.ru/WealthLedger/backend/commit/05747dc3757cdfd4c3d840ad0500861063a76b09))
 * **portfolio:** expose position tickers ([924f60f](https://git.personal.ksv741.ru/WealthLedger/backend/commit/924f60f65357781df967bfbaf1538f3400ad620a))
 * **tbank:** add brokerage account summaries ([e489d45](https://git.personal.ksv741.ru/WealthLedger/backend/commit/e489d45f889656183e88ad68d964f721b715cbdb))
 * use money for upcoming event projections ([f1df104](https://git.personal.ksv741.ru/WealthLedger/backend/commit/f1df1044623862770ecb40fd735e1aea08dc2a68))
 ### Bug Fixes
 * align auth success status contract ([9bd3400](https://git.personal.ksv741.ru/WealthLedger/backend/commit/9bd3400264de40a90b45d0cd997c2c752548c0bb))
 * allow multi-year income analytics periods ([9fcc0ec](https://git.personal.ksv741.ru/WealthLedger/backend/commit/9fcc0ec01068372e6756f60bb49d83643e07466d))
 * harden auth and cache concurrency ([c77b3cf](https://git.personal.ksv741.ru/WealthLedger/backend/commit/c77b3cf782f24ad3007add43f768d721e8f02386))
 * harden backend runtime artifact hygiene ([6052565](https://git.personal.ksv741.ru/WealthLedger/backend/commit/60525656b8ecdc4b63956f0d7b77e4286961edc4))
 * **income:** expose authoritative entry membership ([bdc3847](https://git.personal.ksv741.ru/WealthLedger/backend/commit/bdc384766649bb48513055bb809f0d1b45b91f54))
 * isolate dev output from production builds ([320e8a0](https://git.personal.ksv741.ru/WealthLedger/backend/commit/320e8a04b0ad8e0d57a89e07768e600bc16bab36))
 * little fixes ([e77ebc6](https://git.personal.ksv741.ru/WealthLedger/backend/commit/e77ebc6e8f78f96a4ee57c2684769ea4ec923017))
 * make backend local verification safe ([71d57d6](https://git.personal.ksv741.ru/WealthLedger/backend/commit/71d57d60bcf2186d4f8f02169d1bea4ea4d672e3))
 * make SQLite migrations and e2e reproducible ([ce24a84](https://git.personal.ksv741.ru/WealthLedger/backend/commit/ce24a84b7fb48091d2b91836eb7b702a2f811c96))
 * recover portfolio instrument metadata on backend ([8ec172f](https://git.personal.ksv741.ru/WealthLedger/backend/commit/8ec172f48eefa2237dc0c16919fbb2e726b39a65))
 * **tbank:** isolate caches by connection generation ([19fe7e7](https://git.personal.ksv741.ru/WealthLedger/backend/commit/19fe7e75d59792e9c6d6b702ab192fa2d5ccc936))
 * **tbank:** type connectedAt as date-time ([55b100d](https://git.personal.ksv741.ru/WealthLedger/backend/commit/55b100d5f6bed126633432654a3353f862e6f428))
 * type T-Bank client config ([18d7cfc](https://git.personal.ksv741.ru/WealthLedger/backend/commit/18d7cfcf9fecb89e99f7ba1f5d43602807ae98b2))
 ### Documentation
 * **agents:** link audit remediation registry ([595fc04](https://git.personal.ksv741.ru/WealthLedger/backend/commit/595fc0458b3af37ef5eb0c647c401f39f34fe5f0))
 * **ai:** add scoped backend conventions ([a83e26e](https://git.personal.ksv741.ru/WealthLedger/backend/commit/a83e26e5ef5d7cae3179a182fb5359a440538177))
 * define canonical OpenSpec store ([fee4f8c](https://git.personal.ksv741.ru/WealthLedger/backend/commit/fee4f8c8e6e3aa8fc4c41522dc6697825316f8f6))
 * refresh backend onboarding ([fec542a](https://git.personal.ksv741.ru/WealthLedger/backend/commit/fec542a275ed6c8273bb253ca4b58a497f74cd99))
 * remove useless ([da17893](https://git.personal.ksv741.ru/WealthLedger/backend/commit/da178933509512c05c501773947f35397783f249))
 * update routes to system documentation ([b1906c8](https://git.personal.ksv741.ru/WealthLedger/backend/commit/b1906c8e3ca242a0e30bd63519504c0c070f0354))
 * update system documentation references ([d4fc28c](https://git.personal.ksv741.ru/WealthLedger/backend/commit/d4fc28cbbf0bb76a8c11a68f09bbe41151067d88))
 ### Refactoring
 * centralize domain values and enforce numeric lint ([8637ad2](https://git.personal.ksv741.ru/WealthLedger/backend/commit/8637ad2f346c7e03e709b3a52d1d67995415a707))
 * enforce strict backend typing ([346a6f0](https://git.personal.ksv741.ru/WealthLedger/backend/commit/346a6f0057178a2fe157c45ecf93740140c10440))
 * organize backend by business responsibility ([8ba0053](https://git.personal.ksv741.ru/WealthLedger/backend/commit/8ba005346dbbd515e2c1d71bf99fdacf4b73947f))
 * refactor future event list ([e005541](https://git.personal.ksv741.ru/WealthLedger/backend/commit/e0055414d6947e46fb58db1abe96f4ec3ea74f8c))
 * **tbank:** centralize access rules ([130b303](https://git.personal.ksv741.ru/WealthLedger/backend/commit/130b303ec123f144d3833e5c7afa88d40f16f081))
 ### CI
 * verify backend and secure dependency updates [#1](https://git.personal.ksv741.ru/WealthLedger/backend/issues/1) [#5](https://git.personal.ksv741.ru/WealthLedger/backend/issues/5) [#6](https://git.personal.ksv741.ru/WealthLedger/backend/issues/6) ([4c8ba2f](https://git.personal.ksv741.ru/WealthLedger/backend/commit/4c8ba2fac903c883849359aa354f3ffa749ca085))
 ### Tests
 * cover isolated SQLite invariants and durability ([7fde3ec](https://git.personal.ksv741.ru/WealthLedger/backend/commit/7fde3ece6ec7143723140357602861cd2e20b3a5))
 ### Maintenance
 * codify backend local verification ([2772d53](https://git.personal.ksv741.ru/WealthLedger/backend/commit/2772d53647132e6119e411c6d18234db4301e541))
 * configure releases and develop workflow ([f01b82d](https://git.personal.ksv741.ru/WealthLedger/backend/commit/f01b82d36686ac27495263071bc82b34ae2f9b01))
 * **deps:** pin node.js to v24.21.0 ([97e864b](https://git.personal.ksv741.ru/WealthLedger/backend/commit/97e864bc06a58737cae6669d42255f278d93e887))
 * **deps:** update and pin backend dependencies ([2bc8745](https://git.personal.ksv741.ru/WealthLedger/backend/commit/2bc87454954d0bd3eeab11634ed16eed869dbaab))
 * **deps:** upgrade backend to Nest 12 and TypeScript 6 ([121af70](https://git.personal.ksv741.ru/WealthLedger/backend/commit/121af701b722467353a33bf05e0b27a40ed5736e))
 * save pending changes ([8c074d8](https://git.personal.ksv741.ru/WealthLedger/backend/commit/8c074d85de3bc55d0ba750b86bc7b026649fa6bf))
 * simplify backend verification ([fd4572a](https://git.personal.ksv741.ru/WealthLedger/backend/commit/fd4572a64563c588029af38cd7b4cddc3e014cdf))
 * upgrade Node to 24 LTS ([197ffe2](https://git.personal.ksv741.ru/WealthLedger/backend/commit/197ffe21368b337f27d27c22e473570258ebdc3b))
@@ -0,0 +1,41 @@
 FROM node:24.21.0-bookworm-slim AS base
 WORKDIR /app
 FROM base AS dependencies
 # Native SQLite/bcrypt builds happen only here; compilers stay out of runtime.
 RUN apt-get update && apt-get install -y --no-install-recommends python3=3.11.2-1+b1 make=4.3-4.1 g++=4:12.2.0-3 ca-certificates=20250419~deb12u1 openssl=3.0.20-1~deb12u2 && rm -rf /var/lib/apt/lists/*
 COPY package.json package-lock.json ./
 RUN npm ci
 COPY . .
 RUN npx --no-install prisma generate
 FROM dependencies AS development
 # Nest watch uses ps to stop the previous process tree before restarting.
 RUN apt-get update && apt-get install -y --no-install-recommends procps=2:4.0.2-3 && rm -rf /var/lib/apt/lists/*
 RUN mkdir /data && chown node:node /data && chown -R node:node /app
 USER node
 ENV NODE_ENV=development DATABASE_URL=file:/data/wealthledger.db
 EXPOSE 3000
 CMD ["npm", "run", "start:dev"]
 FROM dependencies AS build
 RUN npm run build && npm prune --omit=dev --omit=optional
 FROM base AS production
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates=20250419~deb12u1 openssl=3.0.20-1~deb12u2 && rm -rf /var/lib/apt/lists/* \
    && mkdir /data && chown node:node /data
 ARG VERSION
 ARG REVISION
 LABEL org.opencontainers.image.version=$VERSION \
      org.opencontainers.image.revision=$REVISION
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=build /app/dist ./dist
 COPY --from=build /app/prisma ./prisma
 COPY --from=build /app/prisma.config.ts ./prisma.config.ts
 COPY --from=build /app/package.json /app/package-lock.json ./
 ENV NODE_ENV=production DATABASE_URL=file:/data/wealthledger.db
 USER node
 EXPOSE 3000
 CMD ["node", "dist/src/main.js"]
 HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=6 \
  CMD node -e 'fetch("http://127.0.0.1:3000/api/v1/auth/me").then(async r=>{await r.arrayBuffer();process.exit(r.status===401?0:1)}).catch(()=>process.exit(1))'
@@ -1,17 +1,19 @@
 # WealthLedger backend
 NestJS API WealthLedger. Backend владеет auth, SQLite-данными и server-side
-интеграцией T-Bank; frontend не обращается к T-Bank напрямую.
+интеграциями. Потребители используют публичный HTTP API и OpenAPI artifact;
 их репозитории не нужны для разработки, сборки и проверок backend.
 ## Быстрый старт
-Требуется Node 22 (`.nvmrc`). Создайте `.env` из примера, замените placeholder
+Требуется Node 24 (`.nvmrc`). Создайте `.env` из примера, замените placeholder
 секреты и установите зависимости строго из lockfile:
 ```bash
 cp .env.example .env
 nvm use --silent
 npm ci
 npx prisma migrate deploy
 npm run start:dev
 ```
@@ -20,6 +22,36 @@ npm run start:dev
 T-Bank token в `.env`: он вводится пользователем и хранится в зашифрованном
 виде.
 ## Контейнерный image
 `Dockerfile` имеет targets `development` (Nest watch, generated Prisma client и Linux native modules)
 и `production` (compiled Node process от UID 1000, Prisma CLI/migrations и T-Bank proto assets). Node соответствует `.nvmrc`.
 Build context ограничен `.dockerignore`; `.env`, local DB и host node_modules
 не попадают в image.
 ```bash
 docker build --target development -t wealthledger-backend:development .
 docker build --target production -t wealthledger-backend:production .
 nvm use --silent
 npm run test:container -- wealthledger-backend:production
 ```
 Gitea `image.yml` запускается на защищённом release tag `vX.Y.Z`, проверяет
 package/lock version и canonical gates. Runner `ubuntu-latest` должен иметь
 Docker/buildx. Образы хранятся в Nexus:
 `nexus.personal.ksv741.ru/docker-hosted/wealthledger/backend`. Пользователь `wealthledger-ci`
 задаётся Actions secrets `NEXUS_USERNAME`/`NEXUS_PASSWORD`; эта же учётная
 запись используется сервером для загрузки образов. Docker endpoint и token realm должны использовать
 HTTPS; в `docker-hosted` включается запрет redeploy. Прежние Gitea secrets
 сохраняются на время перехода и не передаются в Nexus.
 Публикуются semver tags, без `latest`; существующие release tags не перезаписываются. Production выбирает опубликованный version tag.
 Compose topology принадлежит workspace, эксплуатационная последовательность —
 [документация](https://git.personal.ksv741.ru/WealthLedger/docs),
 страница `architecture/deployment.md`.
 Проверка публикации требует настроенного registry/runner; локальный build
 не доказывает package permissions.
 ## Проверка
 Единый completion gate не изменяет versioned-файлы:
@@ -29,33 +61,213 @@ npm run verify
 ```
 Он запускает zero-warning lint,
-application/test typechecks, Jest и build. `npm run lint:fix` — отдельная
+application/test typechecks, Jest с покрытием и build. `npm run lint:fix` — отдельная
-записывающая команда, `npm run test:cov` — диагностика без общего числового
+записывающая команда. `npm run test:cov` также доступен отдельно; общего числового
-threshold. `npm run test:e2e` пока не является passing gate: Prisma schema
+threshold нет. `npm run test:e2e` отдельно проверяет все HTTP suites на новых базах
-engine останавливает migration до запуска Jest. Точный статус и trigger
+и соответствие генерируемого OpenAPI настроенному приложению. Для полной backend-проверки
-пересмотра находятся в [remediation registry](../docs/development/audit-remediation.md).
+выполните обе команды.
 Nest 12 поставляется как ESM. Скрипты Jest включают `--experimental-vm-modules`,
 включая watch/coverage/debug; SQLite runner включает тот же флаг. TypeScript 6
 использует явные `rootDir` и типы Node/Jest в `tsconfig.json`. Переход на
 TypeScript 7 требует поддержки со стороны `ts-jest` и `typescript-eslint`.
 ### CI и обновления зависимостей
 `.gitea/workflows/verify.yml` запускает `npm ci`, генерацию Prisma client,
 `npm run verify` и `npm run test:e2e` на push и PR. Используется только checkout
 backend и его зависимости; OpenAPI генерируется во время проверки, SHA записывается в лог.
 Успешный unit gate не заменяет SQLite/e2e; ошибка любой suite завершает job с FAIL.
 `security.yml` сканирует всю Git-историю Gitleaks 8.30.1 с полностью скрытыми
 значениями и выполняет `npm audit --include=dev --audit-level=low` при push,
 PR и ежедневно. `.gitleaksignore` перечисляет только проверенные исторические
 совпадения: детерминированные fixtures, placeholder и badge из Nest starter.
 Новые коммиты этими исключениями не покрываются.
 Renovate группирует minor/patch updates, а major требует согласования в
 Dependency Dashboard. Автоматический merge не включён. Прямые зависимости
 фиксируются точными версиями: `.npmrc` задаёт `save-exact=true` для npm install,
 Renovate использует `rangeStrategy: pin`. Обновляйте `package.json` вместе с
 `package-lock.json`. Overrides в
 `package.json` закрывают advisories транзитивных `multer`, `deepmerge-ts` и
 `mysql2`; удаляйте их, когда родительские пакеты примут исправленные
 версии. Совместимость Prisma override проверяется генерацией и SQLite migrations.
 Required checks настраиваются отдельно в Gitea: наличие workflow само по себе
 не блокирует merge.
 Общий `tsconfig.json` включает `strict: true` и `noFallthroughCasesInSwitch`
 для приложения, тестов и сборок. ESLint запрещает non-null assertions
 (`value!`) и definite-assignment assertions (`field!: Type`).
 Поля DTO, заполняемые вне конструктора, описываются через `declare`:
 входные значения заполняет и проверяет Nest, ответные DTO описывают форму
 возвращаемых объектов. `declare` не создаёт значение и не заменяет
 runtime-валидацию. В обычном коде нужны инициализация или сужение типа
 после проверки значения.
 ## SonarQube
 Проект `wealthledger-backend` на `https://sonarqube.personal.ksv741.ru`
 использует `sonar-project.properties`. Анализируются исходники `src`; unit specs
 и HTTP specs учитываются как тесты. Внешние T-Bank proto contracts исключены,
 generated Prisma client находится за пределами `sonar.sources`.
 `npm run verify` запускает unit tests с покрытием один раз. Jest штатно создаёт
 `coverage/lcov.info`; scanner импортирует этот отчёт. Покрытие HTTP/e2e tests
 в него не входит, сами HTTP suites остаются обязательным отдельным шагом CI.
 Создайте в SonarQube проект с ключом `wealthledger-backend`, а в Gitea → backend →
 Settings → Actions → Secrets добавьте `SONAR_TOKEN` с правом анализа этого проекта.
 Токен не сохраняется в файлах. Community Edition 9.9.8 получает анализ только
 при push в `develop`, после успешных `verify` и SQLite/e2e checks. CI ожидает
 Quality Gate; отрицательный результат или ошибка scanner завершает job с ошибкой.
 PR и другие ветки проходят штатные проверки без отправки анализа.
 Переименование основной ветки SonarQube не требуется; `sonar.branch.name` не задаётся.
 Runner должен поддерживать Docker actions и иметь доступ к GitHub, Docker Hub
 и HTTPS-адресу SonarQube с действующим сертификатом для этого имени.
 Официальный Docker action закреплён на commit версии 2.3.0, как в frontend.
 `tsconfig.sonar.json` содержит совместимые со старым анализатором настройки
 модулей и decorators с target ES2022, без новых compiler options приложения.
 Штатная компиляция приложения остаётся на ES2023.
 После обновления сервера пересмотрите scanner и необходимость отдельного tsconfig.
 Локально после `nvm use --silent`, `npm ci` и генерации Prisma client выполните
 `npm run verify`, затем `sonar-scanner` с совместимым SonarScanner CLI и
 `SONAR_TOKEN` в окружении. Первый запуск CI после merge должен подтвердить
 загрузку отчёта и покрытия: локальные проверки не доказывают доступность сервера.
 ## Документация
- [Router conventions](.ai/CONVENTIONS.md) и [источники](.ai/SOURCES.md)
+- [AGENTS: правила и источники](AGENTS.md)
- [Backend architecture](.ai/conventions/backend-architecture.md)
+- [Backend architecture](.ai/architecture.md)
- [HTTP API](.ai/conventions/backend-http-api.md), [data](.ai/conventions/backend-data.md) и [testing](.ai/conventions/backend-testing.md)
+- [HTTP API](.ai/conventions/http-api.md), [data](.ai/conventions/data.md) и [testing](.ai/conventions/testing.md)
- [Security/auth](.ai/conventions/security-auth.md) и [integrations](.ai/conventions/backend-integrations.md)
+- [Security/auth](.ai/conventions/security-auth.md) и [integrations](.ai/conventions/integrations.md)
- [Границы проверки API и данных](../docs/development/verification.md#api-и-хранение-данных)
+- [Генерация OpenAPI](#генерация-openapi)
 - [Engineering governance и risk-based testing](../docs/development/engineering-governance.md)
 - [Карта проектных фактов](../docs/README.md)
 - [API contract и runtime OpenAPI](../docs/development/runtime-openapi-verification.md)
 - [Обзор поставленной системы](../docs/overview.md)
 - [Архитектурные решения](../docs/adr/README.md)
 - [Remediation registry](../docs/development/audit-remediation.md)
-Из backend runtime OpenAPI можно read-only сверить с frontend snapshot:
+Генерация без сервера сверяется с OpenAPI настроенного приложения:
 ```bash
 npm run test:openapi-contract
 ```
-Разработка идёт напрямую по задаче пользователя. Каждый affected repo проходит
+## Генерация OpenAPI
-свой verify; при изменении wire contract дополнительно выполняется contract check.
+
-Обязательного OpenSpec/SDD lifecycle нет.
+```bash
 nvm use --silent
 npm run openapi:generate
 ```
 Команда собирает backend и записывает `openapi.json` в корень репозитория.
 Сервер и HTTP-порт не запускаются; Nest preview читает metadata без создания
 провайдеров и подключения к БД/T-Bank. Настроенный `.env` и реальные секреты
 не нужны. `openapi.json` исключён из Git и каждый раз создаётся из DTO/Swagger
 metadata; передай полученный artifact потребителю отдельно.
 `npm run test:openapi-contract` собирает backend и сравнивает результат генератора
 с runtime schema настроенного приложения, используя временный каталог и SQLite.
 `npm run test:e2e` также сначала собирает backend. Изменение публичного API
 проверяй relevant HTTP tests: без versioned snapshot сравнение не отслеживает
 breaking changes относительно предыдущего выпуска.
 Разработка идёт напрямую по задаче пользователя; OpenSpec/SDD — по явному запросу.
 ## Реальная SQLite и сохранность данных
 После `nvm use --silent` запускайте `npm run test:sqlite` при изменении auth,
 карточных операций или DB boundary, `npm run test:e2e` — для всех HTTP suites.
 Обе команды используют один runner: отдельный каталог `wealthledger-e2e-*`
 в системном temp на каждую suite, один `DATABASE_URL` для migrations и Jest.
 Внешний `DATABASE_URL` заменяется временным; `.env` и пользовательские данные
 не изменяются. Прямой Jest без runner отклоняется до обращения к базе.
 При ошибке migration/Jest или SIGINT/SIGTERM runner останавливает дочерние
 процессы, удаляет свой каталог и возвращает ненулевой exit code.
 Нужен доступ к локальным HTTP-портам; sandbox может его запрещать.
 `prisma.config.ts` удаляет унаследованный `RUST_LOG` только в процессе Prisma CLI:
 на Prisma 7.9.1 уровни `warn`/`error` вызывают пустой `Schema engine error`
 при fresh migration, без переменной миграция проходит. Постоянный
 `RUST_LOG=info` и обновление зависимостей не нужны. Logging приложения
 настраивается отдельно. История migrations применяется штатным `migrate deploy`.
 Регрессия самого запуска: `node test/sqlite-regression.cjs`. Она выполняет
 три последовательных и два параллельных полных e2e, проверяет уникальность DB,
 сохранность вымышленного внешнего файла, отказ migration и SIGINT/SIGTERM cleanup.
 Логи остаются в каталоге из вывода. Для одной suite:
 `node test/sqlite.cjs app.e2e-spec.ts`.
 | Риск | Проверка реальной DB |
 | --- | --- |
 | Чужой пользователь | `bank-cards.e2e-spec.ts`: owner каждой карты, категории, покупки и стороны перевода |
 | Повтор и конкурентный update | Те же tests: fingerprint, tombstone, версии, один refund в пределах покупки, archive/write |
 | Конкурентный refresh | `app.e2e-spec.ts`: оба запроса читают прежний hash до CAS; один 200, один 401, cookie победителя работает после replay |
 | Rollback и деньги | Карточные tests: откат source lock, атомарный перевод, точные суммы выше 2^53 и границы signed64 |
 | Migration, restart, backup/restore | `test:durability`: прежнее приложение, новая schema, история, откат приложения и восстановление backup |
 Prisma в этих suites не заменяется mocks. В refresh тесте барьер задерживает
 настоящую подпись JWT, чтобы оба запроса дошли до реальной конкурентной записи.
 Unit tests с mocks отдельно проверяют orchestration и не доказывают DB concurrency.
 При изменении schema/migrations или сохранения данных дополнительно выполните
 `npm run test:durability -- /absolute/path/to/baseline`. Он не входит в lint/verify.
 Baseline — отдельная сборка до проверяемых миграций с неизменённым префиксом
 migration history. Для текущей карточной схемы подходит revision
 `8ec172f48eefa2237dc0c16919fbb2e726b39a65` (до добавления карт):
 ```bash
 # Из backend; экспорт не содержит .env или локальную базу.
 baseline_dir=$(mktemp -d /tmp/wealthledger-baseline-XXXXXX)
 git archive 8ec172f48eefa2237dc0c16919fbb2e726b39a65 | tar -x -C "$baseline_dir"
 (
  cd "$baseline_dir"
  nvm use --silent
  npm ci
  npm run build
 )
 nvm use --silent
 npm run build
 npm run test:durability -- "$baseline_dir"
 ```
 Не подменяйте baseline текущей сборкой: runner отвергает тот же путь,
 отсутствующую сборку и неподходящую migration history. Для следующей schema
 выберите совместимую предыдущую revision и проверьте её API-сценарии runner.
 Durability оставляет временные DB, логи и `result.json` по пути из вывода для
 диагностики; он не откатывает schema пользовательской базы.
 ## Релизы
 Репозиторий выпускается независимо. `develop` — интеграция, `main` — принятые
 релизы. Работа: `codex/<task>` от актуального `develop`, PR в `develop`.
 Обычные PR допускают squash; release и обратная синхронизация сохраняют историю.
 Commits и PR titles — Conventional Commits, включая `spec:`. Версии вручную не повышай.
 1. Получи `main`, `develop` и теги: `git fetch origin --tags`. Убедись, что
   `develop` содержит последний релиз. Создай `release/<name>` от проверенного
   `develop`; `nvm use --silent`, `npm ci`. Hotfix начинается от `main` в
   `release/hotfix-<name>` и проходит тот же процесс.
 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 в `main` с заголовком `chore(release): X.Y.Z`. После зелёных
   `verify`, `security`, `commits` выполни fast-forward-only merge. Если `main`
   изменился, согласуй историю и повтори проверки кандидата.
 4. Получи удалённый `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`.
 5. Верни release-коммит через PR `main → develop` без squash/rebase; проверь,
   что `develop` содержит тег. Опубликованные теги не перемещай. При сбое после
   merge создай отсутствующий тег без нового bump; до merge исправь и проверь
   существующий кандидат без повторного повышения версии.
 `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*` защищены.
 Workflow сам не включает эти настройки. Отдельное review approval для одного
 владельца не требуется. Npm publishing, deploy и Gitea Releases не включены.
@@ -0,0 +1,4 @@
 module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: { "type-enum": [2, "always", ["feat", "fix", "perf", "docs", "spec", "refactor", "build", "ci", "test", "style", "chore", "revert"]] },
 };
@@ -26,10 +26,61 @@ export default tseslint.config(
  },
  {
    rules: {
      'no-magic-numbers': 'off',
      '@typescript-eslint/no-magic-numbers': [
        'error',
        {
          ignore: [
            -60,
            -24,
            -10,
            -2,
            -1,
            0,
            1,
            2,
            10,
            24,
            60,
            '-60n',
            '-24n',
            '-10n',
            '-2n',
            '-1n',
            '0n',
            '1n',
            '2n',
            '10n',
            '24n',
            '60n',
          ],
          ignoreArrayIndexes: true,
          ignoreDefaultValues: true,
          ignoreEnums: true,
          ignoreNumericLiteralTypes: true,
          ignoreReadonlyClassProperties: true,
          ignoreTypeIndexes: true,
          enforceConst: true,
        },
      ],
      '@typescript-eslint/no-explicit-any': 'off',
      '@typescript-eslint/no-non-null-assertion': 'error',
      'no-restricted-syntax': [
        'error',
        {
          selector:
            'PropertyDefinition[definite=true], VariableDeclarator[definite=true]',
          message:
            'Definite assignment assertions are forbidden. Initialize owned values; use declare only for externally populated DTO fields.',
        },
      ],
      '@typescript-eslint/no-floating-promises': 'warn',
      '@typescript-eslint/no-unsafe-argument': 'warn',
-      "prettier/prettier": ["error", { endOfLine: "auto" }],
+      'prettier/prettier': ['error', { endOfLine: 'auto' }],
    },
  },
  {
    files: ['**/*.spec.ts', 'test/**/*.ts'],
    rules: { '@typescript-eslint/no-magic-numbers': 'off' },
  },
 );
@@ -5,7 +5,7 @@
  "compilerOptions": {
    "deleteOutDir": true,
    "assets": [
-      { "include": "tbank/proto/contracts/**/*.proto", "watchAssets": true }
+      { "include": "integrations/tbank/proto/contracts/**/*.proto", "watchAssets": true }
    ]
  }
 }
@@ -1,15 +1,16 @@
 {
  "name": "wealth-ledger-backend",
-  "version": "0.0.1",
+  "version": "1.0.0",
  "description": "",
  "author": "",
  "private": true,
  "license": "UNLICENSED",
  "engines": {
-    "node": "22.x"
+    "node": "v24.21.0"
  },
  "scripts": {
    "build": "prisma generate && nest build",
    "openapi:generate": "npm run build && node scripts/generate-openapi.cjs",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "start": "nest start",
    "start:dev": "NODE_ENV=development nest start --watch --path tsconfig.dev.json",
@@ -20,72 +21,89 @@
    "lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
    "typecheck:app": "tsc --project tsconfig.typecheck.app.json",
    "typecheck:test": "tsc --project tsconfig.typecheck.test.json",
-    "test": "jest",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:watch": "jest --watch",
+    "test:watch": "npm test -- --watch",
-    "test:cov": "jest --coverage",
+    "test:cov": "npm test -- --coverage",
-    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:debug": "node --experimental-vm-modules --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
-    "test:e2e": "DATABASE_URL=file:/tmp/wealth-ledger-e2e.db prisma migrate deploy && NODE_ENV=development NODE_OPTIONS=--experimental-vm-modules jest --config ./test/jest-e2e.json",
+    "test:e2e": "npm run build && node test/sqlite.cjs --all",
-    "test:openapi-contract": "NODE_OPTIONS=--experimental-vm-modules jest --config ./test/jest-e2e.json --runInBand openapi-contract.e2e-spec.ts",
+    "test:sqlite": "node test/sqlite.cjs",
-    "verify": "npm run lint && npm run typecheck:app && npm run typecheck:test && npm test -- --runInBand && npm run build"
+    "test:container": "node test/container-smoke.cjs",
    "test:durability": "node test/bank-cards-durability.cjs",
    "test:openapi-contract": "npm run build && node test/sqlite.cjs openapi-contract.e2e-spec.ts",
    "verify": "npm run lint && npm run typecheck:app && npm run typecheck:test && npm run test:cov -- --runInBand && npm run build",
    "release:preview": "release-it --dry-run --ci",
    "release:prepare": "release-it --ci",
    "commitlint": "commitlint"
  },
  "dependencies": {
-    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/grpc-js": "1.14.4",
-    "@grpc/proto-loader": "^0.8.1",
+    "@grpc/proto-loader": "0.8.1",
-    "@nestjs/common": "^11.0.1",
+    "@nestjs/common": "12.0.1",
-    "@nestjs/config": "^4.0.4",
+    "@nestjs/config": "12.0.0",
-    "@nestjs/core": "^11.0.1",
+    "@nestjs/core": "12.0.1",
-    "@nestjs/jwt": "^11.0.2",
+    "@nestjs/jwt": "12.0.1",
-    "@nestjs/passport": "^11.0.5",
+    "@nestjs/passport": "12.0.0",
-    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/platform-express": "12.0.1",
-    "@nestjs/swagger": "11.4.5",
+    "@nestjs/swagger": "12.0.1",
-    "@prisma/adapter-better-sqlite3": "^7.9.1",
+    "@prisma/adapter-better-sqlite3": "7.10.0",
-    "@prisma/client": "^7.9.1",
+    "@prisma/client": "7.10.0",
-    "bcrypt": "^6.0.0",
+    "bcrypt": "6.0.0",
-    "better-sqlite3": "^12.6.0",
+    "better-sqlite3": "13.0.3",
-    "cheerio": "1.1.2",
+    "cheerio": "1.2.0",
-    "class-transformer": "^0.5.1",
+    "class-transformer": "0.5.1",
-    "class-validator": "^0.15.1",
+    "class-validator": "0.15.1",
-    "cookie-parser": "^1.4.7",
+    "cookie-parser": "1.4.7",
-    "lru-cache": "^11.2.4",
+    "lru-cache": "11.5.2",
-    "nestjs-pino": "^4.6.1",
+    "nestjs-pino": "5.1.0",
-    "passport": "^0.7.0",
+    "passport": "0.7.0",
-    "passport-jwt": "^4.0.1",
+    "passport-jwt": "4.0.1",
-    "pino-http": "^11.0.0",
+    "pino-http": "11.0.0",
-    "reflect-metadata": "^0.2.2",
+    "prisma": "7.10.0",
-    "rxjs": "^7.8.1"
+    "reflect-metadata": "0.2.2",
    "rxjs": "7.8.2"
  },
  "devDependencies": {
-    "@eslint/eslintrc": "^3.2.0",
+    "@commitlint/cli": "21.2.2",
-    "@eslint/js": "^9.18.0",
+    "@commitlint/config-conventional": "21.2.2",
-    "@nestjs/cli": "^11.0.0",
+    "@eslint/eslintrc": "3.3.7",
-    "@nestjs/schematics": "^11.0.0",
+    "@eslint/js": "10.0.1",
-    "@nestjs/testing": "^11.0.1",
+    "@nestjs/cli": "12.0.0",
-    "@types/bcrypt": "^6.0.0",
+    "@nestjs/schematics": "12.0.1",
-    "@types/cookie-parser": "^1.4.10",
+    "@nestjs/testing": "12.0.1",
-    "@types/express": "^5.0.0",
+    "@release-it/conventional-changelog": "12.0.0",
-    "@types/jest": "^30.0.0",
+    "@types/bcrypt": "6.0.0",
-    "@types/node": "^22.10.7",
+    "@types/cookie-parser": "1.4.10",
-    "@types/passport-jwt": "^4.0.1",
+    "@types/express": "5.0.6",
-    "@types/supertest": "^6.0.2",
+    "@types/jest": "30.0.0",
-    "eslint": "^9.18.0",
+    "@types/node": "24.13.4",
-    "eslint-config-prettier": "^10.0.1",
+    "@types/passport-jwt": "4.0.1",
-    "eslint-plugin-prettier": "^5.2.2",
+    "@types/supertest": "7.2.1",
-    "globals": "^16.0.0",
+    "conventional-changelog-conventionalcommits": "10.4.0",
-    "jest": "^30.0.0",
+    "eslint": "10.10.0",
-    "prettier": "^3.4.2",
+    "eslint-config-prettier": "10.1.8",
-    "prisma": "^7.9.1",
+    "eslint-plugin-prettier": "5.5.6",
-    "source-map-support": "^0.5.21",
+    "globals": "17.12.0",
-    "supertest": "^7.0.0",
+    "jest": "30.5.1",
-    "ts-jest": "^29.2.5",
+    "prettier": "3.9.6",
-    "ts-loader": "^9.5.2",
+    "release-it": "21.0.2",
-    "ts-node": "^10.9.2",
+    "source-map-support": "0.5.21",
-    "tsconfig-paths": "^4.2.0",
+    "supertest": "7.2.2",
-    "typescript": "^5.7.3",
+    "ts-jest": "29.4.12",
-    "typescript-eslint": "^8.20.0"
+    "ts-loader": "9.6.2",
    "ts-node": "10.9.2",
    "tsconfig-paths": "4.2.0",
    "typescript": "6.0.3",
    "typescript-eslint": "8.70.0"
  },
  "overrides": {
-    "@nestjs/swagger@11.4.5": {
+    "@nestjs/platform-express": {
-      "js-yaml": "5.2.3"
+      "multer": "2.3.0"
    },
    "@prisma/config@7.10.0": {
      "deepmerge-ts": "8.0.2"
    },
    "prisma": {
      "mysql2": "3.24.4"
    }
  },
  "jest": {
@@ -104,5 +122,15 @@
    ],
    "coverageDirectory": "../coverage",
    "testEnvironment": "node"
  },
  "allowScripts": {
    "@prisma/engines@7.10.0": true,
    "prisma@7.10.0": true,
    "bcrypt@6.0.0": true,
    "better-sqlite3@12.11.1": true,
    "fsevents@2.3.3": true,
    "protobufjs@7.6.5": true,
    "unrs-resolver@1.12.2": true,
    "better-sqlite3@13.0.3": true
  }
 }
@@ -1,6 +1,10 @@
 import 'dotenv/config';
 import { defineConfig } from 'prisma/config';
 // Prisma 7.9.1 fresh SQLite migration fails with inherited RUST_LOG=warn/error.
 // Use the engine default; application logging is configured separately.
 delete process.env.RUST_LOG;
 export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
@@ -0,0 +1,239 @@
 PRAGMA foreign_keys=OFF;
 BEGIN IMMEDIATE;
 -- CreateTable
 CREATE TABLE "TbankAccount" (
    "userId" TEXT NOT NULL,
    "revision" TEXT NOT NULL,
    "accountId" TEXT NOT NULL,
    "type" TEXT NOT NULL,
    "name" TEXT NOT NULL,
    "openedOn" TEXT,
    "upstreamOrder" INTEGER NOT NULL,
    "operationsRevision" INTEGER NOT NULL DEFAULT 0,
    "historyFrom" DATETIME,
    "historyBoundary" TEXT NOT NULL DEFAULT 'unknown',
    PRIMARY KEY ("userId", "revision", "accountId"),
    CONSTRAINT "TbankAccount_userId_revision_fkey" FOREIGN KEY ("userId", "revision") REFERENCES "TbankConnection" ("userId", "revision") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- CreateTable
 CREATE TABLE "TbankPortfolio" (
    "userId" TEXT NOT NULL,
    "revision" TEXT NOT NULL,
    "accountId" TEXT NOT NULL,
    "payload" JSONB NOT NULL,
    "mappingVersion" INTEGER NOT NULL DEFAULT 1,
    "fetchedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("userId", "revision", "accountId"),
    CONSTRAINT "TbankPortfolio_userId_revision_accountId_fkey" FOREIGN KEY ("userId", "revision", "accountId") REFERENCES "TbankAccount" ("userId", "revision", "accountId") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- CreateTable
 CREATE TABLE "TbankOperation" (
    "userId" TEXT NOT NULL,
    "revision" TEXT NOT NULL,
    "accountId" TEXT NOT NULL,
    "brokerOperationId" TEXT NOT NULL,
    "occurredAt" DATETIME NOT NULL,
    "instrumentUid" TEXT,
    "category" TEXT NOT NULL,
    "payload" JSONB NOT NULL,
    "mappingVersion" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("userId", "revision", "accountId", "brokerOperationId"),
    CONSTRAINT "TbankOperation_userId_revision_accountId_fkey" FOREIGN KEY ("userId", "revision", "accountId") REFERENCES "TbankAccount" ("userId", "revision", "accountId") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- CreateTable
 CREATE TABLE "TbankOperationCoverage" (
    "userId" TEXT NOT NULL,
    "revision" TEXT NOT NULL,
    "accountId" TEXT NOT NULL,
    "instrumentPredicate" TEXT NOT NULL DEFAULT '',
    "from" DATETIME NOT NULL,
    "to" DATETIME NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    "asOf" DATETIME NOT NULL,
    PRIMARY KEY ("userId", "revision", "accountId", "instrumentPredicate", "from", "to"),
    CONSTRAINT "TbankOperationCoverage_userId_revision_accountId_fkey" FOREIGN KEY ("userId", "revision", "accountId") REFERENCES "TbankAccount" ("userId", "revision", "accountId") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- CreateTable
 CREATE TABLE "TbankForecast" (
    "userId" TEXT NOT NULL,
    "revision" TEXT NOT NULL,
    "scopeKey" TEXT NOT NULL,
    "membershipRevision" INTEGER NOT NULL,
    "payload" JSONB NOT NULL,
    "dependencyRevisions" JSONB NOT NULL,
    "sourceTimestamps" JSONB NOT NULL,
    "calculatedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("userId", "revision", "scopeKey"),
    CONSTRAINT "TbankForecast_userId_revision_fkey" FOREIGN KEY ("userId", "revision") REFERENCES "TbankConnection" ("userId", "revision") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- CreateTable
 CREATE TABLE "TbankInstrument" (
    "provider" TEXT NOT NULL,
    "uid" TEXT NOT NULL,
    "figi" TEXT,
    "ticker" TEXT,
    "instrumentType" TEXT NOT NULL,
    "metadata" JSONB NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("provider", "uid")
 );
 -- CreateTable
 CREATE TABLE "TbankCatalogDiscovery" (
    "provider" TEXT NOT NULL,
    "instrumentType" TEXT NOT NULL,
    "query" TEXT NOT NULL,
    "instrumentUids" JSONB NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("provider", "instrumentType", "query")
 );
 -- CreateTable
 CREATE TABLE "TbankInstrumentLookup" (
    "provider" TEXT NOT NULL,
    "identifierType" TEXT NOT NULL,
    "identifier" TEXT NOT NULL,
    "matchedUids" JSONB NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("provider", "identifierType", "identifier")
 );
 -- CreateTable
 CREATE TABLE "TbankInstrumentSource" (
    "provider" TEXT NOT NULL,
    "instrumentUid" TEXT NOT NULL,
    "source" TEXT NOT NULL,
    "kind" TEXT NOT NULL,
    "rangeKey" TEXT NOT NULL,
    "payload" JSONB NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("provider", "instrumentUid", "source", "kind", "rangeKey"),
    CONSTRAINT "TbankInstrumentSource_provider_instrumentUid_fkey" FOREIGN KEY ("provider", "instrumentUid") REFERENCES "TbankInstrument" ("provider", "uid") ON DELETE CASCADE ON UPDATE CASCADE
 );
 -- CreateTable
 CREATE TABLE "TbankCandle" (
    "provider" TEXT NOT NULL,
    "instrumentUid" TEXT NOT NULL,
    "interval" TEXT NOT NULL,
    "time" DATETIME NOT NULL,
    "close" TEXT NOT NULL,
    "payload" JSONB NOT NULL,
    "isComplete" BOOLEAN NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    PRIMARY KEY ("provider", "instrumentUid", "interval", "time"),
    CONSTRAINT "TbankCandle_provider_instrumentUid_fkey" FOREIGN KEY ("provider", "instrumentUid") REFERENCES "TbankInstrument" ("provider", "uid") ON DELETE CASCADE ON UPDATE CASCADE
 );
 -- CreateTable
 CREATE TABLE "TbankCandleCoverage" (
    "provider" TEXT NOT NULL,
    "instrumentUid" TEXT NOT NULL,
    "interval" TEXT NOT NULL,
    "from" DATETIME NOT NULL,
    "to" DATETIME NOT NULL,
    "isComplete" BOOLEAN NOT NULL,
    "fetchedAt" DATETIME NOT NULL,
    "dataRevision" INTEGER NOT NULL DEFAULT 1,
    PRIMARY KEY ("provider", "instrumentUid", "interval", "from", "to"),
    CONSTRAINT "TbankCandleCoverage_provider_instrumentUid_fkey" FOREIGN KEY ("provider", "instrumentUid") REFERENCES "TbankInstrument" ("provider", "uid") ON DELETE CASCADE ON UPDATE CASCADE
 );
 -- CreateTable
 CREATE TABLE "TbankSyncWork" (
    "id" TEXT NOT NULL PRIMARY KEY,
    "userId" TEXT NOT NULL,
    "revision" TEXT NOT NULL,
    "scopeKey" TEXT NOT NULL,
    "intent" JSONB NOT NULL,
    "state" TEXT NOT NULL,
    "attemptId" TEXT NOT NULL,
    "processRunId" TEXT NOT NULL,
    "priority" INTEGER NOT NULL,
    "progress" JSONB NOT NULL,
    "errorCode" TEXT,
    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" DATETIME NOT NULL,
    CONSTRAINT "TbankSyncWork_userId_revision_fkey" FOREIGN KEY ("userId", "revision") REFERENCES "TbankConnection" ("userId", "revision") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- CreateTable
 CREATE TABLE "TbankSyncStage" (
    "workId" TEXT NOT NULL,
    "attemptId" TEXT NOT NULL,
    "sourceKey" TEXT NOT NULL,
    "itemKey" TEXT NOT NULL,
    "payload" JSONB NOT NULL,
    PRIMARY KEY ("workId", "attemptId", "sourceKey", "itemKey"),
    CONSTRAINT "TbankSyncStage_workId_attemptId_fkey" FOREIGN KEY ("workId", "attemptId") REFERENCES "TbankSyncWork" ("id", "attemptId") ON DELETE CASCADE ON UPDATE RESTRICT
 );
 -- RedefineTables
 CREATE TABLE "new_TbankConnection" (
    "userId" TEXT NOT NULL,
    "encryptedToken" TEXT NOT NULL,
    "connectedAt" DATETIME NOT NULL,
    "revision" TEXT NOT NULL,
    "invalidToken" BOOLEAN NOT NULL DEFAULT false,
    "membershipAt" DATETIME,
    "membershipRevision" INTEGER NOT NULL DEFAULT 0,
    CONSTRAINT "TbankConnection_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE CASCADE ON UPDATE CASCADE
 );
 -- Preserve credentials and assign an opaque revision to each existing connection.
 INSERT INTO "new_TbankConnection" ("connectedAt", "encryptedToken", "userId", "revision") SELECT "connectedAt", "encryptedToken", "userId", lower(hex(randomblob(16))) FROM "TbankConnection";
 DROP TABLE "TbankConnection";
 ALTER TABLE "new_TbankConnection" RENAME TO "TbankConnection";
 CREATE UNIQUE INDEX "TbankConnection_userId_key" ON "TbankConnection"("userId");
 CREATE UNIQUE INDEX "TbankConnection_userId_revision_key" ON "TbankConnection"("userId", "revision");
 -- CreateIndex
 CREATE INDEX "TbankOperation_userId_revision_accountId_occurredAt_brokerOperationId_idx" ON "TbankOperation"("userId", "revision", "accountId", "occurredAt", "brokerOperationId");
 -- CreateIndex
 CREATE INDEX "TbankOperation_userId_revision_accountId_instrumentUid_occurredAt_idx" ON "TbankOperation"("userId", "revision", "accountId", "instrumentUid", "occurredAt");
 -- CreateIndex
 CREATE INDEX "TbankOperation_userId_revision_accountId_category_occurredAt_idx" ON "TbankOperation"("userId", "revision", "accountId", "category", "occurredAt");
 -- CreateIndex
 CREATE INDEX "TbankInstrument_provider_figi_idx" ON "TbankInstrument"("provider", "figi");
 -- CreateIndex
 CREATE INDEX "TbankInstrument_provider_ticker_instrumentType_idx" ON "TbankInstrument"("provider", "ticker", "instrumentType");
 -- CreateIndex
 CREATE INDEX "TbankSyncWork_userId_revision_state_priority_idx" ON "TbankSyncWork"("userId", "revision", "state", "priority");
 -- CreateIndex
 CREATE UNIQUE INDEX "TbankSyncWork_userId_revision_scopeKey_key" ON "TbankSyncWork"("userId", "revision", "scopeKey");
 -- CreateIndex
 CREATE UNIQUE INDEX "TbankSyncWork_id_attemptId_key" ON "TbankSyncWork"("id", "attemptId");
 COMMIT;
 PRAGMA foreign_keys=ON;
@@ -25,7 +25,212 @@ model TbankConnection {
  userId         String   @unique
  encryptedToken String
  connectedAt    DateTime
  revision       String   @default(uuid())
  invalidToken   Boolean  @default(false)
  membershipAt   DateTime?
  membershipRevision Int @default(0)
  user           User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  accounts       TbankAccount[]
  forecasts      TbankForecast[]
  work           TbankSyncWork[]
  @@unique([userId, revision])
 }
 model TbankAccount {
  userId String
  revision String
  accountId String
  type String
  name String
  openedOn String?
  upstreamOrder Int
  operationsRevision Int @default(0)
  historyFrom DateTime?
  historyBoundary String @default("unknown")
  connection TbankConnection @relation(fields: [userId, revision], references: [userId, revision], onDelete: Cascade, onUpdate: Restrict)
  portfolio TbankPortfolio?
  operations TbankOperation[]
  coverage TbankOperationCoverage[]
  @@id([userId, revision, accountId])
 }
 model TbankPortfolio {
  userId String
  revision String
  accountId String
  payload Json
  mappingVersion Int @default(1)
  fetchedAt DateTime
  dataRevision Int @default(1)
  account TbankAccount @relation(fields: [userId, revision, accountId], references: [userId, revision, accountId], onDelete: Cascade, onUpdate: Restrict)
  @@id([userId, revision, accountId])
 }
 model TbankOperation {
  userId String
  revision String
  accountId String
  brokerOperationId String
  occurredAt DateTime
  instrumentUid String?
  category String
  payload Json
  mappingVersion Int @default(1)
  account TbankAccount @relation(fields: [userId, revision, accountId], references: [userId, revision, accountId], onDelete: Cascade, onUpdate: Restrict)
  @@id([userId, revision, accountId, brokerOperationId])
  @@index([userId, revision, accountId, occurredAt, brokerOperationId])
  @@index([userId, revision, accountId, instrumentUid, occurredAt])
  @@index([userId, revision, accountId, category, occurredAt])
 }
 model TbankOperationCoverage {
  userId String
  revision String
  accountId String
  instrumentPredicate String @default("")
  from DateTime
  to DateTime
  fetchedAt DateTime
  asOf DateTime
  account TbankAccount @relation(fields: [userId, revision, accountId], references: [userId, revision, accountId], onDelete: Cascade, onUpdate: Restrict)
  @@id([userId, revision, accountId, instrumentPredicate, from, to])
 }
 model TbankForecast {
  userId String
  revision String
  scopeKey String
  membershipRevision Int
  payload Json
  dependencyRevisions Json
  sourceTimestamps Json
  calculatedAt DateTime
  dataRevision Int @default(1)
  connection TbankConnection @relation(fields: [userId, revision], references: [userId, revision], onDelete: Cascade, onUpdate: Restrict)
  @@id([userId, revision, scopeKey])
 }
 model TbankInstrument {
  provider String
  uid String
  figi String?
  ticker String?
  instrumentType String
  metadata Json
  fetchedAt DateTime
  dataRevision Int @default(1)
  sources TbankInstrumentSource[]
  candles TbankCandle[]
  candleCoverage TbankCandleCoverage[]
  @@id([provider, uid])
  @@index([provider, figi])
  @@index([provider, ticker, instrumentType])
 }
 model TbankCatalogDiscovery {
  provider String
  instrumentType String
  query String
  instrumentUids Json
  fetchedAt DateTime
  dataRevision Int @default(1)
  @@id([provider, instrumentType, query])
 }
 // Empty and ambiguous successful UID/FIGI/ticker lookups are distinct from failures.
 model TbankInstrumentLookup {
  provider String
  identifierType String
  identifier String
  matchedUids Json
  fetchedAt DateTime
  dataRevision Int @default(1)
  @@id([provider, identifierType, identifier])
 }
 // Source records contain no holdings, personal estimates or credentials errors.
 model TbankInstrumentSource {
  provider String
  instrumentUid String
  source String
  kind String
  rangeKey String
  payload Json
  fetchedAt DateTime
  dataRevision Int @default(1)
  instrument TbankInstrument @relation(fields: [provider, instrumentUid], references: [provider, uid], onDelete: Cascade)
  @@id([provider, instrumentUid, source, kind, rangeKey])
 }
 model TbankCandle {
  provider String
  instrumentUid String
  interval String
  time DateTime
  close String
  payload Json
  isComplete Boolean
  fetchedAt DateTime
  instrument TbankInstrument @relation(fields: [provider, instrumentUid], references: [provider, uid], onDelete: Cascade)
  @@id([provider, instrumentUid, interval, time])
 }
 model TbankCandleCoverage {
  provider String
  instrumentUid String
  interval String
  from DateTime
  to DateTime
  isComplete Boolean
  fetchedAt DateTime
  dataRevision Int @default(1)
  instrument TbankInstrument @relation(fields: [provider, instrumentUid], references: [provider, uid], onDelete: Cascade)
  @@id([provider, instrumentUid, interval, from, to])
 }
 model TbankSyncWork {
  id String @id
  userId String
  revision String
  scopeKey String
  intent Json
  state String
  attemptId String
  processRunId String
  priority Int
  progress Json
  errorCode String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  connection TbankConnection @relation(fields: [userId, revision], references: [userId, revision], onDelete: Cascade, onUpdate: Restrict)
  staged TbankSyncStage[]
  @@unique([userId, revision, scopeKey])
  @@index([userId, revision, state, priority])
  @@unique([id, attemptId])
 }
 model TbankSyncStage {
  workId String
  attemptId String
  sourceKey String
  itemKey String
  payload Json
  work TbankSyncWork @relation(fields: [workId, attemptId], references: [id, attemptId], onDelete: Cascade, onUpdate: Restrict)
  @@id([workId, attemptId, sourceKey, itemKey])
 }
 model Session {
@@ -0,0 +1,31 @@
 {
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommitTypeAll(chore)"
  ],
  "timezone": "Europe/Moscow",
  "labels": [
    "dependencies"
  ],
  "dependencyDashboard": true,
  "rangeStrategy": "pin",
  "packageRules": [
    {
      "matchUpdateTypes": [
        "minor",
        "patch"
      ],
      "groupName": "non-major dependencies"
    },
    {
      "matchUpdateTypes": [
        "major"
      ],
      "dependencyDashboardApproval": true
    }
  ],
  "baseBranchPatterns": [
    "develop"
  ]
 }
@@ -0,0 +1,10 @@
 const assert = require("node:assert/strict");
 const { execFileSync } = require("node:child_process");
 const { version } = require("../package.json");
 const git = (...args) => execFileSync("git", args, { encoding: "utf8" }).trim();
 assert.equal(git("status", "--porcelain"), "", "Commit all changes before preparing a release");
 const tags = git("tag", "--merged", "HEAD", "--list", "v[0-9]*", "--sort=-version:refname")
  .split("\n").filter(tag => /^v\d+\.\d+\.\d+$/.test(tag));
 assert.equal(version, tags[0]?.slice(1) ?? "0.0.0",
  "Version is already prepared or release tags are missing. Fetch tags; finish the existing release before preparing another.");
@@ -0,0 +1,40 @@
 const { randomBytes } = require('node:crypto');
 const { writeFile } = require('node:fs/promises');
 // Schema generation needs no deployment configuration or real credentials.
 Object.assign(process.env, {
  DATABASE_URL: 'file::memory:',
  FRONTEND_ORIGIN: 'http://localhost',
  JWT_SECRET: randomBytes(32).toString('hex'),
  TOKEN_ENCRYPTION_KEY: randomBytes(32).toString('base64'),
  PORT: '3000',
  LOG_LEVEL: 'error',
  TBANK_GRPC_ENDPOINT: 'localhost:443',
  TBANK_RATE_LIMIT_PER_SECOND: '5',
  TBANK_CA_CERT_PATH: '',
 });
 const { NestFactory } = require('@nestjs/core');
 const { AppModule } = require('../dist/src/app.module.js');
 const { API_PREFIX, createOpenApiDocument } = require('../dist/src/openapi.js');
 async function generate() {
  const app = await NestFactory.create(AppModule, {
    preview: true,
    logger: false,
  });
  try {
    app.setGlobalPrefix(API_PREFIX);
    await writeFile(
      'openapi.json',
      JSON.stringify(createOpenApiDocument(app), null, 2) + '\n',
    );
  } finally {
    await app.close();
  }
 }
 generate().catch((error) => {
  console.error(error);
  process.exitCode = 1;
 });
@@ -0,0 +1,12 @@
 sonar.projectKey=wealthledger-backend
 sonar.projectName=WealthLedger backend
 sonar.host.url=https://sonarqube.personal.ksv741.ru
 sonar.sourceEncoding=UTF-8
 sonar.sources=src
 sonar.tests=src,test
 sonar.test.inclusions=src/**/*.spec.ts,test/**/*.e2e-spec.ts
 sonar.exclusions=src/**/*.spec.ts,src/integrations/tbank/proto/contracts/**
 sonar.javascript.lcov.reportPaths=coverage/lcov.info
 # SonarQube 9.9 embeds an older TypeScript analyzer than the application compiler.
 sonar.typescript.tsconfigPaths=tsconfig.sonar.json
@@ -1,13 +1,20 @@
 import { TbankSyncModule } from './modules/investments/tbank-sync/tbank-sync.module';
 import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { randomUUID } from 'node:crypto';
 import { LoggerModule } from 'nestjs-pino';
-import { BankCardsModule } from './bank-cards/bank-cards.module';
+import { randomUUID } from 'node:crypto';
 import { AuthModule } from './auth/auth.module';
 import { LoggingModule } from './common/logging/logging.module';
 import { Environment, validateEnv } from './config/env.validation';
 import { AuthModule } from './modules/auth/auth.module';
 import { BankCardsModule } from './modules/banking/bank-cards/bank-cards.module';
 import { BrokerageAccountsModule } from './modules/investments/brokerage-accounts/brokerage-accounts.module';
 import { IncomeModule } from './modules/investments/income/income.module';
 import { InstrumentsModule } from './modules/investments/instruments/instruments.module';
 import { OperationsModule } from './modules/investments/operations/operations.module';
 import { PortfolioModule } from './modules/investments/portfolio/portfolio.module';
 import { TbankConnectionModule } from './modules/investments/tbank-connection/tbank-connection.module';
 import { UpcomingEventsModule } from './modules/investments/upcoming-events/upcoming-events.module';
 import { PrismaModule } from './prisma/prisma.module';
 import { TbankConnectionModule } from './tbank/tbank-connection.module';
@Module({
  imports: [
@@ -51,7 +58,14 @@ import { TbankConnectionModule } from './tbank/tbank-connection.module';
    PrismaModule,
    AuthModule,
    BankCardsModule,
    BrokerageAccountsModule,
    PortfolioModule,
    OperationsModule,
    IncomeModule,
    UpcomingEventsModule,
    InstrumentsModule,
    TbankConnectionModule,
    TbankSyncModule,
  ],
 })
 export class AppModule {}
@@ -1,5 +0,0 @@
 import { Module } from '@nestjs/common';
 import { BankCardsController } from './bank-cards.controller';
 import { BankCardsService } from './bank-cards.service';
@Module({ controllers: [BankCardsController], providers: [BankCardsService] })
 export class BankCardsModule {}
@@ -1,708 +0,0 @@
 import {
  BadRequestException,
  ConflictException,
  GoneException,
  Injectable,
  NotFoundException,
 } from '@nestjs/common';
 import { createHash, randomUUID } from 'node:crypto';
 import {
  Prisma,
  BankCard,
  BankCardOperation,
 } from '../../generated/prisma/client';
 import { PrismaService } from '../prisma/prisma.service';
 import { parseRubMoney, rubMoney } from '../common/rub-money';
 import {
  bankBalance,
  bankSummary,
  isCalendarDate,
  moscowToday,
 } from './bank-card.calculations';
 import {
  bankPaymentSystems,
  BankCardDto,
  BankOperationDto,
  BankOperationsQueryDto,
  BankPageQueryDto,
  BankPeriodQueryDto,
  BankSummaryQueryDto,
  CreateBankCardDto,
  CreateBankOperationDto,
  UpdateBankCardDto,
  UpdateBankOperationDto,
 } from './bank-card.dto';
 type Tx = Prisma.TransactionClient;
 const seeds = [
  'Продукты',
  'Кафе',
  'Такси',
  'Транспорт',
  'Жильё',
  'Здоровье',
  'Покупки',
  'Развлечения',
  'Другое',
 ];
 const fail = (code = 'BANK_INVALID_INPUT'): never => {
  throw new BadRequestException({ code });
 };
 function periodBounds(query: BankPeriodQueryDto) {
  if (query.month && !query.from && !query.to) {
    const from = `${query.month}-01`;
    if (!isCalendarDate(from)) return fail();
    const end = new Date(`${from}T00:00:00Z`);
    end.setUTCMonth(end.getUTCMonth() + 1, 0);
    return { from, to: end.toISOString().slice(0, 10) };
  }
  if (
    query.month ||
    !query.from ||
    !query.to ||
    !isCalendarDate(query.from) ||
    !isCalendarDate(query.to) ||
    query.from > query.to
  )
    return fail();
  return { from: query.from, to: query.to };
 }
 const conflict = (code = 'BANK_VERSION_CONFLICT'): never => {
  throw new ConflictException({ code });
 };
 const missing = (): never => {
  throw new NotFoundException({ code: 'BANK_NOT_FOUND' });
 };
 const fingerprint = (value: unknown) =>
  createHash('sha256')
    .update(
      JSON.stringify(value, (_key, item: unknown) =>
        typeof item === 'bigint' ? item.toString() : item,
      ),
    )
    .digest('hex');
 function amount(value: Parameters<typeof parseRubMoney>[0], positive = false) {
  try {
    return parseRubMoney(value, positive);
  } catch {
    return fail('BANK_INVALID_MONEY');
  }
 }
 function calendar(value: string) {
  if (!isCalendarDate(value)) fail('BANK_INVALID_DATE');
  return value;
 }
 function currentDate(value: string) {
  calendar(value);
  if (value > moscowToday()) fail('BANK_INVALID_DATE');
 }
 function name(value: string, max: number) {
  if (typeof value !== 'string' || !value.trim() || value.trim().length > max)
    fail();
  return value.trim();
 }
 function cardInput(dto: CreateBankCardDto) {
  const bankName = dto.bankName?.trim() || null;
  if (bankName && bankName.length > 100) fail();
  if (dto.lastFour != null && !/^\d{4}$/.test(dto.lastFour)) fail();
  if (
    dto.paymentSystem != null &&
    !bankPaymentSystems.some((system) => system === dto.paymentSystem)
  )
    fail();
  return {
    ...(dto.paymentSystem == null ? {} : { paymentSystem: dto.paymentSystem }),
    name: name(dto.name, 100),
    bankName,
    lastFour: dto.lastFour || null,
    openingBalanceKopecks: amount(dto.openingBalance),
    openingDate: calendar(dto.openingDate),
  };
 }
 function operationInput(dto: CreateBankOperationDto) {
  if (
    dto.description != null &&
    (typeof dto.description !== 'string' || dto.description.length > 500)
  )
    fail();
  return {
    kind: dto.kind,
    cardId: dto.cardId,
    targetCardId: dto.targetCardId ?? null,
    categoryId: dto.categoryId ?? null,
    originalExpenseId: dto.originalExpenseId ?? null,
    amountKopecks: amount(dto.amount, true),
    date: calendar(dto.date),
    description: dto.description || null,
  };
 }
@Injectable()
 export class BankCardsService {
  constructor(private readonly prisma: PrismaService) {}
  private async write<T>(run: (tx: Tx) => Promise<T>): Promise<T> {
    for (let attempt = 0; ; attempt++) {
      try {
        return await this.prisma.$transaction(run, {
          maxWait: 10000,
          timeout: 15000,
        });
      } catch (error) {
        const code =
          error instanceof Prisma.PrismaClientKnownRequestError
            ? error.code
            : '';
        const busy =
          code === 'P2034' ||
          code === 'P2028' ||
          (error instanceof Error &&
            /SQLITE_BUSY|database is locked/.test(error.message));
        if ((busy || code === 'P2002') && attempt < 2) continue;
        if (busy) conflict('BANK_WRITE_CONFLICT');
        if (code === 'P2002') conflict('BANK_DUPLICATE_CATEGORY');
        throw error;
      }
    }
  }
  private async card(tx: Tx, userId: string, id: string, active = false) {
    const card = await tx.bankCard.findFirst({ where: { id, userId } });
    if (!card) return missing();
    if (active && card.archivedAt) conflict('BANK_CARD_ARCHIVED');
    return card;
  }
  private async operation(tx: Tx, userId: string, id: string) {
    const row = await tx.bankCardOperation.findFirst({ where: { id, userId } });
    if (!row) return missing();
    return row;
  }
  private async seed(tx: Tx, userId: string) {
    for (const [index, label] of seeds.entries()) {
      const seedKey = index === 8 ? 'other' : String(index);
      if (
        !(await tx.expenseCategory.findUnique({
          where: { userId_seedKey: { userId, seedKey } },
        }))
      )
        await tx.expenseCategory.create({
          data: {
            id: randomUUID(),
            userId,
            seedKey,
            name: label,
            nameKey: label.toLocaleLowerCase('ru-RU'),
          },
        });
    }
  }
  private async cardView(tx: Tx, card: BankCard): Promise<BankCardDto> {
    const rows = await tx.bankCardOperation.findMany({
      where: {
        userId: card.userId,
        deletedAt: null,
        OR: [{ cardId: card.id }, { targetCardId: card.id }],
      },
    });
    return {
      id: card.id,
      name: card.name,
      bankName: card.bankName,
      lastFour: card.lastFour,
      paymentSystem: card.paymentSystem,
      openingDate: card.openingDate,
      openingBalance: rubMoney(card.openingBalanceKopecks),
      balance: rubMoney(bankBalance(card.id, card.openingBalanceKopecks, rows)),
      version: card.version,
      archivedAt: card.archivedAt?.toISOString() ?? null,
    };
  }
  private async operationView(
    tx: Tx,
    row: BankCardOperation,
  ): Promise<BankOperationDto> {
    const card = await this.card(tx, row.userId, row.cardId);
    const target = row.targetCardId
      ? await this.card(tx, row.userId, row.targetCardId)
      : null;
    const source = row.originalExpenseId
      ? await this.operation(tx, row.userId, row.originalExpenseId)
      : null;
    const categoryId = source?.categoryId ?? row.categoryId;
    const category = categoryId
      ? await tx.expenseCategory.findFirst({
          where: { id: categoryId, userId: row.userId },
        })
      : null;
    const refunds =
      row.kind === 'expense' || source
        ? await tx.bankCardOperation.findMany({
            where: {
              userId: row.userId,
              originalExpenseId: source?.id ?? row.id,
              deletedAt: null,
              ...(source ? { id: { not: row.id } } : {}),
            },
          })
        : [];
    return {
      id: row.id,
      kind: row.kind as BankOperationDto['kind'],
      cardId: row.cardId,
      cardName: card.name,
      targetCardId: row.targetCardId,
      targetCardName: target?.name ?? null,
      categoryId,
      categoryName: category?.name ?? null,
      originalExpenseId: row.originalExpenseId,
      amount: rubMoney(row.amountKopecks),
      availableRefund:
        row.kind === 'expense' || source
          ? rubMoney(
              (source?.amountKopecks ?? row.amountKopecks) -
                refunds.reduce((sum, r) => sum + r.amountKopecks, 0n),
            )
          : null,
      date: row.date,
      description: row.description,
      version: row.version,
      createdAt: row.createdAt.toISOString(),
    };
  }
  list(userId: string, includeArchived = false) {
    return this.prisma.$transaction(async (tx) =>
      Promise.all(
        (
          await tx.bankCard.findMany({
            where: { userId, ...(includeArchived ? {} : { archivedAt: null }) },
            orderBy: [{ createdAt: 'asc' }, { id: 'asc' }],
          })
        ).map((card) => this.cardView(tx, card)),
      ),
    );
  }
  get(userId: string, id: string) {
    return this.prisma.$transaction(async (tx) =>
      this.cardView(tx, await this.card(tx, userId, id)),
    );
  }
  createCard(userId: string, dto: CreateBankCardDto) {
    const input = cardInput(dto),
      hash = fingerprint(input);
    return this.write(async (tx) => {
      const existing = await tx.bankCard.findUnique({ where: { id: dto.id } });
      if (existing) {
        if (existing.userId !== userId) missing();
        if (existing.createFingerprint !== hash)
          conflict('BANK_INTENT_CONFLICT');
        return this.cardView(tx, existing);
      }
      currentDate(input.openingDate);
      await this.seed(tx, userId);
      return this.cardView(
        tx,
        await tx.bankCard.create({
          data: { ...input, id: dto.id, userId, createFingerprint: hash },
        }),
      );
    });
  }
  updateCard(userId: string, id: string, dto: UpdateBankCardDto) {
    return this.write(async (tx) => {
      const previous = await this.card(tx, userId, id);
      if (previous.version !== dto.version) conflict();
      const input = cardInput({
        id,
        name: dto.name ?? previous.name,
        bankName:
          dto.bankName === undefined
            ? (previous.bankName ?? undefined)
            : (dto.bankName ?? undefined),
        lastFour:
          dto.lastFour === undefined
            ? (previous.lastFour ?? undefined)
            : (dto.lastFour ?? undefined),
        paymentSystem:
          dto.paymentSystem === undefined
            ? previous.paymentSystem
            : dto.paymentSystem,
        openingBalance:
          dto.openingBalance ?? rubMoney(previous.openingBalanceKopecks),
        openingDate: dto.openingDate ?? previous.openingDate,
      });
      const financial =
        input.openingBalanceKopecks !== previous.openingBalanceKopecks ||
        input.openingDate !== previous.openingDate;
      if (financial && previous.archivedAt) conflict('BANK_CARD_ARCHIVED');
      currentDate(input.openingDate);
      if (
        await tx.bankCardOperation.findFirst({
          where: {
            userId,
            deletedAt: null,
            date: { lt: input.openingDate },
            OR: [{ cardId: id }, { targetCardId: id }],
          },
        })
      )
        fail('BANK_OPENING_DATE_CONFLICT');
      const changed = await tx.bankCard.updateMany({
        where: { id, userId, version: dto.version },
        data: {
          ...input,
          paymentSystem: input.paymentSystem ?? null,
          version: { increment: 1 },
          ...(dto.archived === undefined
            ? {}
            : {
                archivedAt: dto.archived
                  ? (previous.archivedAt ?? new Date())
                  : null,
              }),
        },
      });
      if (changed.count !== 1) conflict();
      return this.cardView(tx, await this.card(tx, userId, id));
    });
  }
  async categories(userId: string) {
    return (
      await this.prisma.expenseCategory.findMany({
        where: { userId },
        orderBy: [{ name: 'asc' }, { id: 'asc' }],
      })
    ).map(({ id, name, seedKey, version }) => ({
      id,
      name,
      isDefault: seedKey === 'other',
      version,
    }));
  }
  createCategory(userId: string, value: string) {
    const label = name(value, 80);
    return this.write(async (tx) => {
      await this.seed(tx, userId);
      const row = await tx.expenseCategory.create({
        data: {
          id: randomUUID(),
          userId,
          name: label,
          nameKey: label.toLocaleLowerCase('ru-RU'),
        },
      });
      return {
        id: row.id,
        name: row.name,
        isDefault: false,
        version: row.version,
      };
    });
  }
  updateCategory(userId: string, id: string, value: string, version: number) {
    const label = name(value, 80);
    return this.write(async (tx) => {
      const row = await tx.expenseCategory.findFirst({ where: { id, userId } });
      if (!row) missing();
      if (
        (
          await tx.expenseCategory.updateMany({
            where: { id, userId, version },
            data: {
              name: label,
              nameKey: label.toLocaleLowerCase('ru-RU'),
              version: { increment: 1 },
            },
          })
        ).count !== 1
      )
        conflict();
      return {
        id,
        name: label,
        isDefault: row!.seedKey === 'other',
        version: version + 1,
      };
    });
  }
  private async validateOperation(
    tx: Tx,
    userId: string,
    input: ReturnType<typeof operationInput>,
    old?: BankCardOperation,
  ) {
    const cards = new Set(
      [input.cardId, input.targetCardId, old?.cardId, old?.targetCardId].filter(
        (id): id is string => Boolean(id),
      ),
    );
    currentDate(input.date);
    for (const id of cards) {
      const card = await this.card(tx, userId, id, true);
      if (
        (id === input.cardId || id === input.targetCardId) &&
        input.date < card.openingDate
      )
        fail('BANK_INVALID_DATE');
    }
    if (
      old &&
      (old.kind !== input.kind ||
        old.originalExpenseId !== input.originalExpenseId)
    )
      fail('BANK_IMMUTABLE_OPERATION');
    if (input.kind === 'transfer') {
      if (
        !input.targetCardId ||
        input.targetCardId === input.cardId ||
        input.categoryId ||
        input.originalExpenseId
      )
        fail();
    } else if (input.targetCardId) fail();
    if (input.kind === 'expense') {
      if (input.originalExpenseId) fail();
      if (!input.categoryId) {
        const category = await tx.expenseCategory.findUnique({
          where: { userId_seedKey: { userId, seedKey: 'other' } },
        });
        if (!category) missing();
        input.categoryId = category!.id;
      }
      if (
        !(await tx.expenseCategory.findFirst({
          where: { userId, id: input.categoryId },
        }))
      )
        missing();
    } else if (input.categoryId) fail();
    if (input.kind !== 'refund' && input.originalExpenseId) fail();
    if (input.kind === 'refund') {
      if (!input.originalExpenseId) fail();
      const source = await this.operation(tx, userId, input.originalExpenseId!);
      if (
        source.deletedAt ||
        source.kind !== 'expense' ||
        source.cardId !== input.cardId
      )
        fail('BANK_INVALID_REFUND');
      if (
        (
          await tx.bankCardOperation.updateMany({
            where: {
              id: source.id,
              userId,
              version: source.version,
              deletedAt: null,
            },
            data: { version: { increment: 1 } },
          })
        ).count !== 1
      )
        conflict();
      const refunds = await tx.bankCardOperation.findMany({
        where: {
          userId,
          originalExpenseId: source.id,
          deletedAt: null,
          ...(old ? { id: { not: old.id } } : {}),
        },
      });
      if (input.date < source.date) fail('BANK_INVALID_DATE');
      if (
        refunds.reduce((sum, r) => sum + r.amountKopecks, 0n) +
          input.amountKopecks >
        source.amountKopecks
      )
        conflict('BANK_REFUND_LIMIT');
    }
    if (old?.kind === 'expense') {
      const refunds = await tx.bankCardOperation.findMany({
        where: { userId, originalExpenseId: old.id, deletedAt: null },
      });
      if (
        refunds.length &&
        (input.cardId !== old.cardId ||
          refunds.some((row) => row.date < input.date) ||
          refunds.reduce((sum, row) => sum + row.amountKopecks, 0n) >
            input.amountKopecks)
      )
        conflict('BANK_DEPENDENT_REFUNDS');
    }
  }
  createOperation(userId: string, dto: CreateBankOperationDto) {
    const normalized = operationInput(dto),
      hash = fingerprint(normalized);
    return this.write(async (tx) => {
      const existing = await tx.bankCardOperation.findUnique({
        where: { id: dto.id },
      });
      if (existing) {
        if (existing.userId !== userId) missing();
        if (existing.createFingerprint !== hash)
          conflict('BANK_INTENT_CONFLICT');
        if (existing.deletedAt)
          throw new GoneException({ code: 'BANK_OPERATION_DELETED' });
        return this.operationView(tx, existing);
      }
      const input = { ...normalized };
      await this.validateOperation(tx, userId, input);
      return this.operationView(
        tx,
        await tx.bankCardOperation.create({
          data: { ...input, id: dto.id, userId, createFingerprint: hash },
        }),
      );
    });
  }
  getOperation(userId: string, id: string) {
    return this.prisma.$transaction(async (tx) => {
      const row = await this.operation(tx, userId, id);
      if (row.deletedAt) missing();
      return this.operationView(tx, row);
    });
  }
  updateOperation(userId: string, id: string, dto: UpdateBankOperationDto) {
    return this.write(async (tx) => {
      const old = await this.operation(tx, userId, id);
      if (old.deletedAt) missing();
      if (old.version !== dto.version) conflict();
      const input = operationInput({
        id,
        kind: dto.kind ?? (old.kind as CreateBankOperationDto['kind']),
        cardId: dto.cardId ?? old.cardId,
        targetCardId: dto.targetCardId ?? old.targetCardId ?? undefined,
        categoryId: dto.categoryId ?? old.categoryId ?? undefined,
        originalExpenseId:
          dto.originalExpenseId ?? old.originalExpenseId ?? undefined,
        amount: dto.amount ?? rubMoney(old.amountKopecks),
        date: dto.date ?? old.date,
        description: dto.description ?? old.description ?? undefined,
      });
      await this.validateOperation(tx, userId, input, old);
      if (
        (
          await tx.bankCardOperation.updateMany({
            where: { id, userId, version: dto.version, deletedAt: null },
            data: { ...input, version: { increment: 1 } },
          })
        ).count !== 1
      )
        conflict();
      return this.operationView(tx, await this.operation(tx, userId, id));
    });
  }
  deleteOperation(userId: string, id: string, version: number) {
    return this.write(async (tx) => {
      const row = await this.operation(tx, userId, id);
      if (row.deletedAt) return;
      if (row.version !== version) conflict();
      await this.card(tx, userId, row.cardId, true);
      if (row.targetCardId) await this.card(tx, userId, row.targetCardId, true);
      if (
        row.kind === 'expense' &&
        (await tx.bankCardOperation.findFirst({
          where: { userId, originalExpenseId: id, deletedAt: null },
        }))
      )
        conflict('BANK_DEPENDENT_REFUNDS');
      if (row.originalExpenseId) {
        const source = await this.operation(tx, userId, row.originalExpenseId);
        if (
          (
            await tx.bankCardOperation.updateMany({
              where: { id: source.id, userId, version: source.version },
              data: { version: { increment: 1 } },
            })
          ).count !== 1
        )
          conflict();
      }
      if (
        (
          await tx.bankCardOperation.updateMany({
            where: { id, userId, version, deletedAt: null },
            data: { deletedAt: new Date(), version: { increment: 1 } },
          })
        ).count !== 1
      )
        conflict();
    });
  }
  history(
    userId: string,
    id: string,
    query: BankOperationsQueryDto | BankPageQueryDto,
    expenses = false,
  ) {
    const period = expenses
      ? undefined
      : periodBounds(query as BankOperationsQueryDto);
    return this.prisma.$transaction(async (tx) => {
      await this.card(tx, userId, id);
      const page = query.page ?? 1,
        limit = query.limit ?? 50;
      const where: Prisma.BankCardOperationWhereInput = {
        userId,
        deletedAt: null,
        OR: [{ cardId: id }, { targetCardId: id }],
        ...(expenses
          ? { kind: 'expense' }
          : { date: { gte: period!.from, lte: period!.to } }),
      };
      const total = await tx.bankCardOperation.count({ where });
      const rows = await tx.bankCardOperation.findMany({
        where,
        orderBy: [{ date: 'desc' }, { createdAt: 'desc' }, { id: 'desc' }],
        skip: (page - 1) * limit,
        take: limit,
      });
      return {
        items: await Promise.all(
          rows.map((row) => this.operationView(tx, row)),
        ),
        total,
        page,
        hasNext: page * limit < total,
      };
    });
  }
  summary(userId: string, query: BankSummaryQueryDto) {
    const period = periodBounds(query);
    return this.prisma.$transaction(async (tx) => {
      if (query.cardId) await this.card(tx, userId, query.cardId);
      const rows = await tx.bankCardOperation.findMany({
        where: {
          userId,
          deletedAt: null,
          date: { gte: period.from, lte: period.to },
          kind: { in: ['expense', 'refund'] },
          ...(query.cardId ? { cardId: query.cardId } : {}),
        },
        include: { originalExpense: { select: { categoryId: true } } },
      });
      const totals = bankSummary(
        period,
        rows.map((row) => ({
          ...row,
          categoryId: row.originalExpense?.categoryId ?? row.categoryId,
        })),
      );
      const categories = await tx.expenseCategory.findMany({
        where: { userId },
      });
      return {
        month: query.month,
        ...period,
        cardId: query.cardId ?? null,
        expenses: rubMoney(totals.expenses),
        refunds: rubMoney(totals.refunds),
        net: rubMoney(totals.net),
        categories: totals.categories.map((row) => ({
          categoryId: row.categoryId,
          categoryName: categories.find((c) => c.id === row.categoryId)!.name,
          expenses: rubMoney(row.expenses),
          refunds: rubMoney(row.refunds),
          net: rubMoney(row.net),
        })),
      };
    });
  }
 }
@@ -1,4 +1,4 @@
-import { applyDecorators } from '@nestjs/common';
+import { HttpStatus, applyDecorators } from '@nestjs/common';
 import {
  ApiExtraModels,
  ApiProperty,
@@ -8,10 +8,10 @@ import {
 export class ProblemDetailsDto {
  @ApiProperty({ example: 401 })
-  status: number;
+  declare status: number;
  @ApiProperty({ example: 'UNAUTHORIZED' })
-  code: string;
+  declare code: string;
  @ApiProperty({
    required: false,
@@ -35,10 +35,13 @@ function problemResponse(status: number, description: string) {
 export function ApiProblemResponses(): MethodDecorator & ClassDecorator {
  return applyDecorators(
    ApiExtraModels(ProblemDetailsDto),
-    problemResponse(400, 'Invalid request'),
+    problemResponse(HttpStatus.BAD_REQUEST, 'Invalid request'),
-    problemResponse(401, 'Authentication required'),
+    problemResponse(HttpStatus.UNAUTHORIZED, 'Authentication required'),
-    problemResponse(404, 'Resource not found'),
+    problemResponse(HttpStatus.NOT_FOUND, 'Resource not found'),
-    problemResponse(503, 'Upstream service unavailable'),
+    problemResponse(
-    problemResponse(500, 'Internal server error'),
+      HttpStatus.SERVICE_UNAVAILABLE,
      'Upstream service unavailable',
    ),
    problemResponse(HttpStatus.INTERNAL_SERVER_ERROR, 'Internal server error'),
  );
 }
@@ -0,0 +1,61 @@
 import { BadRequestException, ValidationPipe } from '@nestjs/common';
 import { CredentialsDto } from '../modules/auth/presentation/auth.dto';
 import {
  CreateBankCardDto,
  UpdateBankCardDto,
 } from '../modules/banking/bank-cards/presentation/bank-card.dto';
 describe('DTO validation', () => {
  const pipe = new ValidationPipe({ transform: true, whitelist: true });
  it('requires credentials and normalizes a valid email', async () => {
    const metadata = { type: 'body' as const, metatype: CredentialsDto };
    await expect(pipe.transform({}, metadata)).rejects.toBeInstanceOf(
      BadRequestException,
    );
    await expect(
      pipe.transform({ email: 'user@example.com' }, metadata),
    ).rejects.toBeInstanceOf(BadRequestException);
    await expect(
      pipe.transform(
        { email: ' User@Example.com ', password: 'long-enough-password' },
        metadata,
      ),
    ).resolves.toEqual({
      email: 'user@example.com',
      password: 'long-enough-password',
    });
  });
  it('requires and validates nested money in a new card', async () => {
    const metadata = { type: 'body' as const, metatype: CreateBankCardDto };
    const card = {
      id: '00000000-0000-4000-8000-000000000001',
      name: 'Everyday',
      openingDate: '2026-09-13',
    };
    for (const openingBalance of [undefined, null, {}, { currency: 'RUB' }]) {
      await expect(
        pipe.transform({ ...card, openingBalance }, metadata),
      ).rejects.toBeInstanceOf(BadRequestException);
    }
    const valid = {
      ...card,
      openingBalance: { currency: 'RUB', value: '100.00' },
    };
    await expect(pipe.transform(valid, metadata)).resolves.toEqual(valid);
  });
  it('keeps update fields optional while requiring version and rejecting null', async () => {
    const metadata = { type: 'body' as const, metatype: UpdateBankCardDto };
    await expect(pipe.transform({}, metadata)).rejects.toBeInstanceOf(
      BadRequestException,
    );
    await expect(
      pipe.transform({ version: 1, name: null }, metadata),
    ).rejects.toBeInstanceOf(BadRequestException);
    await expect(
      pipe.transform({ version: 1 }, metadata),
    ).resolves.toMatchObject({ version: 1 });
  });
 });
@@ -1,3 +1,4 @@
 import { constants as httpStatus } from 'node:http2';
 import { Injectable, NestMiddleware } from '@nestjs/common';
 import type { NextFunction, Request, Response } from 'express';
 import { randomUUID } from 'node:crypto';
@@ -46,11 +47,11 @@ export class RequestLoggingMiddleware implements NestMiddleware {
          : {}),
      };
      const level =
-        response.statusCode >= 500
+        response.statusCode >= httpStatus.HTTP_STATUS_INTERNAL_SERVER_ERROR
          ? 'error'
-          : response.statusCode === 429 ||
+          : response.statusCode === httpStatus.HTTP_STATUS_TOO_MANY_REQUESTS ||
-              response.statusCode === 401 ||
+              response.statusCode === httpStatus.HTTP_STATUS_UNAUTHORIZED ||
-              response.statusCode === 403
+              response.statusCode === httpStatus.HTTP_STATUS_FORBIDDEN
            ? 'warn'
            : 'info';
      this.logger.event(level, 'http.request.completed', context);
@@ -1,9 +1,10 @@
 import { ApiProperty } from '@nestjs/swagger';
 import type { Money } from './money.types';
-export class MoneyDto {
+export class MoneyDto implements Money {
  @ApiProperty()
-  currency: string;
+  declare currency: string;
  @ApiProperty()
-  value: string;
+  declare value: string;
 }
@@ -0,0 +1 @@
 export type Money = { currency: string; value: string };
@@ -0,0 +1,2 @@
 export const MILLISECONDS_PER_SECOND = 1_000;
 export const MILLISECONDS_PER_DAY = 86_400_000;
@@ -1,3 +1,8 @@
 const DEFAULT_PORT = 3000;
 const DEFAULT_TBANK_RATE_LIMIT_PER_SECOND = 5;
 const MAX_PORT = 65_535;
 const MIN_JWT_SECRET_LENGTH = 32;
 const TOKEN_KEY_BYTES = 32;
 export interface Environment {
  DATABASE_URL: string;
  FRONTEND_ORIGIN: string;
@@ -13,12 +18,14 @@ export interface Environment {
 export function validateEnv(config: Record<string, unknown>): Environment {
  const databaseUrl = config['DATABASE_URL'];
  const frontendOrigin = config['FRONTEND_ORIGIN'];
-  const port = config['PORT'] ?? 3000;
+  const port = config['PORT'] ?? DEFAULT_PORT;
  const jwtSecret = config['JWT_SECRET'];
  const tokenEncryptionKey = config['TOKEN_ENCRYPTION_KEY'];
  const tbankEndpoint =
    config['TBANK_GRPC_ENDPOINT'] ?? 'invest-public-api.tbank.ru:443';
-  const tbankRateLimit = config['TBANK_RATE_LIMIT_PER_SECOND'] ?? 5;
+  const tbankRateLimit =
    config['TBANK_RATE_LIMIT_PER_SECOND'] ??
    DEFAULT_TBANK_RATE_LIMIT_PER_SECOND;
  const tbankCaCertPath = config['TBANK_CA_CERT_PATH'];
  const logLevel = config['LOG_LEVEL'] ?? 'info';
@@ -47,18 +54,25 @@ export function validateEnv(config: Record<string, unknown>): Environment {
  }
  const parsedPort = Number(port);
-  if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+  if (
    !Number.isInteger(parsedPort) ||
    parsedPort < 1 ||
    parsedPort > MAX_PORT
  ) {
    throw new Error('PORT must be a valid port number');
  }
-  if (typeof jwtSecret !== 'string' || jwtSecret.length < 32) {
+  if (
    typeof jwtSecret !== 'string' ||
    jwtSecret.length < MIN_JWT_SECRET_LENGTH
  ) {
    throw new Error('JWT_SECRET must be at least 32 characters long');
  }
  if (
    typeof tokenEncryptionKey !== 'string' ||
    !/^[A-Za-z0-9+/]+={0,2}$/.test(tokenEncryptionKey) ||
-    Buffer.from(tokenEncryptionKey, 'base64').length !== 32
+    Buffer.from(tokenEncryptionKey, 'base64').length !== TOKEN_KEY_BYTES
  ) {
    throw new Error(
      'TOKEN_ENCRYPTION_KEY must be a base64-encoded 32-byte key',
@@ -0,0 +1,2 @@
 // Public cross-module surface. Nest providers are exported by the matching module.
 export { type MoexBondEvent, MoexClient } from './moex.client';
@@ -1,5 +1,8 @@
 import { constants as httpStatus } from 'node:http2';
 import { Injectable, ServiceUnavailableException } from '@nestjs/common';
 const FALLBACK_PAGE_SIZE = 100;
 const baseUrl = 'https://iss.moex.com/iss';
 const timeoutMs = 10_000;
@@ -121,8 +124,8 @@ export class MoexClient {
      if (!paginated) return rows;
      const cursorBlock = response[`${block}.cursor`];
      if (!cursorBlock) {
-        if (current.length < 100) return rows;
+        if (current.length < FALLBACK_PAGE_SIZE) return rows;
-        start += 100;
+        start += FALLBACK_PAGE_SIZE;
        continue;
      }
      const cursor = parseRows(cursorBlock)[0];
@@ -145,7 +148,7 @@ export class MoexClient {
      const response = await fetch(url, {
        signal: AbortSignal.timeout(timeoutMs),
      });
-      if (response.status === 404) return null;
+      if (response.status === httpStatus.HTTP_STATUS_NOT_FOUND) return null;
      if (!response.ok) throw new Error(`MOEX HTTP ${response.status}`);
      const body: unknown = await response.json();
      if (!body || typeof body !== 'object')
@@ -0,0 +1,8 @@
 import { Module } from '@nestjs/common';
 import { MoexClient } from './moex.client';
@Module({
  providers: [MoexClient],
  exports: [MoexClient],
 })
 export class MoexModule {}
@@ -2,6 +2,12 @@ import { Injectable, ServiceUnavailableException } from '@nestjs/common';
 import { load } from 'cheerio';
 import { LRUCache } from 'lru-cache';
 const REGISTRY_CACHE_TTL_MS = 21_600_000;
 const REQUEST_TIMEOUT_MS = 10_000;
 const COLUMN_COUNT = 6;
 const ISIN_COLUMN = 3;
 const DATE_COLUMN = 5;
 const registryUrl = 'https://ratings.ru/ratings/issues/';
 export type NcrRating = {
  agency: 'NCR';
@@ -18,7 +24,7 @@ export class NcrRatingsClient {
  private readonly cache = new LRUCache<
    string,
    Promise<Map<string, NcrRating>>
-  >({ max: 1, ttl: 6 * 60 * 60_000 });
+  >({ max: 1, ttl: REGISTRY_CACHE_TTL_MS });
  async rating(isin: string): Promise<NcrRating | null> {
    const key = isin.trim().toUpperCase();
@@ -38,7 +44,7 @@ export class NcrRatingsClient {
  private async registry(): Promise<Map<string, NcrRating>> {
    const response = await fetch(registryUrl, {
-      signal: AbortSignal.timeout(10_000),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
    });
    if (!response.ok) throw new Error('NCR unavailable');
    const $ = load(await response.text());
@@ -49,18 +55,18 @@ export class NcrRatingsClient {
      .get();
    if (
      table.length !== 1 ||
-      headings.length !== 6 ||
+      headings.length !== COLUMN_COUNT ||
      headings[2] !== 'Рейтинг' ||
-      headings[3] !== 'ISIN' ||
+      headings[ISIN_COLUMN] !== 'ISIN' ||
-      headings[5] !== 'Дата'
+      headings[DATE_COLUMN] !== 'Дата'
    )
      throw new Error('NCR registry changed');
    const observedAt = new Date().toISOString();
    const result = new Map<string, NcrRating>();
    table.find('tbody tr').each((_, row) => {
      const cells = $(row).find('td');
-      if (cells.length !== 6) throw new Error('NCR row changed');
+      if (cells.length !== COLUMN_COUNT) throw new Error('NCR row changed');
-      const isin = cells.eq(3).text().trim().toUpperCase();
+      const isin = cells.eq(ISIN_COLUMN).text().trim().toUpperCase();
      // Unassigned issues cannot safely be matched to a held instrument.
      if (!/^[A-Z]{2}[A-Z0-9]{9}\d$/.test(isin)) return;
      const raw = cells.eq(2).text().replace(/\s+/g, ' ').trim();
@@ -73,9 +79,9 @@ export class NcrRatingsClient {
      )
        throw new Error('NCR rating changed');
      const dateParts = /^(\d{2})\.(\d{2})\.(\d{4})$/.exec(
-        cells.eq(5).text().trim(),
+        cells.eq(DATE_COLUMN).text().trim(),
      );
-      const href = cells.eq(3).find('a').attr('href');
+      const href = cells.eq(ISIN_COLUMN).find('a').attr('href');
      if (!dateParts || !href || !/^\/ratings\/issues\/\d+\/$/.test(href))
        throw new Error('NCR identity missing');
      const date = `${dateParts[3]}-${dateParts[2]}-${dateParts[1]}`;
@@ -0,0 +1,2 @@
 // Public cross-module surface. Nest providers are exported by the matching module.
 export { NcrRatingsClient } from './ncr-ratings.client';
@@ -0,0 +1,8 @@
 import { Module } from '@nestjs/common';
 import { NcrRatingsClient } from './ncr-ratings.client';
@Module({
  providers: [NcrRatingsClient],
  exports: [NcrRatingsClient],
 })
 export class NcrModule {}
@@ -1,4 +1,4 @@
-import { add, formatDecimal, multiply, subtract } from '../common/decimal';
+import { add, formatDecimal, multiply, subtract } from '../../common/decimal';
 import { decimal } from './decimal';
 describe('decimal', () => {
@@ -1,4 +1,4 @@
-import { Decimal } from '../common/decimal';
+import { Decimal } from '../../common/decimal';
 const NANO = 1_000_000_000n;
@@ -0,0 +1,320 @@
 import { Injectable } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import type {
  Prisma,
  TbankInstrumentLookup as MetadataLookupRow,
  TbankInstrument as MetadataRow,
 } from '../../../generated/prisma/client';
 import { PrismaService } from '../../prisma/prisma.service';
 import type { TbankSyncAttempt } from './tbank-access.service';
 import type { TbankInstrument } from './tbank.client';
 import { tbankSourceTtlMs } from './tbank-source.policy';
 export type MetadataIdentity = {
  instrumentUid?: string | null;
  figi?: string | null;
 };
 export type MetadataLookup = {
  type: 'uid' | 'figi';
  id: string;
  data: TbankInstrument | null;
 };
 const provider = 'tbank';
 // Keep IN lists below the SQLite/Prisma parameter limit, including fixed predicates.
 const metadataReadBatchSize = 400;
 export function metadataKey(identity: MetadataIdentity) {
  return JSON.stringify([
    identity.instrumentUid?.trim() || null,
    identity.figi?.trim() || null,
  ]);
 }
@Injectable()
 export class InstrumentMetadataRepository {
  constructor(private readonly prisma: PrismaService) {}
  async readMany(identities: MetadataIdentity[]) {
    const identifiers = identities.flatMap((identity) => [
      ...(identity.instrumentUid?.trim()
        ? [{ identifierType: 'uid', identifier: identity.instrumentUid.trim() }]
        : []),
      ...(identity.figi?.trim()
        ? [{ identifierType: 'figi', identifier: identity.figi.trim() }]
        : []),
    ]);
    if (!identifiers.length)
      return new Map<string, ReturnType<typeof selectMetadata>>();
    return this.prisma.$transaction(async (tx) => {
      const lookups: MetadataLookupRow[] = [];
      for (const identifierType of ['uid', 'figi']) {
        const values = [
          ...new Set(
            identifiers
              .filter((entry) => entry.identifierType === identifierType)
              .map((entry) => entry.identifier),
          ),
        ];
        for (
          let offset = 0;
          offset < values.length;
          offset += metadataReadBatchSize
        )
          lookups.push(
            ...(await tx.tbankInstrumentLookup.findMany({
              where: {
                provider,
                identifierType,
                identifier: {
                  in: values.slice(offset, offset + metadataReadBatchSize),
                },
              },
            })),
          );
      }
      const uids = [
        ...new Set(lookups.flatMap((row) => row.matchedUids as string[])),
      ];
      const instruments: MetadataRow[] = [];
      for (
        let offset = 0;
        offset < uids.length;
        offset += metadataReadBatchSize
      )
        instruments.push(
          ...(await tx.tbankInstrument.findMany({
            where: {
              provider,
              uid: { in: uids.slice(offset, offset + metadataReadBatchSize) },
            },
          })),
        );
      const byIdentifier = new Map(
        lookups.map((row) => [`${row.identifierType}:${row.identifier}`, row]),
      );
      const byUid = new Map(instruments.map((row) => [row.uid, row]));
      return new Map(
        identities.map((identity) => [
          metadataKey(identity),
          selectMetadata(identity, byIdentifier, byUid),
        ]),
      );
    });
  }
  async reserve(
    attemptOwner: { userId: string; revision: string },
    identity: MetadataIdentity,
    runId: string,
    active: ReadonlySet<string>,
  ) {
    return this.prisma.$transaction(async (tx) => {
      const valid = await tx.tbankConnection.updateMany({
        where: { ...attemptOwner, invalidToken: false },
        data: { membershipRevision: { increment: 0 } },
      });
      if (!valid.count) return null;
      const scope = {
        ...attemptOwner,
        scopeKey: `metadata:${metadataKey(identity)}`,
      };
      const previous = await tx.tbankSyncWork.findUnique({
        where: { userId_revision_scopeKey: scope },
      });
      if (
        previous?.state === 'running' &&
        previous.processRunId === runId &&
        active.has(previous.attemptId)
      )
        return { work: previous, launch: false };
      const data = {
        attemptId: randomUUID(),
        processRunId: runId,
        state: 'running',
        priority: 1,
        intent: { source: 'metadata', ...identity },
        progress: {},
        errorCode: null,
      };
      const work = await tx.tbankSyncWork.upsert({
        where: { userId_revision_scopeKey: scope },
        create: { ...scope, ...data, id: randomUUID() },
        update: data,
      });
      return { work, launch: true };
    });
  }
  work(userId: string, revision: string, identity: MetadataIdentity) {
    return this.prisma.tbankSyncWork.findUnique({
      where: {
        userId_revision_scopeKey: {
          userId,
          revision,
          scopeKey: `metadata:${metadataKey(identity)}`,
        },
      },
      select: { id: true, state: true, errorCode: true },
    });
  }
  publish(attempt: TbankSyncAttempt, results: MetadataLookup[], now: Date) {
    return this.prisma.$transaction(async (tx) => {
      const claimed = await tx.tbankSyncWork.updateMany({
        where: {
          ...attempt,
          state: 'running',
          connection: { invalidToken: false },
        },
        data: { state: 'complete', progress: {} },
      });
      if (!claimed.count) return false;
      const aliases = new Map(
        results.map((result) => [`${result.type}:${result.id}`, result]),
      );
      for (const result of results) {
        if (!result.data) continue;
        const uid =
          result.data.uid?.trim() || (result.type === 'uid' ? result.id : null);
        const figi =
          result.data.figi?.trim() ||
          (result.type === 'figi' ? result.id : null);
        for (const [type, id] of [
          ['uid', uid],
          ['figi', figi],
        ] as const) {
          if (id && uid && !aliases.has(`${type}:${id}`))
            aliases.set(`${type}:${id}`, {
              type,
              id,
              data: { ...result.data, uid },
            });
        }
      }
      for (const result of aliases.values()) {
        const instrument = result.data;
        const uid =
          instrument?.uid?.trim() || (result.type === 'uid' ? result.id : null);
        // FIGI is an alias, never a fabricated provider UID.
        if (instrument && !uid)
          throw new Error('Metadata response has no instrument UID');
        if (instrument && uid) {
          const key = { provider, uid };
          const previous = await tx.tbankInstrument.findUnique({
            where: { provider_uid: key },
          });
          const payload = JSON.parse(
            JSON.stringify(instrument),
          ) as Prisma.InputJsonObject;
          const data = {
            metadata: payload,
            figi:
              instrument.figi ?? (result.type === 'figi' ? result.id : null),
            ticker: instrument.ticker ?? null,
            instrumentType: instrument.instrumentType ?? '',
            fetchedAt: now,
          };
          await tx.tbankInstrument.upsert({
            where: { provider_uid: key },
            create: { ...key, ...data },
            update: {
              ...data,
              dataRevision: {
                increment: isDeepStrictEqual(previous?.metadata, payload)
                  ? 0
                  : 1,
              },
            },
          });
        }
        const key = {
          provider,
          identifierType: result.type,
          identifier: result.id,
        };
        const matchedUids = instrument && uid ? [uid] : [];
        const previous = await tx.tbankInstrumentLookup.findUnique({
          where: { provider_identifierType_identifier: key },
        });
        await tx.tbankInstrumentLookup.upsert({
          where: { provider_identifierType_identifier: key },
          create: { ...key, matchedUids, fetchedAt: now },
          update: {
            matchedUids,
            fetchedAt: now,
            dataRevision: {
              increment: isDeepStrictEqual(previous?.matchedUids, matchedUids)
                ? 0
                : 1,
            },
          },
        });
      }
      return true;
    });
  }
  async finishObserver(attempt: TbankSyncAttempt, success: boolean) {
    await this.prisma.tbankSyncWork.updateMany({
      where: {
        ...attempt,
        state: 'running',
        ...(success ? { connection: { invalidToken: false } } : {}),
      },
      data: {
        state: success ? 'complete' : 'failed',
        errorCode: success ? null : 'TBANK_UNAVAILABLE',
      },
    });
    if (success)
      await this.prisma.tbankSyncWork.updateMany({
        where: {
          ...attempt,
          state: 'running',
          connection: { invalidToken: true },
        },
        data: { state: 'failed', errorCode: 'INVALID_TBANK_TOKEN' },
      });
  }
 }
 function selectMetadata(
  identity: MetadataIdentity,
  lookups: ReadonlyMap<string, MetadataLookupRow>,
  instruments: ReadonlyMap<string, MetadataRow>,
 ) {
  const resolve = (type: string, id: string | null | undefined) => {
    const lookup = lookups.get(`${type}:${id?.trim()}`);
    const uid = (lookup?.matchedUids as string[] | undefined)?.[0];
    const instrument = uid ? instruments.get(uid) : undefined;
    const data = instrument ? (instrument.metadata as TbankInstrument) : null;
    return { lookup, instrument, data };
  };
  const instrumentUid = identity.instrumentUid?.trim();
  const instrumentFigi = identity.figi?.trim();
  const uid = resolve('uid', instrumentUid);
  const figi = resolve('figi', instrumentFigi);
  const usefulUid = Boolean(uid.data?.name?.trim() || uid.data?.ticker?.trim());
  const used =
    usefulUid || !instrumentFigi ? [uid] : instrumentUid ? [uid, figi] : [figi];
  const complete = used.every((row) => Boolean(row.lookup));
  const fetchedAt =
    used
      .flatMap((row) => (row.lookup ? [row.lookup.fetchedAt] : []))
      .sort((a, b) => a.valueOf() - b.valueOf())[0] ?? null;
  return {
    data: usefulUid ? uid.data : (figi.data ?? uid.data),
    complete,
    fresh:
      complete &&
      fetchedAt !== null &&
      Date.now() - fetchedAt.valueOf() < tbankSourceTtlMs.metadata,
    fetchedAt,
    dataRevision: used
      .map(
        (row) =>
          `${row.lookup?.dataRevision ?? 0}:${row.instrument?.dataRevision ?? 0}`,
      )
      .join('/'),
  };
 }
@@ -0,0 +1,208 @@
 import { Injectable } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
 import { StructuredLogger } from '../../common/logging/structured-logger.service';
 import {
  TbankAccessService,
  type TbankSyncAttempt,
 } from './tbank-access.service';
 import { TbankClient, type TbankInstrument } from './tbank.client';
 import {
  InstrumentMetadataRepository,
  metadataKey,
  type MetadataIdentity,
  type MetadataLookup,
 } from './instrument-metadata.repository';
 export { metadataKey } from './instrument-metadata.repository';
 export type { MetadataIdentity } from './instrument-metadata.repository';
 type Producer = {
  identity: MetadataIdentity;
  attempt: TbankSyncAttempt;
  observers: TbankSyncAttempt[];
 };
@Injectable()
 export class InstrumentMetadataService {
  private readonly runId = randomUUID();
  private readonly active = new Set<string>();
  private readonly producers = new Map<string, Producer>();
  private readonly queue: Producer[] = [];
  private reservations: Promise<unknown> = Promise.resolve();
  private running = false;
  constructor(
    private readonly tbank: TbankClient,
    private readonly logger: StructuredLogger,
    private readonly repository: InstrumentMetadataRepository,
    private readonly access: TbankAccessService,
  ) {}
  savedMany(identities: MetadataIdentity[]) {
    return this.repository.readMany(identities);
  }
  async read(
    userId: string,
    identity: MetadataIdentity,
    observe = false,
    revision?: string,
  ) {
    const connection = await this.access.local(userId);
    if (revision && connection.revision !== revision) return null;
    const data = (await this.savedMany([identity])).get(metadataKey(identity));
    if (!observe && !data?.fresh)
      await this.request(userId, connection.revision, identity);
    return {
      ...data,
      work: await this.repository.work(userId, connection.revision, identity),
    };
  }
  async request(
    userId: string,
    revision: string,
    identity: MetadataIdentity,
    force = false,
  ) {
    identity = {
      instrumentUid: identity.instrumentUid?.trim() || null,
      figi: identity.figi?.trim() || null,
    };
    if (!identity.instrumentUid && !identity.figi) return null;
    const normalized = identity;
    const reserved = this.reservations.then(async () => {
      const snapshot = (await this.savedMany([normalized])).get(
        metadataKey(normalized),
      );
      if (!force && snapshot?.fresh) return null;
      const result = await this.repository.reserve(
        { userId, revision },
        normalized,
        this.runId,
        this.active,
      );
      if (!result) return null;
      const { id, attemptId } = result.work;
      if (!result.launch) return id;
      const attempt = { userId, revision, id, attemptId };
      this.active.add(attemptId);
      const key = metadataKey(normalized);
      const producer = this.producers.get(key);
      if (producer) producer.observers.push(attempt);
      else {
        const queued = { identity: normalized, attempt, observers: [] };
        this.producers.set(key, queued);
        this.queue.push(queued);
      }
      if (!this.running) {
        this.running = true;
        setImmediate(() => {
          void this.drain();
        });
      }
      return id;
    });
    this.reservations = reserved.catch(() => undefined);
    return reserved;
  }
  private async drain() {
    try {
      while (this.queue.length) {
        const producer = this.queue.shift();
        if (!producer) break;
        const { attempt, identity } = producer;
        let success = false;
        try {
          const token = await this.access.tokenForAttempt(attempt);
          if (token) {
            const results: MetadataLookup[] = [];
            let useful = false;
            let uidFailed = false;
            if (identity.instrumentUid) {
              let data: TbankInstrument | null | undefined;
              try {
                data = await this.tbank.getInstrumentByUid(
                  token,
                  identity.instrumentUid,
                );
              } catch (error) {
                if (
                  !identity.figi ||
                  (error instanceof Error &&
                    error.message === 'INVALID_TBANK_TOKEN')
                )
                  throw error;
                uidFailed = true;
              }
              if (data?.uid && data.uid !== identity.instrumentUid)
                throw new Error('Metadata UID mismatch');
              if (data !== undefined)
                results.push({ type: 'uid', id: identity.instrumentUid, data });
              useful = Boolean(data?.name?.trim() || data?.ticker?.trim());
              if (!useful && data && !identity.figi)
                throw new Error('Incomplete metadata');
            }
            if (!useful && identity.figi) {
              const data = await this.tbank.getInstrumentByFigi(
                token,
                identity.figi,
              );
              if (data?.figi && data.figi !== identity.figi)
                throw new Error('Metadata FIGI mismatch');
              if (data && !data.name?.trim() && !data.ticker?.trim())
                throw new Error('Incomplete metadata');
              if (data === undefined || (uidFailed && !data))
                throw new Error('Metadata source unavailable');
              results.push({ type: 'figi', id: identity.figi, data });
              // A successful FIGI response identifies its canonical UID too;
              // a failed UID RPC is never persisted as a negative lookup.
              if (
                uidFailed &&
                data?.uid === identity.instrumentUid &&
                identity.instrumentUid
              )
                results.push({ type: 'uid', id: identity.instrumentUid, data });
            }
            if (
              !results.length ||
              (results.some((result) => result.data) &&
                !results.some(
                  (result) =>
                    result.data?.name?.trim() || result.data?.ticker?.trim(),
                ))
            )
              throw new Error('Incomplete metadata');
            success = await this.repository.publish(
              attempt,
              results,
              new Date(),
            );
          }
        } catch (error) {
          if (error instanceof Error && error.message === 'INVALID_TBANK_TOKEN')
            await this.access.rejectMembershipToken(attempt);
          else
            this.logger.event('warn', 'instrument-metadata.failed', {
              code: 'TBANK_UNAVAILABLE',
            });
        }
        // Remove the producer before awaiting finalization: a new request cannot
        // attach to a producer whose observer list has already been drained.
        this.producers.delete(metadataKey(identity));
        for (const observer of [attempt, ...producer.observers]) {
          await this.repository.finishObserver(observer, success);
          this.active.delete(observer.attemptId);
        }
      }
    } catch {
      this.logger.event('error', 'instrument-metadata.persistence-failed', {
        code: 'TBANK_UNAVAILABLE',
      });
      this.active.clear();
      this.producers.clear();
      this.queue.length = 0;
    } finally {
      this.running = false;
    }
  }
 }
@@ -5,12 +5,12 @@ import {
  ServiceUnavailableException,
 } from '@nestjs/common';
-jest.mock('../prisma/prisma.service', () => ({
+jest.mock('../../prisma/prisma.service', () => ({
  PrismaService: class PrismaService {},
 }));
 import { TbankAccessService } from './tbank-access.service';
 import type { TbankAccountContext } from './tbank-access.service';
 import { TbankAccessService } from './tbank-access.service';
 import { TbankTokenService } from './tbank-token.service';
 describe('TbankAccessService', () => {
@@ -0,0 +1,331 @@
 import { tbankSourceNeedsRefresh } from './tbank-source.policy';
 import {
  BadRequestException,
  ConflictException,
  Injectable,
  NotFoundException,
 } from '@nestjs/common';
 import { createHash, randomUUID } from 'node:crypto';
 import { PrismaService } from '../../prisma/prisma.service';
 import {
  SupportedTbankAccount,
  accessibleTbankAccount,
  supportedTbankAccounts,
 } from './tbank-account.policy';
 import { TbankTokenService } from './tbank-token.service';
 import { TbankAccount, TbankClient } from './tbank.client';
 export type TbankConnectionContext = {
  token: string;
  generation: string;
 };
 export type TbankAccountContext = TbankConnectionContext & {
  account: TbankAccount;
 };
 export type TbankSyncAttempt = {
  userId: string;
  revision: string;
  id: string;
  attemptId: string;
 };
@Injectable()
 export class TbankAccessService {
  constructor(
    private readonly prisma: PrismaService,
    private readonly tokens: TbankTokenService,
    private readonly tbank: TbankClient,
  ) {}
  async reserveMembership(
    userId: string,
    revision: string,
    processRunId: string,
    active: ReadonlySet<string>,
    force: boolean,
  ) {
    return this.prisma.$transaction(async (tx) => {
      const current = await tx.tbankConnection.updateMany({
        where: { userId, revision, invalidToken: false },
        data: { membershipRevision: { increment: 0 } },
      });
      if (!current.count) return null;
      const connection = await tx.tbankConnection.findUniqueOrThrow({
        where: { userId },
      });
      if (
        !force &&
        !tbankSourceNeedsRefresh(
          'membership',
          connection.membershipAt,
          new Date(),
        )
      )
        return null;
      const scope = { userId, revision, scopeKey: 'membership' };
      const previous = await tx.tbankSyncWork.findUnique({
        where: { userId_revision_scopeKey: scope },
      });
      if (
        previous?.state === 'running' &&
        previous.processRunId === processRunId &&
        active.has(previous.attemptId)
      )
        return { work: previous, launch: false };
      const data = {
        attemptId: randomUUID(),
        processRunId,
        state: 'running',
        intent: { source: 'membership' },
        progress: {},
        priority: 0,
        errorCode: null,
      };
      const work = await tx.tbankSyncWork.upsert({
        where: { userId_revision_scopeKey: scope },
        create: { ...scope, ...data, id: randomUUID() },
        update: data,
      });
      return { work, launch: true };
    });
  }
  membershipWork(userId: string, revision: string) {
    return this.prisma.tbankSyncWork.findUnique({
      where: {
        userId_revision_scopeKey: { userId, revision, scopeKey: 'membership' },
      },
      select: { id: true, state: true, errorCode: true, updatedAt: true },
    });
  }
  async failMembership(attempt: TbankSyncAttempt, invalidToken: boolean) {
    if (invalidToken) return this.rejectMembershipToken(attempt);
    const result = await this.prisma.tbankSyncWork.updateMany({
      where: {
        ...attempt,
        state: 'running',
        connection: { invalidToken: false },
      },
      data: { state: 'failed', errorCode: 'TBANK_UNAVAILABLE' },
    });
    return result.count === 1;
  }
  async tokenForAttempt(attempt: TbankSyncAttempt): Promise<string | null> {
    const work = await this.prisma.tbankSyncWork.findFirst({
      where: {
        ...attempt,
        state: 'running',
        connection: { invalidToken: false },
      },
      select: { connection: { select: { encryptedToken: true } } },
    });
    return work ? this.tokens.decrypt(work.connection.encryptedToken) : null;
  }
  async publishMembership(
    attempt: TbankSyncAttempt,
    accounts: TbankAccount[],
    fetchedAt: Date,
    completeWork = false,
  ): Promise<boolean> {
    const supported = supportedTbankAccounts(accounts);
    if (new Set(supported.map(({ id }) => id)).size !== supported.length)
      throw new Error('Duplicate T-Bank account identity');
    return this.prisma.$transaction(async (tx) => {
      // Acquire the write fence before reading membership. Replacement and
      // attempt supersession cannot interleave with the publication below.
      const claimed = await tx.tbankSyncWork.updateMany({
        where: {
          ...attempt,
          state: 'running',
          connection: { invalidToken: false },
        },
        data: { updatedAt: new Date() },
      });
      if (!claimed.count) return false;
      const { userId, revision } = attempt;
      const previous = await tx.tbankAccount.findMany({
        where: { userId, revision },
        orderBy: { upstreamOrder: 'asc' },
        select: { accountId: true, type: true, name: true, openedOn: true },
      });
      const next = supported.map(({ id, ...account }) => ({
        accountId: id,
        ...account,
      }));
      const changed =
        previous.length !== next.length ||
        previous.some((account, index) => {
          const incoming = next[index];
          return (
            account.accountId !== incoming.accountId ||
            account.type !== incoming.type ||
            account.name !== incoming.name ||
            account.openedOn !== incoming.openedOn
          );
        });
      await tx.tbankAccount.deleteMany({
        where: {
          userId,
          revision,
          accountId: { notIn: supported.map(({ id }) => id) },
        },
      });
      for (const [upstreamOrder, account] of next.entries()) {
        await tx.tbankAccount.upsert({
          where: {
            userId_revision_accountId: {
              userId,
              revision,
              accountId: account.accountId,
            },
          },
          create: { userId, revision, ...account, upstreamOrder },
          update: { ...account, upstreamOrder },
        });
      }
      await tx.tbankConnection.update({
        where: { userId_revision: { userId, revision } },
        data: {
          membershipAt: fetchedAt,
          membershipRevision: { increment: changed ? 1 : 0 },
        },
      });
      if (completeWork)
        await tx.tbankSyncWork.update({
          where: { id: attempt.id },
          data: { state: 'complete', progress: { accounts: supported.length } },
        });
      return true;
    });
  }
  async rejectMembershipToken(attempt: TbankSyncAttempt): Promise<boolean> {
    return this.prisma.$transaction(async (tx) => {
      const claimed = await tx.tbankSyncWork.updateMany({
        where: { ...attempt, state: 'running' },
        data: { state: 'failed', errorCode: 'INVALID_TBANK_TOKEN' },
      });
      if (!claimed.count) return false;
      await tx.tbankConnection.update({
        where: {
          userId_revision: {
            userId: attempt.userId,
            revision: attempt.revision,
          },
        },
        data: { invalidToken: true },
      });
      return true;
    });
  }
  // This boundary neither decrypts credentials nor starts discovery/sync.
  // Missing membership is distinct from a successfully observed empty list.
  async local(userId: string, accountId?: string) {
    const connection = await this.prisma.tbankConnection.findUnique({
      where: { userId },
      select: {
        userId: true,
        revision: true,
        invalidToken: true,
        membershipAt: true,
        membershipRevision: true,
        accounts: { orderBy: { upstreamOrder: 'asc' } },
      },
    });
    if (!connection)
      throw new ConflictException({ code: 'TBANK_NOT_CONNECTED' });
    if (connection.invalidToken)
      throw new BadRequestException({ code: 'INVALID_TBANK_TOKEN' });
    if (
      connection.membershipAt &&
      accountId &&
      accountId !== 'all' &&
      !connection.accounts.some((account) => account.accountId === accountId)
    )
      throw new NotFoundException();
    return connection;
  }
  async listSupportedAccounts(
    userId: string,
  ): Promise<SupportedTbankAccount[]> {
    return this.withSupportedAccounts(userId, ({ accounts }) => accounts);
  }
  async withSupportedAccounts<T>(
    userId: string,
    handler: (context: {
      token: string;
      generation: string;
      accounts: SupportedTbankAccount[];
    }) => Promise<T> | T,
  ): Promise<T> {
    return this.withConnection(userId, async ({ token, generation }) =>
      handler({
        token,
        generation,
        accounts: supportedTbankAccounts(
          await this.tbank.getOpenAccounts(token),
        ),
      }),
    );
  }
  async withConnection<T>(
    userId: string,
    handler: (context: TbankConnectionContext) => Promise<T> | T,
  ): Promise<T> {
    const connection = await this.connection(userId);
    return this.tokens.translateInvalidToken(async () => handler(connection));
  }
  async withAccount<T>(
    userId: string,
    accountId: string,
    handler: (context: TbankAccountContext) => Promise<T>,
  ): Promise<T> {
    return this.withConnection(userId, (connection) =>
      this.withAccountForConnection(connection, accountId, handler),
    );
  }
  async withAccountForConnection<T>(
    connection: TbankConnectionContext,
    accountId: string,
    handler: (context: TbankAccountContext) => Promise<T>,
  ): Promise<T> {
    const { token, generation } = connection;
    return this.tokens.translateInvalidToken(async () => {
      const account = accessibleTbankAccount(
        await this.tbank.getOpenAccounts(token),
        accountId,
      );
      if (!account) throw new NotFoundException();
      return handler({ token, generation, account });
    });
  }
  private async connection(
    userId: string,
  ): Promise<{ token: string; generation: string }> {
    const connection = await this.prisma.tbankConnection.findUnique({
      where: { userId },
    });
    if (!connection)
      throw new ConflictException({ code: 'TBANK_NOT_CONNECTED' });
    if (connection.invalidToken)
      throw new BadRequestException({ code: 'INVALID_TBANK_TOKEN' });
    return {
      token: this.tokens.decrypt(connection.encryptedToken),
      generation: createHash('sha256')
        .update(connection.encryptedToken)
        .digest('base64url'),
    };
  }
 }
@@ -1,7 +1,7 @@
 import {
  accessibleTbankAccount,
  supportedTbankAccounts,
-} from './tbank-account-policy';
+} from './tbank-account.policy';
 describe('tbank-account-policy', () => {
  it('normalizes supported account types and fallback names', () => {
@@ -1,4 +1,4 @@
-import { BrokerageAccountDto } from './brokerage-account.dto';
+import { MILLISECONDS_PER_SECOND } from '../../common/time';
 import { TbankAccount } from './tbank.client';
 const accountTypes = {
@@ -15,10 +15,16 @@ const accountTypes = {
 } as const;
 type AccountType = keyof typeof accountTypes;
 export type SupportedTbankAccount = {
  id: string;
  name: string;
  type: (typeof accountTypes)[AccountType]['type'];
  openedOn: string | null;
 };
 export function supportedTbankAccounts(
  accounts: TbankAccount[],
-): BrokerageAccountDto[] {
+): SupportedTbankAccount[] {
  return accounts.flatMap((account) => {
    const details = accountTypes[account.type as AccountType];
    if (!details) return [];
@@ -46,7 +52,7 @@ export function accessibleTbankAccount(
 function openedOn(seconds: string | number | undefined): string | null {
  if (seconds === undefined) return null;
-  const date = new Date(Number(seconds) * 1000);
+  const date = new Date(Number(seconds) * MILLISECONDS_PER_SECOND);
  if (Number.isNaN(date.valueOf())) return null;
  return date.toISOString().slice(0, 10);
 }
@@ -1,7 +1,7 @@
 import type {
  TbankDecimal,
  TbankMoney,
  TbankInstrument,
  TbankMoney,
  TbankTimestamp,
 } from './tbank.client';
@@ -0,0 +1,68 @@
 import { Injectable } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
 import { StructuredLogger } from '../../common/logging/structured-logger.service';
 import {
  TbankAccessService,
  type TbankSyncAttempt,
 } from './tbank-access.service';
 import { TbankClient } from './tbank.client';
@Injectable()
 export class TbankMembershipService {
  private readonly processRunId = randomUUID();
  private readonly active = new Map<string, Promise<void>>();
  private reservations: Promise<unknown> = Promise.resolve();
  constructor(
    private readonly access: TbankAccessService,
    private readonly tbank: TbankClient,
    private readonly logger: StructuredLogger,
  ) {}
  request(userId: string, revision: string, force = false) {
    const reservation = this.reservations.then(async () => {
      const requested = await this.access.reserveMembership(
        userId,
        revision,
        this.processRunId,
        new Set(this.active.keys()),
        force,
      );
      if (!requested) return null;
      const { id, attemptId } = requested.work;
      if (requested.launch) {
        const done = new Promise<void>((resolve) => setImmediate(resolve))
          .then(() => this.execute({ userId, revision, id, attemptId }))
          .catch(() =>
            this.logger.event('error', 'tbank.membership.persistence_failed', {
              userId,
              code: 'TBANK_UNAVAILABLE',
            }),
          )
          .finally(() => this.active.delete(attemptId));
        this.active.set(attemptId, done);
      }
      return { id, done: this.active.get(attemptId) ?? Promise.resolve() };
    });
    this.reservations = reservation.catch(() => undefined);
    return reservation;
  }
  private async execute(attempt: TbankSyncAttempt) {
    try {
      const token = await this.access.tokenForAttempt(attempt);
      if (!token) return;
      await this.access.publishMembership(
        attempt,
        await this.tbank.getOpenAccounts(token),
        new Date(),
        true,
      );
    } catch (error) {
      await this.access.failMembership(
        attempt,
        error instanceof Error && error.message === 'INVALID_TBANK_TOKEN',
      );
    }
  }
 }
@@ -0,0 +1,33 @@
 import {
  tbankSourceNeedsRefresh,
  tbankSourceTtlMs,
 } from './tbank-source.policy';
 describe('request-driven source freshness', () => {
  it.each(Object.keys(tbankSourceTtlMs) as (keyof typeof tbankSourceTtlMs)[])(
    '%s expires at its boundary without changing source time',
    (source) => {
      const fetchedAt = new Date('2026-09-01Z');
      const ttl = tbankSourceTtlMs[source];
      expect(
        tbankSourceNeedsRefresh(
          source,
          fetchedAt,
          new Date(fetchedAt.valueOf() + ttl - 1000),
        ),
      ).toBe(false);
      expect(
        tbankSourceNeedsRefresh(
          source,
          fetchedAt,
          new Date(fetchedAt.valueOf() + ttl),
        ),
      ).toBe(true);
      expect(tbankSourceNeedsRefresh(source, fetchedAt, fetchedAt, true)).toBe(
        true,
      );
      expect(tbankSourceNeedsRefresh(source, null, fetchedAt)).toBe(true);
      expect(fetchedAt.toISOString()).toBe('2026-09-01T00:00:00.000Z');
    },
  );
 });
@@ -0,0 +1,26 @@
 // Freshness never establishes completeness. Immutable ranges are planned by
 // their coverage owners; these TTLs apply only to mutable source snapshots.
 export const tbankSourceTtlMs = {
  membership: 300_000,
  portfolio: 60_000,
  quote: 60_000,
  candleTail: 60_000,
  operationsTail: 300_000,
  metadata: 86_400_000,
  catalog: 86_400_000,
  company: 86_400_000,
  calendar: 86_400_000,
 } as const;
 export function tbankSourceNeedsRefresh(
  source: keyof typeof tbankSourceTtlMs,
  fetchedAt: Date | null,
  now: Date,
  force = false,
 ): boolean {
  return (
    force ||
    !fetchedAt ||
    now.valueOf() - fetchedAt.valueOf() >= tbankSourceTtlMs[source]
  );
 }
@@ -1,6 +1,6 @@
 import { BadRequestException, Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
-import { Environment } from '../config/env.validation';
+import { Environment } from '../../config/env.validation';
 import { TbankCrypto } from './tbank.crypto';
@Injectable()
@@ -0,0 +1,36 @@
 // Public cross-module surface. Nest providers are exported by the matching module.
 export { InstrumentMetadataService } from './instrument-metadata.service';
 export {
  TbankAccessService,
  type TbankConnectionContext,
 } from './tbank-access.service';
 export {
  type TbankBond,
  type TbankCandle,
  type TbankCoupon,
  type TbankFundamentals,
  type TbankShare,
 } from './tbank-market.types';
 export { TbankTokenService } from './tbank-token.service';
 export { supportedTbankAccounts } from './tbank-account.policy';
 export {
  TbankClient,
  type TbankDividend,
  type TbankInstrument,
  type TbankMoney,
  type TbankOperationItem,
  type TbankOperationsByCursorResponse,
  type TbankPortfolio,
  type TbankPositions,
  type TbankTimestamp,
 } from './tbank.client';
 export { TbankMembershipService } from './tbank-membership.service';
 export {
  tbankSourceTtlMs,
  tbankSourceNeedsRefresh,
 } from './tbank-source.policy';
 export { metadataKey } from './instrument-metadata.service';
 export type { MetadataIdentity } from './instrument-metadata.service';
@@ -1,5 +1,5 @@
 import { NotFoundException, ServiceUnavailableException } from '@nestjs/common';
 import { status } from '@grpc/grpc-js';
 import { NotFoundException, ServiceUnavailableException } from '@nestjs/common';
 import { TbankClient } from './tbank.client';
 describe('TbankClient operations', () => {
@@ -1,9 +1,4 @@
-import {
+import { MILLISECONDS_PER_SECOND } from '../../common/time';
  Injectable,
  NotFoundException,
  ServiceUnavailableException,
 } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import {
  ChannelCredentials,
  Client,
@@ -14,20 +9,33 @@ import {
  status,
 } from '@grpc/grpc-js';
 import { loadSync } from '@grpc/proto-loader';
-import { existsSync, readFileSync } from 'node:fs';
+import {
  Injectable,
  NotFoundException,
  ServiceUnavailableException,
 } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Environment } from '../config/env.validation';
+import { StructuredLogger } from '../../common/logging/structured-logger.service';
-import { StructuredLogger } from '../common/logging/structured-logger.service';
+import { Environment } from '../../config/env.validation';
 import type {
  TbankShare,
  TbankBond,
  TbankCoupon,
  TbankCandle,
-  TbankLastPrice,
+  TbankCoupon,
  TbankFundamentals,
  TbankLastPrice,
  TbankShare,
 } from './tbank-market.types';
 const RATE_WINDOW_MS = 1_000;
 const METADATA_MAX_ATTEMPTS = 3;
 const RPC_MAX_ATTEMPTS = 2;
 const MAX_QUEUE_SIZE = 50;
 const METADATA_RETRY_DELAY_MS = 2_000;
 const RPC_RETRY_DELAY_MS = 1_000;
 const requestDeadlineMs = 15_000;
 type Unary<Request, Response> = (
@@ -58,6 +66,9 @@ export type TbankPortfolio = {
 };
 export type TbankPositions = { money?: TbankMoney[] };
 export type TbankInstrument = {
  uid?: string;
  figi?: string;
  instrumentType?: string;
  ticker?: string;
  name?: string;
  isin?: string;
@@ -72,6 +83,7 @@ export type TbankDividend = {
 };
 export type TbankTimestamp = { seconds?: string | number; nanos?: number };
 export type TbankOperationItem = {
  state?: string;
  cursor?: string;
  id?: string;
  name?: string;
@@ -134,7 +146,7 @@ class RateLimiter {
  private drain(): void {
    const now = Date.now();
-    if (now - this.windowStartedAt >= 1000) {
+    if (now - this.windowStartedAt >= RATE_WINDOW_MS) {
      this.windowStartedAt = now;
      this.starts = 0;
    }
@@ -145,7 +157,7 @@ class RateLimiter {
    if (this.waiting.length && this.starts === this.perSecond) {
      setTimeout(
        () => this.drain(),
-        Math.max(1, 1000 - (now - this.windowStartedAt)),
+        Math.max(1, RATE_WINDOW_MS - (now - this.windowStartedAt)),
      );
    }
  }
@@ -164,10 +176,7 @@ export class TbankClient {
    config: ConfigService<Environment, true>,
    private readonly logger: StructuredLogger,
  ) {
-    const sourceProtoRoot = join(process.cwd(), 'src/tbank/proto/contracts');
+    const protoRoot = join(__dirname, 'proto/contracts');
    const protoRoot = existsSync(sourceProtoRoot)
      ? sourceProtoRoot
      : join(process.cwd(), 'dist/tbank/proto/contracts');
    const definition = loadSync(
      [
        'users.proto',
@@ -228,16 +237,17 @@ export class TbankClient {
    this.logger.info('tbank.client.configured');
  }
-  async validateToken(token: string): Promise<void> {
+  validateToken(token: string): Promise<TbankAccount[]> {
-    await this.getOpenAccounts(token);
+    return this.getOpenAccounts(token);
  }
  getOpenAccounts(token: string): Promise<TbankAccount[]> {
-    return this.call(token, this.users, 'getAccounts', {
+    return this.call<{ accounts?: TbankAccount[] }>(
-      status: 'ACCOUNT_STATUS_OPEN',
+      token,
-    }).then(
+      this.users,
-      (response: { accounts?: TbankAccount[] }) => response.accounts ?? [],
+      'getAccounts',
-    );
+      { status: 'ACCOUNT_STATUS_OPEN' },
    ).then((response) => response.accounts ?? []);
  }
  getPortfolio(token: string, accountId: string): Promise<TbankPortfolio> {
@@ -275,13 +285,16 @@ export class TbankClient {
    from: string,
    to: string,
  ): Promise<TbankDividend[]> {
-    return this.call(token, this.instruments, 'getDividends', {
+    return this.call<{ dividends?: TbankDividend[] }>(
-      instrumentId,
+      token,
-      from: { seconds: String(utcSeconds(from)) },
+      this.instruments,
-      to: { seconds: String(utcSeconds(to)) },
+      'getDividends',
-    }).then(
+      {
-      (response: { dividends?: TbankDividend[] }) => response.dividends ?? [],
+        instrumentId,
-    );
+        from: { seconds: String(utcSeconds(from)) },
        to: { seconds: String(utcSeconds(to)) },
      },
    ).then((response) => response.dividends ?? []);
  }
  findShares(token: string, query: string): Promise<TbankShare[]> {
@@ -415,8 +428,12 @@ export class TbankClient {
      'getCandles',
      {
        instrumentId: uid,
-        from: { seconds: String(Math.floor(from.valueOf() / 1000)) },
+        from: {
-        to: { seconds: String(Math.floor(to.valueOf() / 1000)) },
+          seconds: String(Math.floor(from.valueOf() / MILLISECONDS_PER_SECOND)),
        },
        to: {
          seconds: String(Math.floor(to.valueOf() / MILLISECONDS_PER_SECOND)),
        },
        interval: 'CANDLE_INTERVAL_DAY',
        limit: 2400,
      },
@@ -449,10 +466,10 @@ export class TbankClient {
    request: object,
  ): Promise<Response> {
    const metadataCall = method === 'getInstrumentBy';
-    const maxAttempts = metadataCall ? 3 : 2;
+    const maxAttempts = metadataCall ? METADATA_MAX_ATTEMPTS : RPC_MAX_ATTEMPTS;
    for (let attempts = 1; attempts <= maxAttempts; attempts += 1) {
      const startedAt = performance.now();
-      const queueFull = this.queue.size >= 50;
+      const queueFull = this.queue.size >= MAX_QUEUE_SIZE;
      try {
        if (queueFull)
          throw new ServiceUnavailableException({ code: 'TBANK_UNAVAILABLE' });
@@ -485,7 +502,12 @@ export class TbankClient {
            durationMs: Math.round(performance.now() - startedAt),
          });
          await new Promise((resolve) =>
-            setTimeout(resolve, metadataCall ? attempts * 2000 : 1000),
+            setTimeout(
              resolve,
              metadataCall
                ? attempts * METADATA_RETRY_DELAY_MS
                : RPC_RETRY_DELAY_MS,
            ),
          );
          continue;
        }
@@ -498,6 +520,7 @@ export class TbankClient {
        if (
          [status.UNAUTHENTICATED, status.PERMISSION_DENIED].includes(grpcCode)
        )
          // eslint-disable-next-line preserve-caught-error -- Discard raw upstream authentication errors at the integration boundary.
          throw new Error('INVALID_TBANK_TOKEN');
        if (
          grpcCode === status.NOT_FOUND &&
@@ -530,5 +553,5 @@ export class TbankClient {
 }
 function utcSeconds(date: string): number {
-  return Math.floor(Date.parse(`${date}T00:00:00Z`) / 1000);
+  return Math.floor(Date.parse(`${date}T00:00:00Z`) / MILLISECONDS_PER_SECOND);
 }
@@ -1,5 +1,7 @@
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
 const KEY_SIZE_BYTES = 32;
 const VERSION = 1;
 const NONCE_SIZE = 12;
 const TAG_SIZE = 16;
@@ -9,7 +11,8 @@ export class TbankCrypto {
  static fromBase64(key: string): TbankCrypto {
    const decoded = Buffer.from(key, 'base64');
-    if (decoded.length !== 32) throw new Error('Invalid token encryption key');
+    if (decoded.length !== KEY_SIZE_BYTES)
      throw new Error('Invalid token encryption key');
    return new TbankCrypto(decoded);
  }
@@ -0,0 +1,26 @@
 import { Module } from '@nestjs/common';
 import { TbankMembershipService } from './tbank-membership.service';
 import { InstrumentMetadataRepository } from './instrument-metadata.repository';
 import { InstrumentMetadataService } from './instrument-metadata.service';
 import { TbankAccessService } from './tbank-access.service';
 import { TbankTokenService } from './tbank-token.service';
 import { TbankClient } from './tbank.client';
@Module({
  providers: [
    TbankClient,
    TbankTokenService,
    TbankAccessService,
    TbankMembershipService,
    InstrumentMetadataService,
    InstrumentMetadataRepository,
  ],
  exports: [
    TbankClient,
    TbankTokenService,
    TbankAccessService,
    TbankMembershipService,
    InstrumentMetadataService,
  ],
 })
 export class TbankModule {}
@@ -2,7 +2,8 @@ import { INestApplication, ValidationPipe } from '@nestjs/common';
 import { NestFactory } from '@nestjs/core';
 import cookieParser from 'cookie-parser';
 import { ConfigService } from '@nestjs/config';
-import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { SwaggerModule } from '@nestjs/swagger';
 import { API_PREFIX, createOpenApiDocument } from './openapi';
 import { Logger } from 'nestjs-pino';
 import { AppModule } from './app.module';
 import { HttpExceptionFilter } from './common/filters/http-exception.filter';
@@ -21,7 +22,7 @@ export function configureApp(app: INestApplication): void {
    credentials: true,
    exposedHeaders: ['X-Request-ID'],
  });
-  app.setGlobalPrefix('api/v1');
+  app.setGlobalPrefix(API_PREFIX);
  app.use(cookieParser());
  const requestLogging = app.get(RequestLoggingMiddleware);
  app.use(requestLogging.use.bind(requestLogging));
@@ -36,13 +37,7 @@ async function bootstrap() {
  const config = app.get<ConfigService<Environment, true>>(ConfigService);
  if (shouldExposeSwagger(process.env['NODE_ENV'])) {
-    const document = SwaggerModule.createDocument(
+    const document = createOpenApiDocument(app);
      app,
      new DocumentBuilder()
        .setTitle('WealthLedger API')
        .setVersion('v1')
        .build(),
    );
    SwaggerModule.setup('api/docs', app, document);
  }
@@ -7,7 +7,7 @@ jest.mock('bcrypt', () => ({
  compare: jest.fn(() => Promise.resolve(true)),
 }));
-jest.mock('../prisma/prisma.service', () => ({
+jest.mock('../../../prisma/prisma.service', () => ({
  PrismaService: class PrismaService {},
 }));
@@ -6,10 +6,13 @@ import {
 import { JwtService } from '@nestjs/jwt';
 import * as bcrypt from 'bcrypt';
 import { createHash, randomUUID } from 'crypto';
-import { Session, User } from '../../generated/prisma/client';
+import { Session, User } from '../../../../generated/prisma/client';
-import { PrismaService } from '../prisma/prisma.service';
+import { PrismaService } from '../../../prisma/prisma.service';
 import { AuthUser, RefreshPayload } from './auth.types';
 const PASSWORD_HASH_ROUNDS = 12;
 const REFRESH_TTL_MS = 604_800_000;
 const ACCESS_TTL = '15m';
 const REFRESH_TTL = '7d';
 const DUMMY_PASSWORD_HASH =
@@ -39,7 +42,7 @@ export class AuthService {
        data: {
          id: randomUUID(),
          email: normalizedEmail,
-          passwordHash: await bcrypt.hash(password, 12),
+          passwordHash: await bcrypt.hash(password, PASSWORD_HASH_ROUNDS),
        },
      });
    } catch (error) {
@@ -162,7 +165,7 @@ export class AuthService {
    );
    const data = {
      refreshTokenHash: this.hash(refreshToken),
-      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+      expiresAt: new Date(Date.now() + REFRESH_TTL_MS),
    };
    if (expectedRefreshTokenHash) {
      const updated = await this.prisma.session.updateMany({
@@ -0,0 +1,3 @@
 // Public cross-module surface. Nest providers are exported by the matching module.
 export { type AccessPayload } from './application/auth.types';
 export { JwtAuthGuard } from './presentation/jwt-auth.guard';
@@ -2,11 +2,11 @@ import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { JwtModule } from '@nestjs/jwt';
 import { PassportModule } from '@nestjs/passport';
-import { Environment } from '../config/env.validation';
+import { Environment } from '../../config/env.validation';
-import { AuthController } from './auth.controller';
+import { AuthController } from './presentation/auth.controller';
-import { AuthService } from './auth.service';
+import { AuthService } from './application/auth.service';
-import { JwtAuthGuard } from './jwt-auth.guard';
+import { JwtAuthGuard } from './presentation/jwt-auth.guard';
-import { JwtStrategy } from './jwt.strategy';
+import { JwtStrategy } from './infrastructure/jwt.strategy';
@Module({
  imports: [
@@ -19,6 +19,7 @@ import { JwtStrategy } from './jwt.strategy';
      }),
    }),
  ],
  exports: [JwtAuthGuard],
  controllers: [AuthController],
  providers: [AuthService, JwtStrategy, JwtAuthGuard],
 })
@@ -2,8 +2,8 @@ import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { PassportStrategy } from '@nestjs/passport';
 import { ExtractJwt, Strategy } from 'passport-jwt';
-import { Environment } from '../config/env.validation';
+import { Environment } from '../../../config/env.validation';
-import { AccessPayload } from './auth.types';
+import { AccessPayload } from '../application/auth.types';
@Injectable()
 export class JwtStrategy extends PassportStrategy(Strategy) {
@@ -1,6 +1,6 @@
 import { HTTP_CODE_METADATA } from '@nestjs/common/constants';
-jest.mock('./auth.service', () => ({
+jest.mock('../application/auth.service', () => ({
  AuthService: class AuthService {},
 }));
@@ -3,11 +3,12 @@ import {
  Controller,
  Get,
  HttpCode,
  HttpStatus,
  Post,
  Req,
  Res,
  UseGuards,
  UnauthorizedException,
  UseGuards,
 } from '@nestjs/common';
 import {
  ApiBearerAuth,
@@ -17,29 +18,29 @@ import {
  ApiTags,
 } from '@nestjs/swagger';
 import type { Request, Response } from 'express';
 import { ApiProblemResponses } from '../../../common/decorators/api-safe-error-response.decorator';
 import { CredentialsDto } from './auth.dto';
-import { AuthService } from './auth.service';
+import { AuthService } from '../application/auth.service';
-import { AccessPayload } from './auth.types';
+import { AccessPayload } from '../application/auth.types';
 import { JwtAuthGuard } from './jwt-auth.guard';
 import { ApiProblemResponses } from '../common/decorators/api-safe-error-response.decorator';
 const REFRESH_COOKIE = 'refresh_token';
 const COOKIE_PATH = '/api/v1/auth';
 class UserDto {
  @ApiProperty()
-  id: string;
+  declare id: string;
  @ApiProperty()
-  email: string;
+  declare email: string;
 }
 class AuthenticationDto {
  @ApiProperty()
-  accessToken: string;
+  declare accessToken: string;
  @ApiProperty({ type: UserDto })
-  user: UserDto;
+  declare user: UserDto;
 }
@ApiTags('auth')
@@ -49,7 +50,7 @@ export class AuthController {
  constructor(private readonly auth: AuthService) {}
  @Post('register')
-  @HttpCode(200)
+  @HttpCode(HttpStatus.OK)
  @ApiOkResponse({ type: AuthenticationDto })
  async register(
    @Body() credentials: CredentialsDto,
@@ -62,7 +63,7 @@ export class AuthController {
  }
  @Post('login')
-  @HttpCode(200)
+  @HttpCode(HttpStatus.OK)
  @ApiOkResponse({ type: AuthenticationDto })
  async login(
    @Body() credentials: CredentialsDto,
@@ -75,7 +76,7 @@ export class AuthController {
  }
  @Post('refresh')
-  @HttpCode(200)
+  @HttpCode(HttpStatus.OK)
  @ApiOkResponse({ type: AuthenticationDto })
  async refresh(
    @Req() request: Request,
@@ -92,7 +93,7 @@ export class AuthController {
  }
  @Post('logout')
-  @HttpCode(204)
+  @HttpCode(HttpStatus.NO_CONTENT)
  @ApiNoContentResponse()
  async logout(
    @Req() request: Request,
@@ -1,26 +1,32 @@
 import { ApiProperty } from '@nestjs/swagger';
 import { Transform } from 'class-transformer';
 import {
  IsString,
  MinLength,
  Validate,
  ValidatorConstraint,
 } from 'class-validator';
-import { Transform } from 'class-transformer';
+
-import { ApiProperty } from '@nestjs/swagger';
+const MAX_EMAIL_LENGTH = 254;
 const ASCII_SPACE = 32;
 const ASCII_DELETE = 127;
 const MIN_PASSWORD_LENGTH = 12;
 const MAX_PASSWORD_BYTES = 72;
@ValidatorConstraint({ name: 'email' })
 class EmailConstraint {
  validate(value: unknown): boolean {
    return (
      typeof value === 'string' &&
-      value.length <= 254 &&
+      value.length <= MAX_EMAIL_LENGTH &&
      value.split('@').length === 2 &&
      !value
        .split('')
        .some(
          (character) =>
            /\s/.test(character) ||
-            character.charCodeAt(0) < 32 ||
+            character.charCodeAt(0) < ASCII_SPACE ||
-            character.charCodeAt(0) === 127,
+            character.charCodeAt(0) === ASCII_DELETE,
        ) &&
      value.split('@').every(Boolean)
    );
@@ -33,7 +39,10 @@ class EmailConstraint {
@ValidatorConstraint({ name: 'passwordBytes' })
 class PasswordBytesConstraint {
  validate(value: unknown): boolean {
-    return typeof value === 'string' && Buffer.byteLength(value, 'utf8') <= 72;
+    return (
      typeof value === 'string' &&
      Buffer.byteLength(value, 'utf8') <= MAX_PASSWORD_BYTES
    );
  }
  defaultMessage(): string {
    return 'must not exceed 72 UTF-8 bytes';
@@ -47,11 +56,15 @@ export class CredentialsDto {
    typeof value === 'string' ? value.trim().toLowerCase() : value,
  )
  @Validate(EmailConstraint)
-  email: string;
+  declare email: string;
-  @ApiProperty({ minLength: 12, maxLength: 72, example: 'a secure password' })
+  @ApiProperty({
    minLength: MIN_PASSWORD_LENGTH,
    maxLength: MAX_PASSWORD_BYTES,
    example: 'a secure password',
  })
  @IsString()
-  @MinLength(12)
+  @MinLength(MIN_PASSWORD_LENGTH)
  @Validate(PasswordBytesConstraint)
-  password: string;
+  declare password: string;
 }
@@ -1,7 +1,7 @@
 import { ExecutionContext, Injectable } from '@nestjs/common';
 import { AuthGuard } from '@nestjs/passport';
-import { RequestContextService } from '../common/logging/request-context.service';
+import { RequestContextService } from '../../../common/logging/request-context.service';
-import { AccessPayload } from './auth.types';
+import { AccessPayload } from '../application/auth.types';
@Injectable()
 export class JwtAuthGuard extends AuthGuard('jwt') {
@@ -0,0 +1,135 @@
 import {
  MAX_CARD_NAME_LENGTH,
  MAX_OPERATION_DESCRIPTION_LENGTH,
 } from '../domain/bank-card-limits';
 import {
  BadRequestException,
  ConflictException,
  NotFoundException,
 } from '@nestjs/common';
 import { createHash } from 'node:crypto';
 import {
  bankPaymentSystems,
  BankPeriodQueryDto,
  CreateBankCardDto,
  CreateBankOperationDto,
 } from '../presentation/bank-card.dto';
 import { isCalendarDate, moscowToday } from '../domain/bank-card.calculations';
 import { parseRubMoney } from '../domain/rub-money';
 export const BankErrorCode = {
  InvalidInput: 'BANK_INVALID_INPUT',
  VersionConflict: 'BANK_VERSION_CONFLICT',
  NotFound: 'BANK_NOT_FOUND',
  InvalidMoney: 'BANK_INVALID_MONEY',
  InvalidDate: 'BANK_INVALID_DATE',
  ImmutableOperation: 'BANK_IMMUTABLE_OPERATION',
  InvalidRefund: 'BANK_INVALID_REFUND',
  RefundLimit: 'BANK_REFUND_LIMIT',
  DependentRefunds: 'BANK_DEPENDENT_REFUNDS',
  IntentConflict: 'BANK_INTENT_CONFLICT',
  OperationDeleted: 'BANK_OPERATION_DELETED',
  CardArchived: 'BANK_CARD_ARCHIVED',
  OpeningDateConflict: 'BANK_OPENING_DATE_CONFLICT',
  WriteConflict: 'BANK_WRITE_CONFLICT',
  DuplicateCategory: 'BANK_DUPLICATE_CATEGORY',
 } as const;
 export type BankErrorCode = (typeof BankErrorCode)[keyof typeof BankErrorCode];
 export function fail(code: BankErrorCode = BankErrorCode.InvalidInput): never {
  throw new BadRequestException({ code });
 }
 export function periodBounds(query: BankPeriodQueryDto) {
  if (query.month && !query.from && !query.to) {
    const from = `${query.month}-01`;
    if (!isCalendarDate(from)) return fail();
    const end = new Date(`${from}T00:00:00Z`);
    end.setUTCMonth(end.getUTCMonth() + 1, 0);
    return { from, to: end.toISOString().slice(0, 10) };
  }
  if (
    query.month ||
    !query.from ||
    !query.to ||
    !isCalendarDate(query.from) ||
    !isCalendarDate(query.to) ||
    query.from > query.to
  )
    return fail();
  return { from: query.from, to: query.to };
 }
 export function conflict(
  code: BankErrorCode = BankErrorCode.VersionConflict,
 ): never {
  throw new ConflictException({ code });
 }
 export function missing(): never {
  throw new NotFoundException({ code: BankErrorCode.NotFound });
 }
 export const fingerprint = (value: unknown) =>
  createHash('sha256')
    .update(
      JSON.stringify(value, (_key, item: unknown) =>
        typeof item === 'bigint' ? item.toString() : item,
      ),
    )
    .digest('hex');
 export function amount(
  value: Parameters<typeof parseRubMoney>[0],
  positive = false,
 ) {
  try {
    return parseRubMoney(value, positive);
  } catch {
    return fail(BankErrorCode.InvalidMoney);
  }
 }
 export function calendar(value: string) {
  if (!isCalendarDate(value)) fail(BankErrorCode.InvalidDate);
  return value;
 }
 export function currentDate(value: string) {
  calendar(value);
  if (value > moscowToday()) fail(BankErrorCode.InvalidDate);
 }
 export function name(value: string, max: number) {
  if (typeof value !== 'string' || !value.trim() || value.trim().length > max)
    fail();
  return value.trim();
 }
 export function cardInput(dto: CreateBankCardDto) {
  const bankName = dto.bankName?.trim() || null;
  if (bankName && bankName.length > MAX_CARD_NAME_LENGTH) fail();
  if (dto.lastFour != null && !/^\d{4}$/.test(dto.lastFour)) fail();
  if (
    dto.paymentSystem != null &&
    !bankPaymentSystems.some((system) => system === dto.paymentSystem)
  )
    fail();
  return {
    ...(dto.paymentSystem == null ? {} : { paymentSystem: dto.paymentSystem }),
    name: name(dto.name, MAX_CARD_NAME_LENGTH),
    bankName,
    lastFour: dto.lastFour || null,
    openingBalanceKopecks: amount(dto.openingBalance),
    openingDate: calendar(dto.openingDate),
  };
 }
 export function operationInput(dto: CreateBankOperationDto) {
  if (
    dto.description != null &&
    (typeof dto.description !== 'string' ||
      dto.description.length > MAX_OPERATION_DESCRIPTION_LENGTH)
  )
    fail();
  return {
    kind: dto.kind,
    cardId: dto.cardId,
    targetCardId: dto.targetCardId ?? null,
    categoryId: dto.categoryId ?? null,
    originalExpenseId: dto.originalExpenseId ?? null,
    amountKopecks: amount(dto.amount, true),
    date: calendar(dto.date),
    description: dto.description || null,
  };
 }
@@ -0,0 +1,147 @@
 import { Injectable } from '@nestjs/common';
 import { BankCard, Prisma } from '../../../../../generated/prisma/client';
 import { PrismaService } from '../../../../prisma/prisma.service';
 import {
  BankCardDto,
  CreateBankCardDto,
  UpdateBankCardDto,
 } from '../presentation/bank-card.dto';
 import { bankBalance } from '../domain/bank-card.calculations';
 import { rubMoney } from '../domain/rub-money';
 import {
  cardInput,
  BankErrorCode,
  conflict,
  currentDate,
  fail,
  fingerprint,
  missing,
 } from './bank-card-input';
 import { BankCardsRepository } from '../infrastructure/bank-cards.repository';
 type Tx = Prisma.TransactionClient;
@Injectable()
 export class BankCardsService {
  constructor(
    private readonly prisma: PrismaService,
    private readonly repository: BankCardsRepository,
  ) {}
  private async cardView(tx: Tx, card: BankCard): Promise<BankCardDto> {
    const rows = await tx.bankCardOperation.findMany({
      where: {
        userId: card.userId,
        deletedAt: null,
        OR: [{ cardId: card.id }, { targetCardId: card.id }],
      },
    });
    return {
      id: card.id,
      name: card.name,
      bankName: card.bankName,
      lastFour: card.lastFour,
      paymentSystem: card.paymentSystem,
      openingDate: card.openingDate,
      openingBalance: rubMoney(card.openingBalanceKopecks),
      balance: rubMoney(bankBalance(card.id, card.openingBalanceKopecks, rows)),
      version: card.version,
      archivedAt: card.archivedAt?.toISOString() ?? null,
    };
  }
  list(userId: string, includeArchived = false) {
    return this.prisma.$transaction(async (tx) =>
      Promise.all(
        (
          await tx.bankCard.findMany({
            where: { userId, ...(includeArchived ? {} : { archivedAt: null }) },
            orderBy: [{ createdAt: 'asc' }, { id: 'asc' }],
          })
        ).map((card) => this.cardView(tx, card)),
      ),
    );
  }
  get(userId: string, id: string) {
    return this.prisma.$transaction(async (tx) =>
      this.cardView(tx, await this.repository.card(tx, userId, id)),
    );
  }
  createCard(userId: string, dto: CreateBankCardDto) {
    const input = cardInput(dto),
      hash = fingerprint(input);
    return this.repository.write(async (tx) => {
      const existing = await tx.bankCard.findUnique({ where: { id: dto.id } });
      if (existing) {
        if (existing.userId !== userId) missing();
        if (existing.createFingerprint !== hash)
          conflict(BankErrorCode.IntentConflict);
        return this.cardView(tx, existing);
      }
      currentDate(input.openingDate);
      await this.repository.seed(tx, userId);
      return this.cardView(
        tx,
        await tx.bankCard.create({
          data: { ...input, id: dto.id, userId, createFingerprint: hash },
        }),
      );
    });
  }
  updateCard(userId: string, id: string, dto: UpdateBankCardDto) {
    return this.repository.write(async (tx) => {
      const previous = await this.repository.card(tx, userId, id);
      if (previous.version !== dto.version) conflict();
      const input = cardInput({
        id,
        name: dto.name ?? previous.name,
        bankName:
          dto.bankName === undefined
            ? (previous.bankName ?? undefined)
            : (dto.bankName ?? undefined),
        lastFour:
          dto.lastFour === undefined
            ? (previous.lastFour ?? undefined)
            : (dto.lastFour ?? undefined),
        paymentSystem:
          dto.paymentSystem === undefined
            ? previous.paymentSystem
            : dto.paymentSystem,
        openingBalance:
          dto.openingBalance ?? rubMoney(previous.openingBalanceKopecks),
        openingDate: dto.openingDate ?? previous.openingDate,
      });
      const financial =
        input.openingBalanceKopecks !== previous.openingBalanceKopecks ||
        input.openingDate !== previous.openingDate;
      if (financial && previous.archivedAt)
        conflict(BankErrorCode.CardArchived);
      currentDate(input.openingDate);
      if (
        await tx.bankCardOperation.findFirst({
          where: {
            userId,
            deletedAt: null,
            date: { lt: input.openingDate },
            OR: [{ cardId: id }, { targetCardId: id }],
          },
        })
      )
        fail(BankErrorCode.OpeningDateConflict);
      const changed = await tx.bankCard.updateMany({
        where: { id, userId, version: dto.version },
        data: {
          ...input,
          paymentSystem: input.paymentSystem ?? null,
          version: { increment: 1 },
          ...(dto.archived === undefined
            ? {}
            : {
                archivedAt: dto.archived
                  ? (previous.archivedAt ?? new Date())
                  : null,
              }),
        },
      });
      if (changed.count !== 1) conflict();
      return this.cardView(tx, await this.repository.card(tx, userId, id));
    });
  }
 }
@@ -0,0 +1,343 @@
 import { BankOperationKind } from '../domain/bank-operation-kind';
 import { GoneException, Injectable } from '@nestjs/common';
 import {
  BankCardOperation,
  Prisma,
 } from '../../../../../generated/prisma/client';
 import { PrismaService } from '../../../../prisma/prisma.service';
 import {
  BankOperationDto,
  DEFAULT_BANK_PAGE_SIZE,
  BankOperationsQueryDto,
  BankPageQueryDto,
  CreateBankOperationDto,
  UpdateBankOperationDto,
 } from '../presentation/bank-card.dto';
 import { rubMoney } from '../domain/rub-money';
 import {
  BankErrorCode,
  conflict,
  currentDate,
  fail,
  fingerprint,
  missing,
  operationInput,
  periodBounds,
 } from './bank-card-input';
 import { BankCardsRepository } from '../infrastructure/bank-cards.repository';
 type Tx = Prisma.TransactionClient;
@Injectable()
 export class BankOperationsService {
  constructor(
    private readonly prisma: PrismaService,
    private readonly repository: BankCardsRepository,
  ) {}
  private async operationView(
    tx: Tx,
    row: BankCardOperation,
  ): Promise<BankOperationDto> {
    const card = await this.repository.card(tx, row.userId, row.cardId);
    const target = row.targetCardId
      ? await this.repository.card(tx, row.userId, row.targetCardId)
      : null;
    const source = row.originalExpenseId
      ? await this.repository.operation(tx, row.userId, row.originalExpenseId)
      : null;
    const categoryId = source?.categoryId ?? row.categoryId;
    const category = categoryId
      ? await tx.expenseCategory.findFirst({
          where: { id: categoryId, userId: row.userId },
        })
      : null;
    const refunds =
      row.kind === BankOperationKind.Expense || source
        ? await tx.bankCardOperation.findMany({
            where: {
              userId: row.userId,
              originalExpenseId: source?.id ?? row.id,
              deletedAt: null,
              ...(source ? { id: { not: row.id } } : {}),
            },
          })
        : [];
    return {
      id: row.id,
      kind: row.kind as BankOperationDto['kind'],
      cardId: row.cardId,
      cardName: card.name,
      targetCardId: row.targetCardId,
      targetCardName: target?.name ?? null,
      categoryId,
      categoryName: category?.name ?? null,
      originalExpenseId: row.originalExpenseId,
      amount: rubMoney(row.amountKopecks),
      availableRefund:
        row.kind === BankOperationKind.Expense || source
          ? rubMoney(
              (source?.amountKopecks ?? row.amountKopecks) -
                refunds.reduce((sum, r) => sum + r.amountKopecks, 0n),
            )
          : null,
      date: row.date,
      description: row.description,
      version: row.version,
      createdAt: row.createdAt.toISOString(),
    };
  }
  private async validateOperation(
    tx: Tx,
    userId: string,
    input: ReturnType<typeof operationInput>,
    old?: BankCardOperation,
  ) {
    const cards = new Set(
      [input.cardId, input.targetCardId, old?.cardId, old?.targetCardId].filter(
        (id): id is string => Boolean(id),
      ),
    );
    currentDate(input.date);
    for (const id of cards) {
      const card = await this.repository.card(tx, userId, id, true);
      if (
        (id === input.cardId || id === input.targetCardId) &&
        input.date < card.openingDate
      )
        fail(BankErrorCode.InvalidDate);
    }
    if (
      old &&
      (old.kind !== input.kind ||
        old.originalExpenseId !== input.originalExpenseId)
    )
      fail(BankErrorCode.ImmutableOperation);
    if (input.kind === BankOperationKind.Transfer) {
      if (
        !input.targetCardId ||
        input.targetCardId === input.cardId ||
        input.categoryId ||
        input.originalExpenseId
      )
        fail();
    } else if (input.targetCardId) fail();
    if (input.kind === BankOperationKind.Expense) {
      if (input.originalExpenseId) fail();
      if (!input.categoryId) {
        const category = await tx.expenseCategory.findUnique({
          where: { userId_seedKey: { userId, seedKey: 'other' } },
        });
        if (!category) missing();
        input.categoryId = category.id;
      }
      if (
        !(await tx.expenseCategory.findFirst({
          where: { userId, id: input.categoryId },
        }))
      )
        missing();
    } else if (input.categoryId) fail();
    if (input.kind !== BankOperationKind.Refund && input.originalExpenseId)
      fail();
    if (input.kind === BankOperationKind.Refund) {
      if (!input.originalExpenseId) fail();
      const source = await this.repository.operation(
        tx,
        userId,
        input.originalExpenseId,
      );
      if (
        source.deletedAt ||
        source.kind !== BankOperationKind.Expense ||
        source.cardId !== input.cardId
      )
        fail(BankErrorCode.InvalidRefund);
      if (
        (
          await tx.bankCardOperation.updateMany({
            where: {
              id: source.id,
              userId,
              version: source.version,
              deletedAt: null,
            },
            data: { version: { increment: 1 } },
          })
        ).count !== 1
      )
        conflict();
      const refunds = await tx.bankCardOperation.findMany({
        where: {
          userId,
          originalExpenseId: source.id,
          deletedAt: null,
          ...(old ? { id: { not: old.id } } : {}),
        },
      });
      if (input.date < source.date) fail(BankErrorCode.InvalidDate);
      if (
        refunds.reduce((sum, r) => sum + r.amountKopecks, 0n) +
          input.amountKopecks >
        source.amountKopecks
      )
        conflict(BankErrorCode.RefundLimit);
    }
    if (old?.kind === BankOperationKind.Expense) {
      const refunds = await tx.bankCardOperation.findMany({
        where: { userId, originalExpenseId: old.id, deletedAt: null },
      });
      if (
        refunds.length &&
        (input.cardId !== old.cardId ||
          refunds.some((row) => row.date < input.date) ||
          refunds.reduce((sum, row) => sum + row.amountKopecks, 0n) >
            input.amountKopecks)
      )
        conflict(BankErrorCode.DependentRefunds);
    }
  }
  createOperation(userId: string, dto: CreateBankOperationDto) {
    const normalized = operationInput(dto),
      hash = fingerprint(normalized);
    return this.repository.write(async (tx) => {
      const existing = await tx.bankCardOperation.findUnique({
        where: { id: dto.id },
      });
      if (existing) {
        if (existing.userId !== userId) missing();
        if (existing.createFingerprint !== hash)
          conflict(BankErrorCode.IntentConflict);
        if (existing.deletedAt)
          throw new GoneException({ code: BankErrorCode.OperationDeleted });
        return this.operationView(tx, existing);
      }
      const input = { ...normalized };
      await this.validateOperation(tx, userId, input);
      return this.operationView(
        tx,
        await tx.bankCardOperation.create({
          data: { ...input, id: dto.id, userId, createFingerprint: hash },
        }),
      );
    });
  }
  getOperation(userId: string, id: string) {
    return this.prisma.$transaction(async (tx) => {
      const row = await this.repository.operation(tx, userId, id);
      if (row.deletedAt) missing();
      return this.operationView(tx, row);
    });
  }
  updateOperation(userId: string, id: string, dto: UpdateBankOperationDto) {
    return this.repository.write(async (tx) => {
      const old = await this.repository.operation(tx, userId, id);
      if (old.deletedAt) missing();
      if (old.version !== dto.version) conflict();
      const input = operationInput({
        id,
        kind: dto.kind ?? (old.kind as CreateBankOperationDto['kind']),
        cardId: dto.cardId ?? old.cardId,
        targetCardId: dto.targetCardId ?? old.targetCardId ?? undefined,
        categoryId: dto.categoryId ?? old.categoryId ?? undefined,
        originalExpenseId:
          dto.originalExpenseId ?? old.originalExpenseId ?? undefined,
        amount: dto.amount ?? rubMoney(old.amountKopecks),
        date: dto.date ?? old.date,
        description: dto.description ?? old.description ?? undefined,
      });
      await this.validateOperation(tx, userId, input, old);
      if (
        (
          await tx.bankCardOperation.updateMany({
            where: { id, userId, version: dto.version, deletedAt: null },
            data: { ...input, version: { increment: 1 } },
          })
        ).count !== 1
      )
        conflict();
      return this.operationView(
        tx,
        await this.repository.operation(tx, userId, id),
      );
    });
  }
  deleteOperation(userId: string, id: string, version: number) {
    return this.repository.write(async (tx) => {
      const row = await this.repository.operation(tx, userId, id);
      if (row.deletedAt) return;
      if (row.version !== version) conflict();
      await this.repository.card(tx, userId, row.cardId, true);
      if (row.targetCardId)
        await this.repository.card(tx, userId, row.targetCardId, true);
      if (
        row.kind === BankOperationKind.Expense &&
        (await tx.bankCardOperation.findFirst({
          where: { userId, originalExpenseId: id, deletedAt: null },
        }))
      )
        conflict(BankErrorCode.DependentRefunds);
      if (row.originalExpenseId) {
        const source = await this.repository.operation(
          tx,
          userId,
          row.originalExpenseId,
        );
        if (
          (
            await tx.bankCardOperation.updateMany({
              where: { id: source.id, userId, version: source.version },
              data: { version: { increment: 1 } },
            })
          ).count !== 1
        )
          conflict();
      }
      if (
        (
          await tx.bankCardOperation.updateMany({
            where: { id, userId, version, deletedAt: null },
            data: { deletedAt: new Date(), version: { increment: 1 } },
          })
        ).count !== 1
      )
        conflict();
    });
  }
  history(
    userId: string,
    id: string,
    query: BankOperationsQueryDto | BankPageQueryDto,
    expenses = false,
  ) {
    const period = expenses
      ? undefined
      : periodBounds(query as BankOperationsQueryDto);
    return this.prisma.$transaction(async (tx) => {
      await this.repository.card(tx, userId, id);
      const page = query.page ?? 1,
        limit = query.limit ?? DEFAULT_BANK_PAGE_SIZE;
      const where: Prisma.BankCardOperationWhereInput = {
        userId,
        deletedAt: null,
        OR: [{ cardId: id }, { targetCardId: id }],
        ...(period
          ? { date: { gte: period.from, lte: period.to } }
          : { kind: BankOperationKind.Expense }),
      };
      const total = await tx.bankCardOperation.count({ where });
      const rows = await tx.bankCardOperation.findMany({
        where,
        orderBy: [{ date: 'desc' }, { createdAt: 'desc' }, { id: 'desc' }],
        skip: (page - 1) * limit,
        take: limit,
      });
      return {
        items: await Promise.all(
          rows.map((row) => this.operationView(tx, row)),
        ),
        total,
        page,
        hasNext: page * limit < total,
      };
    });
  }
 }
@@ -0,0 +1,73 @@
 import { MAX_CATEGORY_NAME_LENGTH } from '../domain/bank-card-limits';
 import { Injectable } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
 import { PrismaService } from '../../../../prisma/prisma.service';
 import { conflict, missing, name } from './bank-card-input';
 import { BankCardsRepository } from '../infrastructure/bank-cards.repository';
@Injectable()
 export class ExpenseCategoriesService {
  constructor(
    private readonly prisma: PrismaService,
    private readonly repository: BankCardsRepository,
  ) {}
  async categories(userId: string) {
    return (
      await this.prisma.expenseCategory.findMany({
        where: { userId },
        orderBy: [{ name: 'asc' }, { id: 'asc' }],
      })
    ).map(({ id, name, seedKey, version }) => ({
      id,
      name,
      isDefault: seedKey === 'other',
      version,
    }));
  }
  createCategory(userId: string, value: string) {
    const label = name(value, MAX_CATEGORY_NAME_LENGTH);
    return this.repository.write(async (tx) => {
      await this.repository.seed(tx, userId);
      const row = await tx.expenseCategory.create({
        data: {
          id: randomUUID(),
          userId,
          name: label,
          nameKey: label.toLocaleLowerCase('ru-RU'),
        },
      });
      return {
        id: row.id,
        name: row.name,
        isDefault: false,
        version: row.version,
      };
    });
  }
  updateCategory(userId: string, id: string, value: string, version: number) {
    const label = name(value, MAX_CATEGORY_NAME_LENGTH);
    return this.repository.write(async (tx) => {
      const row = await tx.expenseCategory.findFirst({ where: { id, userId } });
      if (!row) missing();
      if (
        (
          await tx.expenseCategory.updateMany({
            where: { id, userId, version },
            data: {
              name: label,
              nameKey: label.toLocaleLowerCase('ru-RU'),
              version: { increment: 1 },
            },
          })
        ).count !== 1
      )
        conflict();
      return {
        id,
        name: label,
        isDefault: row.seedKey === 'other',
        version: version + 1,
      };
    });
  }
 }
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
ksv741	92f216d520	chore(release): 1.0.0 Backend security / security (push) Successful in 8s Details Backend image / publish (push) Successful in 12m35s Details Conventional commits / commits (pull_request) Successful in 29s Details Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 9m53s Details Backend verify / verify (push) Successful in 9m56s Details	2026-09-26 22:33:48 +03:00
ksv741	e4232138d0	test: prove reads finish before source synchronization Conventional commits / commits (pull_request) Successful in 31s Details Backend security / security (pull_request) Successful in 9s Details Backend verify / verify (pull_request) Successful in 10m47s Details Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Failing after 12m14s Details Block synthetic upstream with an explicit barrier instead of comparing total HTTP batch time with a two-second timer. Keep the 500 ms server p95 gate and RPC assertions unchanged.	2026-09-26 21:45:50 +03:00
ksv741	d6e6c4ace5	feat!: persist T-Bank data and synchronize reads Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Failing after 10m45s Details Conventional commits / commits (pull_request) Successful in 29s Details Backend security / security (pull_request) Successful in 8s Details Backend verify / verify (pull_request) Failing after 10m37s Details Store account membership, portfolio, operations, forecasts and market sources in SQLite. Coalesce scoped refreshes, fence connection revisions, preserve complete financial snapshots and stabilize operation period state. BREAKING CHANGE: investment reads return data/meta resource envelopes and locally persisted snapshots; consumers must use the matching OpenAPI contract and explicit synchronization endpoints.	2026-09-26 21:29:15 +03:00
ksv741	0862d56c4e	chore(release): 0.2.3 Backend image / publish (push) Successful in 5m20s Details Conventional commits / commits (pull_request) Successful in 28s Details Backend security / security (pull_request) Successful in 9s Details Backend verify / verify (pull_request) Successful in 2m32s Details Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Successful in 3m36s Details	2026-09-19 16:25:12 +03:00
ksv741	7c0150c56b	fix: correct Nexus routing and SonarQube host	2026-09-19 16:24:08 +03:00
ksv741	39f2ce5bc4	chore(release): 0.2.2 Backend image / publish (push) Failing after 2m30s Details Conventional commits / commits (pull_request) Successful in 28s Details Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 2m27s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Failing after 2m55s Details	2026-09-19 15:07:57 +03:00
ksv741	4c916829ea	fix: update Nexus registry host Conventional commits / commits (pull_request) Successful in 26s Details Backend security / security (pull_request) Successful in 8s Details Backend verify / verify (pull_request) Successful in 2m29s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Failing after 3m4s Details	2026-09-19 14:51:27 +03:00
ksv741	386c91670e	chore(release): 0.2.1 Conventional commits / commits (pull_request) Successful in 24s Details Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 2m14s Details Backend image / publish (push) Failing after 2m28s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Failing after 2m46s Details	2026-09-18 08:12:28 +03:00
ksv741	9437b6a311	docs: use shared Nexus account #25 Backend security / security (pull_request) Successful in 8s Details Backend verify / verify (pull_request) Successful in 2m25s Details Conventional commits / commits (pull_request) Successful in 28s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 9m3s Details	2026-09-17 20:53:04 +03:00
ksv741	0ec7ae51af	ci: publish backend images to Nexus #25 Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 2m27s Details Backend security / security (pull_request) Successful in 8s Details Backend verify / verify (pull_request) Successful in 2m22s Details Conventional commits / commits (pull_request) Failing after 22s Details	2026-09-17 20:41:23 +03:00
ksv741	1946192be9	ci: add backend SonarQube analysis #23 Conventional commits / commits (pull_request) Successful in 27s Details Backend security / security (pull_request) Successful in 1m14s Details Backend verify / verify (pull_request) Successful in 2m39s Details Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Successful in 4m26s Details	2026-09-16 21:15:21 +03:00
ksv741	0557f4ad1f	chore(release): 0.2.0 Backend image / publish (push) Successful in 5m29s Details Conventional commits / commits (pull_request) Successful in 27s Details Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 2m28s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 2m29s Details	2026-09-16 11:35:52 +03:00
ksv741	d7cb7e3e20	fix: allow reviewed container smoke fixture Conventional commits / commits (pull_request) Successful in 26s Details Backend security / security (pull_request) Successful in 6s Details Backend verify / verify (pull_request) Successful in 2m19s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 2m22s Details	2026-09-16 10:48:27 +03:00
ksv741	1a6be432f2	feat: add backend container delivery Backend security / security (push) Failing after 5s Details Backend verify / verify (push) Successful in 2m19s Details Backend security / security (pull_request) Failing after 5s Details Backend verify / verify (pull_request) Successful in 2m17s Details Conventional commits / commits (pull_request) Successful in 25s Details	2026-09-16 09:41:56 +03:00
ksv741	32c12fb10d	feat: generate OpenAPI without peer repositories Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 2m28s Details Conventional commits / commits (pull_request) Successful in 25s Details Backend security / security (push) Successful in 6s Details Backend verify / verify (push) Successful in 2m16s Details	2026-09-15 20:45:39 +03:00
ksv741	016782657a	docs: simplify conventions layout Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 2m3s Details Conventional commits / commits (pull_request) Successful in 24s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 2m10s Details	2026-09-15 05:58:33 +03:00
ksv741	9810d47e42	docs: refine backend conventions and routing Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Successful in 2m12s Details Conventional commits / commits (pull_request) Successful in 25s Details Backend security / security (pull_request) Successful in 7s Details Backend verify / verify (pull_request) Successful in 2m3s Details	2026-09-15 05:42:16 +03:00
ksv741	660b250ecd	chore(release): 0.1.0 Conventional commits / commits (pull_request) Successful in 31s Details Backend security / security (pull_request) Successful in 9s Details Backend verify / verify (pull_request) Successful in 2m25s Details Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Successful in 2m40s Details	2026-09-14 07:08:06 +03:00
ksv741	f01b82d366	chore: configure releases and develop workflow	2026-09-14 07:07:24 +03:00
ksv741	d4fc28cbbf	docs: update system documentation references Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 2m5s Details	2026-09-14 05:51:54 +03:00
renovate-bot	97e864bc06	chore(deps): pin node.js to v24.21.0 Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Successful in 2m27s Details	2026-09-13 20:45:06 +03:00
ksv741	121af701b7	chore(deps): upgrade backend to Nest 12 and TypeScript 6 Backend security / security (pull_request) Successful in 8s Details Backend security / security (push) Successful in 7s Details Backend verify / verify (push) Successful in 2m28s Details	2026-09-13 20:43:50 +03:00
ksv741	2bc8745495	chore(deps): update and pin backend dependencies Backend security / security (pull_request) Successful in 13s Details Backend security / security (push) Successful in 10s Details Backend verify / verify (push) Successful in 2m53s Details	2026-09-13 20:29:13 +03:00
ksv741	4c8ba2fac9	ci: verify backend and secure dependency updates #1 #5 #6 Backend security / security (pull_request) Successful in 8s Details Backend security / security (push) Successful in 8s Details Backend verify / verify (push) Successful in 2m26s Details	2026-09-13 19:58:29 +03:00
renovate-bot	a5156fbeb5	Add renovate.json	2026-09-13 14:02:04 +00:00
ksv741	197ffe2136	chore: upgrade Node to 24 LTS	2026-09-13 15:05:38 +03:00
ksv741	ce24a84b7f	fix: make SQLite migrations and e2e reproducible	2026-09-13 14:52:09 +03:00
ksv741	8637ad2f34	refactor: centralize domain values and enforce numeric lint	2026-09-13 14:37:39 +03:00
ksv741	8ba005346d	refactor: organize backend by business responsibility	2026-09-13 13:52:57 +03:00
ksv741	7fde3ece6e	test: cover isolated SQLite invariants and durability	2026-09-13 12:33:17 +03:00
ksv741	346a6f0057	refactor: enforce strict backend typing Enable strict TypeScript and reject non-null and definite-assignment assertions. Declare externally populated DTO fields, preserve runtime validation, and narrow values at their owners. Verified: backend verify (257 tests), unchanged OpenAPI, and 21 SQLite/HTTP tests on retry. The initial SQLite run had two timeouts; baseline HEAD passed 21 tests as well.	2026-09-13 12:17:46 +03:00
		`@@ -0,0 +1 @@`
							`export type Money = { currency: string; value: string };`
		`@@ -0,0 +1,2 @@`
							`export const MILLISECONDS_PER_SECOND = 1_000;`
							`export const MILLISECONDS_PER_DAY = 86_400_000;`
		`@@ -0,0 +1,2 @@`
							`// Public cross-module surface. Nest providers are exported by the matching module.`
							`export { type MoexBondEvent, MoexClient } from './moex.client';`
		`@@ -0,0 +1,2 @@`
							`// Public cross-module surface. Nest providers are exported by the matching module.`
							`export { NcrRatingsClient } from './ncr-ratings.client';`
`@@ -1,4 +1,4 @@`
	`import { Decimal } from '../common/decimal';`	`import { Decimal } from '../../common/decimal';`

	`const NANO = 1_000_000_000n;`	`const NANO = 1_000_000_000n;`