🌤️ MeuClima — Aplicativo de Previsão do Tempo

Consulte temperatura, condição climática, sensação térmica, índice UV, probabilidade de chuva e velocidade do vento de qualquer cidade do mundo, diretamente no navegador — sem chave de API, sem dependências externas.

---

📋 Índice

• Visão Geral
• Instruções de Instalação
• Guia de Uso
• Exemplo de Resultado
• Funcionalidades
• Tratamento de Erros
• Informações da API
• Estrutura do Projeto
• Testes
• Melhorias Futuras

---

🌍 Visão Geral do Projeto

MeuClima é uma aplicação web de previsão do tempo desenvolvida com HTML, CSS e JavaScript puro — sem frameworks ou bibliotecas externas. O usuário digita o nome de qualquer cidade do mundo e a aplicação exibe, em tempo real:

• Temperatura atual em °C
• Condição climática (descrição textual e ícone emoji)
• Temperaturas máxima e mínima do dia
• Sensação térmica
• Probabilidade de chuva (com barra de progresso visual)
• Índice UV com classificação de risco
• Velocidade do vento em km/h

A interface adapta seu tema visual dinamicamente conforme a condição climática e o período do dia (dia ou noite), proporcionando uma experiência imersiva e intuitiva.

Público-alvo: usuários que desejam uma consulta rápida de clima sem necessidade de cadastro ou instalação de aplicativos — basta abrir o navegador.

---

⚙️ Instruções de Instalação

Pré-requisitos

Ferramenta	Versão mínima	Finalidade
Node.js	18.x	Executar os testes com Jest
Navegador moderno	—	Rodar a aplicação em si

A aplicação em si não precisa de Node.js para funcionar — basta abrir o index.html no navegador. O Node.js é necessário apenas para rodar a suíte de testes.

Passo a Passo

1. Clone o repositório

git clone https://github.com/memariaa/projeto-clima.git
cd projeto-clima

2. Instale as dependências de desenvolvimento

npm install

Isso instalará o Jest e o jest-environment-jsdom, usados exclusivamente para os testes automatizados.

3. Execute a aplicação

Abra o arquivo index.html diretamente no navegador:

# Linux / macOS
open index.html

# Windows
start index.html

Ou simplesmente arraste o arquivo index.html para a janela do seu navegador.

Não é necessário um servidor local — a aplicação funciona via file:// pois não depende de rotas de servidor.

---

🖥️ Guia de Uso

1. Abra a aplicação no navegador. Você verá a tela de boas-vindas com sugestões de cidade.

2. Digite o nome de uma cidade no campo de busca no topo da página.
   Exemplos: São Paulo, Lisboa, Tokyo, New York.

3. Pressione Enter ou clique no botão Buscar (ícone de lupa).

4. Aguarde o carregamento — a aplicação realizará duas chamadas em sequência:

   • Primeira: converte o nome da cidade em coordenadas geográficas.
   • Segunda: busca os dados climáticos para essas coordenadas.

5. O resultado é exibido com temperatura atual, condição climática, ícone representativo, variação de temperatura do dia e o painel de métricas detalhadas (sensação térmica, probabilidade de chuva, UV Index e vento).

6. Caso ocorra algum erro, uma mensagem descritiva é exibida junto ao botão Tentar novamente, que reexecuta a última busca automaticamente.

---

📊 Exemplo de Resultado

Ao buscar pela cidade Rio de Janeiro, o resultado exibido na tela seria semelhante a:

📍 Rio de Janeiro · Brasil

        28°C
         ☀️

   Céu limpo
   ↑ 31°   ↓ 22°

┌─────────────┬─────────────┬─────────────┬─────────────┐
│ 🌡 Sensação  │ 🌧 Chuva     │ ☀ UV Index   │ 💨 Vento     │
│   30°C      │    10%      │   8 · Alto  │  18 km/h    │
└─────────────┴─────────────┴─────────────┴─────────────┘

O fundo da aplicação muda para o tema day-clear (gradiente dourado / ensolarado diurno), e no período noturno passaria para night-clear (gradiente escuro / estrelado).

Outros exemplos de saída por condição:

Condição	Ícone	Tema visual
Céu limpo (dia)	☀️	day-clear (tons quentes)
Céu limpo (noite)	🌙	night-clear (tons escuros)
Chuva	🌧️	rain (tons frios/azulados)
Nublado	⛅	cloudy (tons cinzentos)
Tempestade	⛈️	storm (tons roxos/escuros)

---

✅ Funcionalidades

• Busca de clima por nome de cidade — o nome inserido é convertido em coordenadas geográficas via API de geocodificação antes da consulta climática.

• Exibição de temperatura atual — exibe a temperatura em graus Celsius com até uma casa decimal.

• Exibição de máxima e mínima diárias — mostra as temperaturas máxima e mínima previstas para o dia corrente.

• Sensação térmica — exibe a temperatura aparente (apparent_temperature) em °C, indicando como a temperatura é percebida pelo corpo humano.

• Probabilidade de chuva — exibe a probabilidade máxima de precipitação do dia em percentual, acompanhada de uma barra de progresso animada para leitura visual rápida.

• Índice UV com classificação de risco — exibe o índice UV máximo diário com rótulo de risco associado: Baixo (≤2), Moderado (3–5), Alto (6–7), Muito alto (8–10) e Extremo (≥11).

• Velocidade do vento — exibe a velocidade atual do vento a 10 metros de altitude em km/h.

• Condição climática com ícone emoji — mapeia códigos WMO para descrições em português e ícones representativos (cobre mais de 25 condições climáticas distintas).

• Tema visual dinâmico — a interface altera automaticamente o tema de fundo conforme o tipo de clima (clear, rain, cloudy, storm) e o período do dia (day / night), com base no fuso horário da cidade buscada.

• Proteção contra buscas simultâneas — o botão de busca é desabilitado durante o carregamento, evitando requisições duplicadas.

• Botão "Tentar novamente" — em caso de erro, permite reexecutar a última busca sem redigitar o nome da cidade.

• Arquitetura modular — o código está organizado em módulos bem definidos (API, WMO, Tema, Renderização, UI), facilitando manutenção e testes.

• Exportação para testes — as funções principais são exportadas via module.exports para permitir testes unitários com Jest.

---

⚠️ Tratamento de Erros

A aplicação foi projetada para lidar de forma amigável com todos os cenários de falha, exibindo mensagens claras ao usuário em vez de erros técnicos brutos.

Cenário	Mensagem exibida
Cidade não encontrada na API	Cidade "XYZ" não encontrada. Tente um nome diferente.
Campo de busca vazio	Foco retorna ao input; nenhuma requisição é feita
Erro HTTP genérico (ex: 500)	Serviço de localização indisponível (erro 500). Tente mais tarde.
Limite de requisições atingido (429)	Muitas requisições. Aguarde alguns segundos e tente novamente.
Sem conexão com a internet	Sem conexão com a internet. Verifique sua rede e tente novamente.
Resposta da API com estrutura inesperada	Resposta da API incompleta. Tente novamente em instantes.
Dados de temperatura ausentes	Dados de temperatura indisponíveis para esta localidade.

Todos os erros são capturados por um bloco try/catch centralizado na função iniciarBusca, garantindo que a aplicação nunca quebre silenciosamente.

---

🔌 Informações da API

A aplicação consome exclusivamente a Open-Meteo — uma API de previsão do tempo gratuita, de código aberto e sem necessidade de chave de autenticação.

Os dados são utilizados em conformidade com a licença CC BY 4.0, com atribuição adequada conforme exigido.

Endpoints utilizados

1. Geocodificação — converte nome de cidade em coordenadas:

GET https://geocoding-api.open-meteo.com/v1/search
    ?name={cidade}
    &count=1
    &language=pt
    &format=json

2. Previsão do tempo — retorna dados climáticos para as coordenadas:

GET https://api.open-meteo.com/v1/forecast
    ?latitude={lat}
    &longitude={lon}
    &current=temperature_2m,apparent_temperature,weather_code,wind_speed_10m
    &daily=temperature_2m_max,temperature_2m_min,precipitation_probability_max,uv_index_max
    &timezone=auto
    &forecast_days=2
    &wind_speed_unit=kmh
    &temperature_unit=celsius

Dados consumidos

