chore(release): 0.2.1

docs: use shared Nexus account #25
ci: publish backend images to Nexus #25
2026-09-18 08:12:28 +03:00 · 2026-09-17 20:53:04 +03:00 · 2026-09-17 20:41:23 +03:00 · 2026-09-16 21:15:21 +03:00 · 2026-09-16 11:35:52 +03:00 · 2026-09-16 10:48:27 +03:00
39 changed files with 5355 additions and 2549 deletions
@@ -1,25 +0,0 @@
-# Backend router
-
-Объединяй triggers из смысла задачи, путей и обнаруженных boundaries.
-Читай выбранные guides до решения; якорь допускает чтение только нужного раздела.
-Просто backend-файл не требует всех conventions.
-
-| Решение / сигнал | Читать |
-| --- | --- |
-| Новый файл/suffix/layer; поиск feature owner; progressive structure; перенос responsibility | [Architecture](conventions/backend-architecture.md) |
-| TS vocabulary, domain literals, magic values | [Domain literals](conventions/backend-architecture.md#domain-literals-and-magic-values) |
-| Controller, DTO, route/status, validation/exception, публичная HTTP-семантика | [HTTP API](conventions/backend-http-api.md) |
-| Repository/data access; Prisma/schema/query, 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) |
-| External client/integration boundary; T-Bank/gRPC/proto, retry/rate limit/cache | [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 не требуется.
@@ -1,12 +1,54 @@
 # 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

-Backend — domain-oriented modular monolith с лёгким разделением
-по ответственности. `src/modules` группирует код по бизнес-возможности: `auth`, `banking/bank-cards`, области `investments`.
-В инвестициях отдельные Nest modules владеют `brokerage-accounts`, `portfolio`,
-`operations`, `income`, `upcoming-events`, `instruments`, `tbank-connection`.
-`instruments/stocks` и `instruments/bonds` — slices внутри одного модуля.
+Сначала выбери business owner в `modules/`, затем ответственность внутри него.

 ### Progressive structure

@@ -36,15 +78,6 @@ feature/
 Для одного controller или пары DTO дополнительная поддиректория не нужна.
 Пустые папки, новые barrels, CQRS и interfaces не требуются для этой организации.

-В текущем коде слои используют `auth`, `bank-cards`, `portfolio`, `operations`
-и slices `instruments/stocks`, `instruments/bonds`. Общие application helpers
-инструментов находятся в `instruments/application`; `instruments.module.ts`
-компонует оба slice. `stock-position.ts` и `instrument-position.ts` формируют
-результат из portfolio DTO; `instrument-market.ts` обрабатывает внешние данные
-и ошибки Nest. Это application code, а не независимая domain model.
-`brokerage-accounts`, `income`, `upcoming-events`, `tbank-connection` остаются
-компактными плоскими modules. Наличие tests само по себе не требует слоёв.
-
 ## Поиск и создание файла

 При работе над feature проходи владельцев в порядке:
@@ -116,7 +149,7 @@ Cross-module consumers во всех строках ограничены пуб
 `*.decorator.ts`, `*.config.ts`, `*.validation.ts`) сохраняют соответствующие
 существующие роли в common/config. `tbank.crypto.ts` — локальная реализация
 шифрования токена; имя не является разрешением создавать generic crypto layer.
-HTTP/e2e naming и расположение — в [Testing](backend-testing.md).
+HTTP/e2e naming и расположение — в [Testing](conventions/testing.md).

 Без зафиксированной необходимости не вводи `*.helper.ts`, `*.utils.ts`,
 `*.manager.ts`, `*.processor.ts`, `*.handler.ts`, `*.provider.ts`, `*.factory.ts`.
@@ -134,6 +167,10 @@ Tests могут импортировать внутренний owner для п
 Новый export требует текущего потребителя; controller и persistence остаются
 приватными. Не добавляй `index.ts` на каждом уровне.

+Circular dependencies устраняй изменением ownership/composition. `forwardRef()`
+не является стандартным исправлением boundaries; исключение требует конкретной
+неизбежной связи и проверки DI initialization.
+
 Каждый provider регистрируется у одного владельца. Потребители импортируют
 его module, а не повторяют provider: это сохраняет единственный кэш и лимитер.
 `AuthModule` экспортирует guard; наличие JWT не заменяет account access check.
