diff --git a/bot_architecture.html b/bot_architecture.html new file mode 100644 index 0000000..48f88f0 --- /dev/null +++ b/bot_architecture.html @@ -0,0 +1,172 @@ + + + + + +VIZELBERG — Архитектура анкета-бота (Telegram/MAX) + + + +
+
VIZELBERG · Intake Bot Architecture
+

Анкета-бот: Telegram / MAX

+

Мультиклиентский голосовой опрос → структурированные данные

+
+ + +
+
00 · Разделение контуров
+

Два разных механизма — не путать

+
+

① Ops-канал «Заказчик ↔ Claude»

Владелец бизнеса (Наталья и др.) обсуждает проект. «Claude» здесь — рабочая сессия + недельный дайджест. Лёгкий, без отдельной разработки: общий Telegram-чат, голосовые расшифровываются, Руслан ведёт.

не масштабируем, ручной
+

② Продукт «Анкета-бот»

Конечные клиенты Заказчиков наговаривают анкету голосом. Обработка — автоматический бэкенд (STT + Claude API), без человека в петле. Мультиклиентский, переиспользуется для каждого Заказчика.

это и проектируем ↓
+
+
+ + +
+
01 · Поток данных
+

Как работает опрос

+
Клиент переходит по ссылке Заказчика, наговаривает ответы голосом (или текстом), бэкенд расшифровывает, Claude API раскладывает в структуру и помечает риски, результат уходит в кабинет нутрициолога.
+
+
1
Вход по диплинкуt.me/vizelberg_intake_bot?start=natali — параметр определяет Заказчика (tenant). Тот же бот обслуживает всех.Telegram Bot APIMAX Bot API
+
+
2
Согласие на обработку ПДнПервый шаг — кнопка «Согласен(на)». Без согласия опрос не стартует (152-ФЗ).consent log
+
+
3
Опрос: голос или текстДва режима: «наговорить одним рассказом» или «по вопросам». Голосовые .ogg принимаются как есть.webhookstate machine
+
+
4
Расшифровка речи (STT)Голос .ogg/Opus → текст. Русский язык, данные в РФ.Yandex SpeechKit (реком.)/ Whisper self-host
+
+
5
Структурирование (Claude API)Свободный текст → JSON по схеме анкеты, заполнение пропусков уточняющими вопросами, флаги рисков/противопоказаний, черновик рекомендаций.Claude API + tool useprompt caching
+
+
6
Сохранение + доставкаJSON → БД (шифрование ПДн) → очередь интейка в кабинете нутрициолога + уведомление Заказчику.PostgreSQLадмин-кабинет
+
+
+ + +
+
02 · Стек и выбор
+

Технологии

+ + + + + + + + +
СлойРекомендацияПочему / альтернатива
МессенджерыTelegram Bot API + MAX Bot APIОдин бэкенд, два транспорта. Telegram — сейчас, MAX — РФ-рост
Распознавание речиYandex SpeechKitЛучший русский + данные в РФ (важно для ПДн), дёшево. Альтернатива — self-host Whisper (дороже по железу, но без внешнего вендора)
Логика / структурированиеClaude API (Anthropic)Свободная речь → JSON-схема, флаги рисков, черновик рекомендаций. Prompt caching снижает цену
БэкендPython (FastAPI / aiogram)aiogram — зрелая Telegram-библиотека; webhook на FastAPI
ХранилищеPostgreSQL + шифрованиеМультиарендность по tenant_id; ПДн шифруем at-rest
Хостингсуществующий VPSУже есть инфраструктура проекта; данные в РФ
+
+ + +
+
03 · Мультиарендность
+

Один бот — много Заказчиков

+
Каждый Заказчик = tenant с собственным шаблоном анкеты, брендингом и адресом доставки результатов. Тот же код, разная конфигурация.
+
+
+
Конфиг Заказчика (пример) +
{ + "tenant": "natali", + "name": "Наталья Визельберг", + "brand": "vizelberg", + "deeplink": "?start=natali", + "questionnaire": "nutrition_v1", + "deliver_to": { + "cabinet": "admin/intake", + "notify_tg": "@natali_amrita" + }, + "stt_lang": "ru-RU" +}
+
+
+
Выход опроса (та же схема, что в anketa.html) +
{ + "tenant": "natali", + "name": "Анна", + "afp": "32 года, 168 см, 70 кг", + "goal": ["Снизить вес","Больше энергии"], + "goal_text": "...", + "health": "...", "allergy": "...", + "meds": "...", "day": "...", + "water": "...", "life": "...", + "diets": "...", + "_flags": ["низкий витамин D?","гастрит — осторожно с кислым"], + "source": "voice", + "submitted_at": "2026-05-27T..." +}
+
+
+

Схема JSON совпадает с интерактивной анкетой — алгоритм обработки один и тот же для web-формы и бота.

+
+ + +
+
04 · Право и данные
+

Стоп-условия (решение Руслана/юриста)

+
Согласие на ПДн (152-ФЗ). Обязательный первый шаг бота. Без явного согласия опрос не начинается. Текст согласия + политику — подготовить.
+
Медицинские данные. Анкета содержит сведения о здоровье — повышенная категория ПДн. Хранение в РФ, шифрование, ограничение доступа.
+
Голос как биометрия. Храним текст расшифровки, аудио удаляем после распознавания — чтобы не попасть в биометрические ПДн.
+
Дисклеймер. Нутрициология — не мед.услуга; рекомендации не заменяют врача. Формулировку согласовать.
+
+ + +
+
05 · Этапы
+

План внедрения

+
MVP
1–2 нед
Telegram-бот, 1 Заказчик (Наталья). Опрос по вопросам + голос (Yandex STT), структурирование Claude API, выгрузка JSON в кабинет. Согласие на ПДн.
+
V2
+1 нед
Свободный монолог + дозапрос пропусков. «Расскажите о себе» одним голосовым → Claude вытаскивает поля и спрашивает только недостающее.
+
V3
+1–2 нед
Мультиарендность + MAX. Конфиг Заказчиков, диплинки, кабинет с очередью интейка, второй транспорт MAX. Готово к подключению новых Заказчиков.
+
V4
Конструктор анкет. Заказчик сам редактирует вопросы из кабинета — полноценный SaaS-модуль.
+ +
+ +
VIZELBERG · Intake Bot Architecture v1.0 · 2026
+ + diff --git a/index.html b/index.html index f319e67..49c246e 100644 --- a/index.html +++ b/index.html @@ -98,6 +98,12 @@

Роли, матрица решений, цикл работы Заказчик ↔ Claude, стоп-условия. Для согласования процесса.

читать → + +
+

Архитектура анкета-бота

+

Мультиклиентский голосовой опрос Telegram/MAX: поток данных, стек, ПДн, этапы внедрения.

+ читать → +