6.4 Report Service и AI-рекомендации

BR 6.4: Report Service + AI-рекомендации

Демо 29.05.2026 — Сценарий 4 (часть 1)

Этот BR закрывает внутреннюю аналитику Сценария 4: KPI за 6 месяцев, графики выручки, топ-позиции, AI-рекомендации в человеческом виде («у тебя падают продажи веган-бургера на 42%, сними с меню»). Превью — HTML-демо.

Зависит от:

• Order Service — источник данных по заказам
• Warehouse Service — источник данных по списаниям и марже
• LLM-провайдер (TBD) — для AI-рекомендаций. Самописный erp-llm-gateway отказан 2026-05-13, нужен другой подход (платный API, OpenClaw, либо обращение напрямую к Ollama)

Контекст

Сейчас в админке только базовый DashboardPage (welcome + activity tab) и shift-report endpoint в Order Service (см. BR 2.2). Полноценной аналитики нет: ни KPI-дашборда, ни графиков, ни топ-позиций, ни AI-помощника. Report Service зарезервирован в roadmap (erp-report-service, порт 3011, Phase 4), но не создан.

Для демо 29.05 нужно показать продукт как аналитическую платформу: «ERP не просто учёт, а инструмент принятия решений». Лидер заходит в раздел «AI-аналитика» и видит понятный дашборд с KPI, графики выручки и сразу — AI-рекомендации в человеческом языке («у Coffee Lab появилось промо, потеряете 12% утра — запусти контр-промо»).

Что хочет бизнес

Маркетолог / владелец точки открывает «AI-аналитику» и видит за 3 секунды:

1. 4 KPI: выручка за 6 мес, кол-во заказов, средний чек, маржа — с трендом (% к прошлому полугодию)
2. График выручки по месяцам (bar chart)
3. Топ-5 позиций с тегами «⚡ Хит» / «Быстро»
4. AI-рекомендации — 3–5 утверждений на русском языке:
   • Растёт: «Спрос на круассаны вырос на 34%, подними закупку до 60 шт/день»
   • Просадка: «Веган-бургер: продажи −42%, маржа 12% — кандидат на снятие»
   • Связка: «Латте + пончик покупают вместе в 41% чеков — собери комбо за 450 ₽»

Функции «AI-аналитики»

1. Dashboard — основной экран с KPI, графиком, топ-позициями, рекомендациями
2. Фильтры — период (1m / 3m / 6m / YTD), ТТ (одна или все)
3. AI-помощник — асинхронный пересчёт рекомендаций (LLM получает агрегаты, выдаёт текст)
4. Экспорт — CSV / PDF выгрузка KPI (опционально для MVP)

Пользователи

Профиль	Кто	Permissions
Владелец франшизы	Видит всё по франшизе	analytics.read.all
Владелец партнёра	Видит свои ТТ	analytics.read (scope per owner_user_id см. Roles)
Менеджер ТТ	Видит свою ТТ	analytics.read
Кассир	Нет доступа	—

Сущности

report_aggregate (в report_db)

Pre-computed агрегаты для быстрых чтений:

Поле	Тип	Описание
id	UUID	PK
store_id	UUID
period_type	ENUM	day / week / month / quarter / half-year
period_start	DATE
revenue	DECIMAL
orders_count	INTEGER
avg_check	DECIMAL
margin_pct	DECIMAL
top_items	JSONB	[{product_id, qty, revenue, tags: ['hot', 'fast']}] (top 5–10)
computed_at	TIMESTAMPTZ

recommendation

Поле	Тип	Описание
id	UUID
store_id	UUID
type	ENUM	growth / decline / combo / seasonal
title	VARCHAR	Короткое
text	TEXT	Полное на русском
data_refs	JSONB	Какие агрегаты использовались
priority	INTEGER
generated_at	TIMESTAMPTZ
expires_at	TIMESTAMPTZ

API (новый report-service, порт 3011)

