Документация на программу для ЭВМ «Колокол»

1.1. Назначение программы

«Колокол» — программа для ЭВМ, предназначенная для динамического коллтрекинга и аналитики рекламных кампаний. Программа обеспечивает автоматический учёт онлайн-конверсий в интернет-маркетинге и позволяет связать входящий телефонный звонок с конкретным рекламным каналом, кампанией, ключевым словом и страницей входа на сайт.

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

1.2. Задачи, которые решает программа

1. Определение рекламного источника каждого входящего телефонного звонка с детализацией до кампании, объявления, ключевого слова и страницы входа.
2. Автоматическое распределение телефонных номеров из выделенного пула между одновременными посетителями сайта по настраиваемым правилам маршрутизации.
3. Оптимизация ёмкости номерного пула за счёт динамического таймаута сессии и автоматического освобождения номеров неактивных визитов.
4. Подмена телефонных номеров в содержимом веб-страницы без внесения изменений в вёрстку и программный код сайта.
5. Сбор и хранение параметров веб-визитов: меток рекламных кампаний, реферера, страницы входа, идентификатора устройства и идентификатора Яндекс.Метрики.
6. Передача сведений о состоявшихся телефонных обращениях во внешнюю метрическую платформу Яндекс.Метрика в качестве офлайн-конверсий.
7. Двусторонний обмен данными с ERP-системой: загрузка справочников сайтов, линий и телефонных номеров, выгрузка визитов, загрузка обращений.
8. Предоставление рабочего места администратора и маркетолога для настройки правил, просмотра визитов и контроля работы системы.
9. Ведение журнала выполнения фоновых задач и контроль состояния системы.

1.3. Состав программного обеспечения

1.4. Перечень функций

Учёт визитов и подмена номеров

• Идентификация посетителя по устойчивому отпечатку браузера (fingerprint UID) и идентификатору Яндекс.Метрики _ym_uid.
• Создание визита и резервирование свободного телефонного номера из пула.
• Продление активного визита при повторных обращениях посетителя в течение сессии.
• Замена телефонных номеров в текстовых узлах страницы и в ссылках вида tel:, включая содержимое, добавленное после загрузки страницы.
• Исключение из обработки служебных элементов: SCRIPT, STYLE, INPUT, TEXTAREA, TEMPLATE, NOSCRIPT, SELECT, OPTION, редактируемых областей и SVG.
• Восстановление исходных номеров по истечении срока действия выданного номера.

Правила подбора номера

• Настройка параметров подбора по сайту, домену, рефереру, странице входа и параметрам адресной строки.
• Привязка параметра к городу, рекламной линии-источнику, маршруту и пулу номеров.
• Приоритизация правил: при совпадении нескольких условий выбирается правило с наибольшим весом.
• Условия по странице входа как отдельная сущность конфигурации.

Управление номерной ёмкостью

• Автоматическое закрытие визитов, по которым отсутствует активность.
• Освобождение самого раннего визита при исчерпании свободных номеров в пуле.
• Уведомление ответственных лиц о принудительно закрытых визитах.
• Загрузка и актуализация номерного пула из ERP-системы.

Интеграции

• Загрузка из ERP справочников сайтов, линий и телефонных номеров.
• Выгрузка визитов в ERP с контролем состояния отправки по каждому визиту.
• Загрузка из ERP сведений о состоявшихся обращениях (конверсиях).
• Передача конверсий в Яндекс.Метрику по расписанию с авторизацией по протоколу OAuth.
• Управление маршрутизацией телефонных номеров в телефонии.

Администрирование

• Ведение проектов коллтрекинга с привязкой к сайту и счётчику Яндекс.Метрики.
• Генерация кода подключения клиентского скрипта для каждого проекта.
• Просмотр журнала визитов с фильтрами по активности, датам и состоянию выгрузки.
• Просмотр номерного пула, справочников сайтов и рекламных линий.
• Ведение пользователей, групп и прав доступа; выпуск токенов для программного доступа.
• Журнал выполнения фоновых задач с регистрацией ошибок.
• Контроль состояния системы через служебную точку доступа.

