backend/README.md

WealthLedger backend

NestJS API WealthLedger. Backend владеет auth, SQLite-данными и server-side интеграцией T-Bank; frontend не обращается к T-Bank напрямую.

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

Требуется Node 22 (.nvmrc). Создайте .env из примера, замените placeholder секреты и установите зависимости строго из lockfile:

cp .env.example .env
nvm use --silent
npm ci
npm run start:dev

JWT_SECRET должен быть секретом не короче 32 символов, а TOKEN_ENCRYPTION_KEY — base64-кодированным 32-байтным ключом. Не добавляйте T-Bank token в .env: он вводится пользователем и хранится в зашифрованном виде.

Проверка

Единый completion gate не изменяет versioned-файлы:

npm run verify

Он запускает zero-warning lint, application/test typechecks, Jest и build. npm run lint:fix — отдельная записывающая команда, npm run test:cov — диагностика без общего числового threshold. npm run test:e2e пока не является passing gate: Prisma schema engine останавливает migration до запуска Jest. Точный статус и trigger пересмотра находятся в remediation registry.

Общий tsconfig.json включает strict: true и noFallthroughCasesInSwitch для приложения, тестов и сборок. ESLint запрещает non-null assertions (value!) и definite-assignment assertions (field!: Type). Поля DTO, заполняемые вне конструктора, описываются через declare: входные значения заполняет и проверяет Nest, ответные DTO описывают форму возвращаемых объектов. declare не создаёт значение и не заменяет runtime-валидацию. В обычном коде нужны инициализация или сужение типа после проверки значения.

Документация

• Router conventions и источники

• Backend architecture

• HTTP API, data и testing

• Security/auth и integrations

• Границы проверки API и данных

• Engineering governance и risk-based testing

• Карта проектных фактов

• API contract и runtime OpenAPI

• Обзор поставленной системы

• Архитектурные решения

• Remediation registry

Из backend runtime OpenAPI можно read-only сверить с frontend snapshot:

npm run test:openapi-contract

Разработка идёт напрямую по задаче пользователя. Каждый affected repo проходит свой verify; при изменении wire contract дополнительно выполняется contract check. Обязательного OpenSpec/SDD lifecycle нет.

Реальная SQLite и сохранность данных

После nvm use --silent запускайте npm run test:sqlite при изменении auth, карточных операций или DB boundary. Runner запускает существующие HTTP suites последовательно, каждую на новой /tmp/bank-cards-*/test.db, применяет migrations с RUST_LOG=info и удаляет только созданную им директорию. Внешний DATABASE_URL заменяется временным; .env и пользовательские данные не изменяются. Ошибка migration или Jest возвращает ненулевой exit code. Нужен доступ к loopback-порту. Это отдельный scope, а не подтверждение всего test:e2e (задача 03).

Риск	Проверка реальной DB
Чужой пользователь	bank-cards.e2e-spec.ts: owner каждой карты, категории, покупки и стороны перевода
Повтор и конкурентный update	Те же tests: fingerprint, tombstone, версии, один refund в пределах покупки, archive/write
Конкурентный refresh	app.e2e-spec.ts: оба запроса читают прежний hash до CAS; один 200, один 401, cookie победителя работает после replay
Rollback и деньги	Карточные tests: откат source lock, атомарный перевод, точные суммы выше 2^53 и границы signed64
Migration, restart, backup/restore	test:durability: прежнее приложение, новая schema, история, откат приложения и восстановление backup

Prisma в этих suites не заменяется mocks. В refresh тесте барьер задерживает настоящую подпись JWT, чтобы оба запроса дошли до реальной конкурентной записи. Unit tests с mocks отдельно проверяют orchestration и не доказывают DB concurrency.

При изменении schema/migrations или сохранения данных дополнительно выполните npm run test:durability -- /absolute/path/to/baseline. Он не входит в lint/verify. Baseline — отдельная сборка до проверяемых миграций с неизменённым префиксом migration history. Для текущей карточной схемы подходит revision 8ec172f48eefa2237dc0c16919fbb2e726b39a65 (до добавления карт):

# Из backend; экспорт не содержит .env или локальную базу.
baseline_dir=$(mktemp -d /tmp/wealthledger-baseline-XXXXXX)
git archive 8ec172f48eefa2237dc0c16919fbb2e726b39a65 | tar -x -C "$baseline_dir"
(
  cd "$baseline_dir"
  nvm use --silent
  npm ci
  npm run build
)
nvm use --silent
npm run build
npm run test:durability -- "$baseline_dir"

Не подменяйте baseline текущей сборкой: runner отвергает тот же путь, отсутствующую сборку и неподходящую migration history. Для следующей schema выберите совместимую предыдущую revision и проверьте её API-сценарии runner. Durability оставляет временные DB, логи и result.json по пути из вывода для диагностики; он не откатывает schema пользовательской базы.