ZenAi: полная реализация MVP-бэкенда ИИ-менеджера за одну сессию

Date: 2026-02-27 Project: ZenAi — ИИ-менеджер для Telegram Duration context: длинная сессия (полный цикл от проектирования до 51 теста)

Что было сделано

• Спроектирована полная архитектура ИИ-менеджера для продаж пептидов через личные Telegram-аккаунты (Telethon).
• Создан CLAUDE.md и модульная система правил в .claude/rules/ (documentation, database, api, fsm, deploy).
• Написаны 14 SQLAlchemy-моделей (admin_users, tg_accounts, contacts, conversations, messages, fsm_sessions, lead_forms, kb_documents, kb_chunks, crm_sync_events, system_alerts, audit_logs, bot_settings и base mixins).
• Реализован FSM-движок диалога (9 состояний от INIT до DONE, 8 событий, библиотека transitions) в src/fsm/.
• Построен RAG-pipeline: chunker на tiktoken, embedder через OpenRouter, retriever на pgvector cosine distance — src/rag/.
• Написан Telegram gateway: Telethon client wrapper, пул мультиаккаунтов с ротацией и суточными лимитами, обработчики входящих сообщений — src/telegram/.
• Реализован amoCRM-коннектор: OAuth2-клиент, upsert contact/lead, sync service с retry и backoff — src/crm/.
• Собран сервисный слой: DialogService (оркестрация lock -> FSM -> RAG -> LLM -> transition -> save), AccountSelector (least-used стратегия, Redis лимиты, алерты 80%/100%), EncryptionService, AlertService, AuditService.
• Создан FastAPI-бэкенд: app factory, 9 роутеров (auth, tg_accounts, conversations, internal, kb, crm, alerts, audit, ops), health endpoint.
• Настроен ARQ-воркер с задачами reindex_document и sync_to_crm.
• Подготовлена инфраструктура: pyproject.toml (uv), Dockerfile, docker-compose.yml, docker-compose.prod.yml, .env.example, Alembic setup.
• Написаны 51 unit-тест: FSM engine (19), FSM validators (7), encryption (6), chunker (8), health API (1) — все проходят без БД и Redis.
• Пройдены этапы 0-5 плана из 7, этап 7 (тестирование) в процессе.

Проблемы и решения

Проблема: хранение API-ключей

Симптомы: изначально OPENROUTER_API_KEY был в .env, что не подходит для мультиинстансного деплоя — каждый клиент имеет свой ключ.

Решение: создана таблица bot_settings с шифрованием через EncryptionService (Fernet, ключ ENCRYPTION_KEY). API-ключи хранятся в БД, маскируются в UI. Обновлена tech-spec и deployment-guide.

Проблема: архитектура FSM vs LangGraph

Симптомы: стоял вопрос — использовать LangGraph для гибкости или детерминированный FSM для предсказуемости.

Решение: выбран FSM на библиотеке transitions. Причина: воронка продаж строго линейная (9 шагов), LangGraph добавил бы оверхед без пользы. FSM даёт аудируемые переходы, простую отладку и предсказуемое поведение. LLM используется только для генерации ответов внутри состояний, а не для принятия решений о переходах.

Проблема: мультиаккаунтность Telethon

Симптомы: нужно ротировать несколько личных Telegram-аккаунтов с суточными лимитами инициаций (15/день на аккаунт).

Решение: AccountSelector выбирает аккаунт по стратегии least-used, лимиты хранятся в Redis с TTL, при достижении 80% и 100% создаются системные алерты. Если все аккаунты исчерпаны — критический алерт в админку.

Ключевые решения

1. FSM вместо LangGraph — детерминированные переходы для предсказуемой воронки продаж. LLM генерирует текст, но не управляет логикой.
2. pgvector вместо отдельной векторной БД — всё в PostgreSQL, без Pinecone/Weaviate. Меньше сервисов, проще деплой, достаточно для 40 диалогов/день.
3. Секреты в БД, не в .env — bot_settings с шифрованием позволяет мультиинстансный деплой: каждый клиент со своими ключами на одном сервере.
4. ARQ вместо Celery — легковесные фоновые задачи на Redis, без RabbitMQ. Идеально для масштаба MVP.
5. uv вместо pip/poetry — быстрая установка зависимостей, lockfile для воспроизводимости.

Источники и ссылки

Из сессии

• Telethon docs — документация Telethon для работы с Telegram API
• transitions library — FSM-библиотека для Python
• pgvector — расширение PostgreSQL для векторного поиска
• OpenRouter — провайдер LLM API (embeddings и генерация)
• amoCRM API — REST API для CRM-интеграции

Дополнительный контекст

• Building a FastAPI-Powered RAG Backend with PostgreSQL & pgvector — архитектура RAG-бэкенда, аналогичная реализованной в ZenAi
• Building Production-Ready RAG in FastAPI with Vector Databases — рекомендации по продакшн-хардингу: HNSW-индексы, observability, JWT-авторизация
• danny-avila/rag_api (GitHub) — reference-реализация RAG API на FastAPI + pgvector с batched embedding processing
• Garnet — FSM for Telethon — альтернативный подход к FSM для Telethon-ботов (в ZenAi использован свой движок)
• Telegram-Panel — multi-account operations — open-source система управления мультиаккаунтами Telethon

Что дальше

• Деплой на сервер (Ubuntu 24.04, Docker Compose).
• Генерация и применение первой Alembic-миграции.
• Подключение реальных Telegram-аккаунтов и amoCRM credentials.
• Интеграционные тесты с PostgreSQL + pgvector + Redis.
• E2E тесты полного цикла: initiate -> FSM -> handoff -> CRM push.
• Этап 6: React Admin (операционный центр управления).