WealthLedger backend

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

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

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

cp .env.example .env
nvm use --silent
npm ci
npx prisma migrate deploy
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 отдельно проверяет все HTTP suites на новых базах и runtime OpenAPI с соседним frontend checkout. Для полной backend-проверки выполните обе команды. Результаты — в remediation registry.

CI и обновления зависимостей

.gitea/workflows/verify.yml запускает npm ci, генерацию Prisma client, npm run verify и npm run test:e2e на каждом push ветки. Frontend snapshot берётся из main соседнего репозитория; лог сохраняет оба SHA. Изменение контракта согласуется с этой frontend revision. Успешный unit gate не заменяет SQLite/e2e; ошибка любой suite завершает job с FAIL.

security.yml сканирует всю Git-историю Gitleaks 8.30.1 с полностью скрытыми значениями и выполняет npm audit --include=dev --audit-level=low при push, PR и ежедневно. .gitleaksignore перечисляет только проверенные исторические совпадения: детерминированные fixtures, placeholder и badge из Nest starter. Новые коммиты этими исключениями не покрываются.

Renovate группирует minor/patch updates, а major требует согласования в Dependency Dashboard. Автоматический merge не включён. Прямые зависимости фиксируются точными версиями: .npmrc задаёт save-exact=true для npm install, Renovate использует rangeStrategy: pin. Обновляйте package.json вместе с package-lock.json. Overrides в package.json закрывают advisories транзитивных multer, deepmerge-ts и mysql2; удаляйте их, когда родительские пакеты примут исправленные версии. Совместимость Prisma override проверяется генерацией и SQLite migrations. Required checks настраиваются отдельно в Gitea: наличие workflow само по себе не блокирует merge.

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

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

Из 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, npm run test:e2e — для всех HTTP suites. Обе команды используют один runner: отдельный каталог wealthledger-e2e-* в системном temp на каждую suite, один DATABASE_URL для migrations и Jest. Внешний DATABASE_URL заменяется временным; .env и пользовательские данные не изменяются. Прямой Jest без runner отклоняется до обращения к базе. При ошибке migration/Jest или SIGINT/SIGTERM runner останавливает дочерние процессы, удаляет свой каталог и возвращает ненулевой exit code. Нужен доступ к локальным HTTP-портам; sandbox может его запрещать.

prisma.config.ts удаляет унаследованный RUST_LOG только в процессе Prisma CLI: на Prisma 7.9.1 уровни warn/error вызывают пустой Schema engine error при fresh migration, без переменной миграция проходит. Постоянный RUST_LOG=info и обновление зависимостей не нужны. Logging приложения настраивается отдельно. История migrations применяется штатным migrate deploy.

Регрессия самого запуска: node test/sqlite-regression.cjs. Она выполняет три последовательных и два параллельных полных e2e, проверяет уникальность DB, сохранность вымышленного внешнего файла, отказ migration и SIGINT/SIGTERM cleanup. Логи остаются в каталоге из вывода. Для одной suite: node test/sqlite.cjs app.e2e-spec.ts.

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

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

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

# Из 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 пользовательской базы.

11 KiB Raw Blame History Unescape Escape