Plumo

Временный стенд без почтового домена: render.yaml задаёт AUTH_EMAIL_VERIFICATION_REQUIRED=false. Регистрация и вход работают без Resend, адреса остаются неподтверждёнными; восстановление пароля по почте требует настройки Resend. Возврат проверки описан в docs/account-auth.md.

Plumo — ИИ-ассистент для входящих обращений бизнеса. Он отвечает по утверждённым данным компании, выясняет потребность, собирает пожелания на встречу или просмотр и передаёт менеджеру запрос с историей и резюме. Переговоры и закрытие сделки остаются человеку.

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

Приоритет с 24 октября 2026: MVP на мессенджерах — WhatsApp, Telegram и Instagram с кабинетом менеджера (раздел MVP). Телефония отложена.

Статус на 24 октября 2026: кабинет /dashboard объединяет интерфейс по референсу Pleep и backend: закрытый вход команды, «Интеграции» и «Диалоги» на данных PostgreSQL, приём Telegram и Instagram через webhook, worker с надёжной очередью и отправкой ответов. Telegram проверен вживую на тестовом боте (приём, ответы модели, передача менеджеру и обратно) на временном публичном адресе. Instagram проверен вживую частично (26.10.2026): подключение, входящее сообщение от тестового аккаунта и ответ агента; передача менеджеру, окно 24 часа и аккаунты без роли в приложении живьём не проверены. Лендинг и демо-мастер по-прежнему работают на вымышленных данных. Подробно: docs/dashboard-channels.md. Проверка объединения с новым интерфейсом: docs/dashboard-merge-verification.md.

Исходный бюджет — $1000; подтверждённого бюджета на зарплаты нет. Правила работы над проектом — AGENTS.md.

Сценарий агента настраивается в /dashboard#scenarios: цель, уточнения, первый вопрос, условия передачи и fallback. Изменения используют общую публикацию; история сохраняет правила каждой новой версии. Перед выпуском нужна миграция 021. Подробности — DB-11.

Объединение с актуальным main сохраняет привязку менеджера, статусы уведомлений, лимиты расходов, мониторинг и заявки пилота. Миграции main 013–017 не изменены; новые миграции Dashboard идут 018–021. Схемы старого локального стенда ветки Dashboard с прежними номерами миграций не являются схемой main и требуют отдельного переноса.

Что уже есть

Часть	Реализовано в коде	Ограничения
Лендинг /	Адаптивные секции продукта, макеты переписок, голосовой пример с готовым аудио, этапы подключения, статистика, тарифы и FAQ	Сценарии и показатели демонстрационные; живой звонок с сайта не выполняется
Демо /create/wizard	Автосохранение шага, полей, материалов и логотипа в аккаунте; восстановление, защита от конфликта вкладок, перенос гостевого демо; завершение сохраняет карточку бизнеса, публикует материалы в базу знаний и применяет настройки агента	Гостевой черновик и пример чата — локальные; тест аккаунта использует настоящее ядро, отдельную историю и лимиты. Сайты не читаются. Подробности
Кабинет /dashboard	Компактное меню, рабочий список диалогов по умолчанию, отдельные база знаний и настройки бизнеса/агента с общим черновиком мастера, справка по пилоту; закрытый вход; интеграции Telegram/Instagram со статусами сервера; диалоги с серверным поиском, фильтрами, пагинацией и прочтением; взять и вернуть диалог, ответ менеджера в канал со статусом доставки	Один оператор — один бизнес, ролей нет; «Тестирование» подключено к ядру; будущие разделы перечислены в справке, канбан хранит ручные стадии на сервере; WhatsApp — демо-мастер без подключения
Авторизация	Регистрация создаёт отдельный бизнес и черновик; письмо подтверждения через Resend, вход после подтверждения, сброс пароля и отзыв старых сессий; HttpOnly cookie, пароль scrypt	Для реальных писем нужны настройки Resend и домен; Google OAuth не подключён, кнопка скрыта. Настройка
Форма пилота	Заявка сохраняется на сервере (POST /api/v1/leads), посетитель получает номер; повтор не создаёт дубль; команда получает уведомление в Telegram через worker	Нужны TEAM_TELEGRAM_CHAT_ID и служебный бот; без них заявка хранится в БД, уведомления нет. Лимит 5 заявок в час с адреса (в памяти процесса)
Backend	REST API, история и резюме, база знаний, обработка сообщений, передача человеку, пожелания на встречу, метрики, API кабинета с изоляцией по бизнесу, worker	CRM и календарь не подключены
Модели	Опубликованные настройки имени, языка, тона, цели, приветствия, fallback и передачи человеку применяются в ядре; mock-режим, адаптеры OpenRouter и Anthropic, настройка совместимых HTTP-провайдеров, таймауты и резервные модели

