# Nx-монорепозиторий — шаблон Стартовый репозиторий для нового веб-проекта: Nx 22 + yarn workspaces, бэкенд на NestJS с TypeORM и PostgreSQL, фронтенд на React + Vite, e2e-тесты, единый линт, миграции, CI/CD в Gitea Actions со стендом на каждую ветку и документация в MDX. Шаблон содержит пустой каркас приложений (health-check и демо-страница) и полностью рабочую инфраструктуру: сборку, миграции, проверки, деплой и документацию. Новый проект начинается с клонирования репозитория и чек-листа из раздела «Новый проект из шаблона». ## Что уже настроено - **Монорепозиторий.** 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. ## Стек | Слой | Технологии | | -------- | --------------------------------------------------- | | Сборка | 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 ``` Проверить, что всё поднялось: `http://localhost:5000/api/health` и `http://localhost:5173`. Задачи запускаются только через Nx: ```bash yarn nx run : # одна задача yarn nx run-many -t # по всем проектам yarn nx affected -t # только по затронутым проектам ``` ## Команды | Команда | Что делает | | -------------------------------------- | ------------------------------------------------------ | | `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 и восстановление из снимка | Подключение к БД задаётся переменными `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` — в `.env` локально или в окружении контейнера. ## Ветки и пайплайны - `master` — основная ветка. - Рабочие ветки — `i<номер>-краткое-описание`, только `a-z`, `0-9` и `-`; формат проверяют Husky на pre-push и CI. - Пуш в ветку или PR: сборка, проверка имени ветки, проверка списка миграций, сборка Docker-образов `api`/`web`, стенд на `<ветка>.<домен>`, линт, публикация документации. - Удаление ветки: стенд удаляется (`cleanup.yaml`). - Тег `v*`: сборка и выкладка в прод (`production.yaml`), миграции применяются автоматически. ## Новый проект из шаблона 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/migrations.ts` коммитится. 6. **Обновить тексты под проект.** `docs/index.md`, документы в `docs/`, `AGENTS.md`, этот `README.md`. 7. **Проверить ветку в CI.** Первый пуш должен пройти `yarn lint:check` и сборку, а стенд — открыться по своему адресу. ## Документация - [Оглавление](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/55-logging/04-manual-logs.md) - [Миграции и деплой](docs/90-deploy/10-migrations.md) Инструкции для ИИ-агентов (в том числе Claude Code) — в [AGENTS.md](AGENTS.md). ## Полезные ссылки - [Документация Nx](https://nx.dev/getting-started/intro) - [Запуск задач в Nx](https://nx.dev/features/run-tasks) - [Nx Console](https://nx.dev/getting-started/editor-setup)