Files
it-smi/README.md
T
arswarog 7d5156d92e
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:44:48 +03:00

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)