docs(ai): adopt task-driven scoped context

2026-09-09 16:23:11 +03:00
parent 7166ee51d1
commit b7a56b1eb5
17 changed files with 502 additions and 676 deletions
@@ -0,0 +1,59 @@
+# HTTP API и ошибки
+
+## Источник контракта
+
+Nest controllers/DTO/Swagger metadata генерируют runtime OpenAPI. Настройка
+приложения — [configureApp](../../backend/src/main.ts); frontend хранит derived
+snapshot и generated TS. Изменения проходят
+[contract workflow](../development/runtime-openapi-verification.md).
+API имеет prefix `/api/v1`; Swagger публикуется для локальной разработки по
+environment policy, а не используется frontend в runtime.
+
+## Validation и identity
+
+Global ValidationPipe использует `transform: true`, `whitelist: true`.
+Unknown properties удаляются, а их rejection не обещается без
+`forbidNonWhitelisted`. Runtime DTO validators и преобразования задают допустимый
+вход; бизнес-ограничения и доступ к account проверяются service/access boundary.
+Guard подтверждает identity; accountId из URL сам по себе не доказывает доступ.
+
+## Error contract
+
+Общий [HttpExceptionFilter](../../backend/src/common/filters/http-exception.filter.ts)
+возвращает `application/problem+json` со `status` и публичным `code`.
+Неожиданный exception возвращает `500` / `INTERNAL_SERVER_ERROR`, без исходного
+message/stack. Типичный ответ:
+
+```json
+{ "status": 401, "code": "UNAUTHORIZED" }
+```
+
+Для input validation контракт требует `400`, `VALIDATION_ERROR` и `errors` как
+массив `{ pointer, detail }`, где pointer адресует поле запроса. Это требование
+не считается проверенным одним Swagger snapshot: direct controller call не
+запускает ValidationPipe. Текущий filter преобразует `ValidationError.constraints`,
+а default Nest pipe формирует массив строк; корректность field details в
+configured HTTP pipeline нужно проверять отдельно и не копировать этот seam
+как доказанно полный пример.
+
+Документированный DTO — [ProblemDetailsDto](../../backend/src/common/decorators/api-safe-error-response.decorator.ts).
+Filter не добавляет автоматически все поля из RFC (`type`, `title`, `instance`).
+Не вводи дополнительные обязательные поля без согласованного изменения wire contract.
+Caller выбирает поведение по public code, не по внутреннему тексту exception.
+
+## Domain errors и auth
+
+Специальный code задаётся ответственным use case; generic mapping и безопасный
+envelope принадлежат filter. Auth endpoints используют свои status и cookie
+operations: [Authentication](../features/authentication.md).
+T-Bank token failure и временная недоступность имеют разные значения:
+[Connection API](../features/tbank-connection.md#api). Raw upstream/Prisma errors
+и secrets не передаются frontend.
+
+## Граница доказательства
+
+OpenAPI integration проверяет равенство schemas, а не результат каждого request.
+Filter unit test проверяет безопасный unexpected error. Для изменения validation,
+guard, status/cookie или domain error нужны representative configured HTTP cases;
+известный e2e environment blocker не превращает отсутствующую проверку в success.
+Выбор уровня и команд — [backend testing](../../backend/.ai/conventions/backend-testing.md).