Sales Assistant

Локальная рекомендательная система для менеджера продаж. Она анализирует синтетическую историю заказов и каталог товаров, объясняет рекомендации и показывает данные через web-интерфейс и JSON API.

Статус: локально проверенный MVP на демонстрационных данных. Это не production-ready сервис.

Бизнес-задача и пользователи

Система помогает менеджеру быстро подготовить варианты допродажи и замены товара во время работы с заказом. Основные пользователи — менеджеры продаж и руководители, проверяющие гипотезу рекомендательного инструмента.

Реализовано и проверено

Четыре направления рекомендаций:

1. Сопутствующие товары — позиции, встречавшиеся в одних документах с выбранным товаром.
2. Аналоги — симметричные связи из отдельного JSON-справочника.
3. Популярные товары клиента — позиции из его истории за заданный период.
4. Новые товары — рекомендации с исключением уже купленных позиций и fallback по общей популярности.

Также реализованы:

• объяснение причины и признаков рекомендации;
• объединённое бизнес-ранжирование с учётом маржи и остатка;
• фильтрация недоступных позиций в итоговых бизнес-рекомендациях;
• HTTP API и внутренний web-интерфейс;
• локальная SQLite-аналитика событий;
• поиск клиентов, оформление демонстрационного заказа и экспорт аналитики;
• автоматические тесты алгоритмов, загрузки данных, API-функций, аналитики и адаптеров.

Нюанс остатков: объединённые рекомендации исключают позиции с нулевым остатком. Отдельные аналитические endpoints «топ клиента», «сопутствующие» и «аналоги» могут возвращать такую позицию вместе с stock=0, чтобы интерфейс явно показал недоступность.

Интеграционный статус

Основной публичный сценарий работает только с demo/*.csv и demo/*.json.

Код файловой синхронизации и HTTP-adapter сохранён как часть фактической архитектуры и покрыт тестами на временных синтетических данных. Прямая онлайн-интеграция с 1С в публичной версии отсутствует и end-to-end не проверялась. Рабочие EPF/BSL/XML, выгрузки, токены и внутренние инструкции не публикуются.

Архитектура

flowchart LR
    Demo["Синтетические CSV/JSON"] --> Load["Загрузка и очистка"]
    Load --> Models["4 алгоритма рекомендаций"]
    Models --> API["HTTP API"]
    API --> UI["Web-интерфейс"]
    API --> DB["Runtime SQLite analytics"]
    Adapter["Файловый/HTTP adapter"] -. "не проверен live" .-> API

Loading

Подробности: docs/architecture.md и docs/data-format.md.

Установка на Windows

Требуется Python 3.11 или новее. В базовом режиме внешних библиотек нет.

python -m venv .venv
.\.venv\Scripts\python -m pip install --disable-pip-version-check -r requirements.txt

.env.example перечисляет поддерживаемые переменные, но файл автоматически не загружается: приложение читает окружение ОС. Для демонстрационного запуска настройки и секреты не требуются.

Запуск backend и интерфейса

.\.venv\Scripts\python app.py

Откройте http://127.0.0.1:8000. Интерфейс обслуживается тем же локальным сервером; отдельной сборки frontend нет.

Docker Compose в репозитории отсутствует и не заявляется.

Демонстрационный сценарий

1. Запустите сервер.
2. Выберите синтетического клиента, например C001.
3. Добавьте товар P001 в корзину и изучите сопутствующие позиции с объяснениями.
4. Откройте топ клиента, аналоги и режим новых товаров.
5. Сравните ответы с demo/example_response.json.

Все данные в demo/ вымышлены. Схемы файлов описаны в docs/data-format.md.

Основные API endpoints

• GET /api/health — проверка сервера;
• GET /api/bootstrap — каталог, клиенты и базовые показатели;
• GET /api/clients/search?q=... — поиск клиента;
• GET /api/clients/{id}/top-products — популярные товары клиента;
• GET /api/products/{id}/companions — сопутствующие товары;
• GET /api/products/{id}/analogs — аналоги;
• GET /api/analytics — локальные агрегаты;
• GET /api/data-health — состояние демонстрационных данных.

Служебные sync/order endpoints не относятся к основному публичному demo-сценарию; без токена и URL внешняя отправка не настроена.

База данных

analytics_store.py создаёт локальную SQLite-базу во время запуска. Таблица events хранит время, тип события, синтетические идентификаторы клиента/сессии/товара и JSON payload. База является генерируемым runtime-файлом и не публикуется.

Тесты

.\.venv\Scripts\python -m unittest -v

Ограничения

• небольшой demo-набор показывает механику, но не подтверждает качество на реальной истории продаж;
• веса бизнес-ранжирования являются правилами текущего MVP;
• SQLite рассчитан на локальный сценарий, а не многопользовательскую нагрузку;
• live-обмен с 1С не проверен;
• приложение не содержит полноценной ролевой модели;
• рабочие коммерческие метрики и результаты внедрения не заявляются.

Возможное развитие

• согласованный offline-набор для оценки рекомендаций;
• конфигурируемые правила ранжирования по категориям;
• отдельная аутентификация администратора и менеджера;
• наблюдаемость и управляемая синхронизация для пилотной среды.