Функциональные характеристики.

1. Аббревиатуры, сокращения и термины

1. Назначение документа

Данный документ ориентирован на технических специалистов и архитекторов Заказчика. В документе описывается техническая архитектура программного обеспечения «Умный Век. Платформа Управления».

1. Описание архитектуры ПО «Умный Век. Платформа Управления»

ПО «Умный Век. Платформа Управления» представляет собой клиент-серверное веб-приложение для управления сделками, финансовыми показателями, мотивацией сотрудников, данными ЕСУ, аналитическими представлениями и интеграцией с Bitrix24.

Типовой вариант поставки системы разворачивается как набор Docker-контейнеров и включает:

1. клиентский web-контур;
2. сервер приложений backend;
3. операционную БД PostgreSQL;
4. служебные скрипты загрузки, синхронизации и сопровождения данных.

1. Сетевая архитектура

На схеме ниже представлена общая схема расположения и взаимодействия компонентов ПО «Умный Век. Платформа Управления». Детальное описание каждого компонента приведено в последующих секциях документа.

1. Сетевая архитектура ПО «Умный Век. Платформа Управления»

В конфигурации docker compose используются следующие сетевые точки:

1. внешний доступ пользователей к web-интерфейсу через порт 3000;
2. внутренний доступ frontend к backend по HTTP на порт 8000;
3. доступ backend к PostgreSQL по порту 5432.

Во frontend-контейнере Nginx принимает пользовательские HTTP-запросы и проксирует маршруты /api и /auth на backend. Backend выполняет прикладную логику, взаимодействует с PostgreSQL и внешними API Bitrix24. Входящие уведомления от Bitrix24 поступают в backend по webhook-эндпоинтам.

1. Сетевые экраны

Сетевые экраны и правила межсетевого взаимодействия находятся в зоне ответственности Заказчика. Предполагается, что для работы системы будут открыты необходимые сетевые направления между frontend, backend, БД и внешними интеграциями. Точные IP-адреса, DNS-имена и итоговые номера портов для промышленного окружения могут отличаться от локальной конфигурации и уточняются при внедрении.

1. Верхнеуровневое описание компонентов
2. Компоненты контура поставки и сопровождения

В отличие от систем с отдельным контуром Design Time, ПО «УМНЫЙ ВЕК. ПЛАТФОРМА УПРАВЛЕНИЯ» не содержит специализированной среды проектирования. Функции поставки, первичной настройки, загрузки и сопровождения выполняются средствами контейнерной поставки, SQL-скриптами и служебными сценариями.

1. Пакет поставки и конфигурация развертывания

Пакет поставки включает исходные коды frontend и backend, файл docker-compose.yml, Dockerfile для сборки контейнеров, конфигурационные файлы frontend и backend, а также документацию по установке и эксплуатации.
Файл docker-compose.yml описывает многоконтейнерную поставку системы и определяет следующие сервисы:

1. Frontend – контейнер клиентского web-приложения;
2. backend-new – контейнер серверной части;
3. postgres – контейнер операционной БД.

Указанный пакет используется для развертывания экземпляра ПО «Умный Век. Платформа Управления» на инфраструктуре Заказчика или в среде экспертной проверки.

1. Служебные скрипты загрузки и синхронизации данных

В составе backend предусмотрен набор Python-скриптов, предназначенных для служебных операций:

1. первичная загрузка справочников, пользователей, сделок, KPI, мотивации и иных данных;
2. синхронизация данных с Bitrix24;
3. загрузка данных из внешних источников, включая Bubble API и JSON-файлы;
4. пакетный запуск последовательности загрузок в корректном порядке.

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

1. Скрипты инициализации структуры базы данных

Для развертывания структуры операционной БД используются SQL-скрипты из каталога backend/database. Главный сценарий init.sql последовательно подключает SQL-скрипты создания таблиц, индексов и начальных справочных данных.
Указанные сценарии обеспечивают формирование прикладной схемы PostgreSQL, необходимой для запуска и эксплуатации системы.

