docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
This commit is contained in:
1 parent
9d5478ddeb
commit
dbd5762ecf
10 files changed
+1308
-87
No files matched your search
@@ -1,109 +1,130 @@
|
||||
# New Nx Repository
|
||||
# Nx-монорепозиторий — шаблон
|
||||
|
||||
<a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
|
||||
Стартовый репозиторий для нового веб-проекта: 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 <project>:<target> # одна задача
|
||||
yarn nx run-many -t <target> # по всем проектам
|
||||
yarn nx affected -t <target> # только по затронутым проектам
|
||||
```
|
||||
|
||||
To run any task with Nx use:
|
||||
## Команды
|
||||
|
||||
```sh
|
||||
npx nx run <project-name>:<target>
|
||||
```
|
||||
| Команда | Что делает |
|
||||
| -------------------------------------- | ------------------------------------------------------ |
|
||||
| `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)
|
||||
Reference in new issue
Block a user