Защита данных

• Шифрование токенов телефонных линий симметричным алгоритмом (Fernet).
• Авторизация в веб-АРМ по учётной записи, программный доступ — по токену.
• Ограничение состава собираемых данных техническими параметрами визита.

1.5. Вводная информация (входные данные)

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

1.7. Затрачиваемые ресурсы

Значения в таблице приведены для стартовой инсталляции, обслуживающей один проект коллтрекинга. Для инсталляций с большим объёмом трафика конфигурация рассчитывается на этапе предпроектного обследования.

Потребность в ресурсах масштабируется от объёма трафика подключённых сайтов, размера номерного пула, количества проектов и глубины хранения истории визитов. Для распределённых инсталляций конфигурация рассчитывается на этапе предпроектного обследования.

1.8. Условия и ограничения применения

• Для работы программы требуется выделенный пул телефонных номеров и возможность управления их маршрутизацией в телефонии заказчика или оператора связи.
• Число одновременно обслуживаемых посетителей, для которых выполняется подмена номера, ограничено размером номерного пула. При исчерпании пула на странице сохраняется исходный номер компании, обращение остаётся возможным, а событие фиксируется в журнале.
• Подмена номеров выполняется в браузерах Chrome и Edge версии 109 и выше, Firefox версии 115 и выше, Safari версии 15.6 и выше.
• Передача конверсий в Яндекс.Метрику требует действующего счётчика и выданного владельцем счётчика токена доступа.
• Обмен с ERP требует доступа к webservice ERP-системы заказчика.
• Программа не собирает имена, адреса, платёжные реквизиты и иные персональные данные посетителей сайтов; фиксируются только технические параметры визита.

2.1. Требования к аппаратному обеспечению

Программа устанавливается на сервер под управлением операционной системы семейства Linux. Требования к ресурсам приведены в п. 1.7 настоящей документации. Установка возможна как на выделенный физический сервер, так и на виртуальную машину в облачной инфраструктуре или в контуре заказчика.

2.2. Требования к программному обеспечению

2.3. Состав дистрибутива

Программа поставляется в виде двух репозиториев исходного кода с файлами сборки контейнеров.

Серверная часть

/app/
├── app/              # проект Django: настройки, маршруты, конфигурация Celery
├── tracker/          # основное приложение коллтрекера
├── erpclient/        # клиент ERP webservice
├── requirements/     # зависимости Python
└── manage.py

Клиентская часть

/src/js/
├── init.js        # точка входа скрипта, отпечаток браузера, расписание обращений
├── backend.js     # HTTP-клиент серверной части
├── processors.js  # поиск и замена телефонных номеров в документе
└── storage.js     # работа с cookies

2.4. Состав сервисов контейнеризации

2.5. Порядок установки

1. Подготовить сервер Установить операционную систему Linux, Docker и Docker Compose. Обеспечить сетевую доступность сервера для обратного прокси-сервера и для webservice ERP-системы.
2. Разместить исходный код Скопировать репозитории серверной и клиентской части на сервер.
3. Создать файл конфигурации Создать файл .env на основе поставляемого образца env.example и заполнить переменные окружения в соответствии с п. 2.6.
4. Подготовить базу данных Развернуть PostgreSQL, создать базу данных и учётную запись, указать параметры подключения в .env. Проверить, что значения MAX_CLIENT_CONN, DEFAULT_POOL_SIZE и RESERVE_POOL_SIZE для PgBouncer согласованы с лимитами PostgreSQL, числом рабочих процессов gunicorn и параллелизмом обработчиков задач.
5. Собрать и запустить серверную часть Выполнить сборку рабочей конфигурации. Миграции базы данных применяются автоматически сервисом migrate.

   make build-prod

6. Собрать клиентский скрипт Выполнить установку зависимостей и сборку рабочей версии. Результат сборки — файл dist/js/init.js.

   npm install
   npm run production