В «Улучшениях» можно создать замечание из диалога/теста, зафиксировать опубликованное исправление и вручную проверить свежий ответ той же версии. Демо и устаревшие проверки отмечены отдельно; новые ответы сохраняют версии и отпечатки материалов. Перед выпуском требуется миграция 020. Подробности — DB-10.

Канбан доступен переключателем List/Kanban в диалогах: серверные счётчики, поиск и фильтры, перенос мышью или выбором стадии, конфликт версий и ручное подтверждение встречи без бронирования календаря. Перед выпуском нужна миграция 019. Подробности — DB-09.

Интерфейс сайта доступен на RU/EN. Код кыргызского языка предусмотрен, перевод интерфейса ещё не готов. Тарифы на лендинге — предложение для обсуждения пилота; платежи и автоматическое подключение отсутствуют.

Диалоги: восстановление неподтверждённой отправки с прежним ключом, сохранение нового черновика, переходы браузера, история клиента и обработка unknown описаны в DB-05. Живая и мобильная приёмка остаются отдельным шагом.

Тестирование показывает версию публикации, устаревшие сессии и ссылки на материалы. Панель проверок отражает технические условия; качество ответов и живую работу менеджера принимает команда отдельно. Подробнее — DB-06.

Раздел «Клиенты» содержит серверный поиск, фильтр канала, курсорные страницы, карточку с контактами, резюме и историей, переходы в диалоги. Непроверенный телефон не объединяет карточки. Контракт и ограничения — DB-07.

«Статистика» показывает показатели мессенджеров по дням Бишкека и фильтру периода: диалоги, созданные ответы, передачи и текущие состояния неуспешных/неизвестных отправок. Оценка из журнала ИИ частичная и не заменяет полный учёт бюджета. Определения — DB-08.

Структура репозитория

Путь	Назначение
frontend	Next.js App Router, TypeScript, React, Tailwind CSS и Motion
frontend/src/components/landing	Секции сайта и демонстрационные сценарии
frontend/src/features	Авторизация, демо-мастер и кабинет
frontend/src/components/charts	Локальные компоненты Bklit UI / Visx и лицензия
backend	FastAPI, ядро агента, PostgreSQL и интеграционные адаптеры
backend/src/app/domain	Сущности, порты провайдеров, правила и события
backend/src/app/application	Сервисы и сценарии обработки обращений
backend/src/app/infrastructure	Репозитории БД, модели, каналы, телефония и уведомления
backend/src/app/api	REST-маршруты и схемы запросов / ответов
backend/alembic	Миграции базы данных
backend/tests	Unit- и integration-тесты
data/demo	Каталог демонстрационных данных; backend загружает свой пример через app.seed
docs	Проектные документы: структура и поток сообщения, каналы и кабинет, ТЗ
infra	План инфраструктуры; существующие Dockerfile и Compose находятся в backend

Новые frontend-компоненты оформляются Tailwind CSS с токенами Plumo; Preflight отключён для совместимости с существующим CSS. Иконки — Hugeicons Stroke Rounded через общий компонент plumo-icon.tsx. shadcn/ui пока не подключён.

Как устроен backend

Backend — модульный монолит с одной PostgreSQL. Зависимости собираются в backend/src/app/container.py; внешние провайдеры находятся за интерфейсами из domain/ports.py.

Нормализованное сообщение / mock-событие канала
  → определение бизнеса и клиента
  → сохранение сообщения и проверка повтора
  → история, резюме и релевантные знания бизнеса
  → роутер → провайдер модели
  → проверка ответа → разрешённые действия / передача человеку
  → обновление памяти, журналы и метрики
  → ответ API для адаптера канала

