Green Broker — spec.md

modified: 2026-08-03 12:18 · canonical

Спецификация требований: Green Broker Telegram-бот

1. Введение

Основная цель проекта: Разработать полнофункциональный Telegram-бот для питомников растений, который автоматизирует рутинный процесс продаж. Бот ДОЛЖЕН предоставлять функцию удобного внесения карточек товара через телефон для продавцов и главное — мгновенно формировать коммерческие предложения (КП) по неструктурированному запросу заказчиков (текст, фото, файл PDF, Word, Excel). Глобальная цель: Развернуть экосистему (маркетплейс в Telegram) из множества ботов.

Согласно Конституции проекта, реализация разбита на фазы:

---

2. Пользовательские истории (User Stories)

2.1 Клиентская часть (B2B MVP: Ландшафтные дизайнеры / Оптовики)

US-16: Умная обработка неструктурированных заявок (Киллер-фича MVP) (P1)

Как ландшафтный дизайнер или оптовик, я хочу отправить боту список растений в любом удобном формате (текст, фото накладной, а также файлами PDF, Word, Excel), чтобы бот автоматически сопоставил их с актуальными остатками питомника и мгновенно выдал готовое коммерческое предложение (КП) в PDF. Приемочные критерии: Дано: Пользователь отправляет список из 10 растений в виде PDF, Excel или текста. Когда: Алгоритм бота (с помощью LLM) анализирует текст и сопоставляет с БД. Тогда: Все найденные позиции помещаются в "скрытую/виртуальную корзину". И: Пользователь мгновенно получает сгенерированное КП в формате PDF с актуальными ценами и остатками.

US-1: Визуальный каталог для частников (Интернет-магазин) (Фаза 2 / P3)

Как частный покупатель, я хочу перемещаться по визуальному каталогу с картинками, добавлять товары в корзину кнопками и оформлять заказ, не имея заранее готового списка (как в обычном интернет-магазине). Приемочные критерии: Дано: Пользователь (садовод-любитель) открывает бота. Когда: Пользователь выбирает товары по фотографиям и нажимает "В корзину". * Тогда: Формируется классическая видимая корзина, из которой затем можно получить КП.

US-2: Детализированные параметры товара и медиа (P1)

Как покупатель, я хочу видеть в карточке растения детальные характеристики (фото, ростовку, формат упаковки корня), так как цены зависят от этих параметров. Приемочные критерии: Дано: Пользователь открывает карточку конкретного товара (например, Спирея серая Грефшейм P9). Когда: Пользователь просматривает карточку. Тогда: Бот отображает до 3-х фотографий растения (включая сезонные: весенний и летний вид), загруженных из S3 хранилища, актуальную цену и доступный остаток на складе для выбранной модификации. И: Если у растения есть другие доступные варианты упаковки/размера, бот предоставляет инлайн-кнопки для быстрого переключения между ними (например, переключиться с P9 на C3) прямо внутри карточки товара с автоматическим пересчетом цены.

US-3: Оптовый ввод количества в корзине (P1)

Как оптовый покупатель, я хочу вводить точное количество товара цифрами с клавиатуры, чтобы не кликать кнопку "+" сотни раз. Приемочные критерии: Дано: Пользователь находится в карточке товара и нажимает "В корзину". Когда: Пользователь отправляет боту число "500". * Тогда: Бот проверяет остатки (>= 500) и добавляет указанное количество в корзину, выводя подтверждение.

US-4: Умный профиль покупателя (P1)

Как покупатель, я хочу один раз указать свои контактные данные (Имя, Телефон), чтобы бот запомнил их для последующих заказов. Приемочные критерии: Дано: Пользователь впервые оформляет заказ. Когда: Пользователь вводит Имя и Телефон. * Тогда: При следующих заказах бот автоматически подставляет эти данные и предлагает лишь одну кнопку "Изменить данные" для корректировки.

US-5: Автогенерация Коммерческого Предложения (Чек заказа) (P1)

