# Сущности, таблицы и колонки ## Расположение сущностей Все 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).