ElevenLabs Agents
  → initiation webhook: начало звонка и приветствие
  → Custom LLM: реплика → общее ядро агента → ответ в SSE
  → post-call webhook: результат и метрики звонка

Telegram и Instagram приходят на /api/v1/webhooks/*. Событие и задание сохраняются до ответа провайдеру. Worker (python -m app.worker) прогоняет событие через то же ядро и отправляет ответ, заново проверяя режим диалога перед отправкой. Сервисный вход для других адаптеров — POST /api/v1/messages. API также предоставляет карточки и историю клиентов, диалоги, очередь передачи менеджеру, базу знаний, встречи и метрики. Контракт — backend/docs/openapi.json; подключение frontend и каналов — backend/FULLSTACK.md.

В БД уже описаны businesses, knowledge_items, customers, customer_channels, conversations, messages, customer_summaries, handoff_requests, meetings, interaction_logs, ai_usage_logs и voice_calls. Миграция 006 добавила операторов и сессии, подключения каналов, входящие события, очередь заданий, исходящие отправки, режим диалога и курсоры прочтения. Миграции 007–011 добавили самостоятельную регистрацию, почту аккаунта, сохранение мастера, тестовый чат и самостоятельный Telegram, 012 — уведомление менеджеру как задание очереди. Миграция 013 добавляет подтверждённого менеджера для каждого бизнеса и состояния попыток уведомления. Миграция 014 добавляет ручные стадии канбана с версией, временем и оператором изменения; стадия не меняет режим диалога. Миграция 015 добавляет замечания к ответам с исходным снимком и историей проверки. Всего миграций пятнадцать.

Очередь заданий — таблица PostgreSQL с SKIP LOCKED, lease и ограниченными повторами; Redis не нужен. Уведомление менеджеру — задание этой очереди (notify_handoff): оно создаётся в одной транзакции с передачей, отправляет его worker подтверждённому получателю своего бизнеса. Неопределённый результат требует ручного решения; общего chat_id нет. Настройка и ограничения — docs/dashboard-manager.md.

Данные и ограничения

• Факты о ценах, наличии, сроках и условиях должны приходить из утверждённых данных бизнеса. В ядре есть получение знаний и проверка ответа; надёжность этих ограничений нужно оценивать на сценариях пилота.
• Модель предлагает ограниченные действия, а сервер исполняет их. Произвольного SQL от модели нет.
• Встреча сохраняется со статусом proposed: это пожелание клиента, а не подтверждённое резервирование календаря.
• Карточки клиентов, диалоги, подключения и отправки привязаны к business_id. Маршруты кабинета берут бизнес из сессии оператора и отвечают 404 на объекты другого бизнеса. Сервисный PLUMO_API_KEY знает только сервер Next.js.
• Телефон, написанный в тексте, сохраняется как контакт для обратного звонка и не объединяет карточки. Проверка владения номером для объединения ещё не реализована. Связь WhatsApp и звонка по номеру зависит от доверенного транспорта и корректного caller ID.
• История сообщений и резюме хранятся отдельно от знаний бизнеса. Контекст модели собирается из профиля бизнеса, релевантных знаний, карточки, резюме и ограниченной истории.
• Входящие события дедуплицируются по подключению и id провайдера. Каждая отправка имеет статус queued/sending/sent/failed/unknown/cancelled. sent значит, что провайдер принял сообщение, а не что клиент его прочитал. Неоднозначный результат остаётся unknown до решения человека.
• «Взять диалог» переводит его в режим менеджера и отменяет неотправленные ответы агента. Отправка агента начинается только при совпадении версии режима. Сообщение, уже переданное провайдеру, отменить нельзя. MANAGER_PAUSE_HOURS по умолчанию 24; для стенда — 0, агент не возвращается сам.
• Уведомление менеджеру, просьба перезвонить и перевод активного звонка — разные действия. Работающий перевод активного звонка не подтверждён.
• API-ключи и персональные данные не помещаются в Git. Для конфигурации используются .env.example; требования к согласию, записи, хранению и удалению данных необходимо уточнить до работы с реальными покупателями.

Локальный запуск

Frontend и backend запускаются отдельно. Для просмотра сайта PostgreSQL и API не требуются.

Frontend

Из корня репозитория, при установленном Node.js согласно frontend/README.md:

cd frontend
npm install
npm run dev

Сайт: http://localhost:3000. Проверка TypeScript — npm run typecheck, сборка — npm run build. Кабинету нужны запущенный API и frontend/.env.local с PLUMO_API_URL и PLUMO_API_KEY (образец — frontend/.env.example). Без входа /dashboard ведёт на /login.

Backend на Windows

Нужен Python 3.12+. Команды ниже выполняются из папки backend, а не из корня репозитория:

cd backend
.\dev.cmd setup
.\dev.cmd up

setup создаёт виртуальное окружение, устанавливает зависимости и копирует .env.example в .env, если файла ещё нет. up запускает локальный PostgreSQL через scripts/local-db.ps1, применяет миграции, загружает демо-данные и запускает API. Локальный скрипт базы скачивает PostgreSQL при первом запуске.

Swagger: http://127.0.0.1:8000/docs. Проверка здоровья: http://127.0.0.1:8000/health.

Для кабинета и каналов нужны ещё два шага: оператор для входа (.\dev.cmd operator create --email ... --business "Demo Realty") и worker в отдельном окне (.\dev.cmd worker). dev.cmd up worker не запускает. Подключение бота, публичный HTTPS и Meta описаны в docs/dashboard-channels.md.

По умолчанию образец конфигурации использует AI_MODE=mock; для этого режима ключ модели не нужен. Seed создаёт вымышленный бизнес Demo Realty и примеры объектов. Интерактивный чат с backend:

.\dev.cmd demo

Backend на Linux и macOS

Нужны Python 3.12+ и Docker с Compose v2: PostgreSQL запускается сервисом db из docker-compose.yml, строка подключения та же, что в .env.example. Команды те же, что у dev.cmd:

cd backend
./dev.sh setup
./dev.sh up

Оператор и worker — ./dev.sh operator create --email ... --business "Demo Realty" и ./dev.sh worker в отдельном терминале. Тесты и линтер — ./dev.sh test, ./dev.sh lint.

Папки .venv, .tools, .pgdata и frontend/node_modules зависят от ОС: не переносите их между Windows и Linux, а пересоздайте (setup, npm ci).

Backend с Docker

Из папки backend, с установленным Docker и подготовленным .env по образцу .env.example:

docker compose up -d --build
docker compose run --rm api python -m app.seed

Compose поднимает PostgreSQL, API и worker; миграции применяются при старте API. Другие варианты запуска и подключение БД описаны в backend/FULLSTACK.md.

Для внешних интеграций нужны собственные ключи и настройки в локальном окружении. При заданном PLUMO_API_KEY основной API требует X-API-Key; у ElevenLabs отдельная авторизация. Инструкции: backend/INTEGRATION.md и backend/VOICE.md. Актуальные API, модели, тарифы и доступность номеров нужно проверить перед подключением; сведения в проектных документах не являются гарантией доступности провайдера.

Проверки

Сквозной сценарий пилота и что проверяет CI — docs/pilot-path.md. Запуск стенда, секреты, миграции, выпуск и откат — docs/operations.md. Полный список команд с ожидаемым результатом, проверка миграций на пустой БД и различие mock и live режима: docs/dev-checks.md.

Frontend, из frontend; для прямого запуска тестов с импортом TypeScript нужен Node.js 22.18+ согласно frontend-документации:

npm run typecheck
npm run build
npm test

Backend, из backend после setup:

.\.venv\Scripts\python.exe -m pytest tests/unit
.\dev.cmd test
.\dev.cmd lint

Unit-тесты не требуют БД. Полный набор требует PostgreSQL; integration-тесты используют отдельную тестовую БД и пересоздают таблицы. Не направляйте их на БД с рабочими данными.

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

Приёмочный набор через всё ядро (82 реплики, отчёт по языкам) — ACCEPTANCE.md. Живые проверки моделей и голоса, сравнение сценариев и импорт знаний описаны в backend-документации: BENCH.md, многошаговые диалоги через всё ядро — DIALOG_EVAL.md, MODELS.md, VOICE.md. Такие проверки могут расходовать средства внешних сервисов. Для голоса оцениваем задержку, перебивания и точность телефонов, адресов, сумм и дат; кыргызский проверяем с носителем.

MVP

Решение от 24 октября 2026: первая версия — мессенджеры. Клиент пишет в WhatsApp, Telegram или Instagram Direct → агент отвечает по данным бизнеса → при необходимости передаёт диалог → менеджер получает уведомление в Telegram, забирает диалог в кабинете, отвечает в тот же канал и возвращает агенту.

MVP готов, когда:

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

Порядок работ:

1. Надёжность ядра. Сделано: уведомление менеджеру — задание в очереди, создаётся в одной транзакции с передачей (25.10.2026, миграция 012; отправляет worker, без него уведомлений нет), worker в docker-compose.yml. Сделано 03.11.2026: worker фиксирует сообщение клиента до вызова модели, основной ответ модели идёт без открытой транзакции; прерванный ход заканчивает повтор задания. Резюме и извлечение данных после ответа ещё идут внутри транзакции записи результата.
2. Постоянный стенд. VPS, домен, HTTPS, резервное копирование, мониторинг worker. Telegram переносится с временного туннеля.
3. Meta. Сразу завести Meta app и верификацию бизнеса: она нужна и Instagram, и WhatsApp и занимает дни. Не откладывать до конца разработки.
4. Instagram. Живая проверка входящего Direct и ответа (ТЗ §7.4).
5. WhatsApp Cloud API. Webhook с проверкой подписи, телефон как ключ клиента, окно ответа и шаблоны вне окна, подключение из мастера кабинета. Условия, цены для KG и способ подключения номера сверить с официальной документацией Meta перед реализацией.
6. Пилот. Выбрать бизнес, канал и сценарий; проверить кыргызский с носителем; согласовать хранение и удаление данных; двухнедельный пилот.

Метрики пилота: обращения, корректно обработанные запросы, заявки, подтверждённые встречи и передачи человеку; для команды — стоимость диалога, задержки, ошибки ключевых сущностей и интеграций, результаты отдельно по языкам. До запуска нужно определить знаменатель «самостоятельно обработанного обращения»; корректная передача человеку учитывается отдельно.

Не входит в MVP: телефония, роли операторов, платежи, холодный автообзвон, календарь и CRM, объединение карточек между каналами, самостоятельное подключение каналов, кроме Telegram по токену, автоматическое расширение пилота на все каналы. Самостоятельная регистрация, подтверждение почты и сохранение шагов настройки реализованы для проверки MVP. Встречи остаются пожеланием клиента до подтверждения менеджером. Кабинет — рабочий стенд для команды и пилота, а не готовый сервис управления бизнесом.

Отложенная телефонная гипотеза — переадресация звонка в Plumo при неответе менеджера — описана в backend/VOICE.md. Код голоса сохраняется; возвращаемся к нему отдельным решением.

Сбой соединения Vercel с backend при авторизации сопровождается безопасной категорией reason и correlation_id для Runtime Logs; диагностика описана в docs/account-auth.md.

Тест агента в аккаунте и кабинете → «Тестирование» подключён к ядру, опубликованным знаниям и настроенному провайдеру. История и симуляция действий отделены от клиентов; действует общий бюджет бизнеса. Миграция 010 и настройка: docs/agent-test-chat.md.

Самостоятельный Telegram: клиент вводит токен в кабинете, секрет хранится зашифрованно, контрольная доставка проверяется перед включением агента. Очередь обрабатывает отдельный процесс worker (запуск стенда). В «Диалогах» показана готовность бизнеса, материалов, теста и канала. Нужна миграция 011. Инструкция.

ТЗ на Telegram и Instagram с критериями приёмки: docs/dashboard-channel-integration-spec.md.

Текущий рабочий план — стенд оценки диалогов, доработка Telegram и выбор моделей: docs/plan-telegram-core.md.