Локальная разработка

Быстрый старт для разработчика: поднять PostgreSQL и Redis, запустить бэкенд и фронтенд, применить миграции и прогнать проверки. Требуется Node.js 22, npm и Docker.

Что где запускается

Приложение	Порт	Команда	Конфиг
PostgreSQL 16 + pgvector	5432	`docker compose up -d postgres redis`	`docker-compose.yml`
Redis 7 (с паролем)	6379	там же	`REDIS_PASSWORD`, по умолчанию `optima-local`
Backend (NestJS)	3000	`npm run start:dev` в `backend/`	`backend/.env`
Frontend (Next.js)	3001	`npm run dev` в `frontend/`	`frontend/.env.local`
Landing (Vite)	3002	`npm run dev` в `landing/`	`landing/.env`
Docs-site (Docusaurus)	3000 по умолчанию	`npm start` в `docs-site/`	—

Порт документации совпадает с бэкендом: если запускаете оба, укажите другой порт — npm start -- --port 3003.

1. Инфраструктура: docker-compose

Корневой docker-compose.yml описывает PostgreSQL (pgvector/pgvector:pg16, нужен для RAG), Redis и контейнер бэкенда. Порты публикуются только на 127.0.0.1, Redis защищён паролем. Для работы с бэкендом «на хосте» достаточно двух сервисов:

docker compose up -d postgres redis

Учётные данные БД локально: пользователь, пароль и база — optima. Если бэкенд запускается не в compose, в .env нужен Redis-URL с паролем: REDIS_URL=redis://:optima-local@localhost:6379. Контейнер backend из compose тоже доступен (docker compose up), но миграции в нём автоматически не применяются — запустите их с хоста (шаг 3).

2. Переменные окружения

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local
cp landing/.env.example landing/.env

Backend — обязательны DATABASE_URL, REDIS_URL, JWT_ACCESS_SECRET, JWT_REFRESH_SECRET (не короче 16 символов), ENCRYPTION_KEYS (kid:hex64) и ENCRYPTION_ACTIVE_KID. Значения в .env.example — заглушки для разработки (в production они отвергаются). Ключ шифрования можно сгенерировать командой openssl rand -hex 32. LLM-переменные (LLM_*) необязательны: без них ИИ-функции вернут ошибку конфигурации при вызове, остальное работает. Env валидируется при старте — опечатка роняет запуск с понятным сообщением. Справочник — Переменные окружения.
Frontend — NEXT_PUBLIC_API_URL=http://localhost:3000, NEXT_PUBLIC_LANDING_URL=http://localhost:3002.
Landing — VITE_APP_ORIGIN, VITE_DOCS_URL (адреса приложения и документации).

3. Миграции и сиды

cd backend
npm install
npm run migration:run        # применить миграции (через ts-node, DATABASE_URL из .env)
npm run migration:show       # какие миграции применены
npm run migration:revert     # откатить последнюю
npm run migration:generate -- src/core/database/migrations/<Имя>   # сгенерировать по diff сущностей
npm run migration:create -- src/core/database/migrations/<Имя>     # пустая миграция
npm run seed:run             # идемпотентные сиды из src/core/database/seeds/*.seed.ts

Миграции идут первыми: схема, расширение vector и партиции создаются ими. В production те же миграции применяет entrypoint контейнера (Развёртывание). Правила схемы — Данные, решение — ADR-0001.

4. Запуск и первый вход

cd backend  && npm run start:dev    # API http://localhost:3000, Swagger http://localhost:3000/api/docs
cd frontend && npm install && npm run dev   # http://localhost:3001

Зарегистрируйтесь в приложении — новому пользователю назначается роль seller. Чтобы получить роль администратора, обновите запись вручную: UPDATE users SET role = 'admin' WHERE email = '…'; (Безопасность). Подключение кабинета WB требует настоящего токена Wildberries (Кабинеты WB); для безопасных проб можно включить песочницы WB (WB_API_USE_SANDBOX=true).

Очереди и расписания работают в том же процессе: при запущенных Redis и бэкенде плановые задачи стартуют сами (Фоновые задачи). Панель очередей — /admin/queues (локально открыта без пароля).

5. Команды проверок

Где	Команда	Что делает
backend	`npm run lint`	ESLint с автоисправлением
backend	`npm test` / `npm run test:watch` / `npm run test:cov`	юнит-тесты Jest (БД и Redis не нужны)
backend	`npm run test:e2e`	e2e на реальных PostgreSQL и Redis, включая цикл миграций «применить → откатить → применить»
backend	`npm run test:contract`	проверка OpenAPI-контракта (при изменении набора эндпоинтов обновите `test/openapi.e2e-spec.ts`)
backend	`npm run build`	сборка `nest build` в `dist/`
backend	`npm run docs` · `docs:coverage` · `docs:openapi`	Compodoc, порог покрытия документацией 80 %, выгрузка `openapi.json`
frontend	`npm run lint`, `npm run typecheck`	ESLint и `tsc --noEmit`
frontend	`npm run test:unit` (`npm test` — watch)	Vitest
frontend	`npm run e2e`	Playwright (первый раз: `npx playwright install chromium`)
frontend	`npm run build`	production-сборка Next.js
frontend	`npm run api:generate`	выгрузка OpenAPI бэкенда и генерация типов `src/lib/api/schema.d.ts`
landing	`npm run lint`, `npm run typecheck`, `npm run build`	проверки и сборка лендинга
docs-site	`npm run build` · `npm run serve` · `npm run sync:adr`	сборка и просмотр портала, синхронизация ADR из `backend/docs/adr`

После изменения контракта API: npm run docs:openapi в backend/, затем npm run api:generate во frontend/.

Git-хуки

В backend/ husky ставится автоматически при npm install (скрипт prepare). На коммите lint-staged запускает по изменённым backend/src/**/*.ts ESLint с --fix и tsc -p tsconfig.build.json --noEmit; коммит с неисправимой ошибкой блокируется. Все проверки перед PR — CI/CD.

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

Документируем на русском: TSDoc и Swagger-декораторы пишутся вместе с кодом; значимое архитектурное решение — новый ADR в backend/docs/adr/ (затем npm run sync:adr в docs-site/). Описание фич для клиентов — в docs-site/docs/business/. Документацию кода (Compodoc) можно открыть локально: npm run docs:serve в backend/.

Что где запускается​

1. Инфраструктура: docker-compose​

2. Переменные окружения​

3. Миграции и сиды​

4. Запуск и первый вход​

5. Команды проверок​

Git-хуки​

Документация вместе с кодом​