From 9810d47e42d9275cf2520556f517d411058ddcb3 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Tue, 15 Sep 2026 05:42:16 +0300 Subject: [PATCH] docs: refine backend conventions and routing --- .ai/CONVENTIONS.md | 30 ++------ .ai/SOURCES.md | 2 +- .ai/architecture.md | 44 +++++++++++ .ai/conventions/backend-architecture.md | 93 +++++------------------ .ai/conventions/backend-data.md | 7 ++ .ai/conventions/backend-error-handling.md | 40 ++++++++++ .ai/conventions/backend-http-api.md | 17 ++++- .ai/conventions/backend-integrations.md | 7 +- .ai/conventions/backend-observability.md | 24 ++++++ .ai/conventions/backend-testing.md | 8 +- .ai/conventions/security-auth.md | 9 +++ AGENTS.md | 51 ++++++------- 12 files changed, 201 insertions(+), 131 deletions(-) create mode 100644 .ai/architecture.md create mode 100644 .ai/conventions/backend-error-handling.md create mode 100644 .ai/conventions/backend-observability.md diff --git a/.ai/CONVENTIONS.md b/.ai/CONVENTIONS.md index 73d81bd..5791928 100644 --- a/.ai/CONVENTIONS.md +++ b/.ai/CONVENTIONS.md @@ -1,25 +1,9 @@ -# Backend router +# Backend conventions: вход -Объединяй triggers из смысла задачи, путей и обнаруженных boundaries. -Читай выбранные guides до решения; якорь допускает чтение только нужного раздела. -Просто backend-файл не требует всех conventions. +Актуальный routing по задаче, пути и boundary находится в [AGENTS](../AGENTS.md). +Выбирай только активированные темы; при новой границе повтори routing. +[Architecture](architecture.md) объясняет mental model, [SOURCES](SOURCES.md) +ведёт к системным фактам, specifications и ADR по конкретному вопросу. -| Решение / сигнал | Читать | -| --- | --- | -| Новый файл/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 | [Общий выбор реализации](../../AGENTS.md) | -| Изменение request/response/route/status/error shape или Swagger metadata | HTTP API + [Источник HTTP-контракта](../../docs/architecture/http-api.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 файлы. +Этот адрес сохранён для существующих входящих ссылок; второй копии правил +и таблицы маршрутов здесь нет. diff --git a/.ai/SOURCES.md b/.ai/SOURCES.md index 8a78838..07082e0 100644 --- a/.ai/SOURCES.md +++ b/.ai/SOURCES.md @@ -2,7 +2,7 @@ | Что нужно установить | Владелец | | --- | --- | -| Implementation decision и безопасный pattern | [CONVENTIONS](CONVENTIONS.md) | +| Implementation decision и безопасный pattern | [AGENTS](../AGENTS.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#хранимые-данные-и-границы-доступа) | diff --git a/.ai/architecture.md b/.ai/architecture.md new file mode 100644 index 0000000..48724cd --- /dev/null +++ b/.ai/architecture.md @@ -0,0 +1,44 @@ +# Backend mental model + +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 на каждый +класс нет. [Module convention](conventions/backend-architecture.md). + +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/backend-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. + +Runtime OpenAPI из Nest → предоставленный frontend snapshot → generated types. +Problem Details фильтруются общей HTTP boundary; StructuredLogger добавляет +request context и ограничивает поля событий. Jest unit tests, изолированные +SQLite/HTTP suites и OpenAPI parity доказывают разные части поведения. +Системные потоки и ADR выбираются через [SOURCES](SOURCES.md). diff --git a/.ai/conventions/backend-architecture.md b/.ai/conventions/backend-architecture.md index a3e16f1..10734e8 100644 --- a/.ai/conventions/backend-architecture.md +++ b/.ai/conventions/backend-architecture.md @@ -2,11 +2,8 @@ ## 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 внутри одного модуля. +Устройство и data flow — в [mental model](../architecture.md). +Сначала выбери business owner в `modules/`, затем ответственность внутри него. ### Progressive structure @@ -36,15 +33,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 проходи владельцев в порядке: @@ -134,6 +122,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. @@ -169,30 +161,18 @@ DTO остаются транспортными runtime classes; существ Сохраняй существующий error contract: HTTP exceptions остаются на application/ transport boundary. Чистому расчёту не нужен новый framework ошибок. +Mapping и stable codes — по [Errors](backend-error-handling.md). Точные ограничения — [HTTP](backend-http-api.md), [Data](backend-data.md), [Security](security-auth.md), [Integrations](backend-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](../../../.ai/conventions/code-health.md#change-scope). ## Common @@ -205,39 +185,12 @@ 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](../../../.ai/conventions/code-health.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, @@ -255,14 +208,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](backend-observability.md). ## Проверка diff --git a/.ai/conventions/backend-data.md b/.ai/conventions/backend-data.md index 04954b5..bd6cf5b 100644 --- a/.ai/conventions/backend-data.md +++ b/.ai/conventions/backend-data.md @@ -22,6 +22,13 @@ interface/port/adapter. Он владеет queries, includes/filtering, DB mapp согласованным чтением. Суффиксы `*.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`, `GenericRepository` и RepositoryFactory поверх Prisma +не нужны без отдельной общей ответственности. + `BankCardsRepository.summaryData` проверяет владельца карты и получает операции с категориями в одной read transaction. `GetBankSummaryUseCase` выбирает период, вызывает repository, затем чистый `bankSummary` и формирует ответ. Prisma records diff --git a/.ai/conventions/backend-error-handling.md b/.ai/conventions/backend-error-handling.md new file mode 100644 index 0000000..7072d38 --- /dev/null +++ b/.ai/conventions/backend-error-handling.md @@ -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](../../../docs/architecture/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](../../../.ai/conventions/code-health.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](backend-observability.md). Redaction не + делает произвольное сообщение ошибки безопасным. + +## Проверка + +Для изменённого кода проверь observable status/code и сохранность данных. +Для validation нужен request через `configureApp`: fabricated `ValidationError` +в unit test filter не доказывает форму, выходящую из реального ValidationPipe. +OpenAPI parity проверяет schema, а не response pipeline; [Testing](backend-testing.md). diff --git a/.ai/conventions/backend-http-api.md b/.ai/conventions/backend-http-api.md index 850edcd..fcb1022 100644 --- a/.ai/conventions/backend-http-api.md +++ b/.ai/conventions/backend-http-api.md @@ -35,10 +35,9 @@ ValidationPipe уже настроен в `configureApp` (`transform`, `whitelis описывает те же 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. +и существующий `ApiProblemResponses`. Prisma model не является public contract: +response выбирает поля явно. Stable codes, RFC 9457 профиль и mapping принадлежат +[Errors](backend-error-handling.md). **Безопасный путь:** используй exception и общий filter, а не локальный `res.status(...).json(...)`. Исключение — транспортная операция вроде cookie; @@ -46,6 +45,16 @@ raw upstream error, Prisma record с secrets или stack. Текущая фор ## Пример и проверка +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 обновляй canonical source и generated artifacts в определённом diff --git a/.ai/conventions/backend-integrations.md b/.ai/conventions/backend-integrations.md index 1c5d3fb..9ade729 100644 --- a/.ai/conventions/backend-integrations.md +++ b/.ai/conventions/backend-integrations.md @@ -2,7 +2,8 @@ ## Выбор 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 — @@ -40,6 +41,10 @@ Existing client уже владеет bounded FIFO queue, rate limit, deadline CA mechanism. Точные параметры и ограничения принадлежат [connection configuration](../../../docs/integrations/tbank.md#конфигурация-и-ограничения). +Эта 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 diff --git a/.ai/conventions/backend-observability.md b/.ai/conventions/backend-observability.md new file mode 100644 index 0000000..b3ff97c --- /dev/null +++ b/.ai/conventions/backend-observability.md @@ -0,0 +1,24 @@ +# 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](backend-error-handling.md) не отдаёт внутренние детали клиенту. + +Причины — [ADR 008](../../../docs/adr/008-pino-backend-logging.md), системное +поведение — [HTTP observability](../../../docs/architecture/http-api.md#наблюдаемость). +Проверяй новые поля/redaction/correlation existing logging tests; не добавляй +тест на каждую строку log. Existing ESLint не запрещает все вызовы `console` +отдельным правилом: до настройки встроенного `no-console` это semantic review. diff --git a/.ai/conventions/backend-testing.md b/.ai/conventions/backend-testing.md index b86e45c..0b64f93 100644 --- a/.ai/conventions/backend-testing.md +++ b/.ai/conventions/backend-testing.md @@ -1,5 +1,9 @@ # Backend testing +Перед нетривиальными тестами сформулируй +[общий Test Intent](../../../.ai/conventions/testing.md); отдельный документ +не требуется. Trivial low-risk изменения обходятся без него. + ## Выбор уровня Проверяй риски доступа, денежных расчётов, целостности данных, конкурентных @@ -40,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 не считается успешным тестом; повторите проверку в подходящем окружении. diff --git a/.ai/conventions/security-auth.md b/.ai/conventions/security-auth.md index 7534d4b..eafe2a9 100644 --- a/.ai/conventions/security-auth.md +++ b/.ai/conventions/security-auth.md @@ -24,6 +24,10 @@ frontend session/cache очищается и при network failure. ## Trust boundaries +Frontend не является 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 — обязательные @@ -39,6 +43,11 @@ cache invalidation при замене/deletion и ограничение key ro обрабатывает существующий 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. diff --git a/AGENTS.md b/AGENTS.md index 73f4afb..e35f322 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,30 +1,27 @@ -# Backend +# Backend router -NestJS API; общие правила работы — в root `AGENTS.md`. -До backend-решения прочитай [router](.ai/CONVENTIONS.md) и -[sources](.ai/SOURCES.md), затем только применимые документы/разделы. +Общие инструкции — [workspace AGENTS](../AGENTS.md). Объединяй triggers задачи, +путей и обнаруженных boundaries; читай только нужные темы до решения. +[Sources](.ai/SOURCES.md) выбирает факты/spec/ADR по возникшему вопросу. -## Проверка +| Решение / сигнал | Читать | +| --- | --- | +| Первое знакомство, data flow, общая архитектура | [Mental model](.ai/architecture.md) | +| Module/layer/public API/DI/suffix, owner, перенос responsibility | [Modules/application](.ai/conventions/backend-architecture.md) | +| TS vocabulary, domain literals, magic values | [Types/values](.ai/conventions/backend-architecture.md#domain-literals-and-magic-values) | +| Controller/DTO/validation, route/status/response, OpenAPI | [HTTP API](.ai/conventions/backend-http-api.md) | +| Application/domain/HTTP error, exception, code | [Errors](.ai/conventions/backend-error-handling.md) | +| Repository/Prisma/query, transaction, migration, atomic write | [Data](.ai/conventions/backend-data.md) | +| Tests или behavior с regression risk | [Testing](.ai/conventions/backend-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/backend-integrations.md) | +| Logging/context/levels, sensitive logs | [Observability](.ai/conventions/backend-observability.md); sensitive data также Security | +| Изменение публичного wire contract / Swagger metadata | HTTP API + [HTTP contract source](../docs/architecture/http-api.md#источник-контракта) | +| Helper/dependency/новый pattern, refactor/scope | [Code health](../.ai/conventions/code-health.md), для пакета — [Dependencies](../.ai/conventions/dependencies.md) | +| Выбор gate, tooling, завершение | [Guardrails](../.ai/conventions/guardrails.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`. - -HTTP contract changes сохраняют [направление контракта](../docs/architecture/http-api.md#источник-контракта) -и проходят contract check. Общий 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. - -## Ветки и релизы - -Работа — в отдельной ветке от `develop`, затем PR в `develop`; в `main` напрямую -не пушить. Release/hotfix и синхронизация веток — по [root README](../README.md#релизы-и-ветки). -Commits и заголовки PR — Conventional Commits; для спецификаций допустим `spec:`. -Перед подготовкой релиза прочитай root README; версии вручную не повышать. +Новый endpoint обычно требует HTTP API + Testing; Data/Security добавляются +по persistence/access trigger. Auth refresh активирует Security + Data + Testing. +Повтори routing по итоговому diff, включая новые файлы. Migration backlog +читается только при соответствующем finding через +[plan](../.ai/migrations/conventions-v1/plan.md).