- Интеграция Spec Kit для pi: команды `/speckit.*`, bash-скрипты и шаблоны в `.specify` - Конституция JT4D v1.0.0 вместо шаблона: принципы WELD для слоёв web и api, публичный API директории - Слои web описаны по методологии WELD и проверяются `eslint-plugin-weld` - Vitest в api запускает `*.test.ts` рядом с `*.spec.ts`, тесты исключены из сборки приложения - `yarn.lock` пересобран через `yarn deduplicate` ## Мотивация Нужно зафиксировать архитектуру проекта в конституции JT4D v1.0.0 и подключить Spec Kit, чтобы планировать фичи до написания кода. ## Ключевые моменты реализации - `eslint-plugin-weld` настроен только в `apps/web`: схема слоёв API описана конституцией и документацией, но линтером пока не проверяется Reviewed-on: jt4d/jt4d#4 Co-authored-by: Arswarog <arswarog@yandex.ru>
132 lines
9.8 KiB
Markdown
132 lines
9.8 KiB
Markdown
# 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 <project>:<target> # одна задача
|
|
yarn nx run-many -t <target> # по всем проектам
|
|
yarn nx affected -t <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 и восстановление из снимка |
|
|
|
|
Подключение к БД задаётся переменными `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` (`@jt4d-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)
|