Backend Development

Типы задач

Ручные (от бизнеса/команды)

Автоматические

Workflow по типу задачи

feature — Новый API/функционал

Входные данные:

• Бизнес-требования с описанием функционала
• Схема данных (если новые сущности)
• Требования к API от Frontend

Этапы:

1. Создать/обновить Prisma модель
2. Выполнить миграцию: npx prisma migrate dev
3. Реализовать API эндпоинты
4. Добавить валидацию (Zod)
5. Протестировать через REST client
6. Задокументировать API

Git commit: feat(api): description

change — Изменение существующего API

Входные данные:

• Описание новых бизнес-требований
• Текущие потребители API
• План миграции данных (если схема меняется)

Важно:

• Оценить влияние на Frontend потребителей
• Если breaking change — версионировать API или согласовать с Frontend
• Подготовить миграцию данных до деплоя

Примеры:

• Добавление нового поля в ответ API
• Изменение логики расчёта
• Изменение структуры ответа (breaking change)

Git commit: change(api): description

bug — Исправление ошибки

Входные данные:

• Описание ошибки
• Шаги воспроизведения
• Логи сервера (если есть)
• Request/Response примеры

Анализ:

1. Проверить логи сервера
2. Воспроизвести через REST client
3. Проверить валидацию входных данных
4. Проверить Prisma запросы
5. Проверить edge cases

Git commit: fix(api): description

improvement — Оптимизация/рефакторинг

Примеры:

• Оптимизация Prisma запросов (N+1 → include)
• Добавление индексов в БД
• Кэширование часто запрашиваемых данных
• Рефакторинг структуры API

Git commit: refactor(api): description или perf(api): description

deps — Обновление зависимостей

Процесс:

1. Проверить changelog на breaking changes
2. Особое внимание: Prisma, Zod, h3
3. Обновить в dev-ветке
4. Протестировать критичные API
5. Проверить миграции Prisma
6. Merge

Git commit: chore(deps): update package-name to version

security — Аудит безопасности

Процесс:

1. npm audit / Snyk report
2. Проверить Prisma security advisories
3. Оценить severity
4. Обновить уязвимые пакеты
5. Если нет фикса — задокументировать и отслеживать

Git commit: fix(security): patch vulnerability in package-name

migration — Миграции схемы БД

Процесс:

1. Изменить prisma/schema.prisma
2. npx prisma migrate dev --name migration_name
3. Проверить сгенерированный SQL
4. Обновить seed-данные (если нужно)
5. Протестировать миграцию на тестовой БД

Git commit: chore(db): add migration for feature_name

Этапы разработки (общие)

1. Анализ задачи

Входные данные

• Описание задачи с типом (feature, bug, improvement, deps, security, migration)
• Бизнес-требования — для feature
• Инструкция воспроизведения — для bug
• Метрики — для improvement

Действия

1. Прочитать описание задачи
2. Определить тип задачи
3. Определить затрагиваемые сущности (Prisma модели)
4. Определить затрагиваемые API эндпоинты
5. Оценить влияние на Frontend
6. Уточнить edge cases

2. Проектирование схемы данных

Перед написанием кода:

Чек-лист Prisma модели

• Модель соответствует бизнес-сущности?
• Правильные типы полей?
• Нужны ли индексы?
• Связи с другими моделями корректны?
• Нужен ли soft delete?

Чек-лист API дизайна

• RESTful структура URL?
• Правильные HTTP методы?
• Формат ответа консистентен?
• Пагинация для списков?
• Валидация входных данных?

3. Реализация

Порядок работы

1. Обновить Prisma схему (prisma/schema.prisma)
2. Выполнить миграцию (npx prisma migrate dev)
3. Создать валидаторы (server/utils/validators.ts)
4. Создать API эндпоинты (server/api/)
5. Добавить middleware (если нужна авторизация)
6. Обновить типы (если есть shared types)

Структура файлов

server/
├── api/
│   └── resource/
│       ├── index.get.ts      → GET /api/resource
│       ├── index.post.ts     → POST /api/resource
│       ├── [id].get.ts       → GET /api/resource/:id
│       ├── [id].patch.ts     → PATCH /api/resource/:id
│       └── [id].delete.ts    → DELETE /api/resource/:id
├── utils/
│   ├── prisma.ts             → Prisma singleton
│   └── validators.ts         → Zod schemas
└── middleware/
    └── auth.ts               → JWT validation

Правила кода

• standard-backend-api — структура API
• standard-prisma — работа с Prisma
• standard-socket-io — real-time (если нужно)
• Zod для валидации входных данных
• TypeScript strict mode

Git commits (по типу задачи)

# feature
feat(api): add orders CRUD endpoints

# change
change(api): update user response structure

# bug
fix(api): handle null values in order calculation

# improvement
perf(api): optimize users list with includes
refactor(api): extract validation to utils

# deps
chore(deps): update prisma to 7.1.0

# security
fix(security): patch jwt vulnerability

# migration
chore(db): add orders table migration

4. Тестирование

REST Client тестирование

Использовать VS Code REST Client или Postman:

### Создание ресурса
POST http://localhost:3000/api/users
Content-Type: application/json

{
  "email": "test@example.com",
  "name": "Test User"
}

### Получение списка
GET http://localhost:3000/api/users?page=1&limit=10

### Получение по ID
GET http://localhost:3000/api/users/{{userId}}

### Обновление
PATCH http://localhost:3000/api/users/{{userId}}
Content-Type: application/json

{
  "name": "Updated Name"
}

### Удаление
DELETE http://localhost:3000/api/users/{{userId}}

Чек-лист тестирования

• Happy path работает
• Валидация отклоняет некорректные данные (422)
• Несуществующий ресурс возвращает 404
• Неавторизованный запрос возвращает 401
• Запрещённый ресурс возвращает 403
• Пагинация работает корректно
• Edge cases обработаны (null, empty, max values)

Проверка логов

# Смотреть логи Nuxt Server
pnpm dev

# Проверить Prisma запросы (включить logging)
# В prisma.ts:
# new PrismaClient({ log: ['query', 'info', 'warn', 'error'] })

5. Code Review

Перед MR

• Миграции включены в коммит
• Валидация на всех POST/PATCH эндпоинтах
• Правильные HTTP коды (201, 204, 4xx)
• Нет N+1 запросов (используй include/select)
• Нет console.log
• Типы экспортированы (если нужны Frontend)

MR Description

## Тип задачи
<!-- feature | change | bug | improvement | deps | security | migration -->

## Что сделано
- Добавлены CRUD эндпоинты для orders
- Создана миграция для таблицы orders
- Добавлена валидация через Zod

## Миграции
<!-- Описать изменения схемы БД -->
- Добавлена таблица `orders`
- Добавлен индекс на `user_id`

## API изменения
<!-- Описать новые/изменённые эндпоинты -->
| Метод | URL | Описание |
|-------|-----|----------|
| GET | /api/orders | Список заказов |
| POST | /api/orders | Создание заказа |

## Breaking changes
<!-- Если есть — описать и согласовать с Frontend -->

## Тестирование
- [ ] REST Client тесты пройдены
- [ ] Миграция протестирована локально

6. Merge

Критерии

• Code review пройден
• CI/CD прошёл
• Миграция безопасна для production
• Нет конфликтов
• Frontend уведомлён об изменениях API

После merge

1. Убедиться что миграция выполнена на staging
2. Проверить логи на ошибки
3. Уведомить Frontend о готовности API

Real-time функционал (Socket.io)

Когда использовать

Workflow для Socket.io

1. Определить события и их payload
2. Определить rooms/namespaces
3. Реализовать server plugin (server/plugins/socket.io.ts)
4. Реализовать client composable (composables/useSocket.ts)
5. Протестировать через браузер DevTools

См. standard-socket-io для деталей.

Связанные документы

Архитектура

• ADR-012: Nuxt 4 Server Backend
• ADR-013: Socket.io Real-time
• ADR-014: Prisma ORM
• ADR-015: REST API Caching

Стандарты

• standard-backend-api
• standard-prisma
• standard-socket-io
• standard-type-generation

Процессы

• process-code-review
• runbook-backend-setup