@@ -162,37 +199,25 @@ Tests могут импортировать внутренний owner для п
 может использовать application types/input и domain rules; новые interfaces
 ради инверсии зависимостей не обязательны. Domain не импортирует presentation или
 infrastructure. Существующие связные CRUD/transaction services могут сохранять прямые queries
-по [Data](backend-data.md); use case получает данные через repository и сам
+по [Data](conventions/data.md); use case получает данные через repository и сам
 Prisma queries не выполняет. Entity/interface на каждую таблицу не требуется.
 DTO остаются транспортными runtime classes; существующее использование DTO
-на application boundary допустимо по [HTTP API](backend-http-api.md).
+на application boundary допустимо по [HTTP API](conventions/http-api.md).

 Сохраняй существующий error contract: HTTP exceptions остаются на application/
 transport boundary. Чистому расчёту не нужен новый framework ошибок.
-Точные ограничения — [HTTP](backend-http-api.md), [Data](backend-data.md),
-[Security](security-auth.md), [Integrations](backend-integrations.md).
+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` — журнал/переводы/возвраты, `ExpenseCategoriesService` —
-категории, `GetBankSummaryUseCase` — сводку. `BankCardsRepository` сохраняет
-общий transaction retry и owner lookup; денежные транзакции не разрываются.
-Чистые расчёты банковских карт находятся в `domain` этого модуля.
+Разделяй независимые операции, а не строки. Пример: `BankCardsService` владеет
+картами, `BankOperationsService` — журналом/переводами, `GetBankSummaryUseCase` —
+сводкой через repository и чистый расчёт. Не разрывай денежную transaction,
+общий cache/limiter или pending promises при extraction.

-У инструментов `StockCatalogService` / `BondCatalogService` хранят идентичность
-листинга и общий кэш slice; market service — котировки/свечи, income service — выплаты/личные позиции.
-`GetStockCompanyUseCase` владеет сведениями об эмитенте. Ключи, TTL и pending
-promises разделяют прежний экземпляр кэша; extract не должен менять generation.
-Portfolio и operations сохраняют связную координацию снимков/страниц и кэшей.
-Расчёты портфеля находятся в `portfolio/domain`; преобразование брокерских
-позиций — в `tbank-portfolio.mapper.ts`. `bond-money.mapper.ts` преобразует
-ответ клиента и не является value object.
-
-Выбирай обычную функцию для чистого вычисления; repository contract — только
-для реальной границы. CQRS/buses/events, BaseRepository/BaseService, DI token
-для каждого класса, mapper/presenter для каждого DTO и новые dependencies
-не нужны для структурного переноса.
+Расширение abstractions — по [change scope](conventions/engineering.md#change-scope).

 ## Common

@@ -205,45 +230,17 @@ protobuf units/nano conversion — T-Bank integration. Domain используе

 ## Domain literals and magic values

-Finite business vocabulary must be modeled explicitly; incidental implementation
-literals stay inline. Это относится к error codes, statuses, operation/account/
-instrument/transaction types, permissions, roles, feature states и бизнес-режимам.
-
-Перед новым определением найди existing owner/type/value. В branching и comparisons
-используй символическое значение владельца; не повторяй raw domain literals.
-Храни словарь у domain/module/entity с соблюдением границ слоёв, без глобальной
-свалки `constants.ts`. Сохраняй принятый pattern; для нового project-owned словаря
-без подходящего аналога используй `as const` с derived union:
-
-```ts
-const BankErrorCode = {
-  InvalidDate: "BANK_INVALID_DATE",
-  ImmutableOperation: "BANK_IMMUTABLE_OPERATION",
-} as const;
-type BankErrorCode = (typeof BankErrorCode)[keyof typeof BankErrorCode];
-
-// Вместо code === "BANK_INVALID_DATE":
-if (code === BankErrorCode.InvalidDate) { /* existing handling */ }
-```
-
-Значимые numeric policies (timeout, retry, page size, threshold, coefficient)
-называй по смыслу и единицам: `REQUEST_TIMEOUT_MS`, `CACHE_TTL_SECONDS`,
-`MAX_RETRY_COUNT`, `PAGE_SIZE`. Оставляй inline UI labels в принятом месте,
-log messages, индексы, `index + 1`, `Math.max(value, 0)`, `page ?? 1`,
-`percentage * 100` и очевидные локальные детали без semantic benefit.
-При неясном owner/смысле оставь значение и укажи ограничение в review.
-
-Не мигрируй корректные existing enum/union styles массово. Не добавляй ради
-правила factories, registries, schemas, loaders, abstraction layers, dependencies,
-custom lint/AST rules, generation/validation scripts или тесты существования
-констант. Semantic review проверяет ownership, единое написание и неизменность
-wire values; обычные behavior tests проверяют поведение.
+Общий выбор 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)`.
-Frontend переиспользует generated OpenAPI types/values по возможностям генератора,
-а не определяет независимый backend-owned словарь. Внешние/generated enums
+Публичные enum values входят в OpenAPI artifact. Внешние/generated enums
 сохраняй; generated Prisma/protocol code вручную не меняй.

 `@typescript-eslint/no-magic-numbers` включён как error; базовое ESLint rule
