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

1. UBY CRM — документация
Программа для ЭВМ «UBY CRM» — веб-ориентированная корпоративная система управления взаимоотношениями с клиентами и массовыми наборами телефонных номеров в задачах триггерного обзвона у операторов связи.
Система предназначена для организаций, которые готовят задания на обзвон, передают их оператору связи, принимают результаты обзвона, ведут статусы и комментарии по номерам, строят отчётность и конверсию и разграничивают доступ между администраторами, менеджерами и клиентами в персональных кабинетах.
Класс программного обеспечения по Единому реестру российского ПО:
– основной класс: 09.09 — средства управления отношениями с клиентами (CRM);
– дополнительный класс (при необходимости): 12.20 — информационные системы для решения отраслевых задач.
Версия документации: 1.0
Дата последнего обновления: 2026-06-23
Основной сайт продукта: https://ubycrm.ru

2. Технические средства хранения и компиляции
Исходный текст программного обеспечения UBY CRM хранится в системе контроля версий и используется для разработки, сопровождения и внесения изменений в программный код. Объектный код формируется в процессе сборки и размещается в среде развертывания программного обеспечения в составе серверной и клиентской частей системы.
Серверная часть программного обеспечения реализована на Python с использованием фреймворка Django и Django REST Framework. Для выполнения фоновых задач и асинхронных сценариев используются Celery и Celery Beat, для обмена данными в реальном времени — WebSocket на базе Channels, для хранения данных — PostgreSQL, для кэширования и брокера задач — Redis.
Клиентская часть программного обеспечения реализована на React и TypeScript. Сборка клиентской части выполняется с использованием современного фронтенд-сборщика Vite. В промышленной установке используется контейнеризация с помощью Docker Compose, а в промышленной эксплуатации допускается использование обратного прокси на базе веб-сервера Nginx.
Для локальной и промышленной установки применяются следующие версии окружения:

Python 3.11.
Django 4.2.
Django REST Framework 3.14.
PostgreSQL 15.
Redis 7.
React 18.
TypeScript.
Vite.
MUI v6.
Zustand.
Recharts.

Процесс сборки и подготовки к запуску включает установку зависимостей, сборку серверной и клиентской частей, запуск контейнеров и применение настроек окружения. Для промышленного развертывания используется Docker Compose, а для запуска в рабочей среде — контейнеры backend, frontend, database, Redis, Celery и Celery Beat.
В составе документации предусмотрены материалы, относящиеся к установке и эксплуатации программного обеспечения, а также к операциям развертывания и переноса экземпляра системы на Windows Server. Пайплайн сборки и развертывания включает подготовку файла окружения, запуск контейнеров, выполнение миграций, инициализацию справочников и запуск сервисов приложения.

3. Инструкция по установке экземпляра программного обеспечения
3.1. Системные требования
Для установки и работы экземпляра программного обеспечения UBY CRM требуются:

сервер или рабочая станция с поддержкой контейнеризации;
операционная система с возможностью запуска Docker и Docker Compose;
установленный Docker;
установленный Docker Compose;
сетевой доступ между компонентами системы;
доступ к PostgreSQL;
доступ к Redis;
современный веб-браузер для работы с пользовательским интерфейсом.

Для промышленной эксплуатации используется контейнеризированное развертывание, а также допускается использование обратного прокси на базе веб-сервера Nginx.
3.2. Предварительные зависимости
Перед установкой необходимо подготовить:

файл .env;
файл .env.example для формирования рабочих параметров;
параметры подключения к базе данных PostgreSQL;
параметры подключения к Redis;
параметры настройки Django;
параметры настройки CORS;
параметры подключения frontend к backend;
исходный код программного обеспечения.

В составе приложения используются серверная часть на базе Python, Django и Django REST Framework, клиентская часть на React и TypeScript, а также фоновые процессы на Celery и Celery Beat.
3.3. Порядок установки
Шаг 1. Подготовка файла окружения
Скопируйте файл .env.example в файл .env и заполните параметры окружения.
Шаг 2. Настройка параметров подключения
Укажите значения параметров:

DJANGOSECRETKEY;
DJANGODEBUG;
DJANGOALLOWEDHOSTS;
DBHOST;
DBNAME;
DBUSER;
DBPASSWORD;
CELERYBROKERURL;
CELERYRESULTBACKEND;
CORSALLOWEDORIGINS;
VITEAPIBASEURL.

Шаг 3. Запуск контейнеров
Выполните запуск системы с пересборкой контейнеров:
bash
docker-compose up -d --build
После запуска должны быть подняты контейнеры:

базы данных;
Redis;
backend;
Celery;
Celery Beat;
frontend.

