Запуск и разработка (developer setup)

Последняя сверка с кодом: 2026-06-14
Аудитория: новый разработчик, DevOps, QA локально
См. также: README.md · 26-ssr-migration.md · 07-api-codegen.md

---

1. Требования

Требование	Версия / примечание
Node.js	≥ 22 (.nvmrc)
npm	≥ 10
Docker	Postgres локально (npm run db:up)
ffmpeg	Для превью видео (brew install ffmpeg)

---

2. Первый запуск (copy-paste)

git clone <repo>
cd dr_event

npm install

cp env.example .env
cp backend/.env.example backend/.env
# Заполнить BETTER_AUTH_SECRET, DATABASE_URL при необходимости

npm run db:up          # Postgres в Docker
npm run db:migrate     # Prisma migrations
npm run db:seed        # dev@local.test + demo-event

npm run dev            # frontend :3000 + backend :3002

URL	Назначение
http://localhost:3000	Nuxt (SSR в dev через Nitro)
http://localhost:3002/api/docs	Swagger UI
http://localhost:3002/api/openapi.json	OpenAPI для codegen
http://localhost:3000/demo-event	Seed-альбом

Seed: dev@local.test / dev123456

---

3. Ежедневная работа

npm run db:up          # если Docker не запущен
npm run dev            # оба процесса

# только бэк
npm run dev:backend

# только фронт
npm run dev:frontend

# продуктовая дока (VitePress)
npm run docs:dev

---

4. База данных (Prisma)

Команда	Когда
npm run db:up	Поднять Postgres (Docker)
npm run db:migrate	Новые миграции после pull
npm run db:seed	Demo user + demo-event
npm run db:reset	Полный сброс + migrate + seed
npm run db:studio	GUI Prisma Studio
npm -w backend run db:generate	После изменения schema.prisma

Схема: backend/prisma/schema.prisma
Миграции: backend/prisma/migrations/

Типичный цикл после правки schema:

npm -w backend run db:migrate    # создаёт migration
npm -w backend run db:generate   # обновляет Prisma client

---

5. Генерация API-клиента

Фронт использует @eventpass/api из frontend/generated/api/ — не редактировать руками.

# Бэк должен быть на :3002
./generate-api.sh

# или если бэк уже работает
./generate-api.sh --no-start-backend

# только проверить OpenAPI
./generate-api.sh --validate-only

Когда регенерить: после изменения JSDoc/swagger в backend/src/routes/*.ts.

Подробности: 07-api-codegen.md.

---

6. Сборка и проверки

Команда	Что делает
npm run build	Production build backend + frontend
npm run type-check	TypeScript обоих workspaces
npm run lint	ESLint monorepo
npm run docker:stack	Prod-like stack на :8080

Frontend type-check отдельно:

npm -w frontend run type-check

---

7. ENV (минимум для dev)

Корень .env: BACKEND_URL, proxy для Nuxt.

backend/.env:

Переменная	Зачем
DATABASE_URL	Postgres connection string
BETTER_AUTH_SECRET	Сессии
BETTER_AUTH_URL	http://localhost:3002
TRUSTED_ORIGINS	http://localhost:3000
STORAGE_DRIVER	local (dev)
SMTP_USER / SMTP_PASS	Опционально; Zoho App Password. Без них в dev reset password логируется

Примеры: backend/.env.example, env.example.

---

8. SUPER_ADMIN локально

В Prisma Studio или SQL:

UPDATE "user" SET "globalRole" = 'SUPER_ADMIN' WHERE email = 'dev@local.test';

После — перелогин, появится /admin/* в sidebar.

---

9. Troubleshooting

Проблема	Решение
Port 3000 busy	lsof -i :3000 → kill процесс
Auth pending / зависает	Better Auth mount до express.json() — см. app.ts
TUS upload fail	Проверить ffmpeg, STORAGE_DRIVER, event uploadEnabled
OpenAPI codegen fail	Бэк на :3002, ./generate-api.sh
Prisma client stale	npm -w backend run db:generate
Белый экран /account	См. 21-auth-frontend.md

---

10. Деплой (кратко)

Не локальная разработка — см.:

• 13-deploy.md
• 15-git-deploy.md
• 16-cloudflare-setup.md

---

11. Карта команд (шпаргалка)

install     npm install
dev         npm run dev
db          db:up → db:migrate → db:seed
api         ./generate-api.sh
check       npm run type-check && npm run lint
build       npm run build
docs        npm run docs:dev