vector/STATS_API.md

Stats Service API - Статистические рекомендации и агрегаты

Endpoints

GET /api/v1/stats/summary

Получить агрегированную статистику для дашборда.

Response:

{
  "total_cases": 8,
  "active_cases": 7,
  "closed_cases": 1,
  "by_gender": {"М": 8},
  "by_age_group": {
    "8-11": 6,
    "12-14": 2
  },
  "by_psychotype": {},
  "by_diagnosis": {"здоров": 3},
  "by_season": {
    "зима": 3,
    "весна": 1,
    "лето": 1
  },
  "avg_distance_km": 2.3,
  "avg_search_duration_hours": 4.5,
  "survival_rate": 100.0
}

POST /api/v1/stats/recommendation

Получить статистические рекомендации на основе похожих случаев.

Фильтры (в порядке приоритета):

1. Возраст ±2 года + сезон + terrain
2. Возраст ±2 года + сезон (если < 5 случаев)
3. Возраст ±2 года (если < 5 случаев)
4. Все случаи (если < 5 случаев)

Request:

{
  "age": 10,
  "season": "лето",
  "terrain_primary": "лес"
}

Response:

{
  "median_distance_km": 2.3,
  "top_directions": [
    {
      "direction": "СВ",
      "count": 1,
      "percentage": 100.0
    }
  ],
  "top_location_types": ["forest"],
  "survival_rate": 100.0,
  "sample_size": 1,
  "filters_used": {
    "age_range": "8 to 12",
    "season": "лето",
    "terrain": "лес"
  }
}

GET /api/v1/stats/heatmap

Получить данные для тепловой карты находок.

Query Parameters:

• age_min (optional): Минимальный возраст
• age_max (optional): Максимальный возраст
• season (optional): Сезон
• outcome (optional): Исход (alive/deceased)

Response:

{
  "points": [
    {
      "lat": 53.9,
      "lon": 27.56,
      "intensity": 1.0,
      "case_id": "uuid",
      "distance_km": 2.3,
      "outcome": "alive"
    }
  ],
  "total": 1
}

Функции stats_service.py

get_statistical_recommendation()

SQL выборка похожих случаев с фильтрами:

• Возраст ±2 года
• Сезон
• Terrain (тип местности)
• Минимум 5 случаев для выборки

Возвращает:

• median_distance_km - медианное расстояние находки
• top_directions - топ-3 направления с процентами
• top_location_types - топ-5 типов локаций
• survival_rate - процент выживаемости
• sample_size - размер выборки
• filters_used - использованные фильтры

get_dashboard_stats()

Агрегаты для дашборда:

• Общее количество случаев (всего, активных, закрытых)
• Распределение по полу, возрасту, психотипу, диагнозам, сезонам
• Средняя дистанция находки
• Средняя длительность поиска
• Процент выживаемости

get_heatmap_data()

Данные для тепловой карты с фильтрами:

• Возраст (min/max)
• Сезон
• Исход (alive/deceased)

Тестирование

# 1. Получить агрегаты дашборда
curl http://localhost:8000/api/v1/stats/summary

# 2. Получить статистические рекомендации
curl -X POST http://localhost:8000/api/v1/stats/recommendation \
  -H "Content-Type: application/json" \
  -d '{"age": 10, "season": "лето", "terrain_primary": "лес"}'

# 3. Получить данные для тепловой карты
curl "http://localhost:8000/api/v1/stats/heatmap?age_min=8&age_max=12"

Протестировано (2026-05-05)

✅ GET /api/v1/stats/summary - работает ✅ POST /api/v1/stats/recommendation - работает ✅ GET /api/v1/stats/heatmap - работает

Технические детали

• Синхронная SQLAlchemy (не async)
• PostgreSQL ARRAY - используется any() вместо contains()
• Fallback механизм - если выборка < 5 случаев, расширяются фильтры
• Pydantic модели - валидация входных/выходных данных

Дата создания

2026-05-05