- Интеграция 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>
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 |
Быстрый старт
yarn install
yarn start # api на :5000 (Swagger — /api/docs), web на :5173
Проверить, что всё поднялось: http://localhost:5000/api/health и http://localhost:5173. Задачи
запускаются только через Nx:
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), миграции применяются автоматически.
Новый проект из шаблона
- Переименовать воркспейс.
package.json(@jt4d-platform/*),project.json,nx.json,tsconfig.base.json(pathsиcustomConditions),apps/*/package.json. - Настроить доставку. Домен и registry в
.gitea/workflows/*.yaml,docker-compose.production.yml,docker-compose.staging.yml,.docuservix.yml; домен вapps/web/Caddyfileи список CORS-origin вapps/api/src/main.ts. - Задать переменные и секреты репозитория в Gitea.
vars.REGISTRY_USER,vars.STAGING_HOST,vars.STAGING_USER,vars.STAGING_PORT;secrets.REGISTRY_PASSWORD,secrets.STAGING_SSH_PRIVATE_KEY. - Убрать демо-код.
apps/web/src/app/nx-welcome.tsxи демо-страница вapps/web/src/app, тестовый контроллер и сервис вapps/api/src/app. - Пересобрать миграции. Удалить тестовую миграцию из
apps/api/src/database/migrations/и выполнитьyarn db-migrations-list; списокapps/api/src/migrations.tsкоммитится. - Обновить тексты под проект.
docs/index.md, документы вdocs/,AGENTS.md, этотREADME.md. - Проверить ветку в CI. Первый пуш должен пройти
yarn lint:checkи сборку, а стенд — открыться по своему адресу.
Документация
- Оглавление
- Слои API и слои web
- Работа с БД, миграции, доступ к данным, тесты
- Ручное логирование
- Миграции и деплой
Инструкции для ИИ-агентов (в том числе Claude Code) — в AGENTS.md.