Метод	Путь	Описание
GET	/api/v1/admin/reports/kpi?store_id=&period=6m	4 KPI с трендом
GET	/api/v1/admin/reports/sales-trend?store_id=&period=6m&granularity=month	Точки для bar chart
GET	/api/v1/admin/reports/top-items?store_id=&period=6m&limit=5	Топ-позиций
GET	/api/v1/admin/reports/recommendations?store_id=	Текущие AI-рекомендации (cached)
POST	/api/v1/admin/reports/recommendations/regenerate?store_id=	Принудительный пересчёт LLM

Cron-job (внутри report-service)

• Каждый час: пересчёт report_aggregate за свежие данные (тянет из Order Service GET /internal/orders/aggregates?from=&to=&store_id=)
• Раз в день: запрос к LLM-провайдеру (TBD) для пересчёта recommendation

LLM-провайдер (открытый вопрос)

Решение пересмотрено 2026-05-13

Самописный сервис erp-llm-gateway отказан — не оправдал ожиданий. Нужно выбрать другой подход:

• обращение напрямую к Ollama через autossh-туннель (ADR-023)
• OpenClaw framework как proxy (ADR-022 rev 2)
• платный API (Yandex GPT, GigaChat) как fallback

Требования к решению, какое бы ни выбрали:

• Единая точка для LLM-запросов в продукте (report, OSINT BR 6.5, CV BR 6.6)
• Возможные модели: Qwen 2.5 14B (локально), Yandex GPT (платный fallback)
• OpenAI-compatible API: POST /v1/chat/completions

Что НЕ входит в текущий скоуп

• Cohort analysis по клиентам — Phase 2
• Drilldown в конкретный заказ из агрегата — Phase 2
• Кастомные дашборды (drag-and-drop виджеты) — Phase 2
• A/B тестирование рекомендаций — Phase 2
• Push-уведомления о критических метриках — Phase 2

Затронутые сервисы и продукты

Компонент	Что меняется
erp-report-service (новый)	Spring Boot, порт 3011, БД report_db, cron, REST API
LLM-провайдер	См. блок «LLM-провайдер (открытый вопрос)» выше. Самописный erp-llm-gateway отказан 2026-05-13
erp-order-service	Расширить /internal/orders/aggregates — нужен метод для агрегации за period (вероятно уже есть из BR 2.2 X/Z)
erp-warehouse-service	Расширить /internal/warehouse/cogs для расчёта маржи
admin-bff	Прокси для всех /reports/* эндпоинтов
erp-admin/web	Новый раздел «AI-аналитика» в левом меню, страница Dashboard с KPI / chart / top items / recommendations
erp-user-service	Permission analytics.read, analytics.read.all

Acceptance criteria для демо 29.05

1. В левом меню админки появился раздел «AI-аналитика»
2. Открытие раздела → дашборд за ≤ 2 секунды (данные precomputed)
3. 4 KPI отображаются с реальными цифрами за полгода (из seed-данных или реальных)
4. График выручки по 6 месяцам — bar chart как в HTML-превью
5. Топ-5 позиций с тегами «⚡ Хит» / «Быстро»
6. 3+ AI-рекомендации в человеческом виде, упоминают конкретные позиции и цифры
7. Можно сменить период через фильтр (1m / 3m / 6m) — данные обновляются
8. AI-рекомендации правдоподобные (LLM генерирует, не галлюцинирует — даны фиксированные prompts на русском)

Зависимости (см. ADR-022)

• LLM-инфраструктура: где хостим Llama/Qwen, сколько VRAM. Если ADR-022 ещё не решён, для демо можем стартануть с Yandex GPT как fallback (платно, но быстро) — пометить в плане
• Seed-данные за 6 месяцев — пользователь скинет данные с прода (см. план)

Ссылки

• HTML-превью демо
• ADR-022 — LLM-инфраструктура
• BR 6.5 — использует LLM-провайдер
• BR 6.6 — использует LLM-провайдер
• Order Service
• Warehouse Service
• Спека: AI-аналитика