Manual do Usuário — TRM SaaS (Travel Risk Management)

Guia completo de uso da plataforma: telas, ações e exemplos de preenchimento de dados. Para detalhes de arquitetura e desenvolvimento, veja CLAUDE.md e README.md.

---

Índice

1. Visão geral
2. Primeiros passos
3. Central de Risco
4. Equipe (Colaboradores)
5. Alertas e Notificações
6. Broadcast de Emergência e Check-in
7. Configurações
8. Integrações (Fontes de Risco)
9. Catálogo de conectores — como preencher cada um
10. Triagem e Filtro de Relevância
11. Guia de obtenção de acesso e credenciais
12. Privacidade e LGPD
13. Perguntas frequentes (FAQ)
14. Glossário A. Apêndice — Ambientes e acesso

---

1. Visão geral

O TRM SaaS cruza os itinerários dos seus colaboradores com eventos de risco georreferenciados (violência, clima severo, desastres, acidentes, avisos de viagem) e gera alertas automáticos quando alguém está — ou vai estar — perto de uma ameaça.

Fluxo essencial do dia a dia:

1. Cadastrar colaboradores  →  2. Registrar itinerários  →  3. Ingerir fontes de risco
                                                                       ↓
7. Consolidar multi-fonte  ←  6. Despachar notificações  ←  5. Processar alertas  ←  4. Cruzar itinerário × eventos

Conceitos-chave: - Tenant (empresa): cada empresa vive isolada em seu próprio espaço de dados. O painel de demonstração usa empresa_techcorp. - Evento de risco: um ponto no mapa (latitude/longitude) + raio de alcance + severidade (baixa/moderada/alta/extrema) + validade. - Cruzamento: o motor calcula a distância (fórmula de Haversine) entre o destino de um itinerário e cada evento ativo; se o destino cai dentro do raio, gera-se um alerta. - Alerta consolidado: card único que agrupa N eventos de M fontes sobre o mesmo fato — aumenta a confiança quando múltiplas fontes confirmam. - Geofence: zona de risco desenhada manualmente no mapa (polígono/retângulo) — gera alerta mesmo sem evento de risco cruzando.

---

2. Primeiros passos

2.1. Acessar

Abra o endereço do seu ambiente no navegador:

A tela de login exibe um card dividido: painel de marca à esquerda (gradiente + carrossel de taglines) e formulário de email/senha à direita. Use o checkbox "Lembrar-me neste navegador" para pular o login nos próximos acessos.

Credencial de demonstração: admin@techcorp.com.br / trm-demo-2026.

2.2. Anatomia da tela

A sidebar pode ser colapsada (ícone no topo) para ganhar espaço — o estado persiste entre sessões.

2.3. Barra lateral (ícones)

2.4. Busca contextual

O campo de busca na topbar filtra de acordo com a tela ativa: - Na Central de Risco → filtra itinerários (por colaborador ou destino). - Na Equipe → filtra colaboradores (por nome).

2.5. Acesso pelo celular

O painel completo foi desenhado para tela grande. Ao abrir o endereço num celular, você é levado automaticamente para a versão mobile — uma tela enxuta, pensada para consulta rápida em campo. Não é preciso digitar nenhum endereço diferente.

O que a versão mobile tem:

O que ela não tem: cadastro de colaboradores e itinerários, configurações, integrações, gráficos e camadas avançadas do mapa (calor, agrupamento, geofence, linha do tempo). Para essas ações, use o painel completo num computador.

Voltar ao painel completo. O link "Ver versão completa", no rodapé, abre o painel normal e passa a lembrar dessa preferência — você não será mais redirecionado automaticamente naquele navegador. Para voltar ao modo mobile, limpe os dados do site.

Instalar como aplicativo. A versão mobile pode ser adicionada à tela de início e abrir em tela cheia, com ícone próprio, como um app: - Android (Chrome): menu ⋮ → Adicionar à tela inicial. - iPhone (Safari): botão Compartilhar → Adicionar à Tela de Início.

Ela continua exigindo conexão — não há modo offline.

Login compartilhado. A sessão é a mesma do painel completo no mesmo navegador: quem já entrou no computador não precisa fazer login de novo ao abrir no celular, e vice-versa.

---

3. Central de Risco

Tela única que reúne a visão executiva (KPIs, gráficos, mapa) e a operação de risco (motor de ingestão/cruzamento, alertas consolidados, itinerários).

3.1. Cartões de KPI (topo)

• Colaboradores — total de pessoas cadastradas e ativas.
• Em viagem — itinerários com status "em andamento".
• Em área de risco — quantos colaboradores estão perto de um evento (cartão pulsa em vermelho se > 0).
• Alertas hoje — alertas gerados nas últimas 24 h.

Chip de saúde das fontes (na topbar, entre a busca e o sino de notificações) — visível em qualquer tela, sem precisar do token de admin. Mostra o total de fontes ativas, há quanto tempo foi a última ingestão, e um ponto colorido com a pior saúde do conjunto (verde = tudo ok, amarelo = alguma atrasada, vermelho = alguma com erro).

Clique no chip para abrir o detalhe — a mesma quebra ok/atrasada/erro/inativa do painel de Integrações (ver 8.2), com um atalho "Ver painel de integrações".

3.2. Barra de filtros (única)

Um único conjunto de filtros — data (de/até), categoria, severidade, fonte e o checkbox "Só multi-fonte" — afeta simultaneamente: - O mapa (círculos de evento). - Os gráficos (donut de severidade, tendência de alertas). - O painel Alertas Consolidados. - A tabela Itinerários & Cruzamentos (pelo risco/categoria/data atual do itinerário).

Botão Filtrar aplica; Limpar reseta tudo e recarrega sem filtro.

3.3. Gráficos

• Eventos por Severidade (donut) — distribuição dos eventos ativos filtrados.
• Tendência de Alertas (linha) — alertas gerados nos últimos 7 dias, com estatísticas de tendência (total, média/dia, delta com a semana anterior).
• Eventos por Categoria (donut) — distribuição por tipo de risco.
• Exposição — card com duas abas:
• Exposição da equipe — proporção de colaboradores em zona de risco.
• Regiões — distribuição geográfica dos eventos (top regiões).

3.4. O mapa

Mostra os eventos de risco ativos como círculos coloridos (a cor = severidade; o tamanho = raio). Clique num círculo para abrir um popup com título, categoria, severidade explicada em texto, fonte e data — e um link "🔎 Filtrar tabelas por este evento" que aplica o filtro único (3.2) automaticamente pela categoria/severidade/fonte daquele evento. Botão ↻ no cabeçalho recarrega.

3.5. Camadas do mapa

