arswarog 7c60482467
CI / Сборка (push) Failing after 5s
CI / Деплой на стейджинг (push) Skipped
CI / Проверка кода (push) Skipped
CI / Документация (push) Skipped
speckit: внедрение Spec Kit и фиксация архитектуры в конституции JT4D v1.0.0
- Интеграция 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>
2026-11-10 16:37:50 +03:00
2026-10-26 18:24:11 +03:00
2026-10-26 18:24:11 +03:00

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), миграции применяются автоматически.

Новый проект из шаблона

  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 и сборку, а стенд — открыться по своему адресу.

Документация

Инструкции для ИИ-агентов (в том числе Claude Code) — в AGENTS.md.

Полезные ссылки

S
Description
No description provided
Readme
1 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 82.6%
Nix 8.9%
Dockerfile 8.5%