diff --git a/README.md b/README.md
index 1434c82..48f20b3 100644
--- a/README.md
+++ b/README.md
@@ -1,109 +1,130 @@
-# New Nx Repository
+# Nx-монорепозиторий — шаблон
-
+Стартовый репозиторий для нового веб-проекта: Nx 22 + yarn workspaces, бэкенд на NestJS с TypeORM и
+PostgreSQL, фронтенд на React + Vite, e2e-тесты, единый линт, миграции, CI/CD в Gitea Actions со
+стендом на каждую ветку и документация в MDX.
-✨ Your new, shiny [Nx workspace](https://nx.dev) is ready ✨.
+Шаблон содержит пустой каркас приложений (health-check и демо-страница) и полностью рабочую
+инфраструктуру: сборку, миграции, проверки, деплой и документацию. Новый проект начинается с
+клонирования репозитория и чек-листа из раздела «Новый проект из шаблона».
-[Learn more about this workspace setup and its capabilities](https://nx.dev/docs/technologies/typescript/introduction?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) or run `npx nx graph` to visually explore what was created. Now, let's get you up to speed!
+## Что уже настроено
-🚀 If you haven't connected to Nx Cloud yet, [complete your setup here](https://cloud.nx.app/get-started). Get faster builds with remote caching, distributed task execution, and self-healing CI. [See how your workspace can benefit](#nx-cloud).
+- **Монорепозиторий.** Nx 22 управляет задачами, yarn workspaces — зависимостями приложений и
+ пакетов; общие библиотеки добавляются в `packages/`.
+- **Приложения.** `api` (NestJS 11, глобальный префикс `/api`, Swagger на `/api/docs`), `web` (React
+ 19 + Vite 7 + Tailwind, раздача статики через Caddy), `api-e2e` (Jest).
+- **Линт и форматирование.** ESLint flat config, Prettier, Stylelint, `tsc --noEmit`; одна команда
+ `yarn lint` чинит, `yarn lint:check` — проверяет как в CI.
+- **Хуки git.** Husky запускает `lint-staged` на pre-commit и проверку имени ветки на pre-push.
+- **Миграции TypeORM.** Статический список миграций генерируется скриптом (webpack не умеет
+ runtime-glob), есть снимок данных БД в JSON и восстановление из снимка.
+- **CI/CD.** Gitea Actions: ветка → Docker-образы + стенд, удаление ветки → удаление стенда, тег
+ `v*` → прод. Деплой применяет миграции автоматически.
+- **Документация.** MDX в `docs/`, публикуется через Docuservix.
+- **Шаблоны задач.** `bug`, `issue`, `epic`, `user-story` в `.gitea/issue_template/`.
+- **Инструкции для ИИ-агентов.** `AGENTS.md` — обзор, команды, архитектура и конвенции; плюс конфиги
+ для Cursor, GitHub Copilot, Gemini, Codex, OpenCode.
-## Generate a library
+## Стек
-```sh
-npx nx g @nx/js:lib packages/pkg1 --publishable --importPath=@my-org/pkg1
+| Слой | Технологии |
+| -------- | --------------------------------------------------- |
+| Сборка | Nx 22, yarn 1 (workspaces), TypeScript 5.9, Node 24 |
+| Бэкенд | NestJS 11, TypeORM, PostgreSQL, webpack, Vitest |
+| Фронтенд | React 19, Vite 7, Tailwind, Caddy |
+| E2E | Jest |
+| Качество | ESLint, Prettier, Stylelint, Husky, lint-staged |
+| Доставка | Gitea Actions, Docker, docker compose, Docuservix |
+
+## Структура
+
+| Путь | Назначение |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| `apps/api` | NestJS-бэкенд: TypeORM + PostgreSQL, сборка webpack, тесты Vitest |
+| `apps/web` | React + Vite + Tailwind, Caddy раздаёт статику и проксирует `/api` |
+| `apps/api-e2e` | e2e-тесты API на Jest |
+| `packages/` | общие библиотеки воркспейса |
+| `tools/` | скрипты воркспейса: сборка и проверка data source, снимок и восстановление БД |
+| `docs/` | документация в MDX: слои приложений, БД, деплой |
+| `.gitea/workflows/` | CI/CD: `ci.yaml` (ветки), `production.yaml` (теги), `cleanup.yaml` |
+| `.gitea/issue_template/` | шаблоны задач Gitea |
+
+## Быстрый старт
+
+```bash
+yarn install
+yarn start # api на :5000 (Swagger — /api/docs), web на :5173
```
-## Run tasks
+Проверить, что всё поднялось: `http://localhost:5000/api/health` и `http://localhost:5173`. Задачи
+запускаются только через Nx:
-To build the library use:
-
-```sh
-npx nx run pkg1:build
+```bash
+yarn nx run : # одна задача
+yarn nx run-many -t # по всем проектам
+yarn nx affected -t # только по затронутым проектам
```
-To run any task with Nx use:
+## Команды
-```sh
-npx nx run :
-```
+| Команда | Что делает |
+| -------------------------------------- | ------------------------------------------------------ |
+| `yarn start` | запуск всех приложений |
+| `yarn build` | сборка всех проектов |
+| `yarn rebuild` | очистка и сборка заново |
+| `yarn lint` | линт с автофиксом: eslint + prettier + stylelint + tsc |
+| `yarn lint:check` | те же проверки без автофикса (используется в CI) |
+| `yarn db-show` | статус миграций TypeORM |
+| `yarn db-migrate` / `yarn db-revert` | применить непримененные / откатить последнюю миграцию |
+| `yarn db-migrations-list` | перегенерировать статический список миграций |
+| `yarn db-snapshot` / `yarn db-restore` | снимок данных БД в JSON и восстановление из снимка |
-These targets are either [inferred automatically](https://nx.dev/docs/concepts/inferred-tasks?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) or defined in the `project.json` or `package.json` files.
+Подключение к БД задаётся переменными `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`,
+`POSTGRES_PASSWORD`, `POSTGRES_DB` — в `.env` локально или в окружении контейнера.
-[More about running tasks in the docs »](https://nx.dev/docs/features/run-tasks?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+## Ветки и пайплайны
-## Versioning and releasing
+- `master` — основная ветка.
+- Рабочие ветки — `i<номер>-краткое-описание`, только `a-z`, `0-9` и `-`; формат проверяют Husky на
+ pre-push и CI.
+- Пуш в ветку или PR: сборка, проверка имени ветки, проверка списка миграций, сборка Docker-образов
+ `api`/`web`, стенд на `<ветка>.<домен>`, линт, публикация документации.
+- Удаление ветки: стенд удаляется (`cleanup.yaml`).
+- Тег `v*`: сборка и выкладка в прод (`production.yaml`), миграции применяются автоматически.
-To version and release the library use
+## Новый проект из шаблона
-```
-npx nx release
-```
+1. **Переименовать воркспейс.** `package.json` (`@geo-platform/*`), `project.json`, `nx.json`,
+ `tsconfig.base.json` (`paths` и `customConditions`), `apps/*/package.json`.
+2. **Настроить доставку.** Домен и registry в `.gitea/workflows/*.yaml`,
+ `docker-compose.production.yml`, `docker-compose.staging.yml`, `.docuservix.yml`; домен в
+ `apps/web/Caddyfile` и список CORS-origin в `apps/api/src/main.ts`.
+3. **Задать переменные и секреты репозитория в Gitea.** `vars.REGISTRY_USER`, `vars.STAGING_HOST`,
+ `vars.STAGING_USER`, `vars.STAGING_PORT`; `secrets.REGISTRY_PASSWORD`,
+ `secrets.STAGING_SSH_PRIVATE_KEY`.
+4. **Убрать демо-код.** `apps/web/src/app/nx-welcome.tsx` и демо-страница в `apps/web/src/app`,
+ тестовый контроллер и сервис в `apps/api/src/app`.
+5. **Пересобрать миграции.** Удалить тестовую миграцию из `apps/api/src/database/migrations/` и
+ выполнить `yarn db-migrations-list`; список `apps/api/src/database/migrations.ts` коммитится.
+6. **Обновить тексты под проект.** `docs/index.md`, документы в `docs/`, `AGENTS.md`, этот
+ `README.md`.
+7. **Проверить ветку в CI.** Первый пуш должен пройти `yarn lint:check` и сборку, а стенд —
+ открыться по своему адресу.
-Pass `--dry-run` to see what would happen without actually releasing the library.
+## Документация
-[Learn more about Nx release »](https://nx.dev/docs/features/manage-releases?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
+- [Оглавление](docs/index.md)
+- [Слои API](docs/50-developing/01-api-layers.md) и [слои web](docs/50-developing/02-web-layers.md)
+- [Работа с БД](docs/50-developing/10-persistence.md),
+ [миграции](docs/50-developing/20-migrations.md),
+ [доступ к данным](docs/50-developing/30-data-access.md), [тесты](docs/50-developing/40-testing.md)
+- [Миграции и деплой](docs/90-deploy/10-migrations.md)
-## Keep TypeScript project references up to date
+Инструкции для ИИ-агентов (в том числе Claude Code) — в [AGENTS.md](AGENTS.md).
-Nx automatically updates TypeScript [project references](https://www.typescriptlang.org/docs/handbook/project-references.html) in `tsconfig.json` files to ensure they remain accurate based on your project dependencies (`import` or `require` statements). This sync is automatically done when running tasks such as `build` or `typecheck`, which require updated references to function correctly.
+## Полезные ссылки
-To manually trigger the process to sync the project graph dependencies information to the TypeScript project references, run the following command:
-
-```sh
-npx nx sync
-```
-
-You can enforce that the TypeScript project references are always in the correct state when running in CI by adding a step to your CI job configuration that runs the following command:
-
-```sh
-npx nx sync:check
-```
-
-[Learn more about nx sync](https://nx.dev/reference/nx-commands#sync)
-
-## Nx Cloud
-
-Nx Cloud ensures a [fast and scalable CI](https://nx.dev/nx-cloud?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) pipeline. It includes features such as:
-
-- [Remote caching](https://nx.dev/docs/features/ci-features/remote-cache?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-- [Task distribution across multiple machines](https://nx.dev/docs/features/ci-features/distribute-task-execution?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-- [Automated e2e test splitting](https://nx.dev/docs/features/ci-features/split-e2e-tasks?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-- [Task flakiness detection and rerunning](https://nx.dev/docs/features/ci-features/flaky-tasks?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-
-### Set up CI (non-Github Actions CI)
-
-**Note:** This is only required if your CI provider is not GitHub Actions.
-
-Use the following command to configure a CI workflow for your workspace:
-
-```sh
-npx nx g ci-workflow
-```
-
-[Learn more about Nx on CI](https://nx.dev/docs/features/ci-features?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-
-## Install Nx Console
-
-Nx Console is an editor extension that enriches your developer experience. It lets you run tasks, generate code, and improves code autocompletion in your IDE. It is available for VSCode and IntelliJ.
-
-[Install Nx Console »](https://nx.dev/docs/getting-started/editor-setup?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
-
-## 🔗 Learn More
-
-- [Nx Documentation](https://nx.dev/docs)
-- [Crafting Your Workspace Tutorial](https://nx.dev/docs/getting-started/tutorials/crafting-your-workspace)
-- [Module Boundaries](https://nx.dev/docs/features/enforce-module-boundaries)
-- [Releasing Packages](https://nx.dev/docs/features/manage-releases)
-- [Nx Plugins](https://nx.dev/docs/concepts/nx-plugins)
-- [Nx Cloud](https://nx.dev/nx-cloud)
-
-## 💬 Community
-
-Join the Nx community:
-
-- [Discord](https://go.nx.dev/community)
-- [X (Twitter)](https://twitter.com/nxdevtools)
-- [LinkedIn](https://www.linkedin.com/company/nrwl)
-- [YouTube](https://www.youtube.com/@nxdevtools)
-- [Blog](https://nx.dev/blog)
+- [Документация Nx](https://nx.dev/getting-started/intro)
+- [Запуск задач в Nx](https://nx.dev/features/run-tasks)
+- [Nx Console](https://nx.dev/getting-started/editor-setup)
diff --git a/docs/50-developing/01-api-layers.md b/docs/50-developing/01-api-layers.md
new file mode 100644
index 0000000..f448fab
--- /dev/null
+++ b/docs/50-developing/01-api-layers.md
@@ -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` и любой доступ к данным
+- Валидация входных данных
+- Правила доступа
diff --git a/docs/50-developing/02-web-layers.md b/docs/50-developing/02-web-layers.md
new file mode 100644
index 0000000..dfe181d
--- /dev/null
+++ b/docs/50-developing/02-web-layers.md
@@ -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
+- Типы и утилиты
+- Переводы
+- Форматирование значений
+
+**Не входит:**
+
+- Знание о том, где и в каком сценарии он применён
+- Композиция доменного интерфейса
+- Решения о том, что показать и что сделать при ошибке
diff --git a/docs/50-developing/10-persistence.md b/docs/50-developing/10-persistence.md
new file mode 100644
index 0000000..d7cbe91
--- /dev/null
+++ b/docs/50-developing/10-persistence.md
@@ -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).
diff --git a/docs/50-developing/20-migrations.md b/docs/50-developing/20-migrations.md
new file mode 100644
index 0000000..f96ce41
--- /dev/null
+++ b/docs/50-developing/20-migrations.md
@@ -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 {
+ 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 {
+ 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 {
+ await queryRunner.dropColumn('contests', 'description');
+ }
+
+ public async down(): Promise {
+ // откат невозможен: значения удалённой колонки восстановить неоткуда
+ throw new Error('DropContestDescription1790000001000 необратима');
+ }
+}
+```
+
+Второй — та же миграция, но откат разрешён с потерей данных:
+
+```ts
+public async down(queryRunner: QueryRunner): Promise {
+ // колонка возвращается пустой: прежние значения теряются
+ 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-миграция часто необратима в принципе; в одном файле необратимой
+становится вся пара.
+
+Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
+миграцией — бэкфилл данных.
diff --git a/docs/50-developing/30-data-access.md b/docs/50-developing/30-data-access.md
new file mode 100644
index 0000000..66c61d4
--- /dev/null
+++ b/docs/50-developing/30-data-access.md
@@ -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,
+ ) {}
+
+ public findById(id: number): Promise {
+ 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 {
+ 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,
+ ) {}
+
+ public findById(id: number, manager?: EntityManager): Promise {
+ return this.repository(manager).findOne({ where: { id } });
+ }
+
+ private repository(manager?: EntityManager): Repository {
+ 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 по общему правилу.
diff --git a/docs/50-developing/40-testing.md b/docs/50-developing/40-testing.md
new file mode 100644
index 0000000..e8d79fa
--- /dev/null
+++ b/docs/50-developing/40-testing.md
@@ -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
+```
diff --git a/docs/50-developing/_category_.yml b/docs/50-developing/_category_.yml
new file mode 100644
index 0000000..8997e72
--- /dev/null
+++ b/docs/50-developing/_category_.yml
@@ -0,0 +1 @@
+label: 'Разработка'
diff --git a/docs/90-deploy/10-migrations.md b/docs/90-deploy/10-migrations.md
new file mode 100644
index 0000000..3f6c397
--- /dev/null
+++ b/docs/90-deploy/10-migrations.md
@@ -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` в каталоге деплоя (`~/_/`) и
+мапит их в `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
+ 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= docker-compose up -d
+ ```
+
+ ⚠️ Один `VERSION` применяется сразу к `web` и `api`. Команда корректна только если оба образа
+ тегированы синхронно (обычный случай — их собирает один прогон `production.yaml`). Если теги
+ разошлись, поднимайте сервисы по одному (`VERSION= 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
+
+# посмотреть, что применится
+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. снять ручной дамп БД — автоматического бэкапа нет (см. выше).
+
+То же самое верно для первого деплоя на стейджинге (раздел «Применение на стейджинге»).
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..cb299fe
--- /dev/null
+++ b/docs/index.md
@@ -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** — оптимизация под генеративные поисковые системы.