- Интеграция 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>
159 lines
9.8 KiB
Markdown
159 lines
9.8 KiB
Markdown
# AGENTS.md
|
|
|
|
Инструкции для ИИ-агентов при работе с этим репозиторием: обзор, команды, архитектура и конвенции,
|
|
которые нельзя вывести из кода.
|
|
|
|
## Project Overview
|
|
|
|
Монорепозиторий Nx с тремя приложениями:
|
|
|
|
- **api** — NestJS бэкенд (TypeORM + PostgreSQL), порт 5000, глобальный префикс `/api`, Swagger UI
|
|
на `/api/docs`
|
|
- **web** — React фронтенд (Vite), порт 5173, проксирует `/api/*` на бэкенд
|
|
- **api-e2e** — E2E-тесты на Jest для API
|
|
|
|
Package manager: **yarn** (v1 classic). Версия указана в поле `packageManager` в `package.json`. Все
|
|
задачи запускаются через Nx, а не напрямую через инструменты.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Все задачи через Nx (не напрямую)
|
|
yarn nx run api:serve # Запуск бэкенда
|
|
yarn nx run web:serve # Запуск фронтенда
|
|
yarn nx run-many -t serve # Запуск всех приложений
|
|
|
|
yarn nx run api:build # Сборка бэкенда (webpack)
|
|
yarn nx run web:build # Сборка фронтенда (vite)
|
|
|
|
yarn nx run api:test # Тесты бэкенда (vitest)
|
|
yarn nx run web:test # Тесты фронтенда (vitest)
|
|
yarn nx run api:test -- --testPathPattern="users" # Один тест-файл
|
|
|
|
yarn nx run api-e2e:e2e # E2E-тесты
|
|
|
|
yarn nx run api:lint # ESLint для api
|
|
yarn nx run web:lint # ESLint для web
|
|
yarn lint # ESLint + Prettier для всего (с автофиксом)
|
|
yarn lint:check # Проверка без автофикса
|
|
|
|
yarn nx run api:db-show # Список миграций и их статус
|
|
yarn nx run api:db-migrate # Применить непримененные миграции
|
|
yarn nx run api:db-migrations-list # Перегенерировать список миграций
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Backend (apps/api)
|
|
|
|
- NestJS модульная архитектура: модуль — рамка, внутри которой код разложен по слоям
|
|
`Controller → Service → Data Access Layer`; наружу модуль отдаёт только то, что осознанно
|
|
экспортирует. Подробности — `docs/50-developing/01-api-layers.md`
|
|
- Swagger UI доступен на `/api/docs`
|
|
- Сборка: `db-migrations-list` (через `dependsOn`) → `webpack-cli build` (`main.js`) →
|
|
`webpack-cli build --config webpack.data-source.config.js` (`data-source.js`), последовательно
|
|
(`parallel: false`). Запуск через `@nx/js:node`
|
|
|
|
#### Миграции БД
|
|
|
|
- Миграции лежат по модулям: `apps/api/src/<module>/migrations/`
|
|
- Список миграций **генерируется статически** (`tools/buildDataSource.ts` сканирует
|
|
`apps/api/src/**/migrations/` → `apps/api/src/migrations.ts`), потому что webpack не умеет
|
|
runtime-glob
|
|
- Имя файла обязано начинаться с **13-значного** timestamp, а имя класса — оканчиваться тем же
|
|
timestamp: TypeORM берёт его как `parseInt(className.substr(-13))`. Расхождение валит сборку
|
|
- **После добавления или удаления миграции список нужно перегенерировать и закоммитить**
|
|
(`yarn nx run api:db-migrations-list`, либо это сделает `yarn nx run api:build` через
|
|
`dependsOn`). Иначе CI упадёт на шаге `Check migrations list`
|
|
- Деплой применяет миграции автоматически (`migration:run -t each` через `docker exec` на проде /
|
|
`docker compose exec` на стейджинге) — на каждый тег на проде и на каждый push/PR на стейджинге.
|
|
Автоматического бэкапа перед миграцией нет. Подробнее: `docs/90-deploy/10-migrations.md`
|
|
- DDL пишется методами `QueryRunner` (`Table`/`TableColumn`), а не строкой SQL; вывод
|
|
`migration:generate` — черновик, который переписывают. `down` обязателен. Имя таблицы — строковым
|
|
литералом, а не константой `*_TABLE_NAME`: миграция не должна ломаться от удаления модуля.
|
|
Data-миграции — отдельным файлом. Перед коммитом — цикл `db-migrate` → `db-revert` → `db-migrate`.
|
|
Подробнее: `docs/50-developing/20-migrations.md`
|
|
|
|
#### Конвенции кода и тестов
|
|
|
|
Подробности — `docs/50-developing/`:
|
|
|
|
- Сущности — в `entities/` внутри модуля; имя таблицы — константа `*_TABLE_NAME` рядом с сущностью
|
|
(в коде приложения используется везде, в миграциях — нет); колонки — `camelCase`
|
|
- Весь доступ к БД — в `*.dal.ts`: `@InjectRepository`/`Repository`/`DataSource` допустимы только
|
|
там. DAL приватен для модуля (не в `exports`), наружу модуль отдаёт публичные сервисы
|
|
- Тесты — рядом с тестируемым файлом, расширение `.test.ts`; DAL юнит-тестами не покрывается
|
|
|
|
### Frontend (apps/web)
|
|
|
|
- React + Vite + React Router; стили — Tailwind CSS
|
|
- Слои идут строго в одну сторону: `app → pages → @modules → common`; `widgets` и `entities`
|
|
существуют только внутри модуля, обратные зависимости запрещены. Границы объявляются баррелями,
|
|
схема слоёв — в `apps/web/weld.config.mjs`. Подробности — `docs/50-developing/02-web-layers.md`
|
|
- Оболочка, шапка и тема — `docs/50-developing/04-ui-shell.md`
|
|
- Тесты: Vitest с jsdom
|
|
|
|
### TypeScript Paths
|
|
|
|
Определены в `tsconfig.base.json`:
|
|
|
|
- `@jt4d-platform/api/*` → `apps/api/src/*`
|
|
- `@jt4d-platform/web/*` → `apps/web/src/*`
|
|
|
|
При переименовании воркспейса правятся и `paths`, и `customConditions`.
|
|
|
|
## Данные для разработки
|
|
|
|
- `db-snapshot/*.json` — снапшоты dev-БД для локальной разработки (см. `tools/dbSnapshot.ts` /
|
|
`dbRestore.ts`).
|
|
|
|
## Документация (`docs/`)
|
|
|
|
- **Весь новый код должен соответствовать документации в `docs/`.** Существующий код под неё не
|
|
переписывается — приводится к ней по мере того, как его всё равно затрагивают. Отдельные документы
|
|
эту оговорку не повторяют
|
|
- `.md`-файлы в `docs/` компилируются как MDX (Docusaurus) — в обычном тексте (вне code fence
|
|
` ``` ` и вне inline-код-спанов `` ` ``
|
|
`` `) нельзя использовать `{...}` и `<` перед небуквенным/нецифро-небуквенным символом или сразу перед словом (например, `<=`, `<lang>`, `<repo>`), иначе сборка падает с `MDX compilation failed`. Внутри code fence и inline-код-спанов такие символы безопасны — MDX не парсит их содержимое как JSX/выражения. Сравнения вида `<= N` замените на `≤ N` (аналогично `>=` → `≥`), а плейсхолдеры вроде `<lang>` — переносите в backtick-код (``
|
|
`<lang>` ``) или переформулируйте текст
|
|
|
|
## Code Quality
|
|
|
|
- ESLint 9 flat config (корневой `eslint.config.mjs`)
|
|
- Prettier для форматирования
|
|
- Husky + lint-staged: автоформатирование при коммите
|
|
- `@nx/enforce-module-boundaries` включён
|
|
|
|
<!-- nx configuration start-->
|
|
<!-- Leave the start & end comments to automatically receive updates. -->
|
|
|
|
## General Guidelines for working with Nx
|
|
|
|
- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns
|
|
for querying projects, targets, and dependencies
|
|
- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task
|
|
through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling
|
|
directly
|
|
- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`,
|
|
`npm exec nx test`) - avoids using globally installed CLI
|
|
- You have access to the Nx MCP server and its tools, use them to help the user
|
|
- For Nx plugin best practices, check `node_modules/@nx/<plugin>/PLUGIN.md`. Not all plugins have
|
|
this file - proceed without it if unavailable.
|
|
- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure
|
|
|
|
## Scaffolding & Generators
|
|
|
|
- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the
|
|
`nx-generate` skill FIRST before exploring or calling MCP tools
|
|
|
|
## When to use nx_docs
|
|
|
|
- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge
|
|
cases
|
|
- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you
|
|
already know
|
|
- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look
|
|
up generator syntax
|
|
|
|
<!-- nx configuration end-->
|