Изменение API DashboardService

[oveeernight]

Изменение API DashboardService: лидерборд и консолидация аналитических запросов

Суть изменений

1. Добавить «Лидерборд агентов» — новый эндпоинт Top Agents для витрины продаж и геймификации.
2. Провести унификацию аналитических запросов (Total Sales, Agents Sales, Sales Trends):
   • перевести с POST на GET для кэшируемых, идемпотентных чтений;
   • упростить и стандартизировать структуру ответов под сценарии дашборда и внешних интеграций.

Это улучшит совместимость с API-шлюзом и CDN, ускорит ответы и упростит интеграцию BI-инструментов. Изменения содержат breaking change и намеренно затрагивают текущие E2E-тесты.

Бизнес-ценность

• Прозрачная витрина эффективности агентов (мотивация, конкуренция, фокус на результат).
• Снижение латентности и стоимости за счет кэширования GET-запросов на шлюзе и CDN.
• Стандартизированные ответы: проще подключать дашборды, смартфонные виджеты, внешние отчеты.
• Готовность к масштабированию трафика на чтение без нагрузки на бекенд (edge caching).

Изменение 1: Новый эндпоинт «Top Agents» (не ломающий)

• Метод: GET
• Путь: /api/Dashboard/top-agents
• Назначение: вернуть рейтинг агентов за период с опциональной фильтрацией по продукту, сортировкой и пагинацией.
• Параметры (query): productCode?, salesDateFrom, salesDateTo, sortBy=premiumAmount|policiesCount (default=premiumAmount), order=asc|desc (default=desc), limit (1..100, default=10), offset (>=0, default=0).
• Ответ (JSON):
  • total — общее число агентов, подходящих под фильтр;
  • items[] — элементы рейтинга: rank, agentLogin, sales { policiesCount, premiumAmount }.

Пример использования: топ-5 агентов по количеству полисов за квартал для витрины в веб-клиенте и push-виджета для мобильного приложения.

Изменение 2: Унификация текущих аналитических эндпоинтов (ломающий блок)

Что меняется и почему:

• Перевод на GET повышает кэшируемость и снижает задержки в сценариях чтения.
• Единообразные поля в ответах помогают фронтендам и интеграциям проще переиспользовать компоненты.

Затрагиваемые эндпоинты и контракты:

1. Total Sales

   • Было: POST /api/Dashboard/total-sales, тело: { salesDateFrom, salesDateTo }, ответ: { total { policiesCount, premiumAmount }, perProductTotal { [code]: SalesDto } }
   • Стало: GET /api/Dashboard/total-sales?salesDateFrom=...&salesDateTo=...
     Ответ: { overall: { policiesCount, premiumAmount }, byProduct: [{ productCode, sales: { policiesCount, premiumAmount } }] }

2. Agents Sales

   • Было: POST /api/Dashboard/agents-sales, тело: { agentLogin?, productCode?, salesDateFrom, salesDateTo }, ответ: { perAgentTotal: { [agentLogin]: SalesDto } }
   • Стало: GET /api/Dashboard/agents-sales?salesDateFrom=...&salesDateTo=...&agentLogin=...&productCode=...
     Ответ: { items: [{ agentLogin, sales: { policiesCount, premiumAmount } }] }

3. Sales Trends

   • Было: POST /api/Dashboard/sales-trends, тело: { productCode?, salesDateFrom, salesDateTo, unit }, ответ: { periodsSales: [{ periodDate, period, sales }] }
   • Стало: GET /api/Dashboard/sales-trends?salesDateFrom=...&salesDateTo=...&productCode=...&unit=Day|Week|Month|Quarter
     Ответ: { periods: [{ date, label, sales: { policiesCount, premiumAmount } }] }

Ключевые несовместимости (breaking change):

• Методы запросов: POST -> GET.
• Параметры переносятся из тела запроса в query-параметры.
• Переименование полей в ответах:
  • total -> overall (Total Sales), perProductTotal -> byProduct (массив объектов);
  • perAgentTotal (map) -> items (массив пар agentLogin + sales);
  • periodsSales -> periods; periodDate -> date; period -> label.

Влияние на существующие E2E-тесты

Следующие тесты в DashboardService.E2ETest ожидаемо перестанут проходить до внесения изменений в тесты/код:

• PolicyServiceToDashboardServiceIntegrationTest.PolicyCreation_Should_UpdateDashboardAnalytics
  • Делает POST на /api/Dashboard/total-sales и /api/Dashboard/agents-sales и проверяет поля Total и PerAgentTotal.
• PolicyServiceToDashboardServiceIntegrationTest.MultiplePoliciesWithDifferentAgents_Should_ShowCorrectAggregation
  • Делает POST на /api/Dashboard/total-sales, /api/Dashboard/agents-sales и /api/Dashboard/sales-trends, опирается на поля Total, PerAgentTotal и PeriodsSales.

Причина падений:

• Изменены HTTP-методы (POST -> GET) и имена полей в ответах (overall, items, periods). Также изменён формат агрегации по продуктам (массив вместо map).

План миграции и совместимость

• Версия API: 2.0 (major).
• Для поэтапного перехода опционально можно временно держать старые POST-роуты как /api/Dashboard/legacy/* (deprecated) в течение одного релизного цикла, но в этом документе зафиксирован вариант с немедленным переведом (чистый breaking change).
• Гайд по миграции клиентов:
  • заменить POST на GET и перенести параметры в query-строку;
  • обновить парсинг полей ответов согласно новым именам;
  • пересмотреть логику, зависящую от map-структур, на работу с массивами.

Изменения на шлюзе и наблюдаемость

• Api Gateway/Ocelot: добавить маршруты для GET эндпоинтов и удалить/перенаправить POST.
• Включить кэширование на уровне шлюза/CDN по ключам query-параметров, TTL согласовать с продуктом (напр., 60–120 с).
• Логирование: запросы с ключевыми параметрами (диапазон дат, продукт, агент), время обработки, размер ответа, кэш-хиты.

Нефункциональные цели

• P95 ответа: ≤ 300 мс при прогретом кэше, ≤ 700 мс на холодном пути.
• Корректная пагинация и сортировка для Top Agents (limit ∈ [1,100], offset ≥ 0).
• Стойкость к пиковым нагрузкам чтения за счет edge-кэширования.

OpenAPI (высокоуровневый фрагмент)

• GET /api/Dashboard/top-agents → { total, items[{ rank, agentLogin, sales{ policiesCount, premiumAmount } }] }
• GET /api/Dashboard/total-sales → { overall{ ... }, byProduct[{ productCode, sales{ ... } }] }
• GET /api/Dashboard/agents-sales → { items[{ agentLogin, sales{ ... } }] }
• GET /api/Dashboard/sales-trends → { periods[{ date, label, sales{ ... } }] }

Примечание: детальное OpenAPI-описание будет обновлено в DashboardService-openapi.json в рамках реализации.