PrimeAI — обзор системы

PrimeAI — это набор сервисов для логистики Prime Group. Система использует OpenAI Responses API для текстового диалога, OpenAI Realtime для голосового ассистента и общую базу данных MariaDB с единым идентификатором пользователя. Идея в том, чтобы текстовый и голосовой каналы работали поверх одной и той же бизнес‑логики (Lardi, 1С, маржа) и обращались к общей истории диалога.

Архитектура на уровне сервисов

В проекте есть три основных сервиса:

Telegram‑бот (каталог telegram-bot/) обслуживает текстовый канал в Telegram Business: принимает webhook‑запросы, сопоставляет tg_id с внутренним user_id, обращается к Responses API и при необходимости вызывает MCP‑инструменты;
MCP‑сервер (каталог mcp-server/) хранит всю доменную логику: интеграцию с Lardi, работу с заявками и профилями 1С, расчёт маржи, историю диалогов. Этот сервер публикует HTTP‑эндпоинт /mcp, через который модели получают доступ к инструментам;
SIP Hook (каталог sip-hook/) отвечает за голосовой канал: принимает webhook‑события от Realtime SIP, определяет пользователя по номеру телефона, подключает голосового агента и синхронизирует историю диалога с остальными сервисами.

MCP‑сервер выступает центральной точкой доступа к бизнес‑операциям, а боты и голосовые агенты обращаются к нему как к набору инструментов.

Единый пользователь и общая база

Все три сервиса подключены к одной и той же базе MariaDB. Таблицы users, dialogue_history, cargo_requests и transporter_matches общие:

users хранит пользователя и его идентификаторы в каналах (Telegram, телефон и т. д.);
dialogue_history содержит одну общую историю диалогов для текстового и голосового каналов;
cargo_requests и transporter_matches описывают заявки и зафиксированные перевозки.

Единая сущность пользователя обеспечивается через MCP‑инструмент verify_user: сервисы вызывают его с tg_id и/или phone, чтобы получить или создать user_id. Склейка Telegram‑ID ↔ телефон гарантирована только если в verify_user когда‑то были переданы оба идентификатора (либо если Telegram‑бот перепривязал tg_id по телефону напрямую через БД — детали есть в разделе про Telegram‑бота).

Типичный сценарий работы

Клиент пишет в Telegram Business или звонит по SIP‑номеру.
Соответствующий сервис (telegram-bot или sip-hook) определяет пользователя и вызывает MCP‑инструмент verify_user, чтобы получить или создать user_id.
Дальше модель работает поверх MCP‑инструментов: ищет заявки в Lardi, создаёт новые заявки, считает маржу, фиксирует рейсы и т. д.
Все шаги диалога и операций записываются в dialogue_history и связанные таблицы, чтобы следующий контакт продолжался с учётом предыдущего контекста.

Что читать дальше

Чтобы понять, как это разворачивать и использовать, начните с раздела «Быстрый старт». Затем можно перейти к страницам, посвящённым каждому сервису: отдельные разделы описывают Telegram‑бот, MCP‑сервер и SIP Hook, их архитектуру, конфигурацию и взаимодействие с OpenAI.

Дополнительно в документации есть отдельный раздел о работе с Git‑репозиториями PrimeAI. Он пригодится, если вы только подключаетесь к проекту и хотите понять, как правильно вести ветки и коммиты для каждого сервиса.