7. Настроить обратный прокси-сервер Настроить Nginx на раздачу клиентского скрипта по путям /init.js, /v3/init.js, /v4/init.js и на проксирование к серверной части путей /tracker/visits/, /tracker/oauth_token, /tracker/phones/, /tracker/autocomplete/, /tracker/system_status, /wui/.
8. Создать учётную запись администратора Создать суперпользователя Django для входа в веб-АРМ по адресу /wui/.
9. Подключить внешние системы Указать адрес webservice ERP-системы в переменной WEB_SERVICE_BASE_URL. Зарегистрировать приложение в Яндекс.OAuth и указать YA_CLIENT_ID и YA_CLIENT_SECRET. Убедиться, что справочники сайтов, линий и телефонных номеров загружаются фоновыми задачами.
10. Проверить установку Выполнить проверки по п. 2.8.

2.6. Переменные окружения

Конфигурация задаётся в файле .env. Образец поставляется в файле env.example.

При подключении через PgBouncer в режиме transaction pooling в настройках Django устанавливаются CONN_MAX_AGE = 0 и DISABLE_SERVER_SIDE_CURSORS = True.

2.7. Подключение программы к сайту

1. Создать проект В веб-АРМ в разделе «Проекты» создать проект, указав сайт и код счётчика Яндекс.Метрики.
2. Получить код подключения Веб-АРМ формирует код подключения клиентского скрипта, содержащий идентификатор проекта.
3. Разместить код на сайте Добавить полученный код в шаблон страниц сайта. Изменения в вёрстку не требуются.
4. Настроить правила подбора номера В разделе «Параметры» задать правила: сайт, условия по домену, рефереру и странице входа, город, линия-источник, маршрут, пул и приоритет.

2.8. Проверка корректности установки

1. Запросить служебную точку доступа GET /tracker/system_status и убедиться, что ответ получен.
2. Убедиться в доступности клиентского скрипта: curl -I https://<адрес>/v4/init.js.
3. Открыть веб-АРМ по адресу /wui/ и выполнить вход.
4. Убедиться, что фоновая задача загрузки телефонных номеров из ERP отработала и пул заполнен (раздел «Телефоны»).
5. Открыть тестовую страницу с подключённым скриптом и проверить: создание визита в разделе «Визиты», замену обычных номеров, замену ссылок tel:, отсутствие ошибок в консоли браузера.
6. Проверить журналы контейнеров приложения и обработчиков задач на отсутствие ошибок.

2.9. Контакты технических специалистов

Консультации по развёртыванию, настройке и функционированию экземпляра программы предоставляют технические специалисты ООО «Меридиан»: электронная почта help@meridianooo.ru, телефон +7 499 648-54-49, режим работы — понедельник–пятница с 09:00 до 18:00 по московскому времени.

3.1. Доступ к развёрнутому экземпляру программы

Для ознакомления с работой программы развёрнут демонстрационный экземпляр с тестовыми данными. Экземпляр изолирован от рабочей инфраструктуры: интеграция с ERP-системой и с Яндекс.Метрикой, а также фоновые задачи в нём отключены.

Демонстрационные сайты с подключённым скриптом

На перечисленных ниже сайтах установлен клиентский скрипт программы. При открытии страницы телефонный номер на ней подменяется номером из демонстрационного пула, а в разделе «Визиты» веб-АРМ появляется соответствующая запись.

3.2. Загрузка и запуск программы

Программа является серверным веб-приложением. Загрузка и запуск выполняются в двух контурах.

Контур серверной части

1. Запуск всех сервисов программы выполняется командой сборки и запуска рабочей конфигурации make build-prod. Сервис migrate применяет миграции базы данных, после чего запускаются приложение, пул соединений, хранилище очередей, обработчики задач и планировщик.
2. Готовность программы подтверждается успешным ответом служебной точки доступа GET /tracker/system_status.
3. Планировщик периодических задач запускается автоматически при значении переменной APP_MODE=prod.