Campo da API	Descrição	Onde é exibido
current.temperature_2m	Temperatura atual a 2 metros	Card principal
current.apparent_temperature	Sensação térmica	Card de métricas — Sensação
current.weather_code	Código WMO da condição climática	Ícone + descrição + tema
current.wind_speed_10m	Velocidade do vento a 10 metros	Card de métricas — Vento
daily.temperature_2m_max[0]	Temperatura máxima do dia	Indicador de máxima
daily.temperature_2m_min[0]	Temperatura mínima do dia	Indicador de mínima
daily.precipitation_probability_max[0]	Probabilidade máxima de chuva do dia	Card de métricas — Chuva
daily.uv_index_max[0]	Índice UV máximo do dia	Card de métricas — UV Index
timezone	Fuso horário da localidade	Detecção dia/noite

Códigos WMO

Os códigos de condição climática seguem o padrão WMO (World Meteorological Organization). A aplicação mapeia internamente mais de 25 códigos para descrições em português e ícones emoji, cobrindo desde céu limpo (código 0) até tempestades severas com granizo (código 99).

---

📁 Estrutura do Projeto

projeto-clima/
├── assets/
│   ├── css/
│   │   └── styles.css          # Estilos, temas e animações
│   ├── js/
│   |   └── script.js           # Lógica principal da aplicação
│   └── icones/
│       └── favicon.svg         # Ícone da aplicação (favicon)
├── testes/
│   └── script.test.js          # Testes unitários com Jest
├── index.html                  # Ponto de entrada da aplicação
├── package.json                # Configuração do projeto e dependências
├── package-lock.json           # Lock de versões das dependências
└── .gitignore

---

🧪 Testes

A aplicação possui uma suíte de 7 testes unitários escritos com Jest, cobrindo os principais fluxos da lógica de negócio.

Executar os testes

npm test

Cobertura dos testes

#	Cenário testado
1	Nome de cidade válido retorna coordenadas corretamente
2	Cidade inexistente lança exceção com mensagem apropriada
3	Entrada vazia não dispara nenhuma requisição HTTP
4	Erro HTTP 500 gera mensagem de serviço indisponível
5	Erro 429 (rate limit) gera mensagem de excesso de requisições
6	Falha de rede (TypeError: Failed to fetch) gera mensagem de sem conexão
7	Resposta da API com formato inesperado lança exceção de dados incompletos

Os testes utilizam jest.fn() para mockar o fetch global, garantindo isolamento total de rede.

---

🚀 Melhorias Futuras

• Previsão para os próximos dias — exibir um card com previsão de 5 a 7 dias, usando os dados diários já disponíveis na API.

• Dados de umidade — a API já retorna relative_humidity_2m; bastaria adicioná-lo à query e criar o card correspondente no painel de métricas.

• Geolocalização automática — usar a API navigator.geolocation do navegador para detectar a cidade do usuário automaticamente ao abrir o app.

• Histórico de buscas recentes — salvar as últimas cidades consultadas no localStorage e exibi-las como sugestões rápidas.

• Suporte a múltiplas unidades — permitir ao usuário alternar entre Celsius e Fahrenheit.

• Animações CSS para partículas climáticas — adicionar animações visuais (chuva, neve, raios) sincronizadas com os temas já implementados.

• PWA (Progressive Web App) — adicionar um service worker e manifesto para permitir instalação no dispositivo e uso offline com dados em cache.

• Internacionalização (i18n) — suporte a múltiplos idiomas além do português.

---

🔒 Privacidade e Uso de Dados

Esta aplicação não coleta, armazena ou compartilha dados pessoais dos usuários.

As buscas realizadas são processadas em tempo real através da API externa Open-Meteo, sem qualquer tipo de armazenamento local ou remoto.

Os dados meteorológicos são fornecidos por:

• https://open-meteo.com
  Licença: Creative Commons Attribution 4.0 (CC BY 4.0)

Isso significa que os dados podem ser utilizados livremente, desde que a devida atribuição seja mantida.

---

📄 Licença

Este projeto está licenciado sob a licença MIT.

© 2026 Maria Eduarda de Oliveira Gomes

Você pode usar, copiar, modificar e distribuir este software livremente, desde que mantenha o aviso de copyright e a licença original.

---

Dados meteorológicos fornecidos por Open-Meteo (CC BY 4.0) · © 2026 Maria Eduarda de Oliveira Gomes