HelpLy — техническое описание

0. Бизнес-цели и успех (обязательно)

• Цель бизнеса (12–24 мес): Подключить 100 платящих компаний за 18 мес, MRR 500 тыс. ₽.
• Кто платит vs кто пользуется: Платит компания (владелец, руководитель поддержки); пользуются посетители её сайта.
• Ценность для пользователя (одной фразой): Посетитель получает точный ответ по документам компании за секунды, круглосуточно.
• KPI успеха v1 (3–7 измеримых):
  • ≥ 60% вопросов закрываются без оператора
  • Время ответа < 3 с
  • Конверсия лендинга в регистрацию ≥ 3%
  • Доля «неверных» ответов по оценкам ≤ 5%
  • Удержание клиентов через 3 мес ≥ 80%
• Монетизация / экономика: Подписка: Старт 2 990 ₽/мес (1 000 диалогов), Бизнес 9 900 ₽, Корпоративный — индивидуально.
• Go-to-market: Чат на лендинге, бесплатный тест 14 дней, партнёрство с веб-студиями, статьи на VC.ru и Хабре.
• SEO / контент / маркетинг в v1: Страницы по сценариям: «чат-бот для интернет-магазина», «ИИ-консультант для клиники»; сравнения с аналогами.
• Конкуренты / аналоги (1–3) и отличие: Jivo, Chatfuel, Carrot quest. Отличие: ответы по собственной базе знаний (RAG) со ссылками на источник, установка одной строкой.
• Анти-цели v1: Не делаем голосового бота, мессенджеры и обучение собственной модели в v1.

1. Название и суть

• Название проекта: HelpLy — ИИ-ассистент для сайта, отвечающий по базе знаний компании
• Одной фразой: Виджет-чат, который отвечает посетителям по FAQ и документам компании.
• Для кого: Малый и средний бизнес с повторяющимися вопросами клиентов.
• Проблема: Операторы тратят до 70% времени на одинаковые вопросы, ночью клиенты остаются без ответа.
• Связь с §0: каждый сценарий v1 ведёт к KPI конверсии и измеряется целями в аналитике.

2. Границы

IN SCOPE (обязательно в v1):

• Лендинг с живым чатом
• Регистрация компании
• Загрузка базы знаний (PDF, DOCX, URL, FAQ)
• Индексация (эмбеддинги) и ответы с цитатами источника
• Встраиваемый JS-виджет
• Передача диалога оператору по email
• Дашборд: диалоги, оценки ответов

OUT OF SCOPE:

• Голос
• Мессенджеры (Telegram, WhatsApp)
• Собственная LLM
• Интеграции с CRM

Позже (v2+):

• Telegram и VK-бот
• Интеграция с amoCRM
• Онлайн-оплата подписки
• Аналитика непокрытых вопросов

3. Стек

• Frontend: React 19 + Vite (продакшен); макет — чистый HTML/CSS/JS без сборки
• Стили UI: CSS Modules / собственная дизайн-система по INPUT/DESIGN.html
• Backend: Node.js 20 LTS + Express
• БД OLTP: PostgreSQL 16 + pgvector
• Аналитика / OLAP: Яндекс Метрика; OLAP не требуется в v1
• Кэш / очереди / observability: Redis (кэш, очередь индексации BullMQ); логи pino, uptime-мониторинг
• Хостинг / облако: VPS в РФ (Timeweb Cloud / Selectel), Nginx, Docker Compose
• Монолит / модульный монолит / сервисы: модульный монолит

4. Ключевые сценарии

1. Посетитель лендинга задаёт в чате «Сколько стоит?» и получает ответ с тарифами.
2. Владелец магазина загружает PDF с условиями доставки, через минуту виджет отвечает по нему.
3. Посетитель сайта клиента ставит «дизлайк» ответу — диалог уходит оператору на email.

5. Сущности и данные

Сущность	Поля (примерно)	Связи	Заметки
Workspace	name, plan, widget_key, settings	1:N User, 1:N Document	Тенант
User	email, password_hash, role	N:1 Workspace	—
Document	workspace_id, title, source_type, status, uploaded_at	1:N Chunk	PDF/DOCX/URL
Chunk	document_id, text, embedding vector(1536)	N:1 Document	pgvector
Conversation	workspace_id, visitor_id, started_at, handed_off	1:N Message	—
Message	conversation_id, role, text, sources[], rating	N:1 Conversation	Retention 12 мес

6. Интеграции

• LLM API (YandexGPT / GigaChat / OpenAI-совместимый) — генерация
• API эмбеддингов
• PostgreSQL + pgvector — поиск
• SMTP — передача оператору
• Yandex Object Storage — файлы

7. Нефункциональные требования

• Ожидаемая нагрузка: До 100 воркспейсов, 50 000 сообщений/мес, пики 20 RPS
• Latency / доступность: TTFB < 300 мс, LCP < 2,5 с на mobile, доступность 99,5%
• Retention EventLog / evidence / audit: логи 30 дней, заявки/заказы 3 года, бэкап БД ежедневно с хранением 14 дней
• Compliance: 152-ФЗ; не передавать ПД в зарубежные LLM без согласия — по умолчанию российские провайдеры; маскирование телефонов/email перед отправкой в LLM

8. Безопасность

• JWT для дашборда, публичный widget_key с ограничением по домену (CORS/Origin), rate-limit на виджет, изоляция тенантов, защита от prompt injection в документах.
• HTTPS (Let's Encrypt), helmet, CSP, валидация входных данных на сервере, секреты в .env вне репозитория.

9. UX / клиенты

• Web: лендинг, дашборд (desktop), виджет (mobile + desktop).
• Доступность: контраст AA, фокус-состояния, подписи полей форм.

9b. Дизайн

• HTML-референс: INPUT/DESIGN.html (картинки в INPUT/assets/, описания в INPUT/assets/DESCRIPTIONS.md)

9c. CI/CD и окружения

• Окружения: local / ci / staging / production
• CI: GitHub Actions — lint, тесты, сборка Docker-образа; деплой на staging по merge в main, на production по тегу
• Хостинг: VPS в РФ, Docker Compose, Nginx reverse proxy

10. Ограничения

• Язык кода: TypeScript (strict) на фронте и бэке; автотесты Vitest + Playwright для ключевых сценариев
• Запрещённые практики: хранение секретов в репозитории, ПД в логах, inline-SQL без параметров

11. Готовые модули

• logging-pino
• rate-limiting
• caching-redis
• auth-jwt
• websocket-socketio
• admin-panel
• file-upload
• crud-table
• payments-stripe
• search
• email-nodemailer

12. Критерии приёмки v1

• Ответ ассистента содержит ссылку на источник
• Новый документ индексируется < 2 мин
• Виджет встраивается одной строкой и работает на mobile
• Тенант A не видит данные тенанта B
• При отсутствии ответа в базе ассистент честно говорит об этом и предлагает оператора

13. Свободные заметки