Контур рабочего места пользователя

1. Пользователь открывает в браузере адрес веб-АРМ /wui/.
2. Программа выводит форму входа и запрашивает имя пользователя и пароль.
3. После успешной авторизации открывается главный экран со списком разделов и журналом последних действий.

Контур сайта клиента

1. При открытии посетителем страницы сайта браузер загружает клиентский скрипт по адресу /v4/init.js.
2. Скрипт определяет посетителя, собирает параметры визита и отправляет их серверной части.
3. Получив номер, скрипт выполняет замену телефонных номеров в содержимом страницы.

3.3. Выполнение программы: работа в веб-АРМ

Главный экран веб-АРМ содержит перечень разделов, сгруппированных по назначению: «Трекер», «Пользователи и группы», «Токен аутентификации», а также ссылку на документацию.

Во всех списковых разделах доступны поиск, фильтры, сортировка по столбцам, массовые действия над выбранными записями и просмотр истории изменений объекта.

3.4. Команды программного интерфейса и ответы программы

Программа предоставляет интерфейс HTTP. Формат обмена — JSON.

Пример ответа на команду проверки состояния

GET /tracker/system_status

{
  "nrv": 0,
  "nrle": 1
}

Поле nrv — количество визитов за последний час, поле nrle — количество ошибок в журнале за последний час.

Коды результата обработки визита

Ответ на команду POST /tracker/visits/ содержит поле rc с кодом результата.

3.5. Команды управления программой

3.6. Периодические задачи

После запуска программа выполняет регламентные операции без участия пользователя.

3.7. Завершение работы программы

1. Пользователь завершает сеанс работы в веб-АРМ командой «Выйти». Программа закрывает сеанс и возвращает форму входа.
2. Остановка серверной части выполняется остановкой сервисов контейнеризации. Активные визиты сохраняются в базе данных; после повторного запуска обработка продолжается штатно, устаревшие визиты закрываются регламентной задачей.
3. На стороне сайта клиента работа скрипта прекращается при закрытии страницы. Выданный номер действует 2 минуты; по истечении срока, если страница остаётся открытой без обращений, скрипт восстанавливает исходные номера. Период обращений к серверной части ограничен шестью часами с момента загрузки страницы.

3.8. Диагностика и типовые ситуации

4.1. Общие положения

Все процессы жизненного цикла программы «Колокол» — проектирование, разработка, тестирование, поставка, ввод в эксплуатацию, документирование, сопровождение, устранение неисправностей, совершенствование и снятие с эксплуатации — выполняются силами ООО «Меридиан» как правообладателя программы. Внешние подрядчики к выполнению этих процессов не привлекаются.

Разработка, тестирование, техническая поддержка и модернизация программы осуществляются штатными сотрудниками ООО «Меридиан» на территории Российской Федерации.

4.2. Проектирование

• Требования формируются из задач заказчиков, результатов эксплуатации действующих инсталляций и требований к интеграциям с внешними системами.
• По каждому изменению определяется состав затрагиваемых компонентов: клиентский скрипт, серверная часть, фоновые задачи, модуль интеграций, схема базы данных.
• Оценивается влияние изменения на совместимость программного интерфейса и на уже подключённые сайты клиентов.
• Результат проектирования фиксируется в задаче и в описании изменения.

4.3. Разработка

• Исходный код хранится в системе контроля версий в двух репозиториях: серверная часть и клиентская часть.
• Каждое изменение выполняется в отдельной ветке и проходит рецензирование другим разработчиком перед включением в основную ветку.
• Применяются единые правила оформления кода; соблюдение правил контролируется средствами статического анализа (make lint, npm run lint:js) и автоматического форматирования (make format).
• История изменений сохраняется в системе контроля версий и позволяет установить автора и содержание каждого изменения.

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