Шаг 4. Создание учетной записи администратора
После запуска выполните создание учетной записи администратора средствами приложения или через административные команды, используемые в проекте.
Шаг 5. Инициализация справочных данных
При необходимости загрузите справочные данные, используемые приложением для работы с кабинетами, статусами, географическими данными и другими системными справочниками.
3.4. Первый запуск
После завершения установки:

Откройте веб-интерфейс UBY CRM в браузере.
Проверьте доступность пользовательского интерфейса.
Проверьте доступность API.
Проверьте доступность административной панели.
Выполните вход под учетной записью администратора.
Убедитесь, что основные разделы системы открываются без ошибок.

3.5. Проверка успешной установки
Установка считается выполненной успешно, если:

контейнеры системы запущены;
веб-интерфейс открывается в браузере;
backend отвечает на запросы;
API доступно;
административная панель открывается;
пользователь может авторизоваться в системе (логин:d.proverka-test; пароль: 12345678; сайт: https://ubycrm.ru)
фоновые процессы Celery и Celery Beat работают без ошибок.

3.6. Типовые ошибки при установке
К типовым ошибкам относятся:

неверно заполненный файл .env;
отсутствие подключения к PostgreSQL;
отсутствие подключения к Redis;
некорректно заданные параметры DJANGOALLOWEDHOSTS и CORSALLOWEDORIGINS;
не выполнен запуск контейнеров;
отсутствует пересборка образов после изменения конфигурации;
не задан параметр VITEAPIBASEURL;
не создана учетная запись администратора.

4. Функциональные характеристики экземпляра программного обеспечения
Программное обеспечение «UBY CRM» представляет собой веб-ориентированную корпоративную систему управления взаимоотношениями с клиентами и массовыми наборами телефонных номеров в задачах триггерного обзвона у операторов связи. Система предназначена для организаций, которые готовят задания на обзвон, передают их оператору связи, принимают результаты обзвона, ведут статусы и комментарии по номерам, строят отчётность и конверсию, а также разграничивают доступ между администраторами, менеджерами и клиентами в персональных кабинетах.
Назначение CRM
UBY CRM используется для ведения клиентских кабинетов и триггер-проектов, подготовки и выгрузки заданий на обзвон, загрузки ответных файлов от оператора связи, учета статусов обзвона и комментариев, построения дашбордов и аналитики конверсии, формирования отчётов и обеспечения внутреннего контроля за действиями пользователей.
Система поддерживает прямой и обратный контуры обмена данными с оператором связи, автоматизированную синхронизацию по SFTP, журналирование действий пользователей и средства обратной связи в виде тикетов.
Основные роли пользователей
В системе предусмотрено разграничение доступа между несколькими типами пользователей:

администратор;
менеджер;
клиентский кабинет;
пользователь с другими внутренними ролями, используемыми в настройках доступа и кабинетах.

Права доступа определяются на уровне ролей и кабинетов, что позволяет ограничивать доступ к данным, проектам, статусам и операциям в соответствии с назначением пользователя.
Ключевые функции
UBY CRM обеспечивает следующие основные функциональные возможности:

ведение кабинетов клиентов и триггер-проектов;
настройку типов заданий, лимитов и расписания активности по дням недели;
разбиение крупных списков источников на проекты по правилам домена;
подготовку и выгрузку заданий для оператора связи в установленном формате;
сопоставление идентификаторов проектов для последующего импорта;
загрузку файлов ответа оператора;
разбор и сохранение номеров с дедупликацией внутри кабинета клиента;
учет статусов обзвона и комментариев по номерам;
классификацию статусов по ролям для расчёта воронки и конверсии;
применение персональных наборов статусов для кабинетов при необходимости;
ведение чёрных списков номеров, как глобальных, так и в разрезе кабинета;
исключение номеров из импорта;
построение дашбордов, метрик и отчётов;
формирование табличных выгрузок с фильтрами по периоду, проекту и статусу;
автоматизированную синхронизацию с файловым хранилищем оператора по расписанию через SFTP;
разграничение прав пользователей;
аудит операций;
оповещения в режиме реального времени;
модуль обращений в техническую поддержку.

Сценарии работы
Типовой сценарий работы включает несколько последовательных этапов:

Администратор или менеджер создаёт кабинет клиента и триггер-проект.
Задаются параметры проекта: тип задания, лимит, расписание активности, набор источников и дополнительные правила обработки.
Система формирует задания для оператора связи и выгружает их в установленном формате.
Оператор связи выполняет обзвон и возвращает результаты в ответных файлах.
Система загружает ответные файлы, выполняет разбор данных и дедупликацию номеров внутри кабинета.
В карточках номеров обновляются статусы обзвона и комментарии.
На основе накопленных данных формируются отчёты, дашборды и показатели конверсии.
При необходимости выполняется автоматическая синхронизация с файловым хранилищем оператора по SFTP.

Отдельно предусмотрен сценарий работы с чёрными списками, при котором номера исключаются из импорта на уровне глобального списка или списка кабинета.
Входные и выходные данные
Входными данными системы являются:

данные о кабинетах клиентов;
параметры триггер-проектов;
списки телефонных номеров;
файлы заданий для оператора связи;
ответные файлы оператора связи;
данные о статусах обзвона;
комментарии по номерам;
данные для формирования отчётов;
данные для синхронизации по SFTP;
обращения пользователей в техническую поддержку.

Выходными данными системы являются:

задания для оператора связи в установленном формате;
ответные файлы, обработанные системой;
обновлённые статусы и комментарии по номерам;
табличные отчёты;
дашборды и метрики конверсии;
журналы действий пользователей;
данные для отображения в персональных кабинетах;
уведомления в режиме реального времени.

Интеграции
UBY CRM поддерживает интеграцию со следующими компонентами и механизмами:

оператор связи;
файловое хранилище оператора;
SFTP-синхронизация;
REST API;
WebSocket для передачи данных в реальном времени;
модуль журналирования действий;
модуль тикетов для обращений в техническую поддержку.

В технологическом стеке системы используются серверная часть на базе Python, Django и Django REST Framework, фоновые процессы Celery и Celery Beat, клиентская часть на React и TypeScript, хранение данных в PostgreSQL и Redis, а также механизм WebSocket на базе Channels.

5. Описание процессов, обеспечивающих поддержание жизненного цикла программного обеспечения
Поддержание жизненного цикла программного обеспечения UBY CRM включает разработку, тестирование, выпуск обновлений, исправление ошибок, поддержку пользователей, сопровождение технической поддержки и развитие функциональности системы.
5.1. Разработка
Разработка UBY CRM ведётся как веб-ориентированного клиент-серверного приложения. Серверная часть реализована на Python, Django и Django REST Framework, клиентская часть — на React и TypeScript, а фоновые процессы выполняются с использованием Celery и Celery Beat.
При разработке используются механизмы работы с REST API, WebSocket, PostgreSQL, Redis и контейнерным развёртыванием через Docker Compose.
5.2. Тестирование
Тестирование системы включает проверку работы серверной и клиентской частей, корректность обмена данными с оператором связи, выполнение сценариев импорта и экспорта, а также проверку работы фоновых процессов и интерфейсов пользователя.
В документации системы предусмотрены материалы, относящиеся к проверке установки, эксплуатации, API и операций сопровождения, что позволяет использовать их для контроля работоспособности и проверки изменений.
5.3. Выпуск обновлений
Выпуск обновлений осуществляется по мере развития системы, добавления новых функций, доработки существующих сценариев и исправления выявленных ошибок.
История изменений и сведения о развитии системы фиксируются в документации проекта, включая файл CHANGELOG.
5.4. Исправление ошибок
Исправление ошибок производится в рамках сопровождения системы при выявлении неисправностей в процессе эксплуатации, тестирования или при обращениях пользователей.
Для фиксации и обработки обращений предусмотрен модуль технической поддержки, а также журналирование действий пользователей, что позволяет отслеживать и анализировать инциденты.
5.5. Поддержка пользователей
Поддержка пользователей осуществляется через встроенный модуль обращений в техническую поддержку и средства обратной связи системы.
Пользователи могут направлять обращения, связанные с работой CRM, статусами, проектами, отчетами, синхронизацией и доступом к данным.
5.6. Состав команды поддержки
Поддержка системы обеспечивается разработчиками и техническими специалистами, отвечающими за серверную часть, клиентскую часть, фоновые процессы, интеграции и эксплуатацию инфраструктуры.
Также в системе предусмотрены роли администраторов и менеджеров, которые участвуют в управлении кабинетами, проектами, правами доступа и обработкой обращений.
5.7. Каналы обращения
Обращения пользователей принимаются через модуль тикетов, встроенный в систему UBY CRM.
Кроме того, при эксплуатации системы предусмотрено журналирование действий пользователей и контроль событий, связанных с работой интерфейса, импортом, экспортом и синхронизацией данных.

6. Информация, необходимая для эксплуатации экземпляра программного обеспечения
Программное обеспечение UBY CRM предназначено для работы в веб-браузере и используется для управления клиентскими кабинетами, триггер-проектами, статусами обзвона, ответными файлами оператора связи, отчетами и обращениями в техническую поддержку.
6.1. Вход в систему
Для входа в систему используется веб-интерфейс UBY CRM. Аутентификация реализована через JWT, в системе предусмотрены учетные записи с ролями, включая администратора, менеджера и клиентский кабинет.
После входа пользователь получает доступ только к тем разделам и данным, которые разрешены его ролью и принадлежностью к кабинету.
6.2. Создание записей
В системе можно создавать и редактировать следующие основные записи:

кабинеты клиентов;
триггер-проекты;
статусы обзвона;
чёрные списки номеров;
тикеты в техническую поддержку;
настройки SFTP;
расписания синхронизации;
отчёты и служебные записи, связанные с экспортом и импортом данных.

Создание и изменение записей выполняется в интерфейсе системы либо через административные функции, предусмотренные для пользователей с соответствующими правами.
6.3. Поиск данных
Поиск и фильтрация данных в UBY CRM выполняются по различным параметрам, включая:

кабинет;
триггер-проект;
статус;
период;
проект;
идентификатор;
номер телефона;
роль;
признаки активности;
параметры импорта и экспорта.

Система поддерживает табличные представления данных, фильтрацию, дашборды и аналитические отчеты, что позволяет быстро находить нужную информацию по клиентам, номерам, проектам и операциям.
6.4. Выгрузка отчётов
В системе предусмотрено формирование и выгрузка отчётов в табличном виде.
Поддерживаются:

отчёты по номерам;
табличные выгрузки с фильтрами;
выгрузки с учетом периода, проекта и статуса;
формирование файлов в XLSX-формате;
экспорт данных для оператора связи;
экспорт файлов заданий;
загрузка ответных файлов.

Для аналитики также используются дашборды и метрики конверсии.
6.5. Завершение работы
После завершения работы пользователю необходимо закрыть веб-интерфейс UBY CRM и завершить сеанс работы в системе средствами браузера.
Если работа велась с административными функциями, рекомендуется завершить действия с учетом установленного разграничения прав доступа и закрыть все открытые разделы интерфейса.
6.6. Часто возникающие проблемы
В материалах проекта зафиксированы следующие типовые проблемы эксплуатации:

ошибки подключения к PostgreSQL или Redis;
некорректные параметры окружения;
ошибки при настройке DJANGOALLOWEDHOSTS и CORSALLOWEDORIGINS;
ошибки при настройке VITEAPIBASEURL;
ошибки при работе Celery и Celery Beat;
проблемы со сборкой или пересборкой контейнеров;
проблемы с импортом и экспортом файлов;
ошибки при SFTP-синхронизации;
некорректное поведение при обработке ответных файлов оператора;
ошибки при недостатке прав доступа у пользователя;
проблемы с обновлением статусов и отображением данных в интерфейсе.

Также в документации проекта предусмотрены материалы по операциям сопровождения, диагностике и восстановлению работы системы, включая проверки логов, состояния контейнеров и доступности основных сервисов.

7. Сведения о программных модулях
Название модуля: Accounts / Пользователи и роли
Назначение: Управление пользователями системы, ролями доступа, кабинетами и правами работы в CRM.
Зависимости: Django, Django REST Framework, JWT, PostgreSQL.
Где используется: Авторизация, разграничение доступа, работа администраторов, менеджеров и клиентских кабинетов.
Статус: Используется
Название модуля: Cabinets / Кабинеты клиентов
Назначение: Ведение клиентских кабинетов, привязка пользователей к кабинетам, управление параметрами кабинета.
Зависимости: Django, PostgreSQL, REST API.
Где используется: Разделы кабинетов, доступ пользователей, триггер-проекты, черные списки, статусы, отчёты.
Статус: Используется
Название модуля: Triggers / Триггер-проекты
Назначение: Создание, редактирование и управление триггер-проектами, заданиями на обзвон, лимитами, расписанием и источниками.
Зависимости: Django, PostgreSQL, Celery, REST API.
Где используется: Формирование заданий для оператора связи, импорт и экспорт данных, аналитика и дашборды.
Статус: Используется
Название модуля: Trigger phone numbers / Номера обзвона
Назначение: Хранение номеров, статусов обзвона, комментариев и результатов обработки.
Зависимости: PostgreSQL, REST API.
Где используется: Обратный импорт от оператора связи, аналитика, отчёты, дедупликация в пределах кабинета.
Статус: Используется
Название модуля: Call status types / Типы статусов обзвона
Назначение: Классификация статусов обзвона по ролям и логике расчёта воронки и конверсии.
Зависимости: PostgreSQL, справочники системы.
Где используется: Отображение статусов, расчёт конверсии, персональные наборы статусов кабинетов.
Статус: Используется
Название модуля: Black list / Чёрные списки номеров
Назначение: Хранение глобальных и кабинетных чёрных списков номеров для исключения из импорта.
Зависимости: PostgreSQL, REST API.
Где используется: Исключение номеров при обработке входящих файлов и формировании данных.
Статус: Используется
Название модуля: Exports / Экспорт заданий
Назначение: Подготовка и выгрузка заданий для оператора связи в установленном формате.
Зависимости: Celery, Django, REST API, файловая система.
Где используется: Прямой контур передачи данных оператору связи.
Статус: Используется
Название модуля: Imports / Импорт ответов
Назначение: Загрузка и обработка ответных файлов оператора связи, сохранение результатов и дедупликация номеров.
Зависимости: Celery, Django, REST API, файловая система.
Где используется: Обратный контур обработки результатов обзвона.
Статус: Используется
Название модуля: Reports / Отчёты
Назначение: Формирование табличных отчётов, выгрузок и аналитических данных по проектам и номерам.
Зависимости: PostgreSQL, REST API, генерация XLSX.
Где используется: Дашборды, отчётность, аналитика конверсии, выгрузки с фильтрами.
Статус: Используется
Название модуля: Dashboard / Дашборды и аналитика
Назначение: Отображение ключевых метрик, в том числе по конверсии и статусам.
Зависимости: PostgreSQL, REST API, React.
Где используется: Главные панели управления и аналитики для пользователей CRM.
Статус: Используется
Название модуля: SFTP sync / Синхронизация по SFTP
Назначение: Автоматизированная синхронизация файлов с файловым хранилищем оператора по расписанию.
Зависимости: Celery Beat, SFTP, SSH, PostgreSQL.
Где используется: Автоматическая выгрузка и загрузка файлов по заданному расписанию.
Статус: Используется
Название модуля: Tickets / Техническая поддержка
Назначение: Приём обращений пользователей и обработка сообщений техподдержки.
Зависимости: Django, PostgreSQL, REST API.
Где используется: Модуль обратной связи и поддержки пользователей CRM.
Статус: Используется
Название модуля: Audit log / Журналирование
Назначение: Фиксация действий пользователей и событий в системе.
Зависимости: PostgreSQL, Django.
Где используется: Контроль операций, аудит, анализ инцидентов и изменений.
Статус: Используется
Название модуля: API / REST API
Назначение: Предоставление программного интерфейса для работы клиентской части и внешних запросов.
Зависимости: Django REST Framework, JWT, PostgreSQL.
Где используется: Взаимодействие frontend, backend, операций импорта, экспорта и справочников.
Статус: Используется
Название модуля: Frontend / Пользовательский интерфейс
Назначение: Реализация веб-интерфейса CRM для пользователей системы.
Зависимости: React, TypeScript, Vite, MUI, Zustand, Recharts.
Где используется: Работа с кабинетами, проектами, номерами, отчётами и тикетами.
Статус: Используется
Название модуля: Backend / Серверная часть
Назначение: Центральная бизнес-логика системы, обработка запросов и взаимодействие с базой данных.
Зависимости: Python, Django, Django REST Framework, PostgreSQL, Redis.
Где используется: Все сценарии работы CRM, авторизация, справочники, обмен данными, отчёты.
Статус: Используется
Название модуля: Celery / Фоновые задачи
Назначение: Асинхронное выполнение задач импорта, экспорта, генерации отчётов и синхронизации.
Зависимости: Celery, Redis, PostgreSQL.
Где используется: Фоновые процессы системы.
Статус: Используется
Название модуля: WebSocket / Channels
Назначение: Передача данных в реальном времени и уведомлений.
Зависимости: Django Channels, Redis.
Где используется: Реaltime-оповещения, обновление интерфейса, события системы.
Статус: Используется
Название модуля: Database / База данных
Назначение: Хранение данных CRM, справочников, кабинетов, номеров, отчётов и журналов.
Зависимости: PostgreSQL 15.
Где используется: Все основные сущности и операции системы.
Статус: Используется
Название модуля: Operations / Эксплуатация и сопровождение
Назначение: Поддержка запуска, диагностики и восстановления работы системы.
Зависимости: Docker Compose, PostgreSQL, Redis, Nginx.
Где используется: Развертывание, сопровождение, контроль работоспособности.
Статус: Используется
Название модуля: Migration Windows Server
Назначение: Перенос и установка системы в среде Windows Server.
Зависимости: Docker Compose, backend, frontend, database.
Где используется: Развёртывание экземпляра системы на Windows Server.
Статус: Используется