Geodatin · ORA/OTCA

Módulo de Redes Hidrológicas — Integração com API vs. Dados Mockados

Relatório técnico do estado atual do módulo HydrologicalNetworks no client (React/Vite).

Repositório orav2 · branch develop · 02/06/2026 · escopo client/src/.../modules/HydrologicalNetworks + hooks/api/hydrologicalNetworks

O módulo já consome a API real para a camada de estações no mapa e o painel de detalhe de cada estação. Os agregados da aba "Visão geral" (gráficos por rede, por país, por variável e histórico de nível) ainda são mockados no front via queryFn com valores fixos — mesmo havendo, em vários casos, endpoint pronto no backend ainda não conectado.

5
hooks 100% na API
1
parcial (total real, seca/cheia mock)
4
hooks totalmente mockados
3
endpoints prontos, não plugados
API real Parcialmente mockado Mockado (valor fixo no front)

Visão consolidada

Como funciona: o QueryProvider tem uma queryFn padrão que faz api.get('/' + queryKey[0]). Logo, todo hook que não define queryFn própria bate na API real; os que definem queryFn retornando array fixo (com setTimeout de 500ms) são mock.

Widget / recursoHookOrigem dos dadosStatus
Camada de estações no mapa, filtros e lista de cards useHydroStations GET /hydro/stations (GeoJSON) API real
Painel da estação — metadados useHydroStationDetail GET /hydro/stations/:id API real
Painel da estação — última observação useHydroStationLatestObservation GET /hydro/stations/:id/latest/observation API real
Visão geral da estação (composição) useHydroStation compõe detail + latest observation API real
Histórico de precipitação useHydroStationSeries GET /hydro/stations/:id/series/rain/month API real
Cards de resumo (Total / Seca / Cheia) useHydrologicalNetworksCount GET /hydro/stations/count → só o total; seca e cheia são 0 fixos (MOCKED_STATE_COUNTS) Parcial
Total de estações por variável (donut) useHydrologicalNetworksTotalByVariable Array fixo no front · backend já tem GET /hydro/stations/count-by-variable Mock
Estações por tipo de rede (barras) useHydrologicalNetworksStationsByNetwork Array fixo no front · backend já tem GET /hydro/stations/count-by-type Mock
Distribuição de estações por países (ranking) useHydrologicalNetworksStationsRanking Array fixo no front · backend já tem GET /hydro/territories/:group/stations-ranking Mock
Histórico do nível médio (seca/cheia) useHydrologicalNetworksAverageLevelHistory Constante DEFAULT_DATA no front · sem endpoint no backend Mock
🚧
Aviso "Em construção" exibido na própria UI
i18n: hydrologicalNetworks.underConstruction.description
"Este módulo ainda está em construção. As estações e os dados mostrados aqui são apenas exemplos de demonstração — não representam informações reais e não devem ser usados para análises ou tomadas de decisão."

Aba "Visão geral" (Overview)

Ordem dos slots arrastáveis: under-construction → hydro-overview-cards → total-by-variable → stations-by-network → stations-ranking → average-level-history. Abaixo, a reprodução visual de cada slot com seus valores atuais.

Resumo das redes hidrológicas

Slot hydro-overview-cards · hook useHydrologicalNetworksCount

Parcial
Total API
547
Estado de seca mock = 0
0
Estado de cheia mock = 0
0
Print do widget — "Total" vem da API; "seca" e "cheia" são placeholders fixos em 0
TODO(api) no código: expor contagens por estado (ex. GET /hydro/stations/count?state=drought). Hoje só o total chega do backend. (547 é ilustrativo do total; o valor real depende do banco.)

Total de estações por variável

Slot total-by-variable · hook useHydrologicalNetworksTotalByVariable

Mock
Estações 547
Rede Hidrológica Amazônica
412
Nível d'água 250 · Vazão 162
Rede de Estações HYBAM
91
Sedimentos 46 · Temperatura 45
Rede de Qualidade da Água
44
Param. Químicos 22 · Param. Biológicos 22
Print do widget — donut por rede com subcategorias por variável (valores 100% fixos no front)
Mockado. O backend já expõe GET /hydro/stations/count-by-variable — falta apenas trocar a queryFn fixa pela chamada real.

Estações por tipo de Rede

Slot stations-by-network · hook useHydrologicalNetworksStationsByNetwork

Mock
Rede Hidrológica Amazônica
412
Rede de Estações HYBAM
91
Rede de Qualidade da Água
44
Print do widget — barras por tipo de rede (valores fixos no front)
Mockado. Backend já tem GET /hydro/stations/count-by-type disponível para conectar.

Distribuição de estações por países

Slot stations-ranking · hook useHydrologicalNetworksStationsRanking

Mock
🇧🇷 Brasil
466
🇵🇪 Peru
42
🇧🇴 Bolívia
20
🇨🇴 Colômbia
10
🇪🇨 Equador
5
🇻🇪 Venezuela
4
Print do widget — ranking de países (valores fixos no front)
Mockado. Backend já tem GET /hydro/territories/:territoryGroup/stations-ranking (com paginação e filtros) disponível para conectar.

Histórico do nível médio

Slot average-level-history · hook useHydrologicalNetworksAverageLevelHistory

Mock
cm 2022 2023 2024–25
seca enchente
Print do widget — duas séries (seca/cheia) sobre 12 datas fixas em DEFAULT_DATA
Mockado, sem backend. Diferente dos demais, este widget não tem endpoint correspondente no backend — os 12 pontos vêm de uma constante no hook.

Aba "Painel da estação" (StationPanel)

Aberta ao selecionar uma estação. Ordem: under-construction → station-overview → precipitation-history. Aqui os dados são reais.

Visão geral da estação

Slot station-overview · hook useHydroStation (detail + latest)

API real
Estação Manacapuru
🇧🇷 Brasil · Última atualização: Há 2 horas
Precipitação
12 mm/dia
Nível
640 cm
Vazão
28.500 m³/s
Print do widget — nome, país, última leitura e 3 métricas (valores ilustrativos; estrutura real vinda da API)
API real. Nome/país/coordenadas de GET /hydro/stations/:id; precipitação, nível e vazão da .../latest/observation. Quando não há leitura, exibe "—".

Histórico de precipitação

Slot precipitation-history · hook useHydroStationSeries('rain','month')

API real
mm
Print do widget — série mensal de precipitação (estrutura ilustrativa; dados reais de /series/rain/month)
API real. Se a estação não tiver série, mostra "Não há dados de precipitação para esta estação."

Mapa, filtros e cards de estação

Fora da sidebar, três peças compartilham a mesma fonte real useHydroStations (GET /hydro/stations):

Cores das redes (em config/hydroStations.ts): Amazônica #2E90FA (ANA) · HYBAM #09BC0F · Qualidade da Água #F65C05 (ANA). Anéis: seca #F4842A, cheia #FF6C7B.

Backend já pronto, mas não conectado no client

Endpoints de hydro existentes na API (controllers NestJS) que o front ainda não consome:

EndpointO que resolveria
GET /api/hydro/stations/count-by-variableSubstituiria o mock do donut "Total por variável"
GET /api/hydro/stations/count-by-typeSubstituiria o mock de "Estações por tipo de rede"
GET /api/hydro/territories/:group/stations-rankingSubstituiria o mock do "Ranking por países"
GET /api/hydro/stations/:id/water-level-permanenceSem consumidor no front (nenhum hook)
GET /api/hydro/series/variablesSem consumidor no front (nenhum hook)
Resumo da pendência de integração: 3 widgets mockados já têm endpoint pronto (basta remover a queryFn fixa); seca/cheia dos cards e o histórico de nível médio ainda dependem de novos endpoints; e 2 endpoints existentes ainda não têm hook no client.
Reprodução visual dos widgets ("prints") feita a partir dos valores e rótulos exatos do código-fonte (i18n pt-BR, hooks e configs do módulo). Identidade visual espelhada do playbook Geodatin (paleta editorial, tipografia Geist, bordas e sombras hard-edge), com modos claro e escuro.
Arquivos-base: client/src/hooks/api/hydrologicalNetworks/*, client/src/pages/Dashboard/Sidebar/Content/modules/HydrologicalNetworks/*, client/src/providers/QueryProvider.tsx, api/src/infra/http/controllers/hydro/*.