README - Funcionalidades da API SmartCity

Esta API gerencia operações de nós (dispositivos/entidades), controle de acesso através de chaves com diferentes níveis de permissão, registros de dados e funcionalidades avançadas de geolocalização e rotas integradas ao Google Maps. A comunicação principal é feita passando o parâmetro acao via requisições GET ou POST [1].

📌 1. Gestão de Nós (Dispositivos/Locais)

Os "nós" representam as entidades principais que recebem ou enviam dados.

• novoNo: Cadastra um novo nó no banco de dados. O nome do nó é passado via formulário (POST) e salvo com status ativo [2, 3].
• carregaListaNo: Retorna uma lista formatada de todos os nós ativos cadastrados, exibindo seu código, nome e opções para editar, criar chave ou excluir [2, 4].

🔑 2. Gestão de Chaves de Acesso

Cada nó pode ter múltiplas chaves associadas, e cada chave possui uma permissão específica que dita o que ela pode fazer no sistema.

• novaChave: Gera uma nova chave única e aleatória de 30 caracteres alfanuméricos para um nó específico, vinculando-a a um tipo de permissão informado [5, 6].
• listarChaves: Exibe uma tabela com todas as chaves pertencentes a um determinado nó, mostrando suas permissões e status [7, 8].

📝 3. Manipulação de Registros (Ação: Registro)

A funcionalidade mais complexa da API é a ação Registro [3]. O comportamento desta rota muda drasticamente dependendo do nível de permissão da chave (de 1 a 9) que está fazendo a solicitação [9]:

• Permissão 1 (Inserção Básica): Salva um novo registro simples vinculado à chave e ao nó [9].
• Permissão 2 (Atualização/Inserção): Atualiza um registro existente para o nó ou cria um novo caso não exista [9-11].
• Permissão 3 (Leitura em Lista): Retorna todos os registros ativos daquele nó [11].
• Permissão 4 (Leitura Única): Retorna apenas o último (mais recente) registro gravado no nó [12].
• Permissão 5 (Exclusão Lógica): Desativa todos os registros daquele nó (muda o status para 0) [12].
• Permissão 6 (Exportação): Gera o download de um arquivo de texto (.txt) contendo todos os registros ativos do nó [13, 14].
• Permissão 7 (Gravação em Lote): Recebe vários dados separados por @ e os insere sequencialmente no banco de dados [14, 15].
• Permissão 8 (Aquisição de GPS): Recebe dados de telemetria (Latitude, Longitude, Temperatura, Satélites, Bateria) estruturados com ponto e vírgula. O sistema busca a rota definida para o nó e calcula automaticamente a distância entre a posição atual e o ponto mais próximo da rota, marcando se o dispositivo saiu do trajeto delimitado (limite de 30 metros) [15-20].
• Permissão 9 (Geração de Rota Baseada em Endereço): Recebe dados de origem e destino, converte-os em coordenadas via Google Geocoding API, traça a rota ideal usando Google Routes API, e salva os pontos codificados da rota no banco de dados [20-25].

🗺️ 4. Rotas e Mapas

A API fornece diversas ações nativas para trabalhar com coordenadas, cálculos de distância e renderização em mapas.

• gerarRotaEndereco: Traça uma rota veicular entre dois endereços de texto informados. Utiliza o Google Maps para converter os endereços em latitude e longitude e retorna um conjunto de pontos separados por @ [8, 26-28].
• gerarRota: Funciona de forma semelhante à geração por endereço, mas traça a rota recebendo diretamente as coordenadas geográficas exatas de origem e destino [29-31].
• buscarRota: Devolve a string de dados de uma rota previamente salva, validada através de uma chave [7].
• Endpoints JSON de Mapa (getRotaMapa, getAquisoesMapa, getMapaPorChave): Retornam dados prontos em formato JSON (arrays de latitude e longitude) contendo o traçado da rota e as aquisições de GPS para serem plotados diretamente em ferramentas de mapas no frontend. O endpoint centralizado getMapaPorChave inclusive cruza dados de rota com dados de temperatura e saídas de rota para visualização completa [32-38].

🗑️ 5. Exclusões e Limpezas Especiais

Além da exclusão geral de nó (Permissão 5), o sistema possui rotinas específicas de limpeza:

• deletarRegistros: Permite a exclusão lógica (status 0) de registros selecionados em massa passando um array de IDs [32, 39].
• ExcluirAquisoes: Validado estritamente por uma chave de permissão tipo 5 (exclusão), ele apaga permanentemente do banco de dados todos os registros de telemetria/GPS gerados por chaves de tipo 8 que pertencem àquele mesmo nó [40-42].
• listarRegistros: Permite vizualizar e listar os últimos 100 registros captados, de onde também é possível acionar botões para baixar arquivos ou excluir registros pontuais [4, 31].