Documentação
Visão geral de como o gage_manager funciona: o que ele é, o modelo de dados das estações, cada funcionalidade desta interface e como a autenticação se encaixa.
Visão geral
O gage_manager é o cadastro mestre de estações fluviométricas/pluviométricas da CPRM. Ele centraliza os dados de cada estação (código, sensor, bacia, coordenadas, etc.), permite importar cadastros em lote a partir de planilha, sincronizar informações com a ANA (Agência Nacional de Águas) e controlar a visibilidade das estações em mapas consumidos por outros sistemas (como o station_maps).
Arquitetura hexagonal (clean architecture): as rotas HTTP (camada de aplicação) chamam casos de uso e serviços de domínio, que dependem de interfaces (ports) implementadas por adaptadores de infraestrutura — repositório MongoDB, autenticação JWT e cliente HTTP da ANA.
Stack: FastAPI (Python) como backend HTTP, MongoDB como banco de dados (coleção estacoes, com índice único em codigo_estacao), e autenticação via JWT (Bearer token). Esta interface (Next.js) fala com o backend exclusivamente através de um proxy interno — o backend não expõe CORS para o browser.
Modelo de dados — StationModel
O StationModel tem 20 campos: 6 obrigatórios e 14 opcionais (com valor padrão, não obrigatórios no envio) — dado_manual e data_forecastentre eles. Destes 14, 13 são campos de formulário genéricos (listados abaixo) e um,view_map, tem tratamento próprio: nas telas de criação/edição ele aparece como um toggle separado (fora da lista de campos opcionais), e na listagem pode ser alternado em lote — por isso ele é mostrado à parte no card abaixo, não dentro do grid.
Campos obrigatórios
pontotextIdentificador do ponto de monitoramento (texto livre).
codigo_estacaotextCódigo da estação — chave única no MongoDB (índice uk_codigo_estacao). Usado como identificador em quase todas as rotas.
id_noaatextIdentificador da estação no sistema NOAA.
conversorintID do conversor do sensor (inteiro).
sensortextDescrição/tipo do sensor instalado na estação.
baciatextNome da bacia hidrográfica da estação.
Campos opcionais
nome_estacaotextNome amigável da estação, para exibição.
nome_baciatextNome amigável da bacia, para exibição.
rio_nometextNome do rio associado à estação.
altitudetextAltitude em metros acima do nível do mar. Campo texto (string), não número, mesmo sendo uma coordenada.
latitudetextLatitude da estação. Campo texto (string), não número.
longitudetextLongitude da estação. Campo texto (string), não número.
data_periodo_escala_iniciodatetime-localData/hora de início do período de escala (datetime ISO).
dado_manualboolIndica se os dados da estação foram inseridos manualmente (booleano, padrão false).
data_forecastboolIndica se a estação possui previsão associada (booleano, padrão false).
cota_minintCota mínima registrada (inteiro).
janelaintJanela temporal de previsão, em horas (inteiro).
previsaointQuantidade de horas a prever (inteiro).
hybas_idtextCódigo HYBAS da estação, usado pela integração com o Google Flood Hub via flood_api. Opcional — estações cadastradas antes desta funcionalidade ainda não têm esse dado preenchido.
Campo com tratamento próprio
view_mapboolControla se a estação aparece no mapa (booleano, padrão true).
Total: 20 campos (19 listados nos grids acima + view_map). O MongoDB é schemaless — não houve necessidade de migração ao adicionar hybas_id; documentos antigos simplesmente não têm esse campo até serem editados.
Funcionalidades
Listar e buscar estações
Lista todas as estações cadastradas, com filtro por dados_estacao_manual, e permite buscar uma estação específica pelo código.
GET /stations — lista (não requer login)
GET /stations/{codigo_estacao} — busca por código (não requer login)
Criar estação
Cadastra uma nova estação preenchendo os 6 campos obrigatórios e, opcionalmente, os demais. Atenção: esta rota é um upsert — se o codigo_estacao já existir, o registro é sobrescrito.
POST /stations — requer login
Editar estação
Carrega os dados atuais de uma estação e permite editá-los, inclusive a visibilidade no mapa (view_map). Salvar usa a mesma rota de criação (upsert por código).
GET /stations/{codigo_estacao} — carregar dados
POST /stations — salvar (requer login)
Excluir estação
Remove definitivamente uma estação do cadastro, pelo código.
DELETE /stations/{codigo_estacao} — requer login
Importar planilha
Cadastra várias estações de uma vez a partir de um arquivo CSV/TXT (encoding latin1, delimitador ; ou , autodetectado). Formato: 6 colunas obrigatórias na ordem ponto, codigo_estacao, id_noaa, conversor, sensor, bacia, seguidas de até 13 colunas opcionais (incluindo hybas_id como última coluna). Arquivos .xlsx não são suportados — o parser é CSV puro. O checkbox upsert_existing controla se estações já cadastradas devem ser atualizadas (por padrão, duplicatas são apenas ignoradas e reportadas).
POST /station/import — multipart/form-data, requer login
Sincronizar com a ANA
Atualiza os dados de uma ou todas as estações a partir da API da Agência Nacional de Águas (ANA). A sincronização de todas as estações pode demorar, pois depende da API externa responder para cada estação.
POST /stations/sync-ana — todas, requer login
POST /stations/{codigo_estacao}/sync-ana — individual, requer login
Atualizar visibilidade no mapa
Alterna se uma ou várias estações aparecem no mapa (view_map), sem precisar reenviar o cadastro completo. Suporta uma única estação ou uma lista, o que permite ações em lote na listagem.
PATCH /stations/view-map — individual ou em lote, requer login
Autenticação
O gage_manager usa um usuário único compartilhado (credenciais configuradas no ambiente do backend) — não há contas por pessoa nem trilha de auditoria de quem criou, editou ou excluiu cada estação.
O login gera um token JWT válido por 8 horas. Nesta interface, o token fica guardado em um cookie httpOnly — ele nunca fica acessível ao JavaScript do navegador, o que reduz o risco de vazamento por XSS. Todas as chamadas ao backend passam por um proxy interno do servidor, que injeta o cabeçalho Authorization a partir desse cookie.
Ações de leitura (listar e buscar estações) não exigem login. Ações que alteram dados — criar, editar, excluir, importar planilha, sincronizar com a ANA e alterar visibilidade no mapa — exigem estar autenticado, porque modificam o cadastro de produção usado por outros sistemas.