O menu Camadas (ícone no cabeçalho do mapa) organiza as camadas em três grupos. Várias camadas de densidade são mutuamente exclusivas entre si (ligar uma desliga a incompatível), mas todas coexistem com a camada Pessoas e com a Linha do tempo.

Densidade de risco

Operação

Tempo

3.5.1. Zonas de risco (geofencing)

Com a camada Zonas de risco ativa, use as ferramentas de desenho no canto superior direito do mapa (polígono ou retângulo) para marcar uma zona proibida ou zona de atenção. Ao terminar o desenho, informe um nome e o tipo da zona. O motor de risco passa a considerar o destino de cada itinerário contra essas zonas (ponto-dentro-do-polígono) — se o destino cair numa zona ativa, mesmo sem nenhum evento de risco cruzando, o itinerário recebe risco extrema (zona proibida) ou alta (zona de atenção), com categoria "Zona proibida (geofence)"/"Zona de atenção (geofence)".

3.6. Basemap, exportação e tela cheia

3.7. Alertas recentes

Feed lateral (ao lado do mapa) com os últimos alertas (rota, mensagem, tempo relativo).

3.8. Botões do motor de risco

• Sincronizar Tudo (botão principal) — roda o serviço completo em sequência: ingere eventos de todas as integrações ativas (ver seção 8, com deduplicação automática; fontes que falham registram erro sem interromper as demais), cruza todos os itinerários ativos gerando os alertas pendentes, e reconsolida os alertas multi-fonte (ver 3.9). Um toast marca cada etapa (1/3, 2/3, 3/3); o botão fica desabilitado com um spinner enquanto roda. Com ~130 fontes ativas consultadas uma a uma, a etapa de ingestão pode levar 1-2 minutos — é esperado, não travou.
• Processar Alertas — só a etapa de cruzamento (reusa os eventos já ingeridos, sem buscar as fontes de novo). Útil depois de editar um itinerário, quando não há fonte nova para buscar.
• Consolidar — só reconstrói os clusters multi-fonte (ver 3.9), sem ingerir nem processar alertas.
• Atualizar — recarrega a tela com os dados atuais, sem disparar nenhuma ação no motor.

Automação em segundo plano: o sistema roda três tarefas agendadas automaticamente: ingestão de fontes ativas (a cada 1 min), cruzamento de todos os itinerários (a cada 30 min) e despacho de alertas pendentes (a cada 2 min). Os botões manuais acima são para forçar uma execução imediata quando necessário.

3.9. Alertas consolidados (multi-fonte)

Cada card mostra: - Severidade máxima entre as fontes e a categoria. - Um ícone ▾ no canto superior direito indica que o card é clicável — clique em qualquer ponto do cabeçalho para expandir e ver fontes, atualizações e relacionados. - Fontes que confirmam (badges) — quando ≥ 2, aparece "N fontes" e a confiança sobe (fontes oficiais valem mais que notícia). Cada fonte tem um ícone ⓘ — passe o mouse para ver a manchete exata daquela fonte e a credibilidade atribuída a ela. - 🔄 Atualizações — trilha de mudanças de números (ex.: "mortos 10 → 12"), sem criar card novo. - 🔗 Relacionados — eventos do mesmo caso mas distintos ligados, não fundidos. - O checkbox "Só multi-fonte" do filtro único (3.2) restringe a lista a clusters com 2+ fontes.

Nesta versão a similaridade é textual (mesma língua). Notícias em idiomas diferentes sobre o mesmo evento ainda podem não fundir — o próximo degrau (embeddings multilíngues) está no roadmap.

3.10. Itinerários & cruzamentos

Um itinerário é uma viagem planejada de um colaborador (origem, destino, datas) — é o que o sistema cruza contra os eventos de risco. Esta tabela única concentra o cadastro completo (CRUD) e a visão de cruzamento (risco atual, categoria, score, tipo de correspondência).

Cadastro (formulário no próprio frontend): - + Novo Itinerário — abre um modal com colaborador, origem/destino (IATA), datas de ida/volta, latitude/longitude do destino (usados no cruzamento por área), motivo, e um bloco opcional de dados de voo (companhia aérea, sigla, número do voo, bilhete, localizador/PNR, partida/chegada previstas, centro de custo, código da empresa — usados no cruzamento por voo). Salvar cruza o itinerário imediatamente. - Editar (ícone ✏️) — reabre o mesmo modal preenchido; salvar re-executa o cruzamento. - Remover (ícone 🗑️) — apaga o itinerário (com confirmação). - Importar CSV — carga em lote em dois passos: (1) enviar o CSV e ver o preview/validação, (2) confirmar a importação. Baixe o template CSV pelo botão dedicado. - Atualizar Cruzamentos — reavalia todos os itinerários de uma vez (detecta eventos novos ingeridos após a criação e também limpa o risco de itinerários cujo evento expirou).

Colunas: Colaborador, Origem→Destino, Voo (clique para expandir bilhete/localizador/horários), Data Ida, Status, Risco (nível atual), Categoria, Score, Ações (Cruzar/Editar/Remover).

Clique na linha para expandir um painel de detalhe logo abaixo dela, mostrando por extenso o que os badges de Risco/Categoria/Correspondência significam, a lista dos eventos de risco correlatos (título de cada um), e um botão "📍 Destacar no mapa": ele centraliza o mapa no evento de risco correlato com um destaque visual (círculo tracejado ciano) e um marcador com a foto de perfil do colaborador (ou suas iniciais) na posição do destino.

3.11. Como funciona o cruzamento

O motor cruza o itinerário contra os eventos de risco ativos por dois caminhos, dependendo do tipo de evento:

1. Acidente AÉREO (fonte CENIPA/NTSB/Aviation Herald/ASN, ou qualquer evento com dados de voo no registro) — cruza apenas por voo exato: mesma companhia e mesmo número do voo e data próxima (±1 dia) → risco extrema, badge 🚨 Mesmo voo. Não há mais fallback geográfico para acidente aéreo — um acidente aéreo perto do destino do colaborador, em outro voo, não marca risco (evita falso positivo).
2. Todos os demais eventos (violência armada, clima severo, desastre natural, alerta consular, crise sanitária, terrorismo, acidente rodoviário) — cruzam por área: calcula a distância (Haversine) até cada evento; se o destino estiver dentro do raio, cruza. Badge 📍 Área de risco.
3. Geofencing — se o destino cair dentro de uma zona de risco desenhada no mapa (3.5.1), o itinerário recebe risco extrema (zona proibida) ou alta (zona de atenção), independentemente de existir evento de risco.

