- миграции лежат по модулям в `apps/api/src/<module>/migrations/`; `tools/buildDataSource.ts` сканирует `apps/api/src/**/migrations/` и генерирует список в `apps/api/src/migrations.ts` - `deploy-staging` накатывает миграции шагами `migration:show` и `migration:run -t each` - стенды получают маршрутизацию через лейблы `caddy` и `caddy.reverse_proxy`, web-образ стенда собирается с `CADDYFILE=Caddyfile.staging` ## Мотивация Миграции нужно накатывать на стендах автоматически и держать рядом с модулем, которому они принадлежат, а деплой — сводить к одному шагу, который сам копирует компоуз-файл на хост и выполняет скрипт. ## Ключевые моменты реализации - `Caddyfile.staging` слушает `:80` без хостового матчера и HTTPS: имена стендов динамические, маршрутизацию и TLS берёт внешний caddy-docker-proxy по лейблам Reviewed-on: jt4d/jt4d#2 Co-authored-by: Arswarog <arswarog@yandex.ru>
9.6 KiB
9.6 KiB
AGENTS.md
Инструкции для ИИ-агентов при работе с этим репозиторием: обзор, команды, архитектура и конвенции, которые нельзя вывести из кода.
Project Overview
Монорепозиторий Nx с тремя приложениями:
- api — NestJS бэкенд (TypeORM + PostgreSQL), порт 5000, глобальный префикс
/api, Swagger UI на/api/docs - web — React фронтенд (Vite), порт 5173, проксирует
/api/*на бэкенд - api-e2e — E2E-тесты на Jest для API
Package manager: yarn (v1 classic). Версия указана в поле packageManager в package.json. Все
задачи запускаются через Nx, а не напрямую через инструменты.
Common Commands
# Все задачи через Nx (не напрямую)
yarn nx run api:serve # Запуск бэкенда
yarn nx run web:serve # Запуск фронтенда
yarn nx run-many -t serve # Запуск всех приложений
yarn nx run api:build # Сборка бэкенда (webpack)
yarn nx run web:build # Сборка фронтенда (vite)
yarn nx run api:test # Тесты бэкенда (vitest)
yarn nx run web:test # Тесты фронтенда (vitest)
yarn nx run api:test -- --testPathPattern="users" # Один тест-файл
yarn nx run api-e2e:e2e # E2E-тесты
yarn nx run api:lint # ESLint для api
yarn nx run web:lint # ESLint для web
yarn lint # ESLint + Prettier для всего (с автофиксом)
yarn lint:check # Проверка без автофикса
yarn nx run api:db-show # Список миграций и их статус
yarn nx run api:db-migrate # Применить непримененные миграции
yarn nx run api:db-migrations-list # Перегенерировать список миграций
Architecture
Backend (apps/api)
- NestJS модульная архитектура: модуль — рамка, внутри которой код разложен по слоям
Controller → Service → Data Access Layer; наружу модуль отдаёт только то, что осознанно экспортирует. Подробности —docs/50-developing/01-api-layers.md - Swagger UI доступен на
/api/docs - Сборка:
db-migrations-list(черезdependsOn) →webpack-cli build(main.js) →webpack-cli build --config webpack.data-source.config.js(data-source.js), последовательно (parallel: false). Запуск через@nx/js:node
Миграции БД
- Миграции лежат по модулям:
apps/api/src/<module>/migrations/ - Список миграций генерируется статически (
tools/buildDataSource.tsсканируетapps/api/src/**/migrations/→apps/api/src/migrations.ts), потому что webpack не умеет runtime-glob - Имя файла обязано начинаться с 13-значного timestamp, а имя класса — оканчиваться тем же
timestamp: TypeORM берёт его как
parseInt(className.substr(-13)). Расхождение валит сборку - После добавления или удаления миграции список нужно перегенерировать и закоммитить
(
yarn nx run api:db-migrations-list, либо это сделаетyarn nx run api:buildчерезdependsOn). Иначе CI упадёт на шагеCheck migrations list - Деплой применяет миграции автоматически (
migration:run -t eachчерезdocker execна проде /docker compose execна стейджинге) — на каждый тег на проде и на каждый push/PR на стейджинге. Автоматического бэкапа перед миграцией нет. Подробнее:docs/90-deploy/10-migrations.md - DDL пишется методами
QueryRunner(Table/TableColumn), а не строкой SQL; выводmigration:generate— черновик, который переписывают.downобязателен. Имя таблицы — строковым литералом, а не константой*_TABLE_NAME: миграция не должна ломаться от удаления модуля. Data-миграции — отдельным файлом. Перед коммитом — циклdb-migrate→db-revert→db-migrate. Подробнее:docs/50-developing/20-migrations.md
Конвенции кода и тестов
Подробности — docs/50-developing/:
- Сущности — в
entities/внутри модуля; имя таблицы — константа*_TABLE_NAMEрядом с сущностью (в коде приложения используется везде, в миграциях — нет); колонки —camelCase - Весь доступ к БД — в
*.dal.ts:@InjectRepository/Repository/DataSourceдопустимы только там. DAL приватен для модуля (не вexports), наружу модуль отдаёт публичные сервисы - Тесты — рядом с тестируемым файлом, расширение
.test.ts; DAL юнит-тестами не покрывается
Frontend (apps/web)
- React + Vite + React Router; стили — Tailwind CSS
- Слои идут строго в одну сторону:
app → pages → widgets → entities → shared, обратные зависимости запрещены. Подробности —docs/50-developing/02-web-layers.md - Тесты: Vitest с jsdom
TypeScript Paths
Определены в tsconfig.base.json:
@geo-platform/api/*→apps/api/src/*@geo-platform/web/*→apps/web/src/*
При переименовании воркспейса правятся и paths, и customConditions.
Данные для разработки
db-snapshot/*.json— снапшоты dev-БД для локальной разработки (см.tools/dbSnapshot.ts/dbRestore.ts).
Документация (docs/)
- Весь новый код должен соответствовать документации в
docs/. Существующий код под неё не переписывается — приводится к ней по мере того, как его всё равно затрагивают. Отдельные документы эту оговорку не повторяют .md-файлы вdocs/компилируются как MDX (Docusaurus) — в обычном тексте (вне code fence```и вне inline-код-спанов``) нельзя использовать `{...}` и `<` перед небуквенным/нецифро-небуквенным символом или сразу перед словом (например, `<=`, `<lang>`, `<repo>`), иначе сборка падает с `MDX compilation failed`. Внутри code fence и inline-код-спанов такие символы безопасны — MDX не парсит их содержимое как JSX/выражения. Сравнения вида `<= N` замените на `≤ N` (аналогично `>=` → `≥`), а плейсхолдеры вроде `<lang>` — переносите в backtick-код (<lang>``) или переформулируйте текст
Code Quality
- ESLint 9 flat config (корневой
eslint.config.mjs) - Prettier для форматирования
- Husky + lint-staged: автоформатирование при коммите
@nx/enforce-module-boundariesвключён
General Guidelines for working with Nx
- For navigating/exploring the workspace, invoke the
nx-workspaceskill first - it has patterns for querying projects, targets, and dependencies - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task
through
nx(i.e.nx run,nx run-many,nx affected) instead of using the underlying tooling directly - Prefix nx commands with the workspace's package manager (e.g.,
pnpm nx build,npm exec nx test) - avoids using globally installed CLI - You have access to the Nx MCP server and its tools, use them to help the user
- For Nx plugin best practices, check
node_modules/@nx/<plugin>/PLUGIN.md. Not all plugins have this file - proceed without it if unavailable. - NEVER guess CLI flags - always check nx_docs or
--helpfirst when unsure
Scaffolding & Generators
- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the
nx-generateskill FIRST before exploring or calling MCP tools
When to use nx_docs
- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases
- DON'T USE for: basic generator syntax (
nx g @nx/react:app), standard commands, things you already know - The
nx-generateskill handles generator discovery internally - don't call nx_docs just to look up generator syntax