Как ландшафтный дизайнер, я хочу сразу после оформления заказа получать детализированный чек (КП) в формате PDF, чтобы оперативно переслать его своему конечному клиенту. Приемочные критерии: Дано: Пользователь подтверждает заказ в корзине. Когда: Система обрабатывает заявку. Тогда: Пользователь в течение 1 минуты получает сгенерированный PDF-файл. И: PDF содержит: Шапку питомника (логотип), Геометку (адрес), Номер заказа, ссылку на менеджера (кнопка "Связаться"), перечень позиций с фото, описанием и итоговую сумму.

US-10: Разрешение заказа "в минус" (Доверительный B2B-подход) (P2)

Как покупатель, я хочу иметь возможность заказать товар в количестве, превышающем остаток на складе (вплоть до остатка 0). Приемочные критерии: Дано: Пользователь вводит количество, превышающее доступный остаток. Когда: Бот обрабатывает ввод для добавления в корзину. Тогда: Бот не блокирует пользователя, а добавляет полное запрошенное количество в корзину. И: В корзине и итоговом PDF-счете эта позиция (или ее дефицитная часть) помечается звездочкой (подтверждается менеджером), оставляя финальное решение об отгрузке за отделом продаж.

US-6: Прозрачность актуальности прайсов (P1)

Как покупатель, я хочу видеть в выдаче/карточке товара дату обновления информации, чтобы понимать, насколько она свежая. Приемочные критерии: Дано: Пользователь просматривает карточку растения. Когда: Карточка рендерится в чате. * Тогда: Бот выводит текст По данным прайс-листа от DD.MM.YYYY.

US-7: Уточнение остатков и B2B краудсорсинг (P2)

Как ландшафтный дизайнер, я хочу иметь возможность нажать кнопку "Сообщить об отсутствии", если выяснилось, что товара по факту нет в питомнике. Приемочные критерии: Дано: Пользователь просматривает карточку растения. Когда: Пользователь нажимает кнопку "Сообщить об отсутствии". * Тогда: Бот отправляет алерт модератору в Web-Админку на проверку, а пользователю выводит сообщение "Спасибо за сигнал!".

US-8: Подарочные сертификаты (P2)

Как покупатель, я хочу купить подарочный сертификат на любую сумму через онлайн-оплату. Приемочные критерии: Дано: Пользователь нажимает "Купить сертификат". Когда: Пользователь вводит сумму и оплачивает через ЮKassa. * Тогда: Бот выдает уникальный промокод, который можно применить в корзине для получения скидки на сумму сертификата.

US-21: Выгрузка актуального PDF-прайса (P2)

Как ландшафтный дизайнер, я хочу иметь возможность по одной кнопке получить актуальный PDF-прайс со всем ассортиментом, чтобы удобно показать его клиентам вне бота. Приемочные критерии: Дано: Пользователь находится в главном меню или в меню каталога. Когда: Пользователь нажимает кнопку "Скачать PDF прайс-лист". * Тогда: Бот "на лету" (синхронно) генерирует актуальный PDF-документ на основе текущего состояния базы данных (с фотографиями и ценами) и присылает его пользователю. Это гарантирует 100% свежесть данных, несмотря на потенциально большее время ожидания (генерации).

---

2.2 Административная часть и CRM (B2B / Менеджеры питомника)

US-9: Интегрированное управление складом (P1)

Как менеджер питомника, я хочу регулировать складские остатки прямо через Telegram-бота (техническое окно), находясь в поле перед растениями. Приемочные критерии: Дано: Авторизованный менеджер вызывает команду /ostatki. Когда: Менеджер выбирает товар и нажимает кнопки "+10" / "-10" или вводит число вручную. * Тогда: База данных мгновенно обновляется.

US-10: Гибкий контроль остатков (заказ "в минус") (P2)

Как менеджер, я хочу, чтобы система позволяла клиентам делать заказ, даже если товара не хватает на складе (уход остатков "в минус"). Приемочные критерии: Дано: Клиент заказывает 100 туй, а на складе числится 80. Когда: Клиент подтверждает заказ. Тогда: Заказ успешно оформляется, остаток на складе становится -20. И: Менеджер получает уведомление о необходимости пополнения запасов.

US-11: Мини-CRM и экспорт данных (P1)