Exemplo por área: um colaborador com destino em Bogotá (4.60, -74.30) e um evento TravelRisk "Colômbia: Nível 3" ancorado no centroide do país com raio de 400 km → o destino cai dentro do raio → o itinerário passa a risco alta.

Exemplo por voo (marca): um colaborador com companhia LATAM e voo LA3400 no dia 13/07, e um evento de acidente aéreo com companhia_aerea=LATAM e numero_voo=LA3400 na mesma data → cruzamento exato, risco extrema, alerta destacado ("🚨 SEU VOO LA3400...").

Exemplo por voo (não marca): um colaborador com destino em Luxemburgo, voo LH1234 da Lufthansa, e um acidente aéreo a poucos km do aeroporto mas de outra companhia/voo → não cruza — evita alarme falso.

⚠️ Limitação conhecida: nenhuma das fontes reais (ASN, Aviation Herald, NTSB, CENIPA) expõe número de voo estruturado — só companhia aérea e, quando disponível, aeroportos de partida/chegada. Na prática, o critério "voo exato" só dispara com dados carregados manualmente; com as fontes reais em produção, acidentes aéreos raramente cruzam com um itinerário específico (o que é o comportamento correto — evita alarme falso).

---

4. Equipe (Colaboradores)

4.1. Listar e buscar

A tabela mostra Situação (semáforo), Nome, Departamento, Nível, Último check-in, Status e Ações. O campo "Buscar por nome…" filtra em tempo real. Seleção múltipla (checkbox na primeira coluna) habilita a ação em lote "Desativar selecionados".

4.2. Criar colaborador

Clique em + Novo Colaborador. O modal organiza os campos em seções:

Dados básicos:

Foto de perfil: escolha uma imagem (JPEG/PNG/WEBP) — recortada automaticamente para quadrado. A foto aparece nos marcadores do mapa, na linha expandida de itinerários e no popup de "Destacar no mapa".

Contato de emergência: nome, telefone e parentesco (ex.: cônjuge, mãe).

Idioma preferido: Português (Brasil), English ou Español — usado nas notificações.

Passaporte (viagem internacional): número (criptografado em repouso, mascarado na leitura — ex.: ••••1234) e validade. O campo "Deixe em branco para manter o atual" preserva o valor existente ao editar.

Consentimento LGPD: checkbox que registra que o titular foi informado sobre o tratamento de seus dados pessoais, conforme a LGPD. O sistema grava a data e a origem do consentimento.

Nível de acesso: hoje é um rótulo organizacional (viajante/gestor/admin). Ainda não há login de usuário — todo o painel opera sobre a empresa de demonstração.

4.3. Importar colaboradores por CSV

O botão Importar CSV abre um modal de importação em dois passos: 1. Upload do CSV — o sistema analisa e mostra um preview com validação (campos obrigatórios, e-mails duplicados). 2. Confirmar — importa os registros válidos.

O checkbox de consentimento LGPD confirma coletivamente que todos os titulares foram informados. Baixe o template CSV pelo botão na própria tela.

4.4. Editar / Desativar

Use os botões de ação na linha do colaborador. Desativar mantém o histórico, mas remove a pessoa das contagens ativas. A desativação em lote é feita selecionando vários colaboradores (checkbox) e usando o botão "Desativar selecionados".

---

5. Alertas e Notificações

5.1. Tela de Alertas

A tela mostra dois blocos:

1. Alertas aguardando confirmação (topo) — alertas de voo "exato" extraídos por heurística do Aviation Herald ou ASN que exigem confirmação do gestor antes do disparo. Cada card tem botões Confirmar (libera o alerta para despacho) e Rejeitar (descarta).

2. Histórico de alertas enviados — tabela com Data/Hora, Nome do colaborador, Canal, Severidade, Categoria, Centro de Custo, Empresa, Mensagem e Status (pendente / enviado / lido). Chips de filtro por severidade (Todos / Baixa / Moderada / Alta / Extrema) no topo. Clique na linha para expandir os detalhes (passaporte, contato de emergência, dados de voo). Botão "Baixar e-mails (CSV)" exporta o histórico.

5.2. Despachar notificações

O envio usa o dispatcher (POST /risco/alertas/despachar). Ele pega os alertas pendente, envia pelo canal configurado e marca como enviado. Se o envio falhar, o alerta continua pendente (retry natural na próxima rodada).

Canais disponíveis:

Os canais WhatsApp e SMS usam a API REST da Twilio diretamente (sem SDK). O número do colaborador deve estar no campo telefone do cadastro (formato E.164: +5511999998888).

Você também pode sobrepor o canal na hora: POST /risco/alertas/despachar?canal=whatsapp.

Despacho automático: o sistema despacha alertas pendentes automaticamente a cada 2 minutos (configurável). O botão manual continua disponível para forçar o envio imediato.

---

6. Broadcast de Emergência e Check-in

O TRM permite enviar mensagens de emergência em massa aos colaboradores e rastrear quem está bem via check-in (por link web, resposta de SMS ou resposta de WhatsApp).

6.1. Enviar um broadcast

Na tela Equipe, clique em 📢 Broadcast de Emergência. Preencha:

Clique em Enviar. Cada destinatário recebe um link web de check-in (despachado pelo canal configurado — console, e-mail, webhook, SMS ou WhatsApp).

6.2. Check-in dos colaboradores

O link recebido (/checkin/{token}?estado=ok ou ?estado=ajuda) é público — o colaborador não precisa de login para responder. Ao clicar: - "Estou bem" → marca como ✅ (verde no semáforo). - "Preciso de ajuda" → marca como 🔴 (vermelho, exige atenção).

A página de check-in é feita para o celular: um card único com a marca PharosGuard e dois botões grandes, sem menu e sem login. Ela não depende de nenhum recurso externo, para abrir rápido mesmo em conexão ruim — que é a situação em que costuma ser usada.

Check-in por SMS/WhatsApp (via Twilio): o colaborador pode responder diretamente à mensagem recebida com texto (ex.: "ok" ou "ajuda"). O webhook inbound do Twilio processa a resposta e atualiza o estado. Quando o colaborador compartilha sua localização real pelo WhatsApp, o sistema captura latitude/longitude e atualiza a posição no mapa.

6.3. Semáforo de equipe

Na tela Equipe, três cards no topo mostram o semáforo agregado:

O endpoint GET /equipe/status agrupa as respostas por departamento. O gestor identifica rapidamente quem precisa de acompanhamento.

Os mesmos três números aparecem no topo da versão mobile — durante uma emergência, é a informação que o gestor consulta pelo celular.

6.4. Camada Pessoas no mapa