1. Клиентское веб-приложение

Клиентская часть ПО «Умный Век. Платформа Управления» реализована как web-приложение на Next.js и React. Доступ к системе осуществляется через браузер. Пользовательский интерфейс обеспечивает работу с разделами:

1. авторизация;
2. сделки и карточки проектов;
3. мотивация;
4. аналитика;
5. светофор;
6. ЕСУ.

Клиентская часть обеспечивает отображение данных, маршрутизацию между разделами, хранение токена доступа пользователя и отправку запросов к backend REST API.

1. Frontend-шлюз

Во frontend-контейнере используется Nginx. Данный компонент выполняет роль reverse proxy и web-шлюза:

1. принимает внешний HTTP-трафик от пользовательского браузера;
2. перенаправляет маршруты /api и /auth на backend;
3. передает остальные запросы в приложение Next.js для формирования пользовательского интерфейса.

Дополнительно в приложении реализован fallback-механизм proxy-маршрута /api/proxy/*, используемый в сценариях, где внешний Nginx не задействован.

1. Сервер приложений backend

Сервер приложений ПО «Умный Век. Платформа Управления» представляет собой FastAPI-приложение на Python 3.11. Backend является центральным компонентом Runtime и выполняет следующие функции:

1. обработка REST-запросов frontend;
2. аутентификация пользователей и проверка прав доступа;
3. CRUD-операции по прикладным сущностям;
4. расчеты по мотивации, аналитике, светофору и ЕСУ;
5. работа с данными сделок, финансов, пополнений и связанных сущностей;
6. интеграция с Bitrix24 по HTTP API;
7. прием и обработка webhook-событий Bitrix24;
8. публикация health-check и OpenAPI-документации;
9. запуск планового ежедневного сбора активности Bitrix24 при наличии конфигурации webhook.

Backend организован по логическим слоям presentation, domain, infrastructure, core и config. Доступ к данным выполняется через SQLAlchemy и асинхронные подключения к PostgreSQL.
Backend может быть развернут в контейнере Docker, а также локально в среде Python 3.11+. При контейнерной поставке требования к хостовой операционной системе определяются поддержкой Docker и Docker Compose.

1. Операционная база данных

Операционная БД ПО «Умный Век. Платформа Управления» представляет собой реляционную базу данных PostgreSQL. При контейнерном развертывании используется образ postgres:17.
В логическом отношении БД включает следующие области данных:

1. справочники: роли, отделы, должности, статусы, вероятности, продукты и иные нормативные сущности;
2. пользователи и оргструктура;
3. сделки, финансовые записи, поступления и связанные данные;
4. KPI и мотивация;
5. данные светофора;
6. данные ЕСУ и воронок подразделений;
7. кэш и зеркальные данные проектов Bitrix24;
8. журналируемые и агрегируемые данные активности продаж, поступающие из Bitrix24.

1. Внешние интеграции

В Runtime-контуре ПО «Умный Век. Платформа Управления» используется интеграция со следующими внешними системами:

1. Bitrix24 REST API – для получения и синхронизации данных по сделкам, пользователям и активности;
2. исходящие webhook-события Bitrix24 – для оперативного обновления данных внутри системы;
3. внешние источники данных служебной загрузки, включая Bubble API и JSON-файлы.

Интеграционный код реализован в backend и вызывается из прикладных сервисов либо из служебных CLI-сценариев.

1. Отказоустойчивость и масштабирование
2. База данных

Контейнерное развертывание ПО «Умный Век. Платформа Управления» использует один экземпляр PostgreSQL. Для промышленной эксплуатации отказоустойчивость БД должна обеспечиваться стандартными средствами PostgreSQL и инфраструктуры Заказчика, включая:

1. резервное копирование;
2. репликацию или standby-узлы при необходимости;
3. мониторинг состояния и доступности;
4. процедуры восстановления после сбоев.

Горизонтальное масштабирование БД для данного класса систем, как правило, не требуется.

1. Сервер приложений backend

Backend не хранит прикладное пользовательское состояние между HTTP-запросами, так как авторизация реализована через JWT, а основные данные размещаются в PostgreSQL. По этой причине backend может масштабироваться горизонтально путем запуска нескольких экземпляров за внешним балансировщиком нагрузки.
При эксплуатации нескольких экземпляров backend необходимо учитывать наличие встроенного планировщика периодического сбора активности Bitrix24. Во избежание дублирующего запуска задания рекомендуется:

1. оставлять планировщик активным только на одном экземпляре backend;
2. либо выносить плановые задания в отдельный контур worker/cron.

1. Frontend-контур

Frontend-контур является stateless-компонентом и при необходимости может быть масштабирован горизонтально. Привязка пользовательской сессии к конкретному экземпляру frontend не требуется.

1. Плановые задания и интеграции

Интеграции с внешними системами зависят от доступности Bitrix24 и иных внешних источников данных. При недоступности внешних систем:

1. продолжается работа с уже сохраненными в PostgreSQL данными;
2. становятся недоступны операции оперативной загрузки и синхронизации внешних данных;
3. входящие webhook-события не могут быть обработаны до восстановления связи.

Для устойчивой эксплуатации рекомендуется мониторинг доступности backend, PostgreSQL и Bitrix24, а также журналов выполнения плановых заданий.

1. Программные интерфейсы

1. Пользовательский веб-интерфейс

Пользовательский интерфейс предоставляется через web-браузер. В локальной конфигурации доступ к ПО «Умный Век. Платформа Управления» осуществляется по адресу:
http://localhost:3000
В промышленном окружении адрес публикации определяется инфраструктурой Заказчика.

1. REST API прикладных модулей

Backend публикует REST API. Базовый префикс прикладных маршрутов – /api.
В составе API реализованы следующие основные функциональные группы:

1. /api/auth – аутентификация, обновление токена, смена пароля;
2. /api/users и /api/user – пользователи, профиль и связанные данные;
3. /api/deals – сделки, карточка сделки, финансовые и связанные операции;
4. /api/motivation – мотивация, KPI, отделы, должности и связанные расчеты;
5. /api/analytics – аналитические представления;
6. /api/traffic-light – показатели светофора;
7. /api/funnel – ЕСУ и воронки подразделений;
8. /api/bitrix – операции, связанные с данными Bitrix24;
9. корневые справочные маршруты под /api, например /api/deal-probabilities, /api/deal-statuses, /api/products, /api/customer-spheres, /api/gc-types.

OpenAPI-документация backend публикуется автоматически по адресу: 

• http://<backend-host>:8000/docs.

Дополнительно публикуется служебный endpoint проверки работоспособности:

• GET /health.

1. Webhook-интерфейсы Bitrix24

Для приема событий от Bitrix24 backend поддерживает следующие HTTP-endpoint:

1. POST /api/bitrix/webhooks/deal-add;
2. POST /api/bitrix/webhooks/deal-update.

Указанные endpoint поддерживают прием данных в форматах application/x-www-form-urlencoded и application/json.

1. Служебные CLI-интерфейсы

Для первичной загрузки, миграции и синхронизации данных используются CLI-сценарии из каталога backend/scripts/load. Они обеспечивают:

1. загрузку справочников;
2. загрузку пользователей;
3. загрузку сделок и финансовых данных;
4. загрузку KPI, мотивации и светофора;
5. синхронизацию данных Bitrix24;
6. последовательную комплексную загрузку набора данных.

1. Технологический стек
2. Клиентская часть

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

1. Хранение данных

1. Безопасность

1. Контейнеризация и инфраструктурные компоненты

1. Внешние интеграции