Как владелец бизнеса, я хочу чтобы все заявки фиксировались в отдельной таблице БД в одну строку для удобного экспорта в Excel или 1C, а также дублировались в отдельную группу для менеджеров. Приемочные критерии: Дано: Происходит оформление нового заказа. Когда: Данные записываются в БД. Тогда: В таблице Orders создается ровно одна строка, содержащая поля: Order_ID, User_ID, Name, Phone, Telegram_Username, Total_Sum, Order_Details_JSON (все товары заказа списком внутри JSON). И: Сообщение с деталями нового заказа мгновенно пересылается в специализированную Telegram-группу (чат для менеджеров), чтобы менеджеры могли оперативно взять заказ в работу.

US-20: Инструмент массовой рассылки (P2)

Как администратор или владелец питомника, я хочу иметь возможность отправлять рассылки всем пользователям бота (например, об обновлении ассортимента или старте сезона). Приемочные критерии: Дано: Администратор вызывает команду или использует панель для рассылки. Когда: Составляется текст с медиа и нажимается кнопка "Отправить всем". * Тогда: Бот осуществляет массовую рассылку по списку User_ID с соблюдением лимитов Telegram (во избежание бана), чтобы оповестить базу клиентов. На этапе MVP допустимо использование простых in-memory asyncio-очередей (без развертывания Celery/Redis).

US-23: Мобильное рабочее место агронома (Создание товаров "в поле") (P1)

Как менеджер питомника, я хочу иметь возможность создавать новые карточки товаров прямо с телефона, стоя перед растением, чтобы тратить на заведение одной позиции не более минуты. Приемочные критерии: Дано: Авторизованный менеджер запускает сценарий добавления товара в Telegram (например, команда /add). Когда: Менеджер пошагово (FSM) отправляет боту текстовые характеристики (название, ростовка, обхват ствола [опционально], упаковка, цена, остаток) и делает фотографию прямо с камеры телефона. Тогда: Бот мгновенно загружает фотографию в S3 хранилище и сохраняет полную запись в БД. И: Новый товар моментально появляется в публичном каталоге бота без необходимости ручной загрузки Excel-файлов или перезагрузки серверов.

---

2.3 Сбор данных (ETL) и Web-Админка (Платформа)

US-12: Архитектура сбора данных и нормализация (P1)

Как система, я должна регулярно собирать цены и остатки из Excel-файлов (загруженных менеджерами) и нормализовать их (приводить синонимы ОКС/WRB к единому стандарту), чтобы база была канонической. Приемочные критерии: Дано: Менеджер загружает прайс-лист в бота. Когда: Запускается парсер. * Тогда: Нейросеть (или алгоритм) извлекает название, характеристики (ком, размер) и цены. Единым ключом объединения позиций выступает латинское название (plant_name_lat). Недостающие поля подсвечиваются менеджеру для ручного ввода.

US-13: Web-Админка: Модерация краудсорсинга (Soft Delete) (P1)

Как модератор, я хочу подтверждать жалобы "об отсутствии товара" в Web-панели, чтобы вручную переводить товар в статус out_of_stock, избегая вандализма от конкурентов. Приемочные критерии: Дано: Поступила жалоба на отсутствие товара. Когда: Модератор нажимает "Скрыть товар" в панели управления. * Тогда: Товар помечается флагом deleted=true (Soft Delete) и перестает отображаться в выдаче бота, но сохраняется в БД.

US-14: Web-Админка: Аналитика запросов (P2)

Как владелец продукта, я хочу видеть в админке аналитику самых частых поисковых запросов ландшафтников (хиты поиска). Приемочные критерии: Дано: Администратор заходит в раздел "Аналитика". Когда: Загружается дашборд. * Тогда: Отображаются графики Топ-10 поисковых запросов за неделю/месяц на основе логов БД бота.

US-15: Биллинг и Премиум-подписка для питомников (P2)

Как владелец продукта, я хочу назначать статус "Премиум-подписка" определенным питомникам, чтобы бот выводил их растения на первые места в результатах поиска. Приемочные критерии: Дано: Питомник оплатил подписку. Когда: Администратор устанавливает флаг is_premium в панели управления. * Тогда: В поисковой выдаче бота растения этого питомника всегда сортируются выше остальных.

---

2.4 Инновационные функции и Roadmap (Future Proof / P3)

(Примечание: US-1 Обработка заявок перенесена в MVP P1 как киллер-фича)

