ТЗ: Демо-проект (showcase) для umbot

Статус: техническое задание для сообщества / контрибьюторов. Цель: создать один эталонный, реально работающий проект-витрину, который демонстрирует все ключевые возможности umbot в связке и служит живым примером «как правильно». Это то, что разработчик клонирует и запускает за 2 минуты, чтобы понять ценность фреймворка.

1. Мотивация

Сейчас в examples/skills/ лежит набор изолированных демо (папка с index.ts, контроллером и README на каждое), каждое из которых показывает одну фичу. Это хорошо для справочника, но не даёт ответа на главный вопрос нового пользователя: «как выглядит настоящий бот целиком?».

Отдельного демо-проекта нет — его роль частично играет CLI-шаблон (npx umbot create) и визуальный редактор. Но шаблон намеренно минимален, а редактор требует внешнего сервиса.

Нужен один законченный продукт: многокомандный бот с диалогами, формами, состоянием, кнопками, карточками и middleware, который можно запустить локально и сразу «пощупать» в консоли через BotTest.

2. Концепция

«Кофейня-бот» — бот-бариста, который:

• приветствует пользователя и показывает меню (welcome + кнопки);
• принимает заказ через многошаговую форму (напиток → объём → имя);
• хранит историю заказов и любимый напиток в userData;
• показывает карточку-галерею меню;
• понимает свободные фразы через NLU (числа, подтверждения);
• применяет middleware (rateLimiter, requestId);
• работает одинаково на всех платформах через fullPlatforms.

Домен «кофейни» выбран потому, что в нём естественно возникают команды, шаги, формы, состояние и карточки — все ключевые примитивы фреймворка.

3. Функциональные требования

3.1 Команды

Команда	Слоты	Поведение
welcome	привет, здравствуй	Приветствие + кнопки меню
menu	меню, карта	Карточка-галерея напитков
order	заказ, заказать, хочу кофе	Запуск формы заказа
favorite	любимый, мой напиток	Показать любимый напиток из userData
help	помощь, что ты умеешь	Список команд
FALLBACK_COMMAND	—	Дружелюбный ответ + подсказка «помощь»

3.2 Форма заказа (addForm)

Поля:

1. drink — «Что будете пить?» + валидация по списку (кофе, чай, какао);
2. size — «Какой объём?» + валидация (маленький, средний, большой);
3. name — «На чьё имя?» + валидация непустой строки.

onComplete: сохранить заказ в userData.history, обновить userData.favorite, подтвердить заказ текстом с кнопкой «Ещё заказ».

Отдельный шаг confirm_favorite (addStep): если у пользователя уже есть любимый напиток, бот сначала спрашивает «как обычно?» и при подтверждении повторяет последний заказ.

3.3 Состояние (userData)

interface ICoffeeOrder {
    drink: string; // напиток
    size: string; // объём
    name: string; // имя
    total: number; // итоговая сумма (0, если сработала лояльность)
    ts: number; // время оформления (unix-мс)
}

interface ICoffeeUserData extends IUserData {
    favorite?: string;
    history?: ICoffeeOrder[];
}
Copy

Использовать дженерик Bot<ICoffeeUserData> (в server.ts), чтобы показать типобезопасный доступ к ctx.userData. В command-only режиме тот же тип прокидывается в колбэки команд через addCommand<BotController<ICoffeeUserData>> (псевдоним CoffeeCtx), поэтому отдельный класс-контроллер не требуется.

3.4 NLU

• подтверждение в диалоге — интент YANDEX.CONFIRM (Nlu.T_INTENT_CONFIRM) с текстовым фолбэком («да», «конечно» и т.п. через Text.isSayTrue) для консоли и чат-платформ;
• извлечение числа из фразы («два кофе») через nlu / Text.

3.5 Middleware

bot.use(rateLimiter());
bot.use(requestId());
Copy

3.6 UI-примитивы

• buttons.addBtn / addLink — меню, подтверждение;
• card.addImage / галерея — карточка меню;
• sound (опционально) — звук при завершении заказа для голосовых платформ.

4. Технические требования

4.1 Структура проекта

umbot-demo/
├── src/
│   ├── index.ts                 # ВСЯ логика бота: цепочка addCommand/addStep/addForm
│   │                            # + подключение платформ, БД и middleware
│   ├── menu.ts                  # продуктовый слой: меню с ценами, размеры, итог,
│   │                            # лояльность, оформление заказа (чистый TypeScript)
│   ├── config/
│   │   ├── appConfig.ts         # IAppConfig
│   │   └── appParams.ts         # IAppParam (запасные тексты, intents: null)
│   ├── types/
│   │   └── ICoffeeUserData.ts   # типизация userData
│   ├── dev.ts                   # консольный режим (BotTest + bot.test())
│   └── server.ts                # webhook-режим (Bot + bot.start())
├── tests/
│   └── coffee.test.ts           # тесты через BotTest.simulate
├── package.json
├── tsconfig.json
├── jest.config.js
├── eslint.config.js
├── .gitignore
└── README.md
Copy

Стиль — только команды (без своего контроллера). Вся логика описана одной цепочкой addCommand → addStep → addForm прямо в index.ts. Собственный класс-контроллер с action() не нужен: фреймворк по умолчанию использует BaseBotController, а типизированный userData даёт дженерик BotController<ICoffeeUserData> в колбэках команд (см. CoffeeCtx в menu.ts). Это рекомендуемый, самый простой путь для нового бота.

4.2 Запуск в двух режимах

• Консольный (по умолчанию): npm run dev → BotTest + bot.test() — интерактивная отладка без токенов и сети.
• Webhook: npm start → Bot + bot.start() — для подключения к реальным платформам через токены из .env.

4.3 Зависимости

• umbot (текущая стабильная);
• typescript, @types/node (dev);
• БД: FileAdapter из коробки (не требует установки Mongo). Опционально показать подключение MongoAdapter в комментарии.

4.4 Тесты

Покрыть через BotTest:

• welcome возвращает приветствие и кнопки;
• форма заказа проходит все шаги и сохраняет в userData;
• валидация формы отклоняет неверный напиток;
• favorite читает сохранённое значение;
• fallback срабатывает на нераспознанный ввод.

Использовать simulate() для кроссплатформенной проверки (минимум 2 платформы: alisa и telegram).

5. Требования к README демо-проекта

1. Одна фраза: что это и зачем.
2. Быстрый старт: git clone → npm install → npm run dev (3 команды).
3. Скриншот/лог консольной сессии BotTest.
4. Таблица «какая фича umbot где показана» (команды → файл/строка).
5. Как переключиться на реальные платформы (.env, токены).
6. Ссылка на полную документацию.

6. Критерии приёмки

• [ ] Проект запускается в консольном режиме без токенов и внешних сервисов.
• [ ] Продемонстрированы: команды, шаги/формы, userData, кнопки, карточки, NLU, middleware, fallback.
• [ ] Используется типизированный userData через дженерик Bot<T>.
• [ ] Логика построена только на командах/шагах/формах — без собственного класса-контроллера.
• [ ] Тесты проходят (npm test), покрытие ключевых сценариев.
• [ ] npm run build и npm run lint чистые.
• [ ] README позволяет запустить проект за ≤ 3 команды.
• [ ] Код прокомментирован на русском: каждая секция объясняет, какую фичу umbot она демонстрирует.

7. Что НЕ входит в scope

• Реальные токены платформ и деплой (демо должно работать офлайн в консоли).
• Внешние API и вебхуки в базовом сценарии.
• Визуальный редактор flow.json (это отдельный путь входа).