docs: документация по архитектуре, данным и деплою

Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой
миграций, а также оглавление документации и README шаблона.
This commit is contained in:
arswarog committed 2026-10-27 10:43:49 +03:00
1 parent 9d5478ddeb
commit dbd5762ecf
10 files changed
+1308 -87

No files matched your search

+99
View File
@@ -0,0 +1,99 @@
# Сущности, таблицы и колонки
## Расположение сущностей
Все TypeORM-сущности модуля лежат в подпапке `entities/` в корне модуля:
```
apps/api/src/contests/
├── dto/
├── entities/
│ └── contest.entity.ts
├── contests.controller.ts
├── contests.module.ts
└── contests.service.ts
```
- Правило без исключений: даже если сущность в модуле одна, она всё равно в `entities/`. Иначе при
добавлении второй сущности пришлось бы переносить первую и править все её импорты.
- Имя файла — `<сущность>.entity.ts` в kebab-case (`project-member.entity.ts`).
- Один файл — одна сущность.
## Имя таблицы — единая точка правды
Рядом с сущностью, в том же файле, объявляется экспортируемая константа с именем таблицы, и
`@Entity` использует её:
```ts
export const CONTESTS_TABLE_NAME = 'contests';
@Entity({ name: CONTESTS_TABLE_NAME })
export class Contest {
// ...
}
```
- Константа именуется `<СУЩНОСТЬ>_TABLE_NAME` в SCREAMING_SNAKE_CASE.
- Значение — `snake_case`, множественное число (`contests`, `project_members`).
- `@Entity()` без явного `name` не используется: имя таблицы не должно выводиться из имени класса —
переименование класса тогда молча меняет схему.
Константа — единая точка правды об имени таблицы для кода приложения: `@Entity`, DAL, raw-SQL,
алиасы `createQueryBuilder`, утилиты очистки в тестах. Строковый литерал с именем таблицы за
пределами объявления константы в коде приложения не пишется.
### Миграции константу не используют
Миграция — снимок схемы на момент, когда её написали, и она обязана оставаться рабочей независимо от
того, что стало с кодом дальше. Поэтому **в миграции имя таблицы пишется строковым литералом**.
Пример из репозитория: коммит `b710c1b9` удалил модуль подписок вместе с файлом
`subscriptions/subscription-plan.entity.ts` — а миграции `1774000000000-add-subscription-plans.ts` и
`1788825600000-drop-subscriptions-and-metrics-limits.ts` никуда не делись и по-прежнему создают и
удаляют таблицу `subscription_plans`. Импортируй они константу из удалённого файла — сборка встала
бы целиком: миграции попадают в бандл `data-source.js` статическими импортами.
Обратная сторона того же правила: значение константы менять **можно**, миграции на него не смотрят.
Переименование таблицы — это новое значение константы плюс миграция с двумя литералами:
```ts
await queryRunner.renameTable('contests', 'brand_contests');
```
## Имена колонок
Колонки — `camelCase` (`logoId`, `totalBudget`, `createdAt`), в отличие от `snake_case` у таблиц.
Это не разнобой, а следствие дефолтной стратегии именования TypeORM: имя колонки выводится из имени
свойства как есть, и в `@Column()` его не дублируют. С таблицей так нельзя — её имя выводилось бы из
имени класса, — поэтому она и задаётся явно.
Практическое следствие: Postgres приводит неэкранированный идентификатор к нижнему регистру, так что
в raw-SQL такая колонка пишется только в двойных кавычках:
```sql
ALTER TABLE "contests" DROP COLUMN IF EXISTS "totalBudget";
```
## Nullable-колонки — явный `type`
Если тип свойства — объединение с `null`, тип колонки задаётся в декораторе явно:
```ts
@Column({ type: 'varchar', nullable: true })
banReason: string | null;
@Column({ type: 'timestamp', nullable: true })
emailVerificationTokenExpires: Date | null;
```
Без `type` TypeORM выводит тип колонки из метаданных декоратора (`design:type`), а для объединения
`string | null` TypeScript отдаёт `Object` — вывести из него тип колонки нельзя, и приложение падает
на старте с `ColumnTypeUndefinedError` ещё до первого запроса. Ошибка вылезает только при реальном
поднятии контекста: юнит-тесты сервиса метаданные сущностей не строят и остаются зелёными.
Само объявление `string | null` при этом предпочтительнее, чем `string` у nullable-колонки: тип
сущности должен отражать то, что лежит в базе, иначе «пустое» значение приходится проверять вопреки
типу. Схему явный `type` не меняет — `varchar` без длины это то же `character varying`, что и в
миграции, — так что переход на `| null` у уже существующей колонки миграции не требует.
Как писать сами миграции — [Написание миграций](20-migrations.md).