Сервис работы с SJ Reports

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

SJ Reports - Документация

Swagger UI: http://localhost:3030/docs

Описание проекта

Это API для CRM компании, занимающейся продажей рекламы. Сервис автоматизирует путь от входящей заявки до закрывающих документов, фиксируя согласования, сущности (контрагенты, площадки, креативы, договоры) и публикации в рамках рекламных кампаний.

Бизнес-флоу (в общих чертах)

1. Менеджер заводит заявку (предзаказ, запрос) с предварительными данными: заказчик, пожелания к размещению, пример креатива и т.д.
2. По заявке менеджеры собирают и актуализируют информацию, подбирают паблишеров, согласуют креативы.
3. При необходимости создаются сущности в системе: контрагенты/реквизиты, площадки, креативы, договоры.
4. На основании согласованных данных создаётся рекламная кампания, в которую попадают уже зарегистрированные и утверждённые сущности и связи.
5. РК состоит из набора публикаций (публикация = креатив + площадка размещения с параметрами/стоимостью/сроками).
6. По завершении РК формируется акт выполненных работ со списком публикаций, стоимостью, ссылками на креативы, площадки, договоры и контрагентов.

Основные возможности

• Управление предзаказами/заявками и их версиями
• Ведение рекламных кампаний и публикаций
• Справочники: контрагенты, реквизиты, площадки (платформы), креативы, договоры
• Хранение файлов и интеграция с S3-хранилищем
• Уведомления и логирование действий пользователей
• Роли и доступы, аутентификация по JWT
• Swagger-документация и стандартизированные ответы API

Интеграции

• Интеграция с API ОЗОН ОРД: регистрация контрагентов, площадок, договоров, актов, креативов, а также получение токена креатива для публикаций. Реализация расположена в модуле shared/external/ord.
• Интеграция с Яндекс Облако S3: хранение файлов креативов (загрузка/скачивание через presigned URL), управление объектами и правами доступа. Реализация расположена в модулях module/file, module/s3 и shared/s3.

Технологии

• NestJS (TypeScript)
• PostgreSQL
• Prisma ORM (миграции, типобезопасный доступ к БД)
• JWT-аутентификация, Guards/Decorators
• Swagger (OpenAPI)
• Yarn (менеджер пакетов)
• Kubernetes + GitLab CI/CD (на сервере)

Аутентификация и заголовки

• Все запросы требуют заголовки: Accept: application/json, Content-Type: application/json и Authorization: Bearer <token>.
• Получение токена и роли описаны в разделе авторизации Swagger.

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

• Основная спецификация доступна в Swagger по адресу: http://localhost:3030/docs
• Стандарты ответов и ошибок описаны в общих DTO.

Модули (основные)

• health — состояние сервиса
• users — пользователи, роли, доступы
• preorder — заявки/предзаказы
• agent - контрагенты
• requisites — реквизиты контрагентов
• platform — площадки/платформы
• contract — договоры
• creative — креативы
• file/s3 — управление файлами и S3
• advert-campaign — рекламные кампании
• publication — публикации в рамках РК
• notification — уведомления
• action-log — журнал действий

Детальная структура и эндпоинты каждого модуля — в Swagger.

Created By: ASt39