Шаблон ТЗ для разработки ИИ-ассисента на базе действующего проекта

Привет, Антон Миславский - разработчик ИИ-ассисентов. Ниже приведу ТЗ для разрабоки ИИ-асссистента для бизнеса на основе моего действующего проекта для агентства недвижимости, агентства по релокации, открытию банковских счетов и виз

ТЗ: Разработка ИИ-ассистента для обработки лидов (WhatsApp + amoCRM / Kommo)

1) Цели и KPI

Цель: автоматизировать первичный контакт и квалификацию лидов, разгрузить менеджеров, ускорить «speed-to-lead».

KPI (измеримые):

T1. Время первого ответа : ≤ 60 сек (24/7).
T2. Доля квалифицированных лидов (Q-rate): +30–50%.
T3. Доля лидов с назначенной встречей: +15%.
T4. Снижение ручных ответов на нецелевые запросы: –70%.
T5. Полнота заполнения карточки в CRM: >95% обязательных полей.

2) Каналы и охват

Входящий канал: WhatsApp (Wazzup вебхуки).
Исходящие сообщения: WhatsApp (Wazzup Send API).
CRM: amoCRM/Kommo (REST API v4).
Языки: RU/EN/HE/FR/GE/ES/IT, автоопределение по входящему сообщению.

3) Воронка и логика

Воронки:

BANK_ACCOUNT_UAE_OPENING - открытие банковский счетов
REAL_ESTATE_RENT_BUY - покупка недвижимости
GENERIC_FAQ - общие вопросы
SPAM/TEST - СПАМ лид
COMPETITOR - конкурент

Квалификация (пример для «счёт в Дубае»):

Резидентство, тип юрлица (FZ/LLC), обороты, источник средств, KYC документы, сроки

Роутинг:

qualified=true → передать в CRM ответственному + забронировать слот (если календарь подключён).
qualified=false/risky → отказ/альтернативы/база знаний.

Правила первого касания:

Менеджер должен ответить ≤15 мин (рабочее), ≤60 мин (нерабочее). ИИ — пинг/эскалация.

4) Архитектура (высокоуровнево)

Fast API для ассинхронности(/webhook ловит Wazzup вход).
OpenAI Assistants v2: один ассистент на сценарий, thread на диалог.
Redis Upstash: хранение состояния чата, дедупликация, throttle, блокировки.
amoCRM/Kommo: создание/обновление лидов/контактов/задач, заполнение кастомных полей.
Wazzup/GreenAPI: отправка сообщений, медиавложения, статусы доставок.
Логи: структурные (JSON), уровень INFO/DEBUG/ERROR, correlation-id на диалог.

5) Технологии и версии

Python 3.11+, FastAPI, requests/httpx, redis, pydantic (валидация), uvicorn (опц.).
openai новая (Assistants v2). Используем:
import openai и from openai import OpenAI (нужно для openai.NotFoundError).
БД не требуется (на первом этапе) — состояние в Redis.

6) Переменные окружения (.env)

# Flask
FLASK_ENV=production
SECRET_KEY=<<<random>>>

# Wazzup
W_API_TOKEN=<<<token>>>
W_CHANNEL_ID=<<<id>>>
W_WEBHOOK_VERIFY_TOKEN=<<<string>>>

# amoCRM
AMO_SUBDOMAIN=<<<subdomain>>>
AMO_CLIENT_ID=<<<id>>>
AMO_CLIENT_SECRET=<<<secret>>>
AMO_REDIRECT_URI=<<<redirect>>>
AMO_ACCESS_TOKEN=<<<token>>>
AMO_REFRESH_TOKEN=<<<token>>>
AMO_PIPELINE_ID=<<<id>>>
AMO_STATUS_NEW_ID=<<<id>>>
AMO_RESPONSIBLE_USER_ID=<<<id>>>

# OpenAI
OPENAI_API_KEY=<<<key>>>
OPENAI_ASSISTANT_ID=<<<assistant_id_primary>>>

# Redis Upstash
REDIS_URL=<<<tls://...>>>
REDIS_TOKEN=<<<upstash_token>>>

# Misc
TIMEZONE=Asia/Jerusalem

7) Redis: ключи и TTL

lead:thread:{wa_chat_id} → { "thread_id": "...", "assistant_id": "..." } TTL 30d
lead:lock:{wa_msg_id} → предотвращение повторной обработки (TTL 1h)
lead:rate:{wa_chat_id} → антиспам/антифлуд (TTL 60s)
lead:ctx:{wa_chat_id} → компактный контекст (стадия воронки, ответы на анкеты) TTL 7d

8) REST-эндпоинты

8.1 /webhook [POST] — входящий Wazzup вебхук

Тело (пример):

{
"event": "message",
"message": {
"id": "wa_msg_id",
"chat_id": "whatsapp:+9715....",
"from_me": false,
"text": "Хочу открыть счёт в Дубае",
"media": null,
"timestamp": 1730000000
}
}

Ответ: 200 OK всегда (ошибки только в логах).

Действия:

Дедуп по message.id.
Классификация/язык.
Извлечь или создать thread_id (OpenAI Assistants v2).
Отправить в тред системный контекст + сообщение.
Дождаться run-завершения, получить ответ, при необходимости вызвать tools:

tool=crm.upsert_lead_contact
tool=calendar.schedule (опц.)
tool=wazzup.send

Ответить пользователю через Wazzup.

8.2 /healthz [GET]

Возвращает {"status":"ok","ts":...}.

9) Интеграции: требования и маппинг

9.1 amoCRM поля

lead.pipeline_id = AMO_PIPELINE_ID
lead.status_id = AMO_STATUS_NEW_ID
Кастомные поля:
cf_country = страна ПМЖ
cf_company_type = FZ/LLC/solo
cf_turnover = месячный оборот
cf_source_of_funds = источник средств
cf_language = RU/EN
Контакт: телефон (E.164), имя из WA (если есть), теги ["whatsapp","ai-assistant"].
Примечание: вставить краткую сводку квалификации ИИ (5–7 строк).

9.2 Wazzup

Отправка: текст, emoji, вложения (pdf/jpg/png), шаблоны (если подключены).
Повторы: ретраи 3× с backoff (1s/3s/10s).

10) OpenAI Assistants v2 (настройки)

assistant_id: OPENAI_ASSISTANT_ID
Инструкции ассистента (system prompt):
– стиль: деловой, кратко, без «воды»;
– правила воронки: задать 6–8 конкретных вопросов по KYC;
– язык ответа = язык входящего;
– никогда не обещать того, чего нет;
– всегда добавлять «что дальше» (CTA: запрошу документ, предложу слот).
Инструменты (functions): описать JSON-схемы:

crm_upsert_lead(payload)
crm_add_note(lead_id, text)
wazzup_send(chat_id, text|media)
calendar_book(email|phone, slot_pref) (опц.)

Защита: анти-prompt-injection (правила неизменяемы), обрезка контекста до N последних реплик.

11) Ошибки и ретраи

Сетевые/429: @retry (exp backoff) макс. 3–5 раз.
OpenAI openai.NotFoundError: пересоздать thread/assistant по месту, залогировать ERROR.
Вебхуки: всегда 200, внутренние ошибки — в лог + алерт.
Зацикливание tool-вызовов: жёсткий лимит tools_per_run <= 5.

12) Логирование и мониторинг

Корреляционный id: cid = f"{wa_chat_id}:{wa_msg_id}"
Логи JSON: time, level, cid, stage, event, payload_size, latency_ms.
Метрики (Prom-style):
msg_in_total, msg_out_total, run_latency_ms, crm_upsert_errors_total, sla_breaches_total.

13) Безопасность и соответствие

Хранить минимум персональных данных (PII) в Redis, TTL.
Шифрование секретов только в .env/секрет-хранилище Replit.
Валидация входящих вебхуков (Wazzup verify token).
Логи без полного тела документов; не писать медиа в логи.

14) Тест-план (обязательно)

Юниты: парсинг вебхука, дедуп, нормализация телефона, определение языка.
Интеграционные: мок Wazzup/KommoCRM/OpenAI.
E2E: сценарии:

Горячий лид (все ответы в норме) → создаётся лид, идёт на менеджера.
Нецелевой → вежливый отказ + ресурсы.
Ошибка amoCRM (401) → авто-refresh токена (если реализуем) и повтор.
Повторный дубликат сообщения → игнор.
Большой медиафайл → обработка/ошибка-сообщение.

15) Критерии приёмки

A1. Первичный ответ ≤ 60 сек в 99-перцентиле.
A2. Создание лида в amoCRM с заполнением всех указанных полей.
A3. Дедупликация входящих сообщений по message.id.
A4. Ретраи 429/5xx работают, не ломают idempotency.
A5. Логи читаемы, с cid, без PII утечек.

16) План работ и артефакты

W1: каркас FastAPI, /webhook, .env, healthz, базовые логи.
W2: интеграция OpenAI v2, threads/runs, инструменты-заглушки.
W3: Wazzup send/receive, Redis состояние, дедуп/антифлуд.
W4: amoCRM upsert + маппинг полей, заметки, ответственный.
W5: Тест-план, нагрузочное (100 одновременных чатов), финальные логи/метрики.
Deliverables: код + README (переменные, как запустить), Postman-коллекция, пример .env.example.

17) Пример: код /webhook (FastAPI, комментарии для дебага)

Примечание: в проде вынести tool-функции в отдельные модули, добавить pydantic-схемы входов/выходов, трейсинг и метрики.

18) Prompt/Инструкции ассистента (скелет)

Ты — AI-ассистент для первичной квалификации лидов.
Правила:
1) Отвечай на языке пользователя, кратко, по делу.
2) Задавай до 8 вопросов для квалификации KYC/деловой цели.
3) Если лид подходит — предложи удобное время/способ связи и вызови инструмент crm_upsert_lead.
4) Если не подходит — вежливо откажи, предложи альтернативы.
5) Никогда не обещай недоступных услуг.
6) Итог каждого диалога: чёткий next step.

Tools (JSON-схемы для v2): описать поля crm_upsert_lead, wazzup_send и пр. (idempotent!).

19) Документация для разработчика

README.md: как запустить локально/на Replit, переменные, проверка /healthz.
docs/flows.md: диаграмма шагов от вебхука до CRM.
Postman/Insomnia коллекция: примеры вебхуков, ответы Wazzup, amoCRM upsert.