refactor: centralize domain values and enforce numeric lint
This commit is contained in:
@@ -7,6 +7,7 @@
|
||||
| Решение / сигнал | Читать |
|
||||
| --- | --- |
|
||||
| Новый файл/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) |
|
||||
|
||||
@@ -203,6 +203,56 @@ protobuf units/nano conversion — T-Bank integration. Domain используе
|
||||
`money.types.ts`, а не Swagger DTO; это общая форма денег для карт и портфеля.
|
||||
Давай функциям предметные имена; не создавай глобальные `utils.ts`/`helpers.ts`.
|
||||
|
||||
## 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 проверяют поведение.
|
||||
|
||||
OpenAPI enum metadata и runtime validation должны читать тот же vocabulary,
|
||||
что application/domain. Например, `BankOperationKind` принадлежит bank-cards/domain,
|
||||
а DTO получает допустимые значения через `Object.values(BankOperationKind)`.
|
||||
Frontend переиспользует generated OpenAPI types/values по возможностям генератора,
|
||||
а не определяет независимый backend-owned словарь. Внешние/generated enums
|
||||
сохраняй; generated Prisma/protocol code вручную не меняй.
|
||||
|
||||
`@typescript-eslint/no-magic-numbers` включён как error; базовое ESLint rule
|
||||
отключено в пользу TS-версии. Исключения для очевидных чисел и их bigint форм,
|
||||
индексов, default values, enum/type declarations и readonly properties заданы
|
||||
в ESLint config. Test fixtures/expected values остаются inline, остальные lint
|
||||
правила продолжают действовать. Numeric policy получает предметное имя и единицы;
|
||||
semantic magic strings проверяются conventions/review без нового инструмента.
|
||||
|
||||
## Logging
|
||||
|
||||
Единственный logger — nestjs-pino; application events используют существующий
|
||||
|
||||
Reference in New Issue
Block a user