Concierge

Назначение

Внешний AI-портал поддержки Unishift для партнёров и интеграторов. Отдельные аккаунты (cs_users), отдельный UI (:4201 в dev), чат с агентами AI Router, эскалации к модераторам платформы, автоформатеры номеров заявок, интеграционный блок через Flow Manager, авто-создание чатов/партнёров и подсистема фильтров чатов с разделением прав кураторов.

Модераторская админка живёт в основном клиенте (:4200) и ходит в concierge через Gateway. Внешние пользователи ходят в сервис напрямую (CORS + concierge-JWT).

Порты

• HTTP: 8106 (хост в Docker: 18106)
• БД: concierge_db
• UI (dev): web/apps/concierge на порту 4201

Ключевые возможности

• Passwordless-логин внешних пользователей: request-login шлёт одноразовый пароль через Notifications, login выдаёт concierge-JWT (HS256, тот же JWT_SECRET)
• Чаты и ветки: мульти-партнёрские чаты (cs_chat_members), ветки-threads, зеркалирование сообщений в cs_messages
• Прокси в AI Router: provisioning чата (CreateChat) и SendMessage с agent_id
• Автоформатеры заявок (cs_formatters): регулярные выражения для автоматического преобразования номеров заявок (например #INC-1024, #TASK-8821) в кликабельные ссылки. Аудитория partner / staff / both — кто видит ссылки: партнёры во внешнем портале, пользователи системы в админке или оба.
• Интеграция с Flow Manager (Внешние нотификации и форвардинг):
  • Входящие: прием вебхуков внешних систем (банки, CRM, алерты) через inputHttpRequestNode / serviceNode во Flow Manager и сохранение в Concierge через POST /api/v1/external/notifications (sender_type = "external" / "system").
  • Обратный форвардинг: при ответе пользователя или модератора на внешнее сообщение создаётся NATS-событие unishift.concierge.message_replied, которое обрабатывается в пайплайне Flow Manager (inputEventNode) для отправки ответа во внешнюю систему.
• Provisioning API: POST /api/v1/external/provision-chat для автоматического создания партнёра и чата со стартовым сообщением прямо из API или сценариев Flow Manager
• Embed-режим (iframe & postMessage):
  • Встраивание внешнего портала через <iframe> (?embed=true, ?token=..., ?chat_id=..., ?theme=dark|light)
  • CSP заголовок Content-Security-Policy: frame-ancestors ...
  • Поддержка postMessage для обмена событиями (CONCIERGE_EVENT, new_message, chat_loaded) и управления (CONCIERGE_SET_TOKEN, CONCIERGE_OPEN_CHAT)
• Фильтры/группы чатов и разграничение доступа (cs_chat_filters, cs_user_filters):
  • Настройки → Чаты (/concierge/settings/chats): создание/удаление чатов, сниппеты, ассистент, партнёры; кто видит чат через фильтры
  • Настройки → Фильтры (/concierge/settings/filters): группы с сотрудниками и чатами; создание и правка — /concierge/filters/new и /concierge/filters/:id
  • Куратор без назначенного фильтра не видит чаты (deny by default)
  • Администратор и пользователь с правом редактирования Concierge видят все чаты
• Массовые уведомления (cs_broadcasts):
  • Рассылка одного уведомления сразу в группу чатов с акцентным оформлением (is_notification = true, цветная плашка, левый акцентный бордюр, бейдж)
  • Поддержка ссылок в тексте, прикрепления изображений и файлов (concierge-media)
  • Веб-раздел в настройках Concierge (/concierge/settings/notifications) с фильтрацией чатов, прикреплением файлов и живым предпросмотром
  • Метод в Starlark для Flow Manager: up.concierge.send_notification(...) / broadcast(...) с выборкой чатов по названиям или маске
• Эскалации: кнопка «вызвать модератора» → cs_escalations(pending) → ответ модератора закрывает эскалацию
• Сниппеты: глобальные и per-chat, видны во внешнем UI
• Брендинг: заголовок, логотипы, плейсхолдер композера
• Rate limiting: логин 5/мин, сообщения 20/час (cs_rate_limits)
• Real-time: прямая публикация событий в Centrifugo HTTP API

Аутентификация

Клиент	Токен	Куда ходит
Внешний пользователь	concierge-JWT (POST /auth/login)	concierge :8106 напрямую
Внешние сервисы / Flow Manager	Service-Token (X-Service-Token) или StaffAuth	concierge :8106 (/external/*)
Модератор из основного UI	platform JWT (admin / секции concierge)	Gateway → concierge
Локальный модератор concierge	concierge-JWT с ролью moderator	concierge :8106

Real-time и NATS события

Centrifugo WebSocket

Namespace concierge. Токен: GET /api/v1/auth/socket-token.

Канал	Кто подписан	События
concierge:user:{userID}	внешний пользователь	ai_response, moderator_message, user_message, escalation_answered, chat_status, typing
concierge:admin	модераторы	user_message, escalation_created, chat_status, typing

NATS Event Bus (Flow Manager Forwarding)

Subject	Описание	Payload
unishift.concierge.message_replied	Ответ пользователя/модератора на внешнее сообщение	{ "chat_id": "...", "message_id": "...", "reply_to_id": "...", "external_source": "bank_tinkoff", "external_id": "evt_123", "reply_content": "...", "sender_type": "user" }

Структура БД

Таблица	Назначение
cs_users	Внешние аккаунты и модераторы concierge
cs_chats	Чат партнёров; title; user_id — первый партнёр; ссылки на ai-router chat/provider и агента
cs_chat_members	Состав чата (партнёр может быть в нескольких чатах)
cs_partners	Карточка пользователя: email, ФИО, компания, телефон, примечание
cs_threads	Ветки внутри чата (parent_id — вложенность)
cs_messages	Сообщения (external_source, external_id, external_metadata)
cs_agents	Зеркало агентов AI Router (ai_router_agent_id, slug, is_default)
cs_formatters	Правила автоформатирования ссылок на заявки (pattern, link_template, is_enabled, audience: partner / staff / both)
cs_chat_filters	Группы/фильтры чатов (title, description, criteria)
cs_user_filters	Назначенные кураторам фильтры ограничения доступа (user_id, filter_id)
cs_escalations	Эскалации pending / закрытые
cs_snippets	Глобальные и chat-scoped сниппеты
cs_chat_snippets	Назначение глобальных сниппетов чату
cs_branding	Singleton внешнего UI
cs_rate_limits	Бакеты лимитов (identifier, action, window_start)

API

Базовый путь — /api/v1. Swagger: http://localhost:8106/swagger/index.html.

Публично

Метод	Путь	Описание
POST	/auth/request-login	Отправить одноразовый пароль на email
POST	/auth/login	Обменять пароль на concierge-JWT
GET	/branding	Публичный брендинг логина

Пользователь (concierge-JWT)

Метод	Путь	Описание
GET	/auth/me	Текущий пользователь
GET	/auth/socket-token	JWT для Centrifugo
GET	/chats	Список чатов пользователя
GET	/chat	Транскрипт; ?chat_id= выбирает чат
POST	/chat/messages	Отправить сообщение (chat_id в теле)
GET	/chat/messages	История (chat_id, thread_id)
POST	/chat/typing	Индикатор набора (chat_id)
POST · GET	/chat/threads	Ветки (chat_id)
POST	/chat/escalate	Эскалация к модератору (chat_id)
GET	/snippets	Сниппеты, видимые в чате
GET	/formatters	Активные правила для партнёров (audience = partner или both)

Интеграции & Flow Manager (ServiceTokenAuth / StaffAuth)

Метод	Путь	Описание
POST	/external/notifications	Создать внешнее сообщение/нотификацию в чате
POST	/external/broadcast	Массовая рассылка уведомлений по chat_ids, chat_names или паттерну
GET	/external/chats	Список всех чатов для интеграций
POST	/external/provision-chat	Авто-создать пользователя, партнера и чат с начальным сообщением

Модератор (/admin, StaffAuth)

Метод	Путь	Описание
GET · POST	/admin/chats · /admin/chats/:id	Список (с учётом кураторских фильтров), создание, карточка
POST · DELETE	/admin/chats/:id/partners	Добавить / убрать партнёра в чате
POST	/admin/chats/:id/messages	Сообщение модератора
PUT	/admin/chats/:id/title · /agent · /snippet · /status · /escalation	Управление чатом
GET · PUT	/admin/escalations	Очередь эскалаций
GET · POST · PUT · DELETE	/admin/snippets	Глобальные сниппеты
GET · POST · PUT · DELETE	/admin/formatters	Управление автоформатерами
GET · POST · PUT · DELETE	/admin/filters · /admin/filters/:id	Управление фильтрами/группами чатов
GET · PUT	/admin/filters/:id/users	Сотрудники платформы, назначенные на фильтр
GET · PUT	/admin/users/:id/filters	Получить / назначить фильтры пользователю
POST	/admin/partners/provision	Provisioning партнёра и чата из админки
GET · PUT	/admin/branding	Брендинг
POST	/admin/invite	Пригласить партнёра
GET · POST	/admin/partners	Список и создание карточек партнёров (chats — все чаты, где партнёр участник)
PUT	/admin/partners/:id	Обновить контакты партнёра
GET	/admin/users	Список пользователей
PUT	/admin/users/:id/status	active / banned
GET	/admin/agents	Агенты
PUT	/admin/agents/:id/default	Агент по умолчанию
POST	/admin/broadcast	Массовая отправка уведомлений по выбранным чатам
GET	/admin/broadcasts	История массовых рассылок

Интеграции

Сервис	Зачем
Flow Manager	Входящие нотификации в Concierge (/external/notifications) и обработка форвардинга ответов (unishift.concierge.message_replied)
AI Router	Чаты и агенты; RAG-scope concierge (CONCIERGE_RAG_SCOPE)
Notifications	Письма с одноразовым паролем / инвайтом
Gateway	Прокси админки из основного UI (CONCIERGE_SERVICE_URL)
Auth	Секция concierge_chats (concierge_settings держится равным ей). Чаты — view/edit; Настройки (/concierge/settings, редактор фильтров) только при edit
Centrifugo	Каналы concierge:*, origin внешнего UI (:4201) в allowed_origins

Конфигурация

Переменная	По умолчанию	Описание
PORT	8106	HTTP
DB_NAME	concierge_db	БД
JWT_SECRET	— (обяз.)	Подпись concierge-JWT и проверка platform-JWT
SERVICE_TOKEN	— (обяз.)	Вызовы AI Router, Notifications и вызовы от Flow Manager
MESSAGING_URL	nats://localhost:4222	URL NATS для публикации событий форвардинга ответов
AI_ROUTER_SERVICE_URL	http://localhost:8101	AI Router
NOTIFICATIONS_SERVICE_URL	http://localhost:8103	Notifications
CONCIERGE_WEB_URL	http://localhost:4201	Внешний UI (ссылки в письмах)
CONCIERGE_CORS_ORIGINS	http://localhost:4201	CORS и CSP frame-ancestors, через запятую
CONCIERGE_EMAIL_FROM	concierge@unishift.ru	From в письмах
AI_ROUTER_PROVIDER_ID	—	Провайдер для provisioning чата
CONCIERGE_RAG_SCOPE	concierge	RAG-scope базы знаний портала
RATE_LIMIT_LOGIN	5	Логинов в минуту
RATE_LIMIT_CHAT_MESSAGES	20	Сообщений в час
CENTRIFUGO_URL	http://localhost:8100	HTTP API Centrifugo
CENTRIFUGO_API_KEY	—	Ключ HTTP API
CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY	JWT_SECRET	Подпись connection-токена
CENTRIFUGO_WS_URL	ws://localhost:8100/connection/websocket	URL для браузера внешнего UI