• Перед сборкой релиза выполняется набор автоматических тестов командой make test на конфигурации разработки.
• Изменения клиентского скрипта проверяются на тестовой странице: создание визита, замена обычных номеров, замена ссылок tel:, отсутствие ошибок в консоли браузера.
• Для изменений схемы базы данных отдельно оценивается риск: длительность миграции, вероятность блокировок, необходимость переноса данных, совместимость прежней и новой версий кода.
• Функциональная проверка выполняется на демонстрационном стенде, изолированном от рабочей инфраструктуры.

4.5. Поставка и ввод в эксплуатацию

• Программа поставляется в виде исходного кода с файлами сборки контейнеров либо разворачивается правообладателем в облачной инфраструктуре.
• Ввод в эксплуатацию выполняется по порядку, приведённому в разделе 2 настоящей документации.
• По завершении развёртывания проводится обучение сотрудников заказчика и передаётся эксплуатационная документация.
• Результаты работ фиксируются актом.

4.6. Эксплуатация и мониторинг

В ходе эксплуатации контролируются техническое состояние программы и показатели её работы.

О превышении пороговых значений и о принудительно закрытых визитах ответственные сотрудники получают автоматические уведомления.

4.7. Устранение неисправностей, выявленных в ходе эксплуатации

Устранение неисправностей выполняется штатными сотрудниками ООО «Меридиан» в следующем порядке.

1. Приём обращения Обращения принимаются по электронной почте help@meridianooo.ru, по телефону +7 499 648-54-49 и через форму обратной связи на сайте правообладателя. Неисправности также выявляются самой службой сопровождения по данным мониторинга (п. 4.6).
2. Регистрация Каждое обращение регистрируется с присвоением номера. Фиксируются: дата и время поступления, заявитель, инсталляция, описание проблемы, условия воспроизведения, приложенные материалы.
3. Классификация по уровню критичности

   Уровень	Признак	Срок реакции	Срок устранения
   Критичный	Программа недоступна; телефонные номера не выдаются; данные не сохраняются	2 рабочих часа	1 рабочий день
   Существенный	Не работает отдельная функция; не выполняется выгрузка во внешнюю систему; ошибки в отчётных данных	1 рабочий день	5 рабочих дней
   Некритичный	Замечания к интерфейсу, частные неудобства, запросы на консультацию	1 рабочий день	В составе очередного обновления

   Сроки, приведённые в таблице, применяются по умолчанию. Для отдельных инсталляций сроки устанавливаются договором сопровождения.
4. Диагностика и воспроизведение Анализируются журналы приложения и фоновых задач, записи журнала задач в базе данных, состояние очередей, активные запросы и блокировки в базе данных. Неисправность воспроизводится на демонстрационном или тестовом стенде.
5. Исправление Исправление разрабатывается в отдельной ветке, проходит рецензирование и автоматическое тестирование в порядке, установленном пп. 4.3 и 4.4.
6. Выпуск и установка Исправление включается в очередное обновление либо, для критичных неисправностей, выпускается внеочередным обновлением в порядке п. 4.9. После установки выполняются контрольные проверки по п. 2.8.
7. Закрытие обращения и контроль Заявитель уведомляется об устранении неисправности. Обращение закрывается после подтверждения результата. Повторяющиеся обращения анализируются на предмет устранения причины, а не следствия.

4.8. Совершенствование программного обеспечения

Развитие программы ведётся правообладателем на постоянной основе.

1. Сбор предложений Источники предложений по развитию: обращения и пожелания заказчиков; результаты анализа эксплуатации и статистики обращений; изменения в программных интерфейсах внешних систем (ERP, Яндекс.Метрика, телефония); изменения требований законодательства; предложения сотрудников правообладателя.
2. Формирование плана развития Предложения оцениваются по значимости, трудоёмкости и влиянию на действующие инсталляции. На основании оценки формируется план развития программы. План пересматривается по мере поступления новых требований.
3. Реализация Доработки выполняются в порядке, установленном пп. 4.2–4.4. Доработки под требования конкретного заказчика выполняются по отдельному техническому заданию и, при наличии общей применимости, включаются в основную версию программы.
4. Выпуск новой версии Новая версия выпускается в порядке п. 4.9. Состав изменений фиксируется в перечне изменений версии.
5. Информирование пользователей Сведения о выпущенных обновлениях и составе изменений доводятся до заказчиков, находящихся на сопровождении.

