Desenhar Linhas no Mapa¶

Resumo rápido:
Crie cabos de fibra óptica, dutos, cordoalhas e outros elementos lineares diretamente no mapa com cliques precisos. O sistema calcula automaticamente as distâncias e permite conexões inteligentes com pontos existentes.

Por que existe¶

Documentar infraestrutura de rede exige mapear com precisão cabos, dutos e outras conexões entre equipamentos. Esta ferramenta permite:

✅ Desenhar traçados de fibra óptica entre POPs, caixas de emenda e equipamentos
✅ Documentar dutos subterrâneos ou aéreos
✅ Registrar cordoalhas e cabos mensageiros
✅ Calcular distâncias reais automaticamente
✅ Conectar automaticamente a equipamentos existentes (snap to point)

Quickstart (2 minutos)¶

Abra o mapa e clique no botão de desenhar cabo no topo da página (ícone de localização)
Clique no mapa para adicionar cada ponto do traçado
Preencha o formulário que aparece no canto superior direito:
Nome do elemento (obrigatório)
Tipo (cabo de fibra, duto, cordoalha, etc.)
Observações (opcional)
Pressione S ou clique em "Salvar" para finalizar

💡 Dica: O sistema mostra uma linha pontilhada cinza seguindo seu cursor como preview do próximo segmento!

Passo a passo detalhado¶

1. Ativar a ferramenta de desenho¶

No cabeçalho da aplicação, localize os botões de acesso rápido e clique no ícone de localização (primeiro botão):

[📍] [📏]
 ↑
Clique aqui

Assim que ativar, você verá:

Um painel flutuante no canto superior direito com o formulário
O cursor do mouse mudará de comportamento
Status: "Clique no mapa para adicionar pontos"

2. Adicionar pontos no traçado¶

Clique no mapa para adicionar cada vértice da linha:

Primeiro clique: Define o ponto inicial
Cliques seguintes: Adicionam vértices intermediários
Marcadores azuis aparecem em cada ponto
Linha azul sólida conecta os pontos confirmados
Linha cinza pontilhada segue o cursor como preview

Snap Automático

Se você clicar próximo a um equipamento existente (dentro de 10 metros), o sistema automaticamente "gruda" o ponto no equipamento. Isso garante conexões precisas!

3. Preencher informações¶

No painel lateral direito, preencha:

Nome (obrigatório)¶

Nome descritivo do elemento. Exemplos: - Cabo Fibra - POP Centro até CTO Rua Principal - Duto Subterrâneo - Trecho A - Cordoalha Aérea - Quarteirão 5

Tipo (obrigatório)¶

Escolha o tipo de elemento:

Cabo de Fibra Óptica — Cabo com fibras ópticas
Duto — Duto subterrâneo ou conduite
Cordoalha — Cabo mensageiro ou cordoalha de sustentação
Cabo Aéreo — Cabo instalado em postes

Observações (opcional)¶

Informações adicionais: - Número de fibras - Fabricante - Data de instalação - Capacidade - Estado de conservação

4. Acompanhar o progresso¶

O painel mostra em tempo real:

Informação	Descrição
Pontos	Quantidade de vértices adicionados
Distância	Distância total acumulada (em metros ou km)

Cálculo de Distância

A distância é calculada usando a geometria esférica da Terra (Google Maps Geometry Library), garantindo precisão mesmo em grandes distâncias.

5. Finalizar ou cancelar¶

Salvar a linha¶

Você tem 3 formas de salvar:

Botão "Salvar" no painel
Tecla S no teclado
~~Duplo-clique no mapa~~ (removido)

Validação

O botão "Salvar" só fica habilitado quando:

✅ Há pelo menos 2 pontos
✅ O nome foi preenchido (mínimo 3 caracteres)

Desfazer último ponto¶

Se cometeu um erro no último clique:

Botão "Desfazer Último Ponto" no painel, ou
Ctrl+Z (Windows/Linux) / Cmd+Z (Mac)

Você pode desfazer múltiplas vezes até remover todos os pontos.

Cancelar tudo¶

Se quiser descartar o desenho completamente:

Botão "Cancelar" no painel, ou
Tecla ESC no teclado

Uma confirmação será exibida antes de descartar o progresso.

Atalhos de teclado¶

Tecla	Ação	Observações
S	Salvar linha	Só funciona se a linha for válida (2+ pontos e nome preenchido)
Ctrl+Z	Desfazer último ponto	Remove o último vértice adicionado
ESC	Cancelar e fechar	Descarta todo o progresso após confirmação

Digitando no formulário

A tecla S não interfere quando você está digitando em campos de texto (nome ou observações).

Exemplos de uso¶

Cenário 1: Cabo de fibra entre dois POPs¶

Situação: Você precisa documentar um cabo de 12 fibras entre o POP Centro e o POP Bairro Sul.

Passo a passo:

Ative a ferramenta de desenho
Clique no POP Centro (o sistema fará snap automático)
Adicione pontos intermediários representando:
Caixas de emenda pelo caminho
Curvas na rota
Postes onde o cabo passa
Clique no POP Bairro Sul (snap automático novamente)
Preencha:
Nome: Cabo Fibra 12FO - POP Centro → POP Sul
Tipo: Cabo de Fibra Óptica
Observações: 12 fibras monomodo, fabricante XYZ, instalado em 2023
Pressione S para salvar

Resultado: Linha criada com distância calculada automaticamente (ex: 2.35 km).

Cenário 2: Duto subterrâneo com múltiplas curvas¶

Situação: Documentar um duto subterrâneo que passa por baixo de várias ruas.

Passo a passo:

Ative a ferramenta
Clique no ponto de entrada do duto
Adicione um ponto a cada curva ou mudança de direção
Seja preciso nos vértices para refletir o traçado real
Clique no ponto de saída
Preencha:
Nome: Duto Subterrâneo - Quarteirão A
Tipo: Duto
Observações: Diâmetro 50mm, profundidade 80cm
Salve com S

Cenário 3: Cordoalha aérea em linha reta¶

Situação: Registrar uma cordoalha entre dois postes em linha reta.

Passo a passo:

Ative a ferramenta
Clique no primeiro poste
Clique no segundo poste (apenas 2 pontos)
Preencha:
Nome: Cordoalha Aérea - Poste 123 → 124
Tipo: Cordoalha
Salve com S

Observação: O sistema calcula automaticamente a distância entre os postes (ex: 45.2m).

Configurações e comportamentos¶

Snap to Point (conexão automática)¶

O sistema detecta automaticamente quando você clica próximo a um equipamento existente (dentro de um raio de 10 metros).

Como funciona:

Você clica no mapa perto de um equipamento
O sistema calcula a distância entre o clique e equipamentos próximos
Se houver algum dentro do raio de snap, o ponto "gruda" automaticamente
Um log é exibido no console do navegador: "Snap aplicado! Distância: X metros"

Vantagens:

✅ Garante conexões precisas
✅ Evita pequenos desalinhamentos visuais
✅ Facilita conectar múltiplos cabos no mesmo equipamento

Configuração futura

Em versões futuras, o raio de snap poderá ser configurável nas preferências do usuário.

Cálculo de distância¶

A distância é calculada utilizando a Google Maps Geometry Library, que considera:

Curvatura da Terra
Coordenadas geográficas precisas (latitude/longitude)
Distância geodésica entre pontos

Formatação automática:

Menos de 1000 metros → exibido em metros (ex: 245.80 m)
1000 metros ou mais → exibido em quilômetros (ex: 2.35 km)

Validações¶

O sistema realiza validações antes de salvar:

Validação	Regra	Mensagem de erro
Pontos mínimos	Pelo menos 2 pontos	"A linha precisa ter pelo menos 2 pontos"
Nome obrigatório	Campo não vazio	Campo marcado em vermelho
Nome mínimo	Mínimo 3 caracteres	"Nome é obrigatório (mínimo 3 caracteres)"

Perguntas frequentes¶

Como editar uma linha já criada?¶

R: No momento, a ferramenta permite apenas criar novas linhas. A edição de linhas existentes será implementada em breve. Por enquanto, se precisar corrigir algo, você pode:

Deletar a linha existente
Desenhar novamente com as correções

Posso desenhar várias linhas ao mesmo tempo?¶

R: Não. O sistema permite apenas uma operação de desenho por vez. Após salvar ou cancelar a linha atual, você pode iniciar uma nova.

Como sei se o snap funcionou?¶

R: Quando o snap é aplicado, você verá:

O marcador se move ligeiramente para o ponto exato do equipamento
Uma mensagem no console do navegador: "Snap aplicado! Distância: X metros"

Em versões futuras, haverá um feedback visual mais claro (círculo de destaque).

Posso adicionar pontos em uma linha já salva?¶

R: Não no momento. Esta funcionalidade de edição avançada (adicionar, remover ou mover pontos individualmente) está planejada para versões futuras.

O que acontece se eu fechar o navegador sem salvar?¶

R: Atualmente, o progresso é perdido. Em versões futuras, implementaremos salvamento automático no navegador (localStorage) para recuperar rascunhos.

Quantos pontos posso adicionar em uma linha?¶

R: Tecnicamente, não há limite fixo, mas recomendamos até 100 pontos por motivos de performance. Para traçados muito longos, considere dividir em múltiplas linhas.

Como sei a distância de cada segmento individualmente?¶

R: No momento, o sistema mostra apenas a distância total acumulada. A exibição de distância por segmento (entre cada par de pontos) será adicionada em breve.

Solução de problemas¶

Os cliques não estão adicionando pontos¶

Possíveis causas:

✅ Verifique se a ferramenta está ativada (painel lateral deve estar visível)
✅ Tente clicar longe da linha fantasma cinza
✅ Recarregue a página e tente novamente

O botão "Salvar" está desabilitado¶

Verifique:

✅ Há pelo menos 2 pontos adicionados?
✅ O campo "Nome" está preenchido com pelo menos 3 caracteres?

A tecla S não está salvando¶

Verifique:

Você está digitando em um campo de texto? (A tecla S é desabilitada durante a digitação)
A linha é válida? (2+ pontos e nome preenchido)

O snap não está funcionando¶

Possível causa: Os pontos próximos ainda não foram carregados. Por enquanto, o sistema usa dados mock. Na versão final, os pontos serão carregados automaticamente da viewport do mapa.

Roadmap de melhorias¶

Funcionalidades planejadas para futuras versões:

Em breve¶

[ ] Cores dinâmicas: Preview da linha com a cor do tipo selecionado
[ ] Highlight visual: Círculo destacando o ponto quando snap é aplicado
[ ] Integração com API real: Salvar no backend e buscar tipos de item reais
[ ] Snap to points real: Buscar equipamentos existentes automaticamente

Planejado¶

[ ] Distância por segmento: Labels mostrando a distância entre cada par de pontos
[ ] Edição de linhas: Mover, adicionar ou remover pontos de linhas já salvas
[ ] Clique direito em marcador: Remover ponto específico sem desfazer todos
[ ] Rascunho automático: Salvar progresso no navegador para recuperar após refresh
[ ] Validações avançadas: Impedir linhas auto-intersectantes, pontos muito próximos, etc.

Referências¶

Documentação técnica (desenvolvedores): /docs-dev/architecture/09-map-tools.md
Guia de desenvolvimento: /docs-dev/development/map-tools-guide.md
Status de implementação: /docs-dev/development/draw-polyline-tool-status.md
Google Maps Geometry Library: Documentação oficial

Suporte¶

Em caso de dúvidas ou problemas:

Verifique a seção "Perguntas frequentes" acima
Consulte a seção "Solução de problemas"
Entre em contato com o suporte técnico
Reporte bugs no sistema de issues do projeto

Última atualização: Dezembro 2025
Versão da funcionalidade: 1.0