# Корзилла.Админ — бэкенд

REST API сервиса «Корзилла.Админ» — приложения для владельцев бизнеса и администраторов, которое объединяет управление сайтами, заказами и коммуникациями в одном месте. Бэкенд отвечает за регистрацию и авторизацию пользователей, сессии, подключение и синхронизацию сайтов, уведомления (включая push), выдачу доступов другим пользователям и форму обратной связи. Также он предоставляет внешнее API, через которое подключённые сайты синхронизируются и отправляют уведомления.

## Начало работы

Эти инструкции помогут развернуть копию проекта на локальной машине для разработки и тестирования. О развёртывании на боевом сервере см. раздел [Развёртывание](#развёртывание).

### Требования

Для работы понадобятся:

- [Node.js](https://nodejs.org/) 22 или новее
- [pnpm](https://pnpm.io/) 10 (удобнее всего включить через Corepack)
- [PostgreSQL](https://www.postgresql.org/) 15 — локально или в Docker
- SMTP-сервер для отправки писем (подтверждение email, обратная связь)
- [Docker](https://www.docker.com/) и Docker Compose — для запуска в контейнере (необязательно)

```bash
corepack enable
corepack prepare pnpm@10.26.2 --activate
```

### Установка

1. Клонируйте репозиторий и перейдите в папку проекта:

   ```bash
   git clone <url-репозитория>
   cd admin-backend
   ```

2. Установите зависимости:

   ```bash
   pnpm install
   ```

3. Скопируйте пример конфигурации и заполните значения:

   ```bash
   cp .env.example .env
   ```

   | Переменная           | Описание                                                    |
   | -------------------- | ----------------------------------------------------------- |
   | `PORT`               | Порт, на котором запускается API                            |
   | `DATABASE_URL`       | Строка подключения к PostgreSQL                             |
   | `COOKIE_SECRET`      | Секрет для подписи cookie (не короче 32 символов)           |
   | `COOKIE_DOMAIN`      | Домен, для которого выставляются cookie                     |
   | `COOKIE_SECURE`      | Выставлять ли cookie с флагом `Secure`                      |
   | `CORS_ORIGIN`        | Адрес фронтенда, которому разрешены запросы                 |
   | `PUSH_API_URL`       | Адрес сервиса push-уведомлений                              |
   | `PUSH_API_CLIENT_ID` | Идентификатор клиента в сервисе push-уведомлений            |
   | `SMTP_HOST`          | Хост SMTP-сервера                                           |
   | `SMTP_PORT`          | Порт SMTP-сервера                                           |
   | `SMTP_SECURE`        | Использовать ли TLS при подключении к SMTP                  |
   | `SMTP_USER`          | Логин SMTP (адрес отправителя)                              |
   | `SMTP_PASS`          | Пароль SMTP                                                 |
   | `FEEDBACK_EMAIL`     | Адрес, на который приходят сообщения из формы обратной связи |

   Все переменные обязательны: при запуске конфигурация проверяется схемой Zod, и приложение не стартует, если чего-то не хватает.

4. Поднимите базу данных. Проще всего — через Docker Compose:

   ```bash
   docker compose up -d postgres
   ```

5. Сгенерируйте Prisma Client (он создаётся в `src/__gen__`) и примените миграции:

   ```bash
   pnpm prisma generate
   pnpm prisma migrate dev
   ```

6. Запустите сервер в режиме разработки:

   ```bash
   pnpm start:dev
   ```

После запуска API доступно по адресу `http://localhost:<PORT>/api`. Проверить, что всё работает, можно запросом к любому публичному маршруту, например:

```bash
curl -X POST http://localhost:4000/api/auth/signin \
  -H 'Content-Type: application/json' \
  -d '{"email": "user@example.com", "password": "password"}'
```

## Обзор API

Все маршруты имеют префикс `/api`. Пользователь авторизуется через сессионную cookie.

| Префикс            | Назначение                                                       |
| ------------------ | ---------------------------------------------------------------- |
| `/auth`            | Регистрация, вход, выход, подтверждение email, повторная отправка кода |
| `/users`           | Профиль текущего пользователя, смена пароля, удаление аккаунта   |
| `/sessions`        | Список активных сессий, завершение сессий, проверка сессии       |
| `/sites`           | Добавление, редактирование, удаление и отвязка сайтов            |
| `/notifications`   | Список уведомлений, отметка о прочтении, счётчики                |
| `/user-grants`     | Выдача другим пользователям доступа к сайтам с ролью (администратор или менеджер) |
| `/feedback`        | Отправка формы обратной связи на почту                           |
| `/external/sites`  | Синхронизация сайта с сервисом (вызывается со стороны сайта)     |
| `/external/notifications` | Отправка уведомлений с сайта (заказы, формы и т. д.)      |

Внешние маршруты (`/external/*`) авторизуются API-ключом сайта в заголовке `Authorization: Bearer <ключ>`.

Фоновые задачи (`@nestjs/schedule`): каждую ночь удаляются просроченные OTP-коды (в полночь) и сессии (в 01:00).

## Запуск тестов

Автоматические тесты в проекте пока не настроены. Перед отправкой изменений проверьте, что проект собирается и проходит линтер.

### Проверка сборки

```bash
pnpm build
```

### Проверка стиля кода

Линтинг выполняется ESLint с `typescript-eslint` и `eslint-plugin-prettier` (ошибки исправляются автоматически, где это возможно):

```bash
pnpm lint
```

Форматирование — Prettier (одинарные кавычки, висячие запятые; см. `.prettierrc`):

```bash
pnpm format
```

## Развёртывание

Приложение и база данных запускаются через Docker Compose:

```bash
docker compose up -d --build
```

При старте контейнер автоматически применяет миграции (`prisma migrate deploy`) и запускает собранное приложение. Внутри контейнера API слушает порт `3000`, снаружи он доступен на порту `4000`.

Перед запуском на сервере обязательно:

- замените учётные данные PostgreSQL в `docker-compose.yml` на собственные;
- задайте в `.env` надёжный `COOKIE_SECRET`, реальный `COOKIE_DOMAIN` и `COOKIE_SECURE=true`;
- укажите в `CORS_ORIGIN` адрес боевого фронтенда.

## Технологии

- [NestJS 11](https://nestjs.com/) — фреймворк
- [TypeScript](https://www.typescriptlang.org/) — язык
- [Prisma 7](https://www.prisma.io/) и [PostgreSQL](https://www.postgresql.org/) — ORM и база данных
- [Zod](https://zod.dev/) — валидация запросов и переменных окружения
- [Argon2](https://github.com/ranisalt/node-argon2) — хеширование паролей и кодов
- [Nodemailer](https://nodemailer.com/) — отправка писем
- [Winston](https://github.com/winstonjs/winston) — логирование
- [pnpm](https://pnpm.io/) — менеджер пакетов
- [Docker](https://www.docker.com/) — развёртывание

## Структура проекта

Код организован по принципам чистой архитектуры: бизнес-логика не зависит от фреймворка и базы данных, а реализации подключаются через DI-токены.

```
src/
├── domain/          # Сущности, интерфейсы репозиториев, доменные исключения
├── application/     # Сценарии использования (use cases), фабрики, интерфейсы сервисов
├── infrastructure/  # Реализации: Prisma, почта, логгер, хеширование, генераторы, конфиг, DI
├── presentation/    # Контроллеры, DTO, guards, pipes, фильтры, middleware, cron-задачи
├── api/             # Сервисы и внешнее API для подключённых сайтов
├── modules/         # NestJS-модули, связывающие слои между собой
└── main.ts          # Точка входа
prisma/              # Схема базы данных и миграции
```

## Участие в разработке

1. Создайте ветку от основной: `git checkout -b feature/название-задачи`.
2. Внесите изменения, соблюдая стиль кода и разделение на слои.
3. Если меняется схема базы данных, создайте миграцию: `pnpm prisma migrate dev --name описание`.
4. Убедитесь, что `pnpm lint` и `pnpm build` проходят без ошибок.
5. Закоммитьте изменения и создайте merge request.

## Версионирование

Для версионирования используется [SemVer](http://semver.org/). Текущая версия указана в `package.json`. Доступные версии смотрите в тегах репозитория.