4.9. Поддержка версий и выпуск обновлений

Серверная часть

1. Изменения готовятся в отдельной ветке; выполняются сборка конфигурации разработки и автоматические тесты.
2. Для миграций базы данных оценивается риск: блокировки, длительность, необходимость переноса данных, совместимость прежней и новой версий кода.
3. Рабочая конфигурация пересобирается и перезапускается командой make build-prod; миграции применяются автоматически.
4. После установки контролируются: служебная точка доступа, журналы приложения и обработчиков задач, записи журнала задач, блокировки и длительные запросы в базе данных, глубина очередей.

Клиентская часть

1. Изменения вносятся в исходный код клиентского скрипта, выполняются статическая проверка и сборка рабочей версии.
2. Собранный файл размещается на сервере раздачи, откуда обратный прокси-сервер отдаёт его по версионированному пути.
3. Клиентский скрипт версионируется по пути размещения: /v3/init.js, /v4/init.js и далее. При изменении контракта программного интерфейса или поведения скрипта выпускается новая версия пути, а прежняя продолжает обслуживаться. Подключённые сайты переводятся на новую версию постепенно.
4. Доступность новой версии проверяется запросом curl -I, работоспособность — на тестовой странице.

Такой порядок обеспечивает установку обновлений без прерывания работы подключённых сайтов клиентов.

4.10. Документирование

• Эксплуатационная документация поддерживается в актуальном состоянии и публикуется на сайте правообладателя по адресу https://kolokol.meridianooo.ru/documentation/.
• При изменении состава функций, порядка установки или порядка эксплуатации соответствующие разделы документации обновляются в составе выпуска новой версии.
• Внутренняя техническая документация для сотрудников размещается в закрытом разделе /wui/docs/.
• Документация ведётся на русском языке.

4.11. Резервное копирование и восстановление

• Выполняется регламентное резервное копирование базы данных PostgreSQL.
• Проводится периодическая проверка восстановления из резервной копии.
• Файл конфигурации .env и ключи шифрования хранятся отдельно от резервных копий базы данных, с ограничением доступа.
• Для инсталляций в контуре заказчика процедура согласуется с политикой заказчика.

4.12. Персонал, необходимый для обеспечения поддержки

Поддержание жизненного цикла программы обеспечивают штатные сотрудники ООО «Меридиан», состоящие в трудовых отношениях с правообладателем. Все сотрудники являются гражданами Российской Федерации и осуществляют трудовую деятельность на территории Российской Федерации. Внешние подрядчики не привлекаются.

Общая численность персонала, обеспечивающего поддержание жизненного цикла программы, — 11 штатных сотрудников. Гарантийное обслуживание, техническая поддержка и модернизация программного обеспечения осуществляются силами штатных сотрудников правообладателя.

4.13. Фактическое размещение

Все процессы жизненного цикла программы выполняются на территории Российской Федерации.

Серверы, на которых развёрнута программа, размещены в центре обработки данных на территории Российской Федерации. Данные заказчиков за пределы Российской Федерации не передаются.

4.14. Обучение и квалификация персонала

• Сотрудники, участвующие в разработке и сопровождении программы, имеют профильное образование и опыт работы с применяемым технологическим стеком.
• Новые сотрудники проходят внутреннее обучение по архитектуре программы, порядку разработки, выпуска обновлений и сопровождения, с закреплением наставника.
• Поддержание квалификации обеспечивается внутренними обучающими мероприятиями и рецензированием кода.
• Обучение пользователей заказчика проводится при вводе программы в эксплуатацию и при выпуске версий, изменяющих порядок работы.

4.15. Снятие с эксплуатации

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