@@ -255,14 +252,8 @@ semantic magic strings проверяются conventions/review без ново

 ## 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.
+События, levels, correlation и safe fields — по
+[Observability](conventions/observability.md).

 ## Проверка

@@ -1,59 +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
-и не выполняет финансовые расчёты или сложную оркестрацию.
-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](backend-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`. При новых ошибках задай публичный 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/modules/investments/operations/presentation/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 ошибок.
@@ -15,13 +15,20 @@ PrismaService — существующий shared DB provider с lifecycle пр
 | Независимые reads | Не добавляй transaction ради внешнего вида |
 | Общая persistence abstraction | Только при реальной общей ответственности; generic repository для одной Prisma реализации не нужен |

-Размещение repository определяется [Architecture](backend-architecture.md):
+Размещение 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
@@ -44,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),
-пример: [decimal.ts](../../src/common/decimal.ts). UI formatting не меняет
-backend ownership расчётов и доменную семантику.
+Источник формы — `src/common/money.types.ts`;
+пример точной арифметики: [decimal.ts](../../src/common/decimal.ts).
+Форматирование ответа не меняет доменную семантику и точность расчёта.

 ## Schema и migration

@@ -66,12 +73,12 @@ client обновляй из schema. Не переписывай уже прим

 **Безопасный путь:** additive изменение, заполнение/проверка данных и только затем
 удаление прежней формы, если задача этого требует. Примеры schema/migrations:
-[Prisma source](../../prisma/schema.prisma); исторический rationale —
-[ADR 001](../../../docs/adr/001-prisma-sqlite-local-mvp.md), не текущий список таблиц.
+[Prisma source](../../prisma/schema.prisma). SQLite — embedded storage текущего
+приложения; файл БД и 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.
@@ -2,12 +2,12 @@

 ## Выбор boundary

-T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient. Сервисы use case
+T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient; NCR ratings —
+NcrRatingsClient. Сервисы use case
 используют объявленные клиентом records; SDK clients, metadata и transport errors
-остаются внутри integration. 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).
+остаются внутри integration. Credentials и proto client не входят в публичный
+HTTP API. Connection lifecycle проверяется на границе соответствующего module
+и [Security](security-auth.md).

 `modules/investments/tbank-connection` — пользовательская capability чтения,
 создания/замены и удаления подключения. `integrations/tbank` — технические
@@ -17,7 +17,7 @@ RPC, credentials/access и resilience. Эти владельцы не объед
 `*.client.ts` содержит transport и его retries; `*.api.ts` только перечисляет
 публичные exports. Все шесть `auth/operations/portfolio/tbank/moex/ncr.api.ts`
 имеют одинаковую роль программной границы, определённую в
-[Architecture](backend-architecture.md). Логика, DTO definitions и HTTP routes
+[Architecture](../architecture.md). Логика, DTO definitions и HTTP routes
 в эти файлы не помещаются. Type exports обозначаются `export type`.

 Преобразование provider records происходит на boundary: например,
@@ -30,7 +30,7 @@ client или mapper для простого копирования полей.
 Для нового account use case сначала используй TbankAccessService: access,
 connection generation и invalid-token translation не дублируются в callers.
 Mapper внешних финансовых значений остаётся внутри business capability,
-обычно в infrastructure по [Architecture](backend-architecture.md).
+обычно в infrastructure по [Architecture](../architecture.md).

 ## Retry, cache и protocol

@@ -38,13 +38,19 @@ Existing client уже владеет bounded FIFO queue, rate limit, deadline
 классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop
 в service. Не отключай TLS verification ради окружения: используй документированный
 CA mechanism. Точные параметры и ограничения принадлежат
-[connection configuration](../../../docs/integrations/tbank.md#конфигурация-и-ограничения).
+[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. Client Cached Snapshot frontend отличается от backend
-cache/stale policy; semantics конкретного use case читай через
-[feature index](../../../docs/README.md#предметные-области).
+connection generation. Успешная замена/deletion подключения меняет generation
+даже при сохранении прежнего token; ошибка оставляет прежнее подключение.
+Кэш конкретного use case принадлежит его service и tests. Не переноси
+сохранённый snapshot между пользователями или поколениями подключения.

 Внешний auth failure и временная недоступность имеют разные public codes;
 raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService
@@ -64,4 +70,4 @@ Generated artifacts, если есть, создавай из source, без р
 upstream responses. Проверь queue/deadline/retry limit, token translation,
 cache isolation и late response для затронутых ветвей. Fixtures синтетические;
 реальная сеть, секреты и пользовательские accounts не нужны.
-Logging использует [existing logger](backend-architecture.md#logging).
+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) и
-[ADR 006](../../../docs/adr/006-auth-session-policy.md)/[009](../../../docs/adr/009-concurrent-refresh-rotation-policy.md)
-задают session semantics. Access хранится только в памяти frontend; refresh
-передаётся httpOnly cookie. Source code конфигурации cookie —
+Access проверяется JWT strategy; refresh передаётся httpOnly cookie.
+Сроки token/session принадлежат auth source и configured HTTP tests.
+Source code конфигурации cookie —
 [AuthController](../../src/modules/auth/presentation/auth.controller.ts); изменение flags/path требует
 проверки browser/HTTP поведения, не только TypeScript.

 Refresh rotation атомарна: один победитель, проигравший/superseded token получает
 401, но сам по себе не отзывает session победителя. Не вводи replay history/grace
-или иной security contract без текущей задачи. Logout идемпотентен; in-memory
-frontend session/cache очищается и при network failure.
+или иной security contract без текущей задачи. Logout идемпотентен, отзывает
+сессию и очищает 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) определяет
-cache invalidation при замене/deletion и ограничение key rotation.
+Успешная замена/deletion меняет connection generation и инвалидирует её кэши;
+ошибка сохраняет прежнее подключение. Ключ не ротируется автоматически:
+новый ключ не расшифрует сохранённые 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).
-Cookie/guard/HTTP changes требуют configured HTTP proof; frontend Bearer/retry
-проверяется MSW. Schema parity не доказывает отсутствие утечки secret.
+Targeted auth/access/crypto/logging tests + [Testing](testing.md).
+Cookie/guard/HTTP changes требуют configured HTTP proof.
+Schema parity не доказывает отсутствие утечки secret.
@@ -1,8 +1,13 @@
 # Backend testing

+Перед нетривиальными тестами сформулируй
+[общий Test Intent](engineering.md#test-intent); отдельный документ
+не требуется. Trivial low-risk изменения обходятся без него.
+
 ## Выбор уровня

-Применяй [общие testing risks](../../../docs/development/engineering-governance.md#risk-based-testing).
+Проверяй риски доступа, денежных расчётов, целостности данных, конкурентных
+изменений, публичного контракта и подтверждённых регрессий.
 Тесты должны различать правильное и неправильное наблюдаемое поведение.

 | Что меняется | Проверка |
@@ -10,7 +15,7 @@
 | 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 |
+| 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 |

@@ -24,7 +29,7 @@ Unit specs colocated в `src/**/*.spec.ts`; HTTP/integration — `test/`.
 - [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 + frontend snapshot, без записи snapshot и без T-Bank.
+- [OpenAPI integration](../../test/openapi-contract.e2e-spec.ts): генератор без сервера + configured app; временный JSON, без versioned snapshot и без T-Bank.

 При bug сначала воспроизведи именно его исход, затем исправь responsible owner.
 Не создавай tests для каждой декларации, logs строки или поведения Prisma/Nest
@@ -39,8 +44,8 @@ Unit specs colocated в `src/**/*.spec.ts`; HTTP/integration — `test/`.
 `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 7.9.1. Подробности и регрессия запуска —
+`prisma.config.ts` исключает влияние унаследованного `RUST_LOG=warn/error`
+на fresh migration; точная Prisma version принадлежит manifest/lockfile. Подробности и регрессия запуска —
 [Backend README](../../README.md#реальная-sqlite-и-сохранность-данных).
 HTTP suites требуют разрешения открывать локальные порты. Ошибка sandbox
 не считается успешным тестом; повторите проверку в подходящем окружении.
@@ -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.ksv741.keenetic.pro/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.ksv741.keenetic.pro --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
@@ -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`.
-После lockfile install `npm ci` полный gate — `npm run verify`:
-zero-warning ESLint, application/test TypeScript, Jest и build.
-`lint:fix`/`format` пишут файлы и запускаются отдельно от доказательства проверки.
-`test:cov` — диагностика без общего threshold; scripts принадлежат `package.json`.
+Новый endpoint обычно требует HTTP API + Testing; Data/Security добавляются
+по persistence/access trigger. Auth refresh активирует Security + Data + Testing.
+Перед завершением повтори routing по новым и изменённым файлам. Для Git/release
+прочитай [Git и релизы](.ai/conventions/engineering.md#git-и-релизы).

-HTTP contract changes дополнительно проходят общий
-[contract workflow](../docs/development/runtime-openapi-verification.md).
-Общий e2e запускается на отдельных временных DB; применимость и маршрут проверки
-описаны в [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,110 @@
+# Changelog
+
+## [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,7 +1,8 @@
 # WealthLedger backend

 NestJS API WealthLedger. Backend владеет auth, SQLite-данными и server-side
-интеграцией T-Bank; frontend не обращается к T-Bank напрямую.
+интеграциями. Потребители используют публичный HTTP API и OpenAPI artifact;
+их репозитории не нужны для разработки, сборки и проверок backend.

 ## Быстрый старт

@@ -21,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.ksv741.keenetic.pro/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-файлы:
@@ -30,12 +61,40 @@ npm run verify
 ```

 Он запускает zero-warning lint,
-application/test typechecks, Jest и build. `npm run lint:fix` — отдельная
-записывающая команда, `npm run test:cov` — диагностика без общего числового
-threshold. `npm run test:e2e` отдельно проверяет все HTTP suites на новых базах
-и runtime OpenAPI с соседним frontend checkout. Для полной backend-проверки
-выполните обе команды. Результаты — в
-[remediation registry](../docs/development/audit-remediation.md).
+application/test typechecks, Jest с покрытием и build. `npm run lint:fix` — отдельная
+записывающая команда. `npm run test:cov` также доступен отдельно; общего числового
+threshold нет. `npm run test:e2e` отдельно проверяет все HTTP suites на новых базах
+и соответствие генерируемого OpenAPI настроенному приложению. Для полной backend-проверки
+выполните обе команды.
+
+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
@@ -46,30 +105,73 @@ threshold. `npm run test:e2e` отдельно проверяет все HTTP su
 runtime-валидацию. В обычном коде нужны инициализация или сужение типа
 после проверки значения.

+## SonarQube
+
+Проект `wealthledger-backend` на `https://sonarqube.ksv741.keenetic.pro`
+использует `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)
- [Backend architecture](.ai/conventions/backend-architecture.md)
- [HTTP API](.ai/conventions/backend-http-api.md), [data](.ai/conventions/backend-data.md) и [testing](.ai/conventions/backend-testing.md)
- [Security/auth](.ai/conventions/security-auth.md) и [integrations](.ai/conventions/backend-integrations.md)
+- [AGENTS: правила и источники](AGENTS.md)
+- [Backend architecture](.ai/architecture.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/integrations.md)

- [Границы проверки API и данных](../docs/development/verification.md#api-и-хранение-данных)
- [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)
+- [Генерация OpenAPI](#генерация-openapi)

-Из backend runtime OpenAPI можно read-only сверить с frontend snapshot:
+Генерация без сервера сверяется с OpenAPI настроенного приложения:

 ```bash
 npm run test:openapi-contract
 ```

-Разработка идёт напрямую по задаче пользователя. Каждый affected repo проходит
-свой verify; при изменении wire contract дополнительно выполняется contract check.
-Обязательного OpenSpec/SDD lifecycle нет.
+## Генерация OpenAPI
+
+```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 и сохранность данных

@@ -133,3 +235,39 @@ npm run test:durability -- "$baseline_dir"
 выберите совместимую предыдущую 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"]] },
+};
@@ -1,15 +1,16 @@
 {
  "name": "wealth-ledger-backend",
-  "version": "0.0.1",
+  "version": "0.2.1",
  "description": "",
  "author": "",
  "private": true,
  "license": "UNLICENSED",
  "engines": {
-    "node": "24.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,74 +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:watch": "jest --watch",
-    "test:cov": "jest --coverage",
-    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
-    "test:e2e": "node test/sqlite.cjs --all",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "npm test -- --watch",
+    "test:cov": "npm test -- --coverage",
+    "test:debug": "node --experimental-vm-modules --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "npm run build && node test/sqlite.cjs --all",
    "test:sqlite": "node test/sqlite.cjs",
+    "test:container": "node test/container-smoke.cjs",
    "test:durability": "node test/bank-cards-durability.cjs",
-    "test:openapi-contract": "node test/sqlite.cjs openapi-contract.e2e-spec.ts",
-    "verify": "npm run lint && npm run typecheck:app && npm run typecheck:test && npm test -- --runInBand && npm run build"
+    "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/proto-loader": "^0.8.1",
-    "@nestjs/common": "^11.0.1",
-    "@nestjs/config": "^4.0.4",
-    "@nestjs/core": "^11.0.1",
-    "@nestjs/jwt": "^11.0.2",
-    "@nestjs/passport": "^11.0.5",
-    "@nestjs/platform-express": "^11.0.1",
-    "@nestjs/swagger": "11.4.5",
-    "@prisma/adapter-better-sqlite3": "^7.9.1",
-    "@prisma/client": "^7.9.1",
-    "bcrypt": "^6.0.0",
-    "better-sqlite3": "^12.6.0",
-    "cheerio": "1.1.2",
-    "class-transformer": "^0.5.1",
-    "class-validator": "^0.15.1",
-    "cookie-parser": "^1.4.7",
-    "lru-cache": "^11.2.4",
-    "nestjs-pino": "^4.6.1",
-    "passport": "^0.7.0",
-    "passport-jwt": "^4.0.1",
-    "pino-http": "^11.0.0",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.1"
+    "@grpc/grpc-js": "1.14.4",
+    "@grpc/proto-loader": "0.8.1",
+    "@nestjs/common": "12.0.1",
+    "@nestjs/config": "12.0.0",
+    "@nestjs/core": "12.0.1",
+    "@nestjs/jwt": "12.0.1",
+    "@nestjs/passport": "12.0.0",
+    "@nestjs/platform-express": "12.0.1",
+    "@nestjs/swagger": "12.0.1",
+    "@prisma/adapter-better-sqlite3": "7.10.0",
+    "@prisma/client": "7.10.0",
+    "bcrypt": "6.0.0",
+    "better-sqlite3": "13.0.3",
+    "cheerio": "1.2.0",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "cookie-parser": "1.4.7",
+    "lru-cache": "11.5.2",
+    "nestjs-pino": "5.1.0",
+    "passport": "0.7.0",
+    "passport-jwt": "4.0.1",
+    "pino-http": "11.0.0",
+    "prisma": "7.10.0",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
  },
  "devDependencies": {
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.18.0",
-    "@nestjs/cli": "^11.0.0",
-    "@nestjs/schematics": "^11.0.0",
-    "@nestjs/testing": "^11.0.1",
-    "@types/bcrypt": "^6.0.0",
-    "@types/cookie-parser": "^1.4.10",
-    "@types/express": "^5.0.0",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^24.13.3",
-    "@types/passport-jwt": "^4.0.1",
-    "@types/supertest": "^6.0.2",
-    "eslint": "^9.18.0",
-    "eslint-config-prettier": "^10.0.1",
-    "eslint-plugin-prettier": "^5.2.2",
-    "globals": "^16.0.0",
-    "jest": "^30.0.0",
-    "prettier": "^3.4.2",
-    "prisma": "^7.9.1",
-    "source-map-support": "^0.5.21",
-    "supertest": "^7.0.0",
-    "ts-jest": "^29.2.5",
-    "ts-loader": "^9.5.2",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.20.0"
+    "@commitlint/cli": "21.2.2",
+    "@commitlint/config-conventional": "21.2.2",
+    "@eslint/eslintrc": "3.3.7",
+    "@eslint/js": "10.0.1",
+    "@nestjs/cli": "12.0.0",
+    "@nestjs/schematics": "12.0.1",
+    "@nestjs/testing": "12.0.1",
+    "@release-it/conventional-changelog": "12.0.0",
+    "@types/bcrypt": "6.0.0",
+    "@types/cookie-parser": "1.4.10",
+    "@types/express": "5.0.6",
+    "@types/jest": "30.0.0",
+    "@types/node": "24.13.4",
+    "@types/passport-jwt": "4.0.1",
+    "@types/supertest": "7.2.1",
+    "conventional-changelog-conventionalcommits": "10.4.0",
+    "eslint": "10.10.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.6",
+    "globals": "17.12.0",
+    "jest": "30.5.1",
+    "prettier": "3.9.6",
+    "release-it": "21.0.2",
+    "source-map-support": "0.5.21",
+    "supertest": "7.2.2",
+    "ts-jest": "29.4.12",
+    "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": {
-      "js-yaml": "5.2.3"
+    "@nestjs/platform-express": {
+      "multer": "2.3.0"
+    },
+    "@prisma/config@7.10.0": {
+      "deepmerge-ts": "8.0.2"
+    },
+    "prisma": {
+      "mysql2": "3.24.4"
    }
  },
  "jest": {
@@ -108,12 +124,13 @@
    "testEnvironment": "node"
  },
  "allowScripts": {
-    "@prisma/engines@7.9.1": true,
-    "prisma@7.9.1": true,
+    "@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
+    "unrs-resolver@1.12.2": true,
+    "better-sqlite3@13.0.3": true
  }
 }
@@ -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.ksv741.keenetic.pro
+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
@@ -15,7 +15,7 @@ import {
  ServiceUnavailableException,
 } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { StructuredLogger } from '../../common/logging/structured-logger.service';
 import { Environment } from '../../config/env.validation';
@@ -172,13 +172,7 @@ export class TbankClient {
    config: ConfigService<Environment, true>,
    private readonly logger: StructuredLogger,
  ) {
-    const sourceProtoRoot = join(
-      process.cwd(),
-      'src/integrations/tbank/proto/contracts',
-    );
-    const protoRoot = existsSync(sourceProtoRoot)
-      ? sourceProtoRoot
-      : join(process.cwd(), 'dist/integrations/tbank/proto/contracts');
+    const protoRoot = join(__dirname, 'proto/contracts');
    const definition = loadSync(
      [
        'users.proto',
@@ -522,6 +516,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 &&
@@ -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(
-      app,
-      new DocumentBuilder()
-        .setTitle('WealthLedger API')
-        .setVersion('v1')
-        .build(),
-    );
+    const document = createOpenApiDocument(app);
    SwaggerModule.setup('api/docs', app, document);
  }

@@ -0,0 +1,11 @@
+import { INestApplication } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+
+export const API_PREFIX = 'api/v1';
+
+export function createOpenApiDocument(app: INestApplication) {
+  return SwaggerModule.createDocument(
+    app,
+    new DocumentBuilder().setTitle('WealthLedger API').setVersion('v1').build(),
+  );
+}
@@ -0,0 +1,69 @@
+// Real image boundary: catches missing native modules, proto assets and migrations.
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+
+const image = process.argv[2];
+assert.ok(image, 'Pass a built backend image reference');
+const name = `wealthledger-smoke-${randomUUID()}`;
+const docker = (...args) => execFileSync('docker', args, { encoding: 'utf8' }).trim();
+const environment = [
+  '-e', 'DATABASE_URL=file:/data/wealthledger.db',
+  '-e', 'FRONTEND_ORIGIN=http://localhost',
+  '-e', 'JWT_SECRET=disposable-image-smoke-secret-at-least-32-characters',
+  '-e', 'TOKEN_ENCRYPTION_KEY=MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY=',
+  '-e', 'LOG_LEVEL=error',
+];
+
+async function ready() {
+  for (let attempt = 0; attempt < 90; attempt++) {
+    const state = JSON.parse(docker('inspect', name, '--format', '{{json .State}}'));
+    assert.equal(state.Running, true, 'Image exited before readiness');
+    if (state.Health.Status === 'healthy') return;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  throw new Error('Image readiness timed out');
+}
+
+(async () => {
+  docker('volume', 'create', name);
+  try {
+    assert.throws(() => docker('run', '--rm', '--read-only', image),
+      'Missing runtime configuration must prevent startup');
+    const migrate = () => docker('run', '--rm', '--read-only', '-v', `${name}:/data`,
+      ...environment, image, 'node', 'node_modules/prisma/build/index.js', 'migrate', 'deploy');
+    migrate();
+    docker('run', '-d', '--name', name, '--read-only', '-v', `${name}:/data`, ...environment, image);
+    await ready();
+    assert.deepEqual(JSON.parse(docker('inspect', name, '--format', '{{json .HostConfig.PortBindings}}')), {});
+    docker('exec', name, 'node', '-e', `
+      const assert = require('node:assert/strict');
+      const fs = require('node:fs');
+      assert.notEqual(process.getuid(), 0);
+      assert.equal(fs.existsSync('src'), false);
+      assert.equal(fs.existsSync('.env'), false);
+      assert.equal(fs.existsSync('node_modules/typescript'), false);
+      assert.equal(fs.existsSync('node_modules/@nestjs/cli'), false);
+      fs.accessSync('dist/src/integrations/tbank/proto/contracts/users.proto');
+      fetch('http://localhost:3000/api/v1/auth/register', {
+        method: 'POST', headers: {'content-type':'application/json'},
+        body: JSON.stringify({email:'image-smoke@example.test',password:'fictional-image-smoke-password'})
+      }).then(async r => {assert.equal(r.status, 200); await r.json()}).catch(e => {console.error(e); process.exitCode=1});
+    `);
+    docker('stop', name);
+    migrate();
+    docker('start', name);
+    await ready();
+    docker('exec', name, 'node', '-e', `
+      const assert = require('node:assert/strict');
+      const db = require('better-sqlite3')('/data/wealthledger.db');
+      assert.equal(db.prepare('SELECT count(*) AS n FROM User').get().n, 1);
+      assert.equal(db.prepare('SELECT count(*) AS n FROM Session').get().n, 1);
+      assert.equal(db.pragma('integrity_check', {simple:true}), 'ok');
+      db.close();
+    `);
+    console.log('PASS image: fresh/existing migration, non-root read-only runtime, auth, persistence, proto assets');
+  } finally {
+    try { docker('rm', '-f', name); } finally { docker('volume', 'rm', name); }
+  }
+})().catch((error) => { console.error(error); process.exitCode = 1; });
@@ -1,22 +1,12 @@
 import { INestApplication } from '@nestjs/common';
 import { Test } from '@nestjs/testing';
-import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
-import { readFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { resolve } from 'node:path';
 import { AppModule } from '../src/app.module';
 import { configureApp } from '../src/main';
-
-function canonicalize(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(canonicalize);
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(
-      Object.entries(value)
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([key, nestedValue]) => [key, canonicalize(nestedValue)]),
-    );
-  }
-  return value;
-}
+import { createOpenApiDocument } from '../src/openapi';

 describe('OpenAPI contract (integration)', () => {
  let app: INestApplication;
@@ -32,21 +22,38 @@ describe('OpenAPI contract (integration)', () => {

  afterAll(() => app.close());

-  it('matches the committed frontend OpenAPI snapshot', async () => {
-    const runtimeDocument = SwaggerModule.createDocument(
-      app,
-      new DocumentBuilder()
-        .setTitle('WealthLedger API')
-        .setVersion('v1')
-        .build(),
-    );
-    const snapshot = JSON.parse(
-      await readFile(
-        resolve(__dirname, '../../frontend/src/shared/api/spec/openapi.json'),
-        'utf8',
-      ),
-    ) as unknown;
-
-    expect(canonicalize(runtimeDocument)).toEqual(canonicalize(snapshot));
+  it('generates the runtime contract without server startup or deployment configuration', async () => {
+    const directory = await mkdtemp(resolve(tmpdir(), 'wealthledger-openapi-'));
+    try {
+      const networkGuard = resolve(directory, 'no-network.cjs');
+      await writeFile(
+        networkGuard,
+        `
+        const net = require('node:net');
+        const forbidden = () => { throw new Error('Schema generation must not use the network'); };
+        net.Server.prototype.listen = forbidden;
+        net.Socket.prototype.connect = forbidden;
+      `,
+      );
+      execFileSync(
+        process.execPath,
+        [
+          '--require',
+          networkGuard,
+          resolve(__dirname, '../scripts/generate-openapi.cjs'),
+        ],
+        {
+          cwd: directory,
+          env: { PATH: process.env.PATH },
+          timeout: 30_000,
+        },
+      );
+      const generated = JSON.parse(
+        await readFile(resolve(directory, 'openapi.json'), 'utf8'),
+      ) as unknown;
+      expect(generated).toEqual(createOpenApiDocument(app));
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
  });
 });
@@ -13,7 +13,8 @@
    "target": "ES2023",
    "sourceMap": true,
    "outDir": "./dist",
-    "baseUrl": "./",
+    "rootDir": ".",
+    "types": ["node", "jest"],
    "incremental": true,
    "skipLibCheck": true,
    "strict": true,
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "ES2022",
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "dist", "generated"]
+}
Author	SHA1	Message	Date
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