Clique na camada Pessoas no menu de Camadas do mapa para exibir os colaboradores em viagem. Cada viajante aparece como um marcador circular com sua foto de perfil (ou suas iniciais), posicionado na localização presumida (destino do itinerário em andamento). A cor de fundo do marcador segue o estado de check-in (verde/amarelo/vermelho). Clicar no marcador abre um popup com nome, departamento, status e, quando houver, a lista de eventos de risco próximos.

---

7. Configurações

A tela ⚙️ Config tem quatro abas: Aparência, Notificações, Integrações e Demonstração.

7.1. Aparência (Temas)

Escolha entre 13 temas:

A troca é imediata, fica salva por empresa (no backend) e também no navegador (cache anti-flash). Há também um seletor rápido 🎨 na topbar.

7.2. Imagem de fundo da tela de login

Ainda na aba Aparência, o card "Imagem de Fundo — Tela de Login" permite enviar uma foto (JPEG/PNG/WEBP, até 5 MB) que substitui o degradê padrão do painel de marca (lado esquerdo da tela de login). Botão Remover volta ao degradê padrão.

A imagem só aparece automaticamente em navegadores onde algum usuário daquela empresa já logou antes — a lógica usa o mesmo cache local do tema.

7.3. Notificações

A aba Notificações (ícone 🔔⚙️) configura o canal de envio dos alertas e broadcasts pela interface, sem editar .env:

• Canal ativo: selecione console, email, webhook, whatsapp ou sms.
• Credenciais: os campos mudam conforme o canal escolhido:
• Email: SMTP Host, Porta, Usuário, Senha, Remetente, TLS.
• Webhook: URL do webhook (Slack/Teams/sistema próprio).
• WhatsApp: Twilio Account SID, Auth Token, número de origem (whatsapp:+14155238886).
• SMS: Twilio Account SID, Auth Token, número de origem.
• Testar: botão que envia uma mensagem de teste real pelo canal configurado.

Credenciais configuradas pela interface são criptografadas em repouso e mascaram o valor na leitura, igual às credenciais de integrações.

7.4. Demonstração (dados de exemplo)

Botão de um clique para popular o sistema com um cenário de demonstração completo.

• Ativar dados demo — cria ~10 colaboradores, ~10 itinerários (incluindo dois casos de voo exato), ~7 eventos de risco e os alertas correspondentes. Os registros demo são marcados internamente (email terminado em @demo.trm) para não se misturar com dados reais.
• Desativar dados demo — remove apenas os registros marcados como demo; dados reais cadastrados manualmente não são afetados.
• O card de status mostra se o modo demo está ativo ou não, com um resumo de quantos registros foram criados/removidos na última ação.

---

8. Integrações (Fontes de Risco)

Área restrita por token de admin (aba Integrações em ⚙️ Config). É onde você liga/desliga fontes de risco, configura credenciais, testa a conexão e ingere eventos.

8.1. Entrar (gate de admin)

Ao abrir ⚙️ Config → Integrações, informe o token de admin. No ambiente de desenvolvimento, o padrão é trm-admin.

Em produção, troque via variável de ambiente ADMIN_TOKEN.

8.2. Dashboard de saúde das fontes

No topo do painel, há uma barra "Saúde das fontes" com o status agregado:

Clique em qualquer número da barra (ex.: "9 Inativas") para filtrar a lista de fontes por esse status. Cada card também tem um badge colorido no canto superior direito.

Dica: se vir "Atrasada", é um sinal de alerta — a fonte estava configurada para rodar a cada 60 min, mas já passaram 120+ min sem executar. Clique em Testar para diagnosticar.

Atalho: a mesma contagem (sem o detalhe por fonte, sem exigir o token de admin) aparece resumida no chip de saúde das fontes, na topbar de qualquer tela — ver 3.1.

8.3. Anatomia de um card de integração

8.4. Ingestão automática (agendamento)

Todo conector aceita o campo "Ingestão automática a cada (minutos)" no modal Editar: - Vazio ou 0 = só manual (botão "Ingerir agora"). - Ex.: 10 = o sistema ingere sozinho a cada 10 minutos (fonte precisa estar ativa). - O card mostra ⏱ Auto a cada Xmin · próxima em ~Ymin; cada conector sugere um intervalo padrão.

8.5. Passo a passo típico

1. Editar → preencha os campos (ver seção 9 para cada fonte).
2. Salvar.
3. Testar → confirme "Conexão OK — N evento(s)".
4. Ligar o toggle.
5. Ingerir (ou use "Ingerir Fontes" na tela Central de Risco para todas de uma vez).

Credenciais são criptografadas (Fernet) em repouso e mascaradas na leitura. Ao editar, deixe um campo de senha em branco para manter o valor atual; preencha só para trocá-lo.

8.6. Webhook de OBT (agência de viagens)

O TRM aceita receber itinerários diretamente de um sistema de reservas (OBT — Online Booking Tool) ou agência de viagens, via webhook (POST /webhook/obt). O payload recebido é mapeado automaticamente para um itinerário do colaborador correspondente. Configure os campos de mapeamento no card da integração tipo "OBT".

8.7. Tokens de webhook por integração

Integrações do tipo webhook (OBT ou genérica) podem ter tokens de autenticação dedicados. Na edição da integração, use os botões: - Gerar token — cria um token aleatório para autenticar chamadas inbound. - Listar tokens — vê os tokens ativos. - Revogar token — invalida um token sem afetar os outros.

---

9. Catálogo de conectores — como preencher cada um

Legenda: 🌐 pública (sem credencial) · 🔑 requer credencial · 💼 comercial · 🧩 configurável.

9.1. 🌐 Mock (demonstração)

Gera eventos fictícios. Sem campos. Use para demonstração/teste do fluxo.

9.2. 🌐 INMET — Clima (Brasil)

Avisos meteorológicos oficiais do INMET. Sem campos. Basta ligar e ingerir.

9.3. 🌐 METAR — Clima em aeroportos

Condições de voo (teto/visibilidade/vento) via AviationWeather.gov (global).

9.4. 🌐 GDACS — Desastres globais

Alertas de terremoto, ciclone, enchente etc. (ONU/UE).

9.5. 🌐 USGS — Terremotos (global)

Terremotos em tempo real dos feeds públicos do USGS. Sem credencial. Cadência sugerida: 10 min.

Severidade por magnitude: ≥6 extrema · ≥5 alta · ≥4 moderada.

9.6. 🌐 Canadá — Avisos de viagem por país

Avisos oficiais do governo canadense (Global Affairs), por país → centroide. Sem credencial. Cadência sugerida: 1x/dia (1440 min).

Nível → severidade: 0 normal→baixa · 1 alta cautela→moderada · 2 evitar não-essencial→alta · 3 evitar toda viagem→extrema.