US-17: AI-Агроном (Виртуальный консультант 24/7) (P3)

Как покупатель, я хочу задавать вопросы по агротехнике бота (как сажать, чем удобрять). Встроенная LLM должна отвечать, опираясь на базу знаний.

US-18: Интеграция с учетными системами (Бизнес Пак / 1С) (P3)

Автоматическая двусторонняя синхронизация остатков между ботом и складскими программами (API/Webhooks).

US-19: B2B Маркетплейс-Агрегатор (Green Broker Pro) (P3)

Как участник рынка, я хочу чтобы питомники были объединены в централизованный Telegram-бот агрегатор, чтобы клиент мог найти нужный питомник по региону или специализации. Приемочные критерии: Дано: Пользователь запускает бота-агрегатор "Green Broker Pro". Когда: Пользователь выбирает фильтры (например, "Московская область", "Хвойные"). Тогда: Бот выдает список питомников, соответствующих критериям. И: В карточке каждого питомника отображается краткая информация, контакты и прямая ссылка (Deep link) на индивидуального Telegram-бота этого питомника для совершения заказа.

US-22: Автоматический расчет логистики через Яндекс.Карты (P3)

Как покупатель, я хочу, чтобы бот автоматически рассчитывал стоимость доставки при формировании заказа. Приемочные критерии: Дано: Клиент находится на этапе оформления корзины. Когда: Бот запрашивает гео-точку доставки (предлагая кнопку "Отправить геопозицию" и текстовый ввод). Тогда: Если клиент отправляет текст, система использует Yandex Geocoder API для получения координат. И: Система обращается к API Яндекс.Карт для вычисления километража от склада до гео-точки клиента. * И: Стоимость доставки автоматически калькулируется и включается отдельной строкой в сгенерированное PDF Коммерческое Предложение.

---

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

1. Производительность бота: Ответ бота < 2 секунд. Реализован антиспам-механизм (троттлинг). 2. Парсер и ETL: Запуск задачи (cron) для сбора и нормализации прайсов. Использование Fuzzy Matching для компенсации опечаток. 3. Хранение данных: SQLite/PostgreSQL для бизнес-логики. Обязательное использование S3-совместимого хранилища (Yandex Object Storage) для отдачи медиа (фото и PDF). 4. Словари синонимов: Поддержка словарей для приведения BR, ОКС, P9, D9, WRB, ком к единому формату. 5. Безопасность: Web-Админка защищена JWT / Basic Auth. Доступ к /ostatki разграничен по ролям.

---

4. Уточнения (Clarifications по итогам speckit-clarify)

1. US-22 (Геолокация): Выбран гибридный подход. Бот просит гео-точку, но умеет принимать и текстовый адрес (обрабатывая его через Yandex Geocoder API). 2. US-20 (Рассылки): Вопрос масштабируемых очередей (Celery) пока не в приоритете. Для MVP используем простые in-memory asyncio-задачи. 3. US-21 (PDF-прайс): Прайс генерируется строго "на лету" синхронно при каждом запросе для обеспечения 100% свежести данных. 4. US-10 (Корзина в минус): Реализуется доверительный B2B подход. Товар добавляется в корзину полностью, но сверх-остаток помечается "звездочкой" для ручного подтверждения менеджером. 5. US-19 (Агрегатор): Отказ от Telegram Forum в пользу создания централизованного Супер-Бота Агрегатора с фильтрацией питомников по регионам и специализациям. 6. CRM (YouGile): Заказы клиентов больше не обрабатываются внутри самописной админки. Бот интегрируется с YouGile API, создавая Канбан-карточки заказов с прикрепленными PDF-счетами. Web-админка оставлена только для модерации каталога. 7. US-16 (Парсинг ненайденных позиций): Если точного совпадения нет, нейросеть предлагает релевантные позиции для замены. Если замен нет — товар переносится в блок "На уточнении". 8. US-16 (Обработка больших файлов): Большие Excel-заявки разбиваются на чанки скрыто от пользователя. Бот выводит статус "Файл большой, обработка займет пару минут" и выдает единое КП. 9. US-16 (Учет замен в стоимости): Предложенные замены НЕ плюсуются к итоговой сумме КП, а выводятся справочно в отдельном блоке, пока клиент их не согласует.