Endpoints de Dashboard

Visão Geral

A API de Dashboard fornece insights em tempo real sobre operações de fazendas, desempenho de lotes e métricas de produção com análises abrangentes.

Atualizado em b1.3.1

A resposta de /dashboard/overview foi redesenhada para a home MVP com top/pior lote e gráfico de biomassa dos últimos 30 dias.

Todos os endpoints requerem autenticação.

Authorization: Bearer <token>

---

GET /dashboard/overview

Obter KPIs consolidados para a home, incluindo top/pior lote, top viveiro, tendência de biomassa e alertas críticos.

Requisição

GET /api/v1/dashboard/overview?farm_id={farm_id}
Authorization: Bearer <token>

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
farm_id	UUID	✅	ID da fazenda

Resposta 200 OK

{
  "farm_id": "farm-uuid",
  "farm_name": "Fazenda Alpha",
  "top_batch": {
    "batch_id": "batch-top-uuid",
    "batch_code": "LOTE-2026-004",
    "pond_name": "Viveiro 07",
    "growth_rate_g_day": 0.156,
    "survival_rate_percentage": 95.5,
    "days_of_culture": 45,
    "current_biomass_kg": 1250.5
  },
  "worst_batch": {
    "batch_id": "batch-risk-uuid",
    "batch_code": "LOTE-2026-002",
    "pond_name": "Viveiro 03",
    "growth_rate_g_day": 0.065,
    "survival_rate_percentage": 78.2,
    "days_of_culture": 52,
    "current_biomass_kg": 420.3,
    "issues": ["low_growth", "low_survival"]
  },
  "top_pond": {
    "pond_id": "pond-uuid",
    "pond_name": "Viveiro 07",
    "total_batches_completed": 8,
    "avg_growth_rate_g_day": 0.148,
    "avg_survival_rate_percentage": 92.3,
    "avg_fca": 1.45,
    "success_score": 186.5
  },
  "total_biomass_kg": 5432.10,
  "avg_growth_rate_g_day": 0.142,
  "avg_survival_rate_percentage": 91.8,
  "biomass_chart": [
    {
      "date": "2026-02-05",
      "total_biomass_kg": 4500.0
    },
    {
      "date": "2026-02-12",
      "total_biomass_kg": 4800.0
    }
  ],
  "biomass_growth_percentage": 20.71,
  "critical_alerts": 2,
  "last_updated": "2026-03-05"
}

Notas

• top_batch é ranqueado por desempenho combinado de crescimento e sobrevivência.
• worst_batch.issues pode incluir: low_growth, low_survival, low_biomass, negative_growth.
• biomass_chart cobre os últimos 30 dias para visualização de tendência.

Breaking Changes em relação às versões anteriores

Campos removidos: active_batches_count, active_ponds_count, total_batches_biomass_kg, total_ponds, inactive_ponds, total_batches, finished_batches, total_alerts.

Campos adicionados: top_batch, worst_batch, top_pond, biomass_chart, biomass_growth_percentage.

---

GET /dashboard/ponds

Obter resumos detalhados de todos os viveiros de uma fazenda incluindo informações do lote atual e cálculos de biomassa.

Requisição

GET /api/v1/dashboard/ponds?farm_id={farm_id}
Authorization: Bearer <token>

Resposta 200 OK

{
  "ponds": [
    {
      "pond_id": "pond-uuid-1",
      "pond_cod": "VV-01",
      "pond_type": "FATTENING",
      "size_m2": 5000,
      "has_active_batch": true,
      "batch_id": "batch-uuid",
      "batch_number": "LOTE-2026-001",
      "days_in_production": 45,
      "current_population": 212500,
      "survival_rate": 85.0,
      "current_biomass_kg": 850.0,
      "biomass_per_m2": 0.17,
      "average_weight_g": 4.0,
      "status": "ACTIVE"
    }
  ]
}

---

GET /dashboard/biomass-trend

Obter crescimento histórico de biomassa ao longo do tempo para análise e visualização de tendências.

Requisição

GET /api/v1/dashboard/biomass-trend?batch_id={batch_id}
Authorization: Bearer <token>

Resposta 200 OK

{
  "batch_id": "batch-uuid",
  "batch_number": "LOTE-2026-001",
  "data_points": [
    {
      "date": "2026-01-08T00:00:00Z",
      "days_in_production": 0,
      "biomass_kg": 125.0,
      "average_weight_g": 0.5
    },
    {
      "date": "2026-02-19T00:00:00Z",
      "days_in_production": 42,
      "biomass_kg": 850.0,
      "average_weight_g": 4.0
    }
  ]
}

---

GET /dashboard/growth-rates

Obter análise de taxa de crescimento comparando peso atual vs peso esperado baseado em padrões da espécie.

Requisição

GET /api/v1/dashboard/growth-rates?farm_id={farm_id}
Authorization: Bearer <token>

Resposta 200 OK

{
  "batches": [
    {
      "batch_id": "batch-uuid",
      "batch_number": "LOTE-2026-001",
      "pond_cod": "VV-01",
      "days_in_production": 42,
      "species": "LITOPENAEUS_VANNAMEI",
      "current_weight_g": 4.0,
      "expected_weight_g": 4.2,
      "weight_difference_g": -0.2,
      "growth_rate_percent": 95.2,
      "status": "BELOW_EXPECTED",
      "weekly_growth_g": 0.67
    }
  ]
}

Status de Crescimento

Status	Descrição
ABOVE_EXPECTED	Crescendo mais rápido que o padrão
ON_TRACK	Crescendo de acordo com o padrão (±5%)
BELOW_EXPECTED	Crescendo mais devagar que o padrão

---

GET /dashboard/survival-rates

Obter monitoramento de taxa de sobrevivência comparando população atual vs inicial.

Requisição

GET /api/v1/dashboard/survival-rates?farm_id={farm_id}
Authorization: Bearer <token>

Resposta 200 OK

{
  "batches": [
    {
      "batch_id": "batch-uuid",
      "batch_number": "LOTE-2026-001",
      "pond_cod": "VV-01",
      "days_in_production": 42,
      "initial_population": 250000,
      "current_population": 212500,
      "survival_rate": 85.0,
      "mortality_count": 37500,
      "status": "GOOD"
    }
  ]
}

Status de Sobrevivência

Status	Limite	Descrição
GOOD	≥ 80%	Excelente taxa de sobrevivência
ACCEPTABLE	60-79%	Taxa de sobrevivência aceitável
POOR	< 60%	Taxa baixa, intervenção necessária

---

GET /dashboard/feed-efficiency

Obter análise de eficiência alimentar incluindo FCA (Fator de Conversão Alimentar) e custo por kg.

Requisição

GET /api/v1/dashboard/feed-efficiency?farm_id={farm_id}
Authorization: Bearer <token>

Resposta 200 OK

{
  "batches": [
    {
      "batch_id": "batch-uuid",
      "batch_number": "LOTE-2026-001",
      "pond_cod": "VV-01",
      "days_in_production": 42,
      "total_feed_kg": 340.0,
      "total_feed_cost": 5100.0,
      "current_biomass_kg": 850.0,
      "biomass_gained_kg": 725.0,
      "fca": 1.8,
      "cost_per_kg_feed": 15.0,
      "feed_cost_per_kg_shrimp": 27.0,
      "efficiency_status": "EXCELLENT"
    }
  ]
}

Status de FCA

Status	Faixa de FCA	Descrição
EXCELLENT	< 1.5	Eficiência alimentar excepcional
GOOD	1.5-2.0	Boa eficiência alimentar
ACCEPTABLE	2.0-2.5	Eficiência aceitável
POOR	> 2.5	Eficiência baixa, revisar estratégia

Nota

FCA (Fator de Conversão Alimentar) = Total de Ração (kg) / Ganho de Biomassa (kg). Valores menores indicam melhor eficiência.