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

+167
View File
@@ -0,0 +1,167 @@
# Слои API
Модуль — единица организации кода в `apps/api`: внутри него код разложен по слоям, а наружу он
поставляет только то, что осознанно экспортирует.
Слоёв три, и зависимости между ними идут строго в одну сторону:
```
Controller → Service → Data Access Layer
```
Сквозь все три слоя проходят два **контракта данных**:
- **DTO** — форма данных на границе HTTP: что приходит в запросе и что уходит в ответе.
- **Entities** — форма данных на границе БД: из чего состоит таблица.
Модуль — не слой, а рамка, которая собирает эти части и определяет, что из них видно снаружи.
## Controllers
**Тонкий контроллер.**
Контроллер — точка входа HTTP. Он принимает запрос, объявляет контракт ручки для Swagger, проверяет
формат входных данных и делегирует работу сервису. При этом контроллер не принимает доменных
решений, не вычисляет и не агрегирует данные: почти всё тело метода занимает объявление API.
Контроль доступа на этом уровне **декларативный**: `JwtAuthGuard`, `RolesGuard` с `@Roles(...)`,
`ProjectAccessGuard` с декоратором роли в проекте. Проверка «пользователь — админ?» или «есть ли
доступ к проекту?» читается из декораторов, а не вычисляется в теле метода. Валидация формата
подключается пайпом **на конкретный параметр** (`@Body(...)`, `@Query(...)`), а не на весь метод: у
проекта нет глобального `ValidationPipe`.
**Входит:**
- Контроль доступа на основе декларативных систем (guards, роли, декораторы)
- Описание API (Swagger-декораторы, HTTP-статусы ответов)
- Проверка формата входных данных (пайпы, DTO)
**Не входит:**
- Бизнес-логика
- Проверка входных данных на основе бизнес-правил
- Транзакции
- Запросы к БД
## Services
**Бизнес-логика и оркестрация.**
Сервис — место, где принимаются решения. Здесь проверяются бизнес-правила, бросаются доменные
ошибки, оркестрируются вызовы DAL и публичных сервисов других модулей, открываются транзакции и
пишутся бизнес-события. Сложный домен делится на вложенные модули — по одному на поддомен (пример —
`billing/modules/*`), а не разрастается в один сервис на весь домен.
В публичный API модуля попадают сервисы, но не обязательно все: `exports` перечисляет их явно.
Другие модули импортируют только сервисы, поэтому правило «доступ к данным чужого домена — через его
публичный сервис» выполняется именно здесь, на уровне сервисов.
**Входит:**
- Бизнес-логика
- Оркестрация: вызовы своего DAL и публичных сервисов других модулей
- Транзакции (через `DataSource` — единственное исключение из правила «TypeORM только в DAL»)
- Контроль доступа на основе сложных бизнес-правил
- Проверка входных данных на основе бизнес-правил
- Логирование бизнес-событий
- Вызовы внешних систем — после коммита транзакции
**Не входит:**
- Выполнение запросов к БД
- Прямой доступ к репозиториям и `QueryBuilder` TypeORM
- HTTP-специфика (объекты `Request`/`Response`, HTTP-статусы)
## Data Access Layer
**Абстракция над БД.**
DAL знает о бизнес-сущностях и предоставляет к ним удобный API. Сервис вызывает осмысленный метод и
получает данные, не зная, как именно они достаются. DAL возвращает сущности как есть — отдельного
слоя доменных моделей и мапперов в проекте нет.
Минимум бизнес-логики: решения принимает сервис. Исключение — логика, которую **необходимо выполнять
на стороне БД**: агрегаты, массовые `UPDATE`/`upsert`, выборки с блокировкой, оконные функции. Ради
них DAL может выполнять чужую таблицу через join вместо похода в чужой сервис.
DAL — **приватная часть модуля**: он не попадает в `exports` и недоступен другим модулям ни при
каких условиях, даже родительскому модулю. Доступ к данным чужого домена — только через публичные
сервисы модуля-владельца.
Высокоуровневый API к данным выглядит так: `findById`, `getActiveProjects`, `softRemoveComment`,
`getCommentsWithAuthors` — за именем стоит намерение, а не способ выборки (имена условные, они
показывают уровень абстракции, а не конкретный модуль). Методы добавляются по мере необходимости, а
не заранее «чтобы было». Метод принимает опциональный `manager?: EntityManager`: открывать
транзакцию или нет — решает вызывающий, DAL лишь работает с тем контекстом, который ему передали.
Транзакции, приватность модуля и логика на стороне БД разобраны подробно в
[слое доступа к данным](30-data-access.md).
**Входит:**
- Выполнение запросов
- Логика, которую необходимо выполнять на стороне БД
**Не входит:**
- Бизнес-логика (кроме логики, выполняемой в БД)
- Открытие транзакций
- Знание о HTTP и о том, кто его вызвал
## DTO
**Контракт входа и валидация формата.**
DTO описывает форму данных на границе HTTP: тело запроса, query-параметры, тело ответа. В нём
объявлены поля, Swagger-описание (`@ApiProperty`) и class-validator-декораторы формата. Это описание
данных, а не поведение: своих методов у DTO нет, кроме статической фабрики `from` — она переводит в
форму ответа то, что вернул сервис, и держит белый список полей рядом с контрактом. Один DTO — один
контракт ручки.
Валидация формата (тип, обязательность, диапазон, формат строки) живёт здесь; проверка на основе
бизнес-правил — уже в сервисе. DTO описывает и вход, и выход: response-модели вроде
`*-response.dto.ts` кладутся в те же `dto/` и подставляются в `@ApiOkResponse({ type: ... })`.
Отдельного слоя ответов нет; часть модулей держит свои read-модели плоскими интерфейсами в
`*.types.ts`.
**Входит:**
- Форма входных и выходных данных
- Валидация формата
- Swagger-описание полей
- Перевод данных в форму ответа — статическая фабрика `from` у response-моделей
**Не входит:**
- Бизнес-логика
- Обращения к БД
- Решения на основе бизнес-правил
- Собственные методы, кроме `from`: входной DTO заполняет `ValidationPipe`, а не код самого DTO, а
считать и решать, что отдавать, — дело сервиса
## Entities
**Схема таблицы, а не модель поведения.**
TypeORM-сущность описывает таблицу: колонки, типы, связи, индексы и имя таблицы. Имя таблицы —
константа `*_TABLE_NAME`, объявленная рядом с сущностью и используемая в коде приложения. Сущность
содержит только поля и связи — `Active Record` не используется, методов сохранения или поиска на ней
нет.
Бизнес-логики и валидации в сущности тоже нет: и то, и другое живёт в сервисе, а структура таблицы —
здесь. Соглашения об именовании, расположении и связях описаны в
[сущностях, таблицах и колонках](10-persistence.md).
**Входит:**
- Схема таблицы: колонки и типы
- Связи и правила `onDelete`
- Индексы
- Имя таблицы
**Не входит:**
- Бизнес-логика
- Методы `save`/`find` и любой доступ к данным
- Валидация входных данных
- Правила доступа
+150
View File
@@ -0,0 +1,150 @@
# Слои web
`apps/web` — React-приложение. Его код разложен по слоям, и зависимости между слоями идут строго в
одну сторону:
```
app → pages → widgets → entities → shared
```
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `shared` не знает, где
применён и по чьей воле вызван, а `entities` не знает о `widgets`.
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном
экземпляре, других — столько, сколько модулей.
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `entities` и `widgets` и определяет,
что из них видно снаружи, — тем же способом, каким это делает модуль в
[слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля.
## app
**Точка входа и оболочка.**
`app` — внешний край приложения. Он монтирует React, объявляет маршруты и их защиту, держит
глобальные провайдеры и рисует оболочку: шапку, подвал, лейауты, общие для целой группы страниц.
Сюда попадает всё, что относится к приложению целиком, а не к отдельному экрану: например, баннер
согласия на cookie. `app` — единственный слой, который видит приложение снизу доверху, и его самого
не импортирует никто.
**Входит:**
- Точка входа приложения
- Маршруты и их защита
- Глобальные провайдеры
- Оболочка и лейауты страниц
- Элементы, относящиеся к приложению целиком
**Не входит:**
- Конкретные страницы и их содержимое
- Доменные данные и сценарии
- Формы, модалки и прочие блоки интерфейса
## pages
**Общий вид страницы и расстановка блоков.**
`pages` отвечает за то, как страница выглядит целиком, и объявляет **хлебные крошки**. Страница
решает, какие виджеты на ней стоят, в каком они порядке и как расположены, — и задаёт каждому
начальные данные: идентификатор из маршрута, стартовое значение фильтра, активную вкладку.
Собственное состояние страницы допустимо ровно одно — то, которым страница **связывает виджеты**
между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является
бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
Как и модуль, страница бывает вложенной: лейаут с вкладками — это тоже `pages`, и он объявляет
крошки за все свои вкладки, потому что только у него есть нужные для этого данные.
**Входит:**
- Композиция виджетов и их расположение на странице
- Хлебные крошки
- Начальные данные виджетов
- Состояние страницы как связь между виджетами
**Не входит:**
- Бизнес-логика
- Собственное отображение доменных данных — это дело виджетов
- Передача сообщений между виджетами
- Работа с API
## widgets
**Самостоятельный блок интерфейса.**
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку,
раскрытые строки. Наружу он поставляет готовый блок, а внутрь принимает только параметры —
идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о
том, что внутри.
Один виджет — один законченный участок работы: `AdminCreditsSummary` рисует карточку баланса
платёжного аккаунта и держит диалоги лотов, броней и ручного начисления.
Виджет собирается из `entities` и `shared` и о других виджетах на странице не знает: связать два
виджета — задача `pages`.
**Входит:**
- Загрузка своих данных
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
- Композиция `entities` и `shared`
- Действия пользователя в границах блока
**Не входит:**
- Хлебные крошки и общая раскладка страницы
- Знание о других виджетах
- Доменные правила
## entities
**Показ доменной сущности.**
Entity отвечает за то, как выглядит одна доменная сущность или одно значение: `TokenValue`
показывает значение токенов, `SummaryRow` — строку сводки. Данные приходят пропсами; entity ничего
не загружает и ничего не меняет. Она отвечает только за вид и форматирование того, что ей передали:
числа, даты, статусы.
**Входит:**
- Показ одной доменной сущности или значения
- Форматирование значения: числа, даты, статусы
- Локальное состояние отображения
**Не входит:**
- Загрузка данных
- Действия над сущностью: создание, изменение, удаление
- Композиция нескольких сущностей
- Знание о странице и о том, где entity показана
## shared
**Общий слой.**
`shared` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API (`shared/api`), типы,
утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному
сценарию.
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на
домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его
вызвал.
`shared` — нижний слой: его берут все, он не берёт никого.
**Входит:**
- UI-примитивы
- Вызовы API
- Типы и утилиты
- Переводы
- Форматирование значений
**Не входит:**
- Знание о том, где и в каком сценарии он применён
- Композиция доменного интерфейса
- Решения о том, что показать и что сделать при ошибке
+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).
+131
View File
@@ -0,0 +1,131 @@
# Написание миграций
Здесь — как **писать** миграцию. Про то, как список миграций собирается, как они применяются на
деплое и какие есть команды, см. [Миграции базы данных](../90-deploy/10-migrations.md).
## DDL пишется через API TypeORM, а не строкой SQL
Схема меняется методами `QueryRunner` с объектами `Table` / `TableColumn`. Строка SQL в
`queryRunner.query()` — крайняя мера, а не способ по умолчанию.
```ts
import { MigrationInterface, QueryRunner, Table } from 'typeorm';
export class AddContests1790000000000 implements MigrationInterface {
name = 'AddContests1790000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.createTable(
new Table({
name: 'contests',
columns: [
{
name: 'id',
type: 'int',
isPrimary: true,
isGenerated: true,
generationStrategy: 'increment',
},
{ name: 'title', type: 'varchar', length: '255', isUnique: true },
{ name: 'logoId', type: 'varchar', length: '64', isNullable: true },
{ name: 'description', type: 'text' },
{ name: 'totalBudget', type: 'int' },
{ name: 'createdAt', type: 'timestamp', default: 'now()' },
{ name: 'updatedAt', type: 'timestamp', default: 'now()' },
],
}),
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.dropTable('contests');
}
}
```
У `createTable` есть второй аргумент `ifNotExist`, и ставить его в `true` не надо: он глушит ровно
ту ошибку, ради которой существует [проверка перед коммитом](#проверка-перед-коммитом) — если `down`
отработал не полностью и оставил таблицу, повторный `up` с `ifNotExist: true` пройдёт мимо дефекта
молча. Дважды одна и та же миграция не применяется и без флага, за этим следит таблица `migrations`.
Имя таблицы — строковый литерал: константа `*_TABLE_NAME` из файла сущности в миграциях не
используется, см.
[Миграции константу не используют](10-persistence.md#миграции-константу-не-используют).
### `migration:generate` — это черновик
`typeorm migration:generate` (запуск — в
[Как добавить миграцию](../90-deploy/10-migrations.md#как-добавить-миграцию)) всегда выдаёт тело из
строк `queryRunner.query(...)`, иначе он не умеет. Генератор полезен тем, что показывает полный
список расхождений схемы с сущностями — руками их легко не заметить. Но сгенерированный файл
дописывается до конца: DDL переписывается на методы `QueryRunner`, строкой SQL остаётся только то,
что под них не подходит.
### Когда допустим `queryRunner.query()`
Там, где API TypeORM нужную конструкцию не выражает. Типичные случаи: частичные и функциональные
индексы (`WHERE`, `lower(...)`), `ALTER COLUMN TYPE ... USING`, `CREATE INDEX CONCURRENTLY`,
`CREATE EXTENSION`, любые запросы к данным. В таком месте ставится комментарий, почему используется
строка SQL.
## `down` пишется всегда
Обратный метод обязателен для каждой миграции: `db-revert` — штатная команда проекта, и откат должен
работать не только на бумаге.
Если операция необратима по природе (удаление колонки с данными, добавление значения в enum-тип), у
`down` есть два варианта: упасть с ошибкой либо откатить схему с потерей данных. Что из этого
уместно, решается при написании конкретной миграции и фиксируется комментарием.
Первый вариант — откат запрещён:
```ts
export class DropContestDescription1790000001000 implements MigrationInterface {
name = 'DropContestDescription1790000001000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.dropColumn('contests', 'description');
}
public async down(): Promise<void> {
// откат невозможен: значения удалённой колонки восстановить неоткуда
throw new Error('DropContestDescription1790000001000 необратима');
}
}
```
Второй — та же миграция, но откат разрешён с потерей данных:
```ts
public async down(queryRunner: QueryRunner): Promise<void> {
// колонка возвращается пустой: прежние значения теряются
await queryRunner.addColumn(
'contests',
new TableColumn({ name: 'description', type: 'text', isNullable: true }),
);
}
```
## Проверка перед коммитом
Миграция считается проверенной, только если на локальной БД прошёл полный цикл:
```bash
yarn nx run api:db-migrate # накатить
yarn nx run api:db-revert # откатить
yarn nx run api:db-migrate # накатить снова
```
Все три шага должны отработать без ошибок. Второй накат ловит самый частый дефект — `down`, который
отработал не полностью и оставил в базе объект, на который потом спотыкается `up`.
Исключение — миграция, `down` которой намеренно падает: для неё проверяется только накат.
## Data-миграции — отдельным файлом
Изменение схемы и перенос/заполнение данных не смешиваются в одной миграции. Причина: миграция схемы
откатывается механически, а data-миграция часто необратима в принципе; в одном файле необратимой
становится вся пара.
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
миграцией — бэкфилл данных.
+188
View File
@@ -0,0 +1,188 @@
# Слой доступа к данным (DAL)
## Зачем
Цель — не абстракция «на случай смены СУБД», а независимость бизнес-кода **от методов работы с
базой**. Сервис не должен знать, что данные достаются через `Repository.findOne`, `save` или
`QueryBuilder`: он вызывает осмысленный метод и получает данные. Тогда изменение способа выборки —
добавление join'а, замена двух запросов одним, кэш — остаётся внутри одного файла и не требует
трогать бизнес-логику.
## Как устроено
DAL — это обычный Nest-провайдер, технически такой же сервис, но с суффиксом `Dal`:
```
apps/api/src/contests/
├── entities/
│ └── contest.entity.ts
├── contests.dal.ts
├── contests.service.ts
├── contests.controller.ts
└── contests.module.ts
```
```ts
@Injectable()
export class ContestsDal {
constructor(
@InjectRepository(Contest)
private readonly repository: Repository<Contest>,
) {}
public findById(id: number): Promise<Contest | null> {
return this.repository.findOne({ where: { id } });
}
}
```
- `@InjectRepository`, `Repository`, `DataSource`, `QueryBuilder` и любые прочие API TypeORM
допустимы **только внутри DAL**. Сервисы, контроллеры, guard'ы и интерцепторы к ним не обращаются.
- **Active Record не используется**: сущность содержит только поля и связи, никаких методов
сохранения/поиска на ней не появляется.
- **Мапперы не нужны.** DAL возвращает сущности как есть; отдельный слой доменных моделей не
вводится.
- Методы добавляются **по мере необходимости** — под конкретный запрос вызывающего кода. Заранее,
«чтобы было», API не пишется.
- Типы TypeORM в сигнатурах (`FindOptionsWhere`, `FindManyOptions` и подобные) — допустимое зло:
ради них не городится собственный язык запросов.
## Бизнес-логики в DAL нет
DAL отвечает за «достать и положить», решения принимает сервис.
Единственное исключение — логика, которую **необходимо выполнять на стороне БД**: агрегаты, массовые
`UPDATE`, `upsert`, выборки с блокировками, оконные функции. Абстрагироваться от них без потери
смысла (и производительности) нельзя, поэтому такая логика живёт в DAL.
## DAL — приватная часть модуля
DAL не попадает в `exports` модуля и **недоступен другим модулям ни при каких условиях**.
`TypeOrmModule.forFeature([...])` регистрируется в модуле-владельце и наружу не реэкспортируется.
Доступ к данным чужого модуля — только через его **публичные сервисы**.
Исключение — тот самый случай, когда бизнес-логика реализована в DAL (выполняется в БД). Тогда
детали схемы одного модуля могут протечь в другой: например, запрос с join'ом на чужую таблицу
вместо похода в чужой сервис. Это допустимо, но нежелательно — так делают, когда обход через
публичный сервис обходится дорого (N+1, выборка заведомо лишних данных), а не по умолчанию.
## Транзакции
Транзакцию открывает **сервис — владелец сценария**, а не DAL: одна транзакция накрывает вызовы
нескольких DAL, и ни один из них не знает о соседях.
Ради этого сервису разрешено внедрять `DataSource` — **зафиксированное исключение** из правила «API
TypeORM только внутри DAL». Исключение узкое: `DataSource` в сервисе используется **исключительно**
ради `dataSource.transaction(...)`. Репозитории и `QueryBuilder` из него не берутся — вся работа с
данными остаётся в DAL, а `manager` передаётся в его методы параметром.
Так устроено создание пользователя: владелец сценария `UsersService`
(`apps/api/src/users/users.service.ts`) открывает транзакцию, а участвует в ней чужой модуль —
`BillingAccountService` → `AccountsService` → `AccountsDal` (`apps/api/src/billing/`).
Дальше — схематичные примеры на вымышленном модуле конкурсов: такого кода в репозитории нет, он
показывает форму записи, а не место. Сервис-владелец сценария:
```ts
@Injectable()
export class ContestsService {
constructor(
private readonly contests: ContestsDal,
private readonly reviews: ReviewsDal,
// Исключение: `DataSource` здесь нужен только ради `transaction`.
@InjectDataSource()
private readonly dataSource: DataSource,
) {}
public launch(input: LaunchContestInput): Promise<Contest> {
return this.dataSource.transaction(async (manager) => {
await this.reviews.closeOpen(input.contestId, manager);
return this.contests.markLaunched(input.contestId, manager);
});
}
}
```
DAL принимает `manager` опциональным параметром и по нему выбирает репозиторий:
```ts
@Injectable()
export class ContestsDal {
constructor(
@InjectRepository(Contest)
private readonly contests: Repository<Contest>,
) {}
public findById(id: number, manager?: EntityManager): Promise<Contest | null> {
return this.repository(manager).findOne({ where: { id } });
}
private repository(manager?: EntityManager): Repository<Contest> {
return manager?.getRepository(Contest) ?? this.contests;
}
}
```
Параметр опционален у любого метода — и у чтения, и у записи. Выполнять операцию в транзакции или
нет — ответственность вызывающей стороны: метод работает с тем `manager`, который ему передали, а
без него — вне транзакции. Так один и тот же `AccountsDal.findRegionByCode` читает справочник
регионов и в транзакции создания пользователя (из `AccountsService.create`), и без неё — на
стартовой проверке `BillingModule`. Выборка с блокировкой (`SELECT ... FOR UPDATE`) устроена так же:
блокировка держится только внутри транзакции, и открыть её — забота вызывающего.
Публичный метод сервиса, который может участвовать в чужой транзакции, тоже принимает
`manager?: EntityManager` и пробрасывает его дальше. Контекст передаётся явно, `AsyncLocalStorage`
не вводится.
Внешние вызовы — HTTP, SMTP, очереди — внутрь транзакции не заводятся: письмо верификации
`AuthService.registration` отправляет **после** возврата из `UsersService.createUser`, то есть после
коммита. Иначе транзакция держит соединение с базой на время сетевого таймаута, а откат письмо уже
не отзовёт.
### Модуль без своего DAL
Пока модуль на DAL не переведён (сегодня это `users`), внутри `dataSource.transaction(...)` все
операции с его сущностями идут через `manager.getRepository(...)` **прямо в сервисе**. Внедрённый
`this.userRepository` работает вне транзакции — он берёт собственное соединение, и откат его записи
не отменит.
```ts
// Сервис модуля без DAL, которому нужна транзакция:
return this.dataSource.transaction(async (manager) => {
// Именно `manager.getRepository`, а не внедрённый `this.userRepository`.
const users = manager.getRepository(User);
// Только анкетные поля: `create(dto)` перенёс бы на сущность любую пришедшую колонку и связь.
const user = users.create({
email: dto.email,
password: dto.password,
firstName: dto.firstName,
lastName: dto.lastName,
});
// Чужая операция вызывается тем же `manager`: аккаунт и строка пользователя пишутся одной
// транзакцией. Регион резолвит сам биллинг — `users` про его конфигурацию не знает.
const account = await this.billingAccount.create({ name: user.email }, manager);
user.billingAccountId = account.id;
return users.save(user);
});
```
Строка собирается из явного перечня анкетных полей, а не из `dto` целиком: у
`POST /auth/registration` валидирующего пайпа нет, поэтому в воронку уезжает сырое тело анонимного
запроса, а `create(dto)` (typeorm 0.3.x) перенёс бы на сущность и служебные колонки (`id`,
`emailVerified`, `banned`, `refreshToken`), и связь `roles`. Перечень — основная защита воронки,
поэтому расширяется осознанно (докблок `UsersService.createWithBillingAccount`).
Аккаунт заводится **до** вставки пользователя, чтобы строка сразу писалась со ссылкой
`users.billingAccountId`, а не догонялась вторым `save`. Такой порядок возможен потому, что
`billing_accounts` на `users` не ссылается.
Вне транзакции тот же сервис пишет через внедрённый `this.userRepository` — так устроены одиночные
записи вроде `UsersService.setUserEmailVerified` и `saveRefreshToken`, где менять нечего, кроме
одной строки `users`.
Оговорка временная: с появлением `users.dal.ts` этот код уезжает в DAL по общему правилу.
+31
View File
@@ -0,0 +1,31 @@
# Тесты
## Расположение и имя
Юнит-тест лежит **рядом с тестируемым файлом**, отдельной папки под тесты нет:
```
apps/api/src/contests/
├── contests.service.ts
└── contests.service.test.ts
```
Расширение — `.test.ts` (`.test.tsx` для React-компонентов).
В репозитории встречается и `.spec.ts` — vitest подхватывает оба паттерна.
## DAL тестами не покрывается
Юнит-тест DAL с замоканным репозиторием проверял бы сам себя: что `findOne` вызван с теми
аргументами, с которыми его вызвали. Такие тесты не пишутся.
Логика, ради которой стоит писать тест, живёт в сервисе — там она и тестируется, с замоканным DAL.
Исключение — [БД-логика внутри DAL](30-data-access.md#бизнес-логики-в-dal-нет): её корректность
проверяется на реальной базе, а не моками.
## Запуск
```bash
yarn nx run api:test
yarn nx run web:test
```
+1
View File
@@ -0,0 +1 @@
label: 'Разработка'
+377
View File
@@ -0,0 +1,377 @@
# Миграции базы данных
Миграции TypeORM применяются **автоматически при деплое** — и на проде (на каждый тег), и на
стейджинге (на каждый push/PR); деплой падает, если миграция не прошла. См.
[Обязательные переменные `.env` на стейджинг-хосте](#обязательные-переменные-env-на-стейджинг-хосте).
⚠️ Перед первым прод-деплоем убедитесь, что `aigeo_app` имеет права на DDL и что таблица
`migrations` согласована со схемой — см. [Права на БД](#права-на-бд). Автоматического бэкапа перед
миграцией нет.
Схема БД в рантайме не синхронизируется: `synchronize: false`, `migrationsRun: false`. Единственный
способ изменить схему — миграция.
Как **писать** саму миграцию (API `QueryRunner`, `down`, data-миграции) —
[Написание миграций](../50-developing/20-migrations.md).
## Как это устроено
Webpack не умеет runtime-glob: запись `migrations: ['*.js']` внутри бандла не работает в принципе.
Поэтому список миграций генерируется статически на этапе сборки.
1. **Кодогенерация.** `tools/buildDataSource.ts` сканирует `apps/api/src/database/migrations/*.ts`,
вытаскивает имена экспортируемых классов и пишет `apps/api/src/database/migrations.ts` со
статическими импортами. Сортировка — по числовому timestamp из имени файла (возрастание).
Результат прогоняется через Prettier внутри генератора и **коммитится в репозиторий**.
2. **Единый DataSource.** `apps/api/src/config/typeorm.config.ts` берёт `migrations` из
сгенерированного файла. Один и тот же файл работает локально через `typeorm-ts-node-commonjs` и в
собранном виде внутри контейнера.
3. **Отдельный бандл.** `apps/api/webpack.data-source.config.js` собирает `data-source.js` в тот же
`apps/api/dist`, что и `main.js` (`output.clean: false`, иначе затрёт основной бандл). В образе
оба файла лежат в `/app` рядом с `node_modules`.
⚠️ Попадание `dist` в образ держится на том, что **`apps/api/.dockerignore` отсутствует**:
контекст сборки — `apps/api`, а правило `**/dist` из корневого `.dockerignore` при наличии
локального файла перестало бы игнорироваться (docker берёт `.dockerignore` из корня контекста).
Создание `apps/api/.dockerignore` молча соберёт образ без `main.js` и `data-source.js`.
Отдельной CI-проверки этого нет: если файлов не окажется в образе,
`migration:show`/`migration:run` на деплое упадут с понятной ошибкой
(`Cannot find module '/app/data-source.js'` или аналогичной).
4. **Шаги в деплое.** После подъёма контейнеров — `migration:show` в лог, затем
`migration:run -t each`, на проде и на стейджинге.
Генерация подключена к сборке через `dependsOn`, отдельно её запускать не нужно:
```bash
yarn nx run api:build # db-migrations-list → main.js → data-source.js
yarn nx run api:db-migrations-list # только перегенерация списка
```
Запись в `migrations.ts` идемпотентна: если содержимое не изменилось, файл не переписывается (иначе
`api:serve` в watch-режиме уходил бы в бесконечный цикл пересборок).
## Как добавить миграцию
1. Создать файл в `apps/api/src/database/migrations/` — вручную или через
`typeorm migration:generate`. Имя файла обязано начинаться с **13-значного** timestamp:
`1774001000000-fix-subscription-plan-id-default.ts`, а имя класса — оканчиваться тем же timestamp
(`FixSubscriptionPlanIdDefault1774001000000`). TypeORM берёт timestamp как
`parseInt(className.substr(-13))` и игнорирует порядок массива в `migrations.ts`, поэтому
расхождение суффикса класса и префикса файла означает применение не в том порядке. Генератор
проверяет это и валит сборку.
`migration:generate` запускается из **корня воркспейса** и требует двух переменных окружения —
без них ts-node не подхватит `experimentalDecorators` и TS-алиасы:
```bash
TS_NODE_PROJECT=apps/api/tsconfig.app.json \
NODE_OPTIONS="-r tsconfig-paths/register" \
yarn typeorm-ts-node-commonjs migration:generate \
apps/api/src/database/migrations/add-something \
-d apps/api/src/config/typeorm.config.ts
```
Те же две переменные задаются один раз в `nx.json` → `targetDefaults` под ключом
`db-{show,migrate,revert,drop}` и подмешиваются в эти четыре таргета. Namespace-паттерн важен:
`db-*` захватил бы ещё `db-snapshot` / `db-restore` / `db-migrations-list`, которые запускаются
обычным `ts-node` из корня и с api-шным tsconfig сломались бы.
Вывод генератора — черновик: он всегда пишет тело строками `queryRunner.query(...)`, а в проекте
DDL оформляется методами `QueryRunner`. См.
[Написание миграций](../50-developing/20-migrations.md).
2. Перегенерировать список: `yarn nx run api:db-migrations-list` (или просто
`yarn nx run api:build`).
3. **Закоммитить оба файла** — саму миграцию и `apps/api/src/database/migrations.ts`.
4. Проверить локально: `yarn nx run api:db-show` (миграция должна появиться в списке), затем цикл
накат → откат → накат — см.
[Проверка перед коммитом](../50-developing/20-migrations.md#проверка-перед-коммитом).
Генератор падает с ненулевым кодом, если: в файле нет `export class`; в файле больше одного
`export class`; имя файла не начинается с 13-значного timestamp; суффикс имени класса не совпадает с
префиксом имени файла; файлов не найдено вовсе; два файла дают одинаковое имя класса. Так как он
висит на `dependsOn` у `build`, любая из этих ошибок валит сборку.
Файлы-спутники (`*.d.ts`, `*.spec.ts`, `*.test.ts`) в директории миграций игнорируются и
генератором, и `tools/checkDataSource.ts` — последний вызывает `readMigrations()` генератора, так
что правило фильтрации физически одно.
### Локальные команды
| Команда | Что делает |
| ------------------------------------ | ------------------------------------- |
| `yarn nx run api:db-migrations-list` | перегенерировать статический список |
| `yarn nx run api:db-show` | список миграций и их статус |
| `yarn nx run api:db-migrate` | применить непримененные |
| `yarn nx run api:db-revert` | откатить последнюю применённую |
| `yarn nx run api:db-drop` | удалить схему целиком (`schema:drop`) |
| `yarn nx run api:db-snapshot` | снять снимок данных в JSON |
| `yarn nx run api:db-restore` | восстановить данные из снимка |
Все они, кроме `db-migrations-list` (он работает только с файлами), подключаются к БД из `.env`
(`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` / `POSTGRES_HOST` / `POSTGRES_PORT`).
Отдельную базу можно подставить переменной окружения — `dotenv` работает с `override: false`,
поэтому окружение имеет приоритет над `.env`:
```bash
POSTGRES_DB=aigeo_migtest yarn nx run api:db-migrate
```
## Проверки в CI
`.gitea/workflows/ci.yaml`:
- **`Check migrations list`** — `yarn ts-node tools/buildDataSource.ts --check`. Генератор рендерит
список, сравнивает с содержимым `apps/api/src/database/migrations.ts` и падает при расхождении,
ничего не записывая. Сравнение идёт с тем же отформатированным текстом, что и запись, поэтому git
в проверке не участвует вовсе.
- **`Check data-source`** (после `yarn build`) — `yarn ts-node tools/checkDataSource.ts` загружает
собранный `apps/api/dist/data-source.js`, проверяет, что экспорт ведёт себя как `DataSource`
(`initialize()` + объект `options`), и что список классов в бандле **посимвольно совпадает** с
тем, что даёт `readMigrations()` генератора по файлам на диске (там же валидируются 13-значные
timestamp-суффиксы имён классов).
Оба шага идут **до** сборки docker-образов: битый data-source не попадёт в реестр. Оба
продублированы в `.gitea/workflows/production.yaml` — теги не проходят через `ci.yaml` (он
срабатывает на push в master и на PR), поэтому свою копию проверок прод-путь обязан иметь.
### ⚠️ SQL миграций попадает в логи job
`MigrationRunCommand` принудительно выставляет `logging: ["query", "error", "schema"]` поверх
настроек `DataSource`, отключить это флагом или из `typeorm.config.ts` нельзя. Каждый выполненный
запрос — вместе со значениями параметров — уходит в лог job деплоя, видимый любому, у кого есть
доступ на чтение репозитория.
Это ограничение принято осознанно: тот же лог — основной инструмент разбора инцидента (см. Runbook,
шаг 1). Но из него следует жёсткое правило для авторов миграций:
**Data-миграции не должны переносить секреты и персональные данные литералами.** Если миграции нужно
изменить пароли, токены, email-адреса и т. п. — делайте это выражениями на стороне SQL
(`UPDATE … SET token = encode(gen_random_bytes(32), 'hex')`), а не `INSERT`/`UPDATE` с готовыми
значениями в тексте миграции. Разовые операции с реальными данными выполняйте вручную через
`docker exec` (раздел «Ручной запуск миграций на проде»), а не деплоем.
## Применение на стейджинге
Job `deploy-staging` в `.gitea/workflows/ci.yaml` (запускается на каждом PR и push в master), сразу
после `docker compose up -d`:
1. `migration:show` (в лог), затем `migration:run -t each` — через `docker compose exec -T api …`.
Отдельного ожидания готовности контейнера нет: живой/healthy HTTP-слой NestJS для
`typeorm migration:run` не нужен, он идёт отдельным процессом через `data-source.js`. Если
контейнер всё же не поднялся (например, при пустых `DB_*`), `docker compose exec` упадёт с
понятной ошибкой сам.
2. `docker system prune -f` — после миграций, одним вызовом в конце скрипта. Если `migration:run`
упадёт, под `set -e` prune не выполнится — почистится на следующем деплое.
Ненулевой код валит job: у шага стоит `script_stop: true` (штатный механизм `appleboy/ssh-action`),
а первой строкой скрипта — `set -e`.
### Обязательные переменные `.env` на стейджинг-хосте
`docker-compose.staging.yml` берёт креды БД из `.env` в каталоге деплоя (`~/<repo>_<branch>/`) и
мапит их в `POSTGRES_*`, которые единственные читают и приложение (`app.module.ts`), и typeorm CLI.
Полный список — в [Configuration](20-configuration.md#переменные-окружения-деплоя).
Переменные объявлены через `${DB_HOST:-}`, то есть **не** обязательные. Обязательный синтаксис
`${DB_HOST:?…}` здесь применять нельзя: он валит любую подкоманду compose, включая `pull` и `down`.
Каталог деплоя создаётся заново для каждой новой ветки (его делает `appleboy/scp-action`), `.env`
туда не кладёт ни CI, ни кто-либо ещё — обязательные переменные означали бы красный `deploy-staging`
на первом же пуше любой новой ветки и невозможность даже погасить полуподнятый стек.
Ценой этого при пустых `DB_*` api не подключится к БД, и `docker compose exec … migration:show`
упадёт с ошибкой подключения — это и есть сигнал, что в `.env` каталога деплоя не заданы `DB_HOST` /
`DB_USERNAME` / `DB_PASSWORD` / `DB_DATABASE`.
⚠️ **Ветки не делят одну базу.** Стейджинг-БД в compose не поднимается, она внешняя и общая по сети
`net`. Общая база означает, что миграция из одного PR меняет схему для всех остальных веток и для
master, а закрытый без мержа PR оставляет свою миграцию применённой навсегда — автоматического
отката нет.
`concurrency.cancel-in-progress` в `ci.yaml` оставлен `true` (в отличие от прода). Группа привязана
к ветке, поэтому отменяется только предыдущий прогон той же ветки, а быстрая итерация по PR важнее.
Плата реальна: отмена посреди `migration:run -t each` оставит стейджинг-БД частично мигрированной
(лечится повторным прогоном job).
Кроме того, TypeORM не берёт кросс-процессную блокировку: два одновременных прогона `migration:run`
по одной базе (разные PR при общей БД) попытаются применить один и тот же набор.
## Применение на проде
Job `deploy-production` в `.gitea/workflows/production.yaml`, блок `Deploy via SSH` (heredoc — не
`appleboy/ssh-action`, синтаксис отличается от стейджинга). Порядок:
1. `docker-compose pull` → `down` → `up -d`.
2. Сразу после `up -d` — `migration:show` (в лог видно, что именно будет применено), затем
`migration:run -t each`. Последняя команда скрипта, её код выхода уходит через `ssh` и валит job.
Ожидания готовности контейнера между шагами 1 и 2 нет, и это намеренно:
- postgres поднимается **до** api — у api стоит `depends_on: postgres: condition: service_healthy`,
так что `up -d` не вернётся, пока БД не готова;
- `docker exec` сам падает, если контейнер не `running`, — отдельная проверка того же лишь
дублировала бы это раньше по времени и потому менее достоверно (с `restart: unless-stopped`
крешлупящий контейнер периодически бывает `running`);
- ждать `healthy` не нужно тем более: healthcheck образа (`curl /api/health`, `start-period=15s`)
поднимает HTTP-слой NestJS, а `migration:run` идёт отдельным процессом со своим соединением через
`data-source.js`.
Логи приложения при провале смотрятся на хосте: `docker logs geo-platform_api --tail 50`.
⚠️ `migration:show` — не безобидная команда «только посмотреть»:
- `showMigrations()` вызывает `createMigrationsTableIfNotExist()`
(`typeorm/migration/MigrationExecutor.js`), то есть выполняет настоящий
`CREATE TABLE "migrations"`, если таблицы ещё нет;
- `MigrationShowCommand` завершается кодом `0` только на успешном пути. В `catch` стоит
`process.exit(1)` — например, при `permission denied for schema public` у `aigeo_app`.
Под `set -e` это означает, что деплой упадёт уже на `migration:show`, если у `aigeo_app` нет прав на
DDL, — и упадёт после того, как новый образ ушёл на трафик.
`concurrency.group` этого workflow — константа `production-deploy`, а не имя ref. Workflow
запускается по тегам, и группа с тегом в имени давала бы каждому тегу собственную группу: два тега
подряд запустили бы два `migration:run -t each` параллельно по одной БД, а кросс-процессной
блокировки у TypeORM нет. `cancel-in-progress: false` — отмена job посреди набора рвёт SSH-сессию и
оставляет БД частично мигрированной.
`VERSION` и `LOG_LEVEL` передаются в remote-скрипт через `env:` шага, а не подстановкой `${{ … }}` в
тело heredoc: `VERSION` приходит из git-тега, а в имени ref допустимы кавычки, `;`, `$` и обратные
кавычки — шаблонизатор вписал бы их в текст скрипта до запуска шелла. Оба значения к тому же
валидируются по белому списку символов (`VERSION` — в job `build`, `LOG_LEVEL` — перед `ssh`).
### Почему `-t each`
Каждая миграция выполняется в своей транзакции, а не весь набор в одной длинной. Это осознанное
решение: не держим блокировки на всё время деплоя. Плата — при провале на N-й миграции первые N−1
остаются применёнными, БД оказывается в промежуточном состоянии. Разбор такого состояния ручной.
### Почему миграции после `up -d`, а не до
Осознанное решение. Риск не в нескольких секундах старой схемы, а в том, что при провале миграции
новый образ продолжает обслуживать трафик против старой схемы бесконечно
(`restart: unless-stopped`). Именно поэтому деплой логирует предыдущий тег образа, а ниже описан
runbook отката.
## ⚠️ Автоматического бэкапа перед миграцией нет
Деплой **не снимает дамп БД** перед запуском миграций. Это вынесено в отдельную задачу и на момент
написания не реализовано.
Существующий cron-бэкап (`apps/api/src/database/backup.service.ts` + `backup-scheduler.service.ts`)
на прод рассчитывать нельзя: в `apps/api/Dockerfile` нет `postgresql-client`, а `BACKUP_DIR` не
смонтирован томом в `docker-compose.production.yml`.
**Практический вывод:** если содержимое БД критично, снимите дамп вручную перед запуском
прод-деплоя. При разборе инцидента не рассчитывайте на существование свежей резервной копии.
## Runbook: миграция упала на проде
Из-за `-t each` набор может быть применён частично. Порядок разбора:
1. **Определить, до какой миграции дошли.** В логе job шаг `Применение миграций` печатает каждую
применённую миграцию с её `START TRANSACTION` / `COMMIT`. Последняя успешная строка — граница;
следующая за ней миграция и есть упавшая, там же лежит текст ошибки от Postgres.
2. **Сверить с реальным состоянием БД:**
```bash
ssh <prod>
docker exec geo-platform_api node_modules/.bin/typeorm migration:show -d data-source.js
```
`[X]` — применена, `[ ]` — нет. Этот вывод — источник истины, а не лог job.
3. **Решить, катить вперёд или чинить.**
- Ошибка разовая (таймаут, блокировка, нехватка прав) — починить причину и повторить
`migration:run -t each` вручную (см. ниже). Уже применённые миграции пропустятся.
- Ошибка в самой миграции — исправлять кодом: новая миграция поверх либо правка упавшей с
последующим передеплоем. Ручные правки схемы мимо миграций оставляют прод и репозиторий в
расхождении, и следующий деплой упадёт снова.
4. **Откатить образ, если сервис сломан.** Предыдущий тег — это предыдущий тег `v*` в репозитории
(`git tag --sort=-creatordate | head`); что именно скачано на хост, видно в
`docker images git.jt4d.ru/geo-helm/geo-platform/api`:
```bash
cd /srv/geo-platform
VERSION=<prev> docker-compose up -d
```
⚠️ Один `VERSION` применяется сразу к `web` и `api`. Команда корректна только если оба образа
тегированы синхронно (обычный случай — их собирает один прогон `production.yaml`). Если теги
разошлись, поднимайте сервисы по одному (`VERSION=<prev> docker-compose up -d api`).
Откат образа **не откатывает схему БД** — применённые миграции остаются применёнными. Если
старый код несовместим с новой схемой, откатывать схему придётся отдельно (`migration:revert`,
по одной миграции за вызов) или восстанавливать из ручного дампа.
5. **Проверить результат:** `/api/health` и `docker logs geo-platform_api --tail 100`.
## Ручной запуск миграций на проде
Понадобится, если миграции нужно применить вне деплоя (повтор после разбора инцидента, разовая
операция). Порт postgres наружу не проброшен, поэтому всё делается через `docker exec` внутри
контейнера api — `WORKDIR` образа `/app`, там же лежат `data-source.js` и `node_modules`:
```bash
ssh <prod>
# посмотреть, что применится
docker exec geo-platform_api node_modules/.bin/typeorm migration:show -d data-source.js
# применить
docker exec geo-platform_api node_modules/.bin/typeorm migration:run -t each -d data-source.js
# откатить последнюю применённую (по одной за вызов)
docker exec geo-platform_api node_modules/.bin/typeorm migration:revert -d data-source.js
```
Перед запуском учтите, что автоматического бэкапа нет (см. выше).
## Права на БД
Api ходит в прод-БД под `aigeo_app` — это не владелец схемы. Первое, обо что упадёт `migration:run`
в свежем окружении, — нехватка прав на DDL. Проверяется пробным `CREATE TABLE _ddl_probe(...)` /
`DROP TABLE _ddl_probe` из-под `aigeo_app`.
Если схема уже содержит объекты из миграций, а записей в таблице `migrations` нет, `migration:run`
попытается создать существующее и упадёт. Такое состояние надо **забаселайнить** — проставить записи
без выполнения `up()`.
**Полный baseline** (вся схема уже соответствует всем непримененным миграциям) — штатный флаг
TypeORM `--fake` / `-f` (`MigrationRunCommand`, `MigrationExecutor`):
```bash
docker exec geo-platform_api node_modules/.bin/typeorm migration:show -d data-source.js # сначала посмотреть список
docker exec geo-platform_api node_modules/.bin/typeorm migration:run --fake -d data-source.js
```
`--fake` вставляет записи в таблицу `migrations`, не выполняя `up()`. Он применяется ко **всему**
набору непримененных миграций сразу, выборочно пометить одну нельзя. Поэтому использовать его можно
только когда `migration:show` показывает `[ ]` ровно у тех миграций, объекты которых в схеме уже
есть.
**Частичный baseline** (часть непримененных миграций в схеме есть, часть — нет): `--fake` не
подходит, записи проставляются вручную по одной:
```sql
INSERT INTO migrations (timestamp, name) VALUES (1764100000000, 'AddPublicMetricRequests1764100000000');
```
`name` — имя класса точь-в-точь, `timestamp` — числовой префикс из имени файла (он же обязан
совпадать с 13-значным суффиксом имени класса — это проверяет генератор). Ошибка в `name` не
диагностируется ничем: миграция либо молча выполнится повторно, либо будет пропущена навсегда.
### Перед первым прод-деплоем
Прод-деплой применяет миграции на каждый тег — поэтому проверки ниже делаются **до** первого деплоя
с миграциями, а не после:
1. проверить права `aigeo_app` на DDL: пробный `CREATE TABLE _ddl_probe(...)` / `DROP TABLE` из-под
него (раздел «Права на БД» выше). Без них деплой упадёт уже на `migration:show`;
2. привести таблицу `migrations` в согласованное состояние — baseline, если схема уже содержит
объекты из непримененных миграций (там же). Иначе первая же миграция упадёт на
`relation already exists`, а с `-t each` набор останется применённым частично;
3. снять ручной дамп БД — автоматического бэкапа нет (см. выше).
То же самое верно для первого деплоя на стейджинге (раздел «Применение на стейджинге»).
+56
View File
@@ -0,0 +1,56 @@
# Geo Platform
Geo Platform — рабочее пространство для управления присутствием бренда в поисковиках и генеративных
ИИ-системах (ChatGPT, Perplexity, Google AI Overviews и т. п.). Платформа помогает подготовить о
бренде структурированные, проверяемые и согласованные данные, чтобы поиск и LLM отвечали о нём
корректно. Аббревиатура GEO расшифровывается как **Generative Engine Optimization**.
## Кому подходит
- Владельцам бизнеса, которым важно, как их компанию описывают поисковики и ИИ-ассистенты.
- SEO- и контент-специалистам, отвечающим за структурированные данные, Entity Home и E-E-A-T.
- Маркетологам и агентствам, ведущим сразу несколько брендов.
- Администраторам, управляющим пользователями платформы.
## Что можно делать
- Заводить и вести карточки брендов: название, сайт, ключевые слова, статус, команда с ролями.
- Заполнять «паспорт бренда» через пошаговый мастер: юридические данные, миссия, описание, контакты,
адрес, политики.
- Автоматически генерировать JSON-LD (Organization, LocalBusiness и др.) на основе паспорта и
выгружать его для встраивания на сайт.
- Проводить NAP-аудит: сверять имя, адрес и телефон бренда во внешних справочниках, соцсетях и
сайтах отзывов, отслеживать оценку согласованности.
- Собирать Entity Home — авторитетные страницы о компании, команде, доверии и контактах со
структурированными фактами.
- Связывать бренд с Wikidata через Q-элементы, чтобы закрепить сущность в открытом графе знаний.
- Измерять GEO-видимость через LLM-метрики: как часто бренд упоминается ИИ-моделями, в каком
контексте и по каким запросам.
- Проверять технику сайта: доступность, SSL, базовые сигналы качества.
- Отслеживать историю изменений в журнале аудита — ручные правки, импорты, автосинхронизации.
- Сравнивать тарифы на витрине — она открыта и без входа, а вошедшему отмечает его текущий план.
- Смотреть свою подписку: план, его условия и дата окончания оплаченного периода.
- Администраторам — вести тарифную линейку (планы и их версии) и разбирать биллинг конкретного
пользователя в его карточке.
## Разделы интерфейса
- **Workspace** — список брендов и создание нового.
- **Brand Management** — управление одним брендом: сущности, метрики, проверки сайта, отчёты.
- **Entity Graph** — работа с данными сущности: Overview, Passport, JSON-LD, Connectors, Audit,
Entity Home, Wikidata.
- **Тарифы (`/pricing`)** — публичная витрина планов: цены и условия, доступна без входа.
- **Settings** — профиль пользователя, язык, тема, вкладка «Моя подписка» с текущим тарифом.
- **Admin** — управление пользователями (в карточке пользователя есть вкладка биллинга), тарифная
линейка («Тарифы», `/admin/plans`) и системные настройки платформы.
## Термины
- **Бренд (Brand / Project)** — основная сущность платформы, объединяет все данные компании.
- **Сущность (Entity)** — отдельный объект бренда: филиал, локация, юрлицо.
- **NAP** — Name, Address, Phone: канонические контактные данные, которые сверяются с внешними
профилями.
- **Паспорт бренда (Passport)** — структурированная анкета о компании, из которой строятся JSON-LD и
Entity Home.
- **JSON-LD** — формат структурированных данных, который читают поисковики и ИИ-модели.
- **GEO** — оптимизация под генеративные поисковые системы.