docs(ai): add scoped backend conventions
This commit is contained in:
@@ -1,37 +1,23 @@
|
||||
# Backend
|
||||
|
||||
## Назначение и authority
|
||||
NestJS API; общие правила работы — в root `AGENTS.md`.
|
||||
До backend-решения прочитай [router](.ai/CONVENTIONS.md) и
|
||||
[sources](.ai/SOURCES.md), затем только применимые документы/разделы.
|
||||
|
||||
NestJS API WealthLedger владеет доменной логикой, данными, конфигурацией и
|
||||
server-side интеграциями. Workspace layout и reference policy — в root
|
||||
`AGENTS.md`. Для planning, implementation, validation и завершения читай
|
||||
[canonical lifecycle](../docs/development/openspec-authority-and-lifecycle.md);
|
||||
для recovery и выбора relevant evidence —
|
||||
[context discipline](../docs/development/agent-token-efficiency.md).
|
||||
Они доступны без optional agent skills или commands.
|
||||
## Проверка
|
||||
|
||||
Для устойчивых backend decisions читать [`../docs/adr/README.md`](../docs/adr/README.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`.
|
||||
|
||||
## Canonical gate
|
||||
HTTP contract changes дополнительно проходят общий
|
||||
[contract workflow](../docs/development/runtime-openapi-verification.md).
|
||||
Общий e2e имеет известный environment blocker; применимость и маршрут проверки
|
||||
описаны в [backend testing](.ai/conventions/backend-testing.md).
|
||||
Generated Prisma client не редактируется вручную. Credentials, авторизация
|
||||
доступа к счетам и внешние интеграции остаются server-side.
|
||||
|
||||
Перед Node-командами активировать `.nvmrc` через `nvm use --silent`; это выбирает
|
||||
Node 22. Не запускать отдельную проверку версии, кроме диагностики runtime issue.
|
||||
После lockfile install единственный completion gate:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run verify
|
||||
```
|
||||
|
||||
Gate non-mutating и последовательно проверяет ESLint, application/test TypeScript, risk-based Jest suite и build. `npm run lint:fix` и `npm run format` изменяют files и выполняются только явно; `npm run test:cov` — диагностика без общего threshold. `npm run test:e2e` не входит в passing gate до WL-P2-05 trigger из remediation registry. `npm run test:openapi-contract` — отдельный contract gate для изменений обеих сторон API contract.
|
||||
Актуальные scripts проверять в `package.json`/`npm run`.
|
||||
|
||||
## Enforceable boundaries
|
||||
|
||||
- Style задают `eslint.config.mjs` и TypeScript configs; zero-warning lint и оба typecheck обязательны.
|
||||
- Публичный HTTP API версионируется как `/api/v1`; generated backend OpenAPI — contract authority для frontend snapshot.
|
||||
- Frontend не вызывает T-Bank напрямую; credentials, rate limiting и integration resilience остаются server-side.
|
||||
- Не размещать frontend code, generated client или durable documentation в backend.
|
||||
- Security, money, data integrity, concurrency, public contracts, critical journeys и regressions требуют risk-based tests. DTO, declarative config и thin scripts не требуют отдельного unit test без собственной logic.
|
||||
|
||||
Непроверяемые предпочтения являются guidance и не заменяют canonical gate.
|
||||
ESLint/TypeScript не доказывают правильность domain boundaries, security или
|
||||
денежных вычислений: для них нужны semantic review и risk-based tests.
|
||||
|
||||
Reference in New Issue
Block a user