9.7. 🌐 TravelRisk — Avisos de viagem por país

Nível de aviso 1-4 por país, do feed público do US State Department. Ancora no centroide do país (raio ~400 km). Fonte pública, sem credencial.

Mapeamento de nível → severidade: 1 → baixa · 2 → moderada · 3 → alta · 4 → extrema.

9.8. 🌐 UK FCO — Avisos de viagem (Reino Unido)

Avisos de viagem oficiais do governo britânico, via Content API estruturada do GOV.UK (não é scraping de HTML). Cobre ~226 países. Sem credencial.

Só gera evento para países com aviso ativo ("evite toda viagem" ou "evite viagens não essenciais"); países sem aviso especial não aparecem.

9.9. 🌐 PRF — Acidentes rodoviários (Brasil)

Camada histórica de trechos críticos (dados abertos Datatran).

9.10. 🌐 CENIPA — Acidentes aéreos (Brasil)

Ocorrências aeronáuticas oficiais (Força Aérea Brasileira), via Portal de Dados Abertos. Não é um feed em tempo real — é um dataset histórico.

9.11. 🔑 NTSB — Acidentes de aviação (EUA)

Órgão oficial americano (National Transportation Safety Board). Cobre só acidentes nos EUA/aeronaves americanas.

1. Cadastre-se gratuitamente em developer.ntsb.gov.
2. Gere uma API key e cole no campo API Key do painel.

9.12. 🌐 Aviation Herald — Notícias de aviação (mundial)

Cobertura mundial e quase em tempo real — site jornalístico, não oficial. Sem credencial.

⚠️ Melhor esforço: o conector lê a página pública gratuita, que pode quebrar se o site mudar de layout.

9.13. 🌐 ASN — Aviation Safety Network (mundial)

A base de acidentes mais completa do mundo (11.000+ ocorrências). Gratuito e sem login.

9.14. 🌐 EMSC / LastQuake — Sismos (Euro-Mediterrâneo)

Sismos em tempo real do EMSC (seismicportal.eu), complementa o USGS na região Euro-Mediterrânea.

9.15. 🌐 Copernicus EMS — Ativações de emergência (UE)

Ativações oficiais de mapeamento de emergência da União Europeia (incêndios, enchentes, terremotos), via API pública. Sem credencial.

9.16. 🔑 Fogo Cruzado — Violência armada (Brasil)

Ocorrências de tiroteio. Cadastro gratuito em api.fogocruzado.org.br.

9.17. 🔑 ACLED — Conflitos e violência política

Eventos de conflito georreferenciados ponto a ponto da ACLED. Requer API key + e-mail registrado (cadastro gratuito).

9.18. 🔑 NewsAPI — Notícias por keyword

Cobertura global de notícias de risco via newsapi.org. Cada artigo é ancorado no centroide do país citado no título.

9.19. 🔑 OpenWeatherMap — Alertas por local

Alertas meteorológicos oficiais nos locais que você monitora. Usa o One Call 3.0.

9.20. 🔑 GeoSure — Scores de risco

Scores por localidade. API comercial — requer contrato/API key.

9.21. 🔑 Xweather — Clima severo (mundial)

Alertas oficiais de clima severo em escala mundial (Vaisala / Xweather). Cobre países fora do eixo BR/EU (Japão, Coreia, México, Índia, Austrália, África do Sul...). Requer credencial gratuita (free tier developer: 15.000 acessos/mês, sem cartão — cadastre em signup.xweather.com).

Cota: 10 âncoras × cadência de 30 min ≈ 14.400 chamadas/mês — cabe no free tier.

9.22. 🔑 Apify — Travel Risk Report

Roda um actor da plataforma Apify (ou lê um dataset existente). Requer token de API.

Modo A — rodar um actor: | Campo | Exemplo | |-------|---------| | Actor ID | seu-usuario~travel-risk-report | | Input JSON | {"countries":["BR","MX"]} (opcional) | | API token | apify_api_xxxxxxxxxxxx |

Modo B — ler um dataset já existente: | Campo | Exemplo | |-------|---------| | Dataset ID | aBcDeFgHiJkLmNoP | | API token | apify_api_xxxxxxxxxxxx |

9.23. 🔑 TuGo — Travel Advisory

Avisos de viagem por país da TuGo (parceiro/comercial). Requer API key. Ancora no centroide do país.

9.24. ⛔ CEMADEN

Indisponível — não há API pública estável de alertas do CEMADEN. Use INMET para clima no Brasil. O card existe para transparência; o Testar falha explicando.

9.25. 🧩 Conector REST genérico ("Nova integração")

Para qualquer API REST que devolva JSON. Clique em Nova integração e preencha:

9.26. 📰 Conector RSS genérico ("+ Nova (RSS)")

Para qualquer feed RSS/Atom de notícias. Clique em + Nova (RSS) e preencha:

Como o filtro funciona. Um item entra se nenhum termo excluído casar e, havendo palavras-chave, alguma casar. Detalhes: - Casamento por palavra inteira (não substring). flood não casa "flooding". - Acentos são ignorados: explosao casa "Explosão" e vice-versa. - Por padrão olha só o título. Use Título + resumo só em feed cujo resumo seja limpo.

Como o item é posicionado no mapa. O conector procura no texto um estado, província ou país conhecido. Item sem local reconhecido é descartado.

Restringir por país/estado (evita local errado). Feeds regionais de um único país (ex.: G1 São Paulo) podem citar de passagem um lugar de outro país ("Delaware", "Washington") que o detector confunde com uma palavra comum do texto ("de", preposição). Preenchendo Restringir a este país, qualquer detecção fora dele é descartada (não vira o local do evento) — o item cai de volta na âncora fixa, se houver, ou é descartado se não houver âncora. Restringir a este estado/região é mais específico ainda: só aceita o estado exato (ex.: só eventos detectados como "São Paulo", rejeitando até outros estados brasileiros). O campo de estado é dinâmico — as opções mudam conforme o país selecionado, e ficam desabilitadas se nenhum país estiver escolhido.

Feed regional precisa de âncora fixa. Nomes de cidade não são reconhecidos. Para um feed como o G1 Santos, preencha a âncora com a coordenada da cidade-polo e marque Uso da âncora = Sempre.

Feeds sugeridos:

BBC World:      https://feeds.bbci.co.uk/news/world/rss.xml
The Guardian:   https://www.theguardian.com/world/rss
Al Jazeera:     https://www.aljazeera.com/xml/rss/all.xml
Reuters*:       https://news.google.com/rss/search?q=site:reuters.com+world+when:1d&hl=en-US&gl=US&ceid=US:en
AP News*:       https://news.google.com/rss/search?q=site:apnews.com+world+when:1d&hl=en-US&gl=US&ceid=US:en
France 24/AFP:  https://www.france24.com/en/rss

* Reuters e AP News não publicam mais feeds RSS próprios. Os URLs acima usam o Google News como proxy — retornam artigos dessas agências das últimas 24h.

Seed automático: scripts/seed_feeds_risco.py cria 107 fontes de uma vez — 7 internacionais, 2 nacionais brasileiros (UOL, Folha), 54 regionais do G1 (27 estaduais + 27 sub-regionais com âncora na capital/cidade-polo), 3 buscas temáticas do Google News (terremoto, atentado, queda de avião) e 41 países do MeteoAlarm. É o script a rodar ao provisionar banco novo. Use --atualizar para alinhar feeds existentes sem sobrescrever edições manuais; rode com --dry-run primeiro.

9.27. 📰 Conector CAP genérico ("+ Nova (CAP)")

Para feeds no formato CAP-em-Atom (Common Alerting Protocol) de autoridades — o mesmo padrão usado pelo MeteoAlarm (alertas meteorológicos oficiais da Europa).

MeteoAlarm por país: troque portugal na URL pelo nome do país em inglês minúsculo.

---

10. Triagem e Filtro de Relevância

Nem todo evento ingresso na base de risco é relevante ao viajante. Notícias sobre política, esportes, tecnologia ou economia não geram risco físico direto — e os RSS feeds genéricos (BBC, Reuters, Google News) capturam muita coisa fora do escopo. O filtro de relevância descarta esse ruído e reclassifica eventos quando o conteúdo revela um padrão mais específico.

10.1. Camadas do filtro

O filtro de relevância processa cada evento em 3 camadas, na ordem:

Tier 1 — Bypass automático (fontes oficiais)

Eventos de fontes oficiais e curadas passam intactos — esses dados já vêm tratados:

• Meteorologia: INMET, CEMADEN, OpenWeatherMap, MeteoAlarm, METAR
• Sismologia: USGS, EMSC
• Alertas de desastre: GDACS, Copernicus, CAP
• Conflito armado: ACLED, Fogo Cruzado
• Aviação: CENIPA, NTSB, Aviation Herald, ASN
• Avisos de viagem: Travel Risk, UK Foreign Office (FCO), TuGo, Canadá
• Segurança: GeoSure
• Mock (teste)

Todas as outras fontes (RSS genéricos, NewsAPI, etc.) passam pelas camadas 2 e 3.

Camada 2 — Score de relevância

O sistema soma pontos (e subtrai) baseado em 7 critérios:

Exemplo: "Terremoto mata 3 em Tóquio" → magnitude (+8) + contagem de vítimas (+8) + termo "earthquake" (+5) = score 21.

Exemplo ruído: "Presidente demite secretário" → negativo "demissão política" (-8) + termo "diz" (-6) = score -14.

Camada 3 — Threshold (corte mínimo)

Eventos com score ≥ 2.0 (padrão) são mantidos; abaixo disso, são descartados.

Este threshold é ajustável por integração no modal Editar (campo "Threshold de relevância"). Use números maiores para filtro mais apertado (ex.: 4.0 = só eventos muito óbvios) ou menores para mais permissivos (ex.: 0.5 = quase nada é descartado).

10.2. Reclassificação automática

Quando um evento passa pelo filtro mas o conteúdo revela uma categoria mais específica, o sistema reclassifica:

• RSS genérica encontra "earthquake 7.1 em Haiti" com categoria vaga → reclassifica para DESASTRE_NATURAL
• Feed de notícias encontra "3 killed in cross-fire Rio" → reclassifica de FEED_NOTICIAS para VIOLENCIA_ARMADA
• NewsAPI encontra "travel advisory / do not travel" → reclassifica para ALERTA_CONSULAR

Isso garante que o operador vê a categoria correta no mapa e nos filtros da Central de Risco, mesmo que a fonte original tenha classificado genéricamente.

10.3. Bypass por integração (modo permissivo)

No modal Editar de qualquer integração, há um checkbox "Bypass de filtro (mantém tudo)". Se ativado, nenhum evento dessa fonte será descartado — útil para debugar ou confiar completamente em uma fonte.

10.4. Defects recentes e correções (2026-07-30)

4 defeitos foram corrigidos que causavam alertas falsos nos feeds RSS:

D1 — Sufixo de veículo confundindo localização

Problema: "Terremoto no Japão — BBC World" → o sufixo " — BBC World" continha "World" que era detectado como localização genérica; o resultado era plotar o evento em São Paulo (matriz da BBC).

Solução: novo função separar_veiculo() remove sufixos " — " antes de geolocalizar, afetando qualquer fonte com nome de jornal no título (The Guardian, Miami Herald, Diario do Rio).

D2 — Classificação contextual sobrescrita

Problema: "Toyota e Nissan param fabricas ... após terremoto" → o conector tinha rebaixado com bom motivo para FEED_NOTICIAS (evento é a paralização, não o terremoto), mas o filtro de relevância usava substring simples e reclassificava de volta para DESASTRE_NATURAL/ALTA.

Solução: camada com mais contexto (conector) tem agora a última palavra — se já julgado contextual, o filtro não reclassifica.

D3 — Tupla crua vs objeto (crash silencioso)

Problema: _resolver_local devolvia tupla (lat, lng, nome) em um caminho e objeto LocalDetectado em outro. ingerir() esperava local.lat → AttributeError. Como RiscoEngine.ingerir_uma isola erro por fonte, os 54 feeds regionais do G1 eram descartados em silêncio (operador não via falha).

Solução: contrato unificado — sempre devolve objeto; erro de "rede" não mais oculta bug de código.

D4 — Regex de magnitude rejeitava vírgula (padrão português)

Problema: regex magnitude\s+\d+\.\d+ exigia ponto decimal. Em português escreve-se "magnitude 7,1". O sinal sismico mais forte do planeta era perdido em 100% dos feeds em português.

Solução: aceita magnitude\s+\d+[.,]\d+ — ponto ou vírgula.

Efeito no exemplo original: local passa de São Paulo para Japão, categoria sai de FEED_NOTICIAS, severidade não é promovida (bom!), score sobe de 4.0 para 12.0 (D4 voltando a contar magnitude).

10.5. Debugging — score no painel

Cada evento tem um campo score_relevancia no banco (em dado_bruto). Use Config → Integrações → ⚙️ Editar → Ingerir (ou Testar) — os logs mostram resumo:

filtro_relevancia [rss_bbc_world]: 15 entrada → 11 mantidos (0 tier1), 4 descartados, 0 reclassificados
  DESCARTADO: 'Stock prices rise...' [fonte=rss_bbc_world, score=-3.2] -5 stock price ...

Para saber por que um evento foi descartado, note o score e o motivo — os termos negativos listados indicam o que triggerou a rejeição.

---

11. Guia de obtenção de acesso e credenciais

11.1. Visão geral

O TRM coleta dados de risco de fontes externas para alimentar o mapa e gerar alertas:

Onde essas credenciais são usadas? Todas são digitadas dentro do próprio TRM, na tela ⚙️ Config → Integrações. Basta abrir o card da fonte, clicar em Editar, preencher os campos e Salvar.

O que acontece com minhas senhas e chaves? O sistema criptografa todas as credenciais e nunca mostra o valor completo na tela.

11.2. Fontes públicas

As fontes abaixo funcionam imediatamente, sem criar conta.

11.2.1. Mock (demonstração)

• Precisa de conta? Não.
• O que preencher: nada — basta ligar e ingerir.

11.2.2. INMET — Avisos meteorológicos (Brasil)

• Precisa de conta? Não. Feed público do governo brasileiro.
• O que preencher: nada. Ligue e ingira.

11.2.3. METAR — Condições em aeroportos (global)

• Precisa de conta? Não (AviationWeather.gov).
• Aeroportos ICAO: códigos de 4 letras (ex.: SBGR). Vazio = 13 hubs BR padrão.
• Como descobrir: world-airport-codes.com.

11.2.4. GDACS — Desastres globais (ONU)

• Precisa de conta? Não.
• Níveis: Orange,Red (recomendado — Green gera muitos eventos).

11.2.5. USGS — Terremotos em tempo real (global)

• Precisa de conta? Não.
• Feed: 4.5_day (recomendado). Para zonas sísmicas, use 2.5_day com magnitude 3.0.

11.2.6. TravelRisk — Avisos de viagem (EUA)

• Precisa de conta? Não. Feed público.
• Nível mínimo: 2 (padrão). Use 3 para ver apenas destinos críticos.

11.2.7. Canadá — Avisos de viagem

• Precisa de conta? Não.
• Nível mínimo: 2 (padrão).

11.2.8. UK FCO — Avisos de viagem (Reino Unido)

• Precisa de conta? Não. API pública do GOV.UK.
• Filtro ISO2: vazio = todos os ~226 países.

11.2.9. PRF — Acidentes rodoviários (Brasil)

• Precisa de conta? Não. Dados públicos.
• URL do CSV: baixe em dados.prf.gov.br → Datatran → copie o link do CSV/ZIP.

11.2.10. CENIPA — Acidentes aéreos (Brasil)

• Precisa de conta? Não. Dataset público em dados.gov.br.
• Cole a URL do CSV manualmente (o portal bloqueia acesso automatizado).

11.2.11. Aviation Herald — Notícias de aviação

• Precisa de conta? Não (scraping da página pública).

11.2.12. ASN — Aviation Safety Network

• Precisa de conta? Não. Base pública.

11.2.13. EMSC / LastQuake — Sismos

• Precisa de conta? Não. Feed público seismicportal.eu.

11.2.14. Copernicus EMS — Ativações de emergência

• Precisa de conta? Não. API pública da UE.

11.3. Fontes com cadastro gratuito

Requerem que você crie uma conta no site do fornecedor para receber uma API key ou login.

O que é uma "API key"? Um código longo de letras e números que identifica quem está acessando os dados. Basta copiá-la e colar no TRM.

11.3.1. 🔑 Fogo Cruzado — Violência armada (Brasil)

1. Acesse https://api.fogocruzado.org.br/ e cadastre-se (e-mail + senha).
2. Confirme pelo e-mail de verificação.
3. No TRM: preencha E-mail e Senha com os dados do cadastro.

11.3.2. 🔑 ACLED — Conflitos e violência política

1. Acesse https://developer.acleddata.com/register/.
2. Preencha: nome, e-mail, organização, finalidade ("Risk management").
3. Aguarde o e-mail com a API Key (pode levar algumas horas).
4. No TRM: preencha E-mail registrado e API Key.

11.3.3. 🔑 NewsAPI — Notícias de risco

1. Acesse https://newsapi.org/ → Get API Key.
2. Copie a chave exibida.
3. No TRM: cole no campo API Key.

No plano gratuito, as notícias atrasam 24 horas.

11.3.4. 🔑 OpenWeatherMap — Alertas meteorológicos

1. Cadastre-se em https://openweathermap.org/ → Sign Up.
2. Vá em API keys → copie ou crie uma.
3. Ative o plano One Call 3.0 (Free — 1.000 chamadas/dia).
4. No TRM: cole no campo API Key e preencha Locais monitorados.

A chave pode levar até 2 horas para ser ativada.

Como descobrir latitude/longitude: Google Maps → clique direito → copie os números.

11.3.5. 🔑 Xweather — Clima severo (mundial)

1. Cadastre-se em https://signup.xweather.com/ (free tier — sem cartão).
2. Copie o Client ID e o Client Secret do painel developer.
3. No TRM: cole nos campos correspondentes.

Cota: 15.000 acessos/mês. 10 âncoras × cadência de 30 min ≈ 14.400/mês.

11.3.6. 🔑 NTSB — Acidentes de aviação (EUA)

1. Cadastre-se em https://developer.ntsb.gov.
2. Gere uma API key.
3. No TRM: cole no campo API Key.

11.3.7. 🔑 Apify — Relatórios de risco

1. Cadastre-se em https://apify.com/ (e-mail ou Google/GitHub).
2. Settings → Integrations → + Create token → copie.
3. No TRM: cole no campo API token e informe o Actor ID ou Dataset ID.

11.4. Fontes comerciais

Exigem contrato comercial com o fornecedor.

11.4.1. 💼 GeoSure — Scores de risco

Contrate em https://geosureglobal.com/. Receberá URL base + API Key.

11.4.2. 💼 TuGo — Avisos de viagem

Contrate via https://www.tugo.com/. Receberá URL + API Key + header de autenticação.

11.5. Fontes genéricas

Se a sua organização usa uma fonte fora da lista, use o conector REST genérico (qualquer API JSON) ou RSS genérico (qualquer feed de notícias). Os campos de mapeamento normalmente requerem apoio da equipe de TI.

11.6. Fonte indisponível: CEMADEN

O CEMADEN não possui API pública estável. Use INMET para alertas de clima no Brasil.

11.7. Resumo rápido

11.8. Boas práticas e cuidados de segurança

1. Nunca compartilhe chaves por e-mail ou chat. Use gerenciador de senhas.
2. Use e-mails profissionais nos cadastros.
3. Anote qual conta pertence a quem. Registro interno (planilha, cofre de senhas).
4. Troque o token de admin em produção. O valor padrão trm-admin é apenas para testes.
5. Não altere o SECRET_KEY sem necessidade. Trocar invalida todas as credenciais salvas.
6. Atenção com limites de uso. NewsAPI (100 consultas/dia), OpenWeatherMap (1.000/dia), Xweather (15.000/mês). Ajuste a cadência de auto-ingestão.
7. Teste sempre antes de ligar.
8. Fontes com erro não travam o sistema.

---

12. Privacidade e LGPD

O TRM implementa recursos para conformidade com a Lei Geral de Proteção de Dados (LGPD).

12.1. Trilha de auditoria

Toda ação relevante (criação, edição, exclusão de colaboradores e itinerários; ingestão e cruzamento; mudanças de configuração) é registrada em log de auditoria por tenant, com usuário, ação, timestamp e dados afetados. Acessos ao sistema (login, uso de admin token) são registrados em log global separado.

A trilha de auditoria é consulta somente via API (não há tela dedicada no frontend nesta versão).

12.2. Exportação de dados (portabilidade)

O colaborador pode ter seus dados exportados em formato estruturado:

GET /colaboradores/{id}/exportar-dados

Retorna todos os dados pessoais do colaborador (cadastro, itinerários, alertas recebidos, respostas de check-in) em JSON — atendendo ao direito de portabilidade da LGPD.

12.3. Anonimização (eliminação)

Quando o colaborador solicita a eliminação de seus dados:

POST /colaboradores/{id}/anonimizar

O sistema substitui todos os dados pessoais (nome, email, telefone, passaporte, contato de emergência) por valores genéricos ("Colaborador anonimizado"), mantendo a integridade referencial do banco. O registro permanece para fins estatísticos, mas sem identificação.

12.4. Passaporte criptografado

O número de passaporte é criptografado em repouso (Fernet, derivado do SECRET_KEY). Na leitura, o sistema retorna apenas a versão mascarada (ex.: ••••1234). O valor completo nunca é exposto pela API.

12.5. Consentimento

O formulário de cadastro de colaborador inclui checkbox de consentimento LGPD ("Confirmo que o titular foi informado sobre o tratamento de seus dados pessoais, conforme a LGPD"). O sistema grava data e origem do consentimento. Na importação CSV, o consentimento é registrado coletivamente.

---

13. Perguntas frequentes (FAQ)

"Liguei uma fonte mas o mapa não mudou." Ligar o toggle só habilita a fonte. Você precisa Ingerir (no card) ou clicar em Ingerir Fontes na tela Central de Risco. Depois, Atualizar o mapa.

"Testei e deu 'Conexão OK — 0 eventos'. Está errado?" Não necessariamente. Muitas fontes só retornam eventos quando há risco ativo.

"Reingeri a mesma fonte e vieram 0 eventos novos." Correto — a deduplicação evita duplicar eventos já ingeridos.

"Uma fonte aparece com ✗ erro." Fontes que exigem credencial falham até você preencher os dados. CEMADEN falha por não ter API pública. Isso não interrompe as outras fontes.

"Os avisos de país cobrem uma área enorme no mapa." Avisos de viagem (TravelRisk/TuGo/Canadá/UK FCO) são de nível-país: ancoramos no centroide com raio grande (~400 km). É uma aproximação para sinalizar "há destino em país sob alerta".

"Troquei o SECRET_KEY e as credenciais sumiram." O SECRET_KEY deriva a chave que criptografa as credenciais. Trocá-lo invalida o que já estava salvo — você precisará reinformar as credenciais.

"Enviei um broadcast mas ninguém respondeu o check-in." Verifique se o canal de notificação está funcionando. O colaborador precisa clicar no link que recebe (ou responder por SMS/WhatsApp) — não há notificação push nativa.

"O semáforo mostra todo mundo amarelo." Amarelo = sem resposta. O estado de check-in só muda quando o colaborador responde ao broadcast.

"Os alertas consolidados aparecem como 1 fonte só." O consolidador precisa de eventos de 2+ fontes distintas sobre o mesmo incidente. Use "Só multi-fonte" para filtrar.

"Abri no celular e caiu numa tela diferente, sem o menu." É a versão mobile, aberta automaticamente em telas pequenas. Ela mostra situação da equipe, mapa e alertas. Para o painel completo, use "Ver versão completa" no rodapé — a preferência fica salva naquele navegador.

"No celular não consigo cadastrar colaborador nem mexer nas integrações." Correto: a versão mobile é só de consulta. Cadastros, configurações e integrações ficam no painel completo, num computador.

"O site demora muito para abrir na primeira vez." Se estiver usando a versão publicada (Render), a API hiberna após ~15 min sem uso. O primeiro acesso "acorda" o servidor e leva 30–60 segundos. Acessos subsequentes são rápidos.

"Config → Integrações não mostra os feeds RSS/CAP." Os feeds RSS/CAP vivem no banco e só existem após o seed (seed_feeds_risco.py). Se o banco é novo e o seed não foi rodado, os grupos "Feed RSS/Atom" e "CAP" não aparecem.

"Um alerta de voo não disparou." O cruzamento por voo exato requer que o evento tenha os mesmos dados de companhia + número de voo que o itinerário. As fontes reais (AVHerald, ASN, NTSB, CENIPA) raramente fornecem esses dados estruturados — o cruzamento de voo na prática dispara mais com dados manuais ou demo.

---

14. Glossário

---

A. Apêndice — Ambientes e acesso

Local / demo

Login de demonstração: admin@techcorp.com.br / trm-demo-2026.

Produção

O que muda no plano grátis:

• A API hiberna após ~15 min sem uso. O primeiro acesso "acorda" o servidor e leva 30–60 segundos (acessos subsequentes são rápidos).
• Sem Redis — o cache quente e o rate limiter caem para memória/banco. Funcionalidade preservada, desempenho levemente menor sob carga.
• Fotos de colaborador não persistem entre reinícios do servidor (o plano não oferece disco permanente).

Quando algo parece "vazio":

Os feeds RSS/CAP vivem no banco, não no código. Se o banco de produção é novo e o seed (seed_feeds_risco.py) ainda não foi rodado, a tela Config → Integrações não exibirá os grupos "Feed RSS/Atom" e "CAP". Nesse caso, peça ao administrador que execute o seed.

---

TRM SaaS — Manual do Usuário v4.0 · Julho 2026. Para dúvidas técnicas, consulte CLAUDE.md.