Initial Clima Cuida app

docs/EXECUCAO.md

@@ -0,0 +1,45 @@
+# Execução
+
+## Arquitetura
+
+```text
+src/
+  api/openMeteo.ts       chamadas e normalização das APIs públicas
+  components/           peças de interface do dashboard
+  data/mock.ts          dados de fallback e perfis de uso
+  lib/formatters.ts     datas, unidades e textos curtos
+  lib/riskScore.ts      score local e recomendações
+  lib/riskScore.test.ts testes unitários do score
+  App.tsx               estado, preferências e composição da tela
+```
+
+## Fluxo de dados
+
+1. O usuário busca uma cidade ou autoriza geolocalização.
+2. `openMeteo.ts` chama Weather Forecast e Air Quality em paralelo.
+3. Os dados são normalizados para `WeatherBundle`.
+4. `riskScore.ts` calcula fatores de UV, chuva, sensação térmica, vento e poluição.
+5. A UI mostra semáforo, métricas, recomendações, timeline e previsão.
+6. Perfil e local escolhido ficam no `localStorage`.
+
+## Decisões técnicas
+
+- Vite + React + TypeScript para manter o projeto pequeno e didático.
+- CSS próprio para evitar dependências de UI e facilitar explicação em aula.
+- `lucide-react` apenas para ícones funcionais.
+- `Vitest` para testes unitários do cálculo de risco.
+- Sem backend, banco de dados, autenticação ou chaves privadas.
+- Fallback local explícito quando a API não responde.
+
+## Cálculo de risco
+
+O score combina:
+
+- UV alto.
+- Chance e intensidade de chuva.
+- Sensação térmica extrema.
+- Vento e rajadas.
+- PM2.5, PM10 e AQI dos EUA.
+- Ajuste por perfil de uso.
+
+O maior fator individual também pesa no resultado final para impedir que uma média esconda um risco grave, como poluição alta para quem tem rinite/asma.

docs/FINALIZACAO.md

@@ -0,0 +1,30 @@
+# Finalização
+
+## Antes do commit
+
+- [ ] `npm install` executado e `package-lock.json` versionado.
+- [ ] `npm test` passando.
+- [ ] `npm run build` passando.
+- [ ] `README.md` revisado.
+- [ ] Docs em `docs/` revisados.
+- [ ] Nenhum arquivo de build em `dist/` no commit.
+- [ ] Nenhum segredo, token ou chave privada no repositório.
+
+## Antes do deploy
+
+- [ ] Confirmar nome do repositório GitHub: `clima-cuida-care-weather`.
+- [ ] Confirmar `base: '/clima-cuida-care-weather/'` em `vite.config.ts`.
+- [ ] Ativar GitHub Pages por GitHub Actions.
+- [ ] Fazer push na branch `main`.
+- [ ] Abrir a URL pública e testar busca, perfis e fallback.
+
+## Roteiro de apresentação
+
+1. Abrir o app e explicar a dor em uma frase.
+2. Pesquisar uma cidade real.
+3. Mostrar o semáforo e a frase principal.
+4. Trocar para perfil criança, idoso, rinite/asma e atividade física.
+5. Abrir "Por que essa recomendação?" e explicar o score.
+6. Mostrar `src/lib/riskScore.ts` e `src/lib/riskScore.test.ts`.
+7. Rodar `npm test` e `npm run build`.
+8. Mostrar o deploy no GitHub Pages.

docs/PLANEJAMENTO.md

@@ -0,0 +1,36 @@
+# Planejamento
+
+## Problema
+
+As pessoas precisam tomar decisões rápidas sobre sair, trabalhar na rua, levar crianças ou idosos, fazer exercício e se proteger. A informação existe, mas fica fragmentada entre previsão do tempo, índice UV e qualidade do ar.
+
+## Público-alvo
+
+- Pessoas comuns que querem uma leitura objetiva antes de sair.
+- Professores e alunos em aula de coding com APIs reais.
+- Famílias com crianças, idosos ou pessoas com rinite/asma.
+- Pessoas que praticam atividade física ao ar livre.
+
+## Proposta de valor
+
+O Clima Cuida resume clima e ar em um semáforo de risco, explica os fatores que pesaram e entrega ações práticas: levar guarda-chuva, beber água, evitar exercício intenso, usar protetor solar, fechar janelas ou ter atenção com grupos sensíveis.
+
+## Escopo MVP
+
+- Busca de cidade com Open-Meteo Geocoding.
+- Geolocalização opcional do navegador.
+- Dados atuais, próximas 12 horas e próximos 7 dias.
+- Perfis de uso com impacto no score.
+- Score de risco local de 0 a 100.
+- Fallback com dados de exemplo quando a API falha.
+- Preferências persistidas no `localStorage`.
+- UI estática compatível com GitHub Pages.
+
+## Critérios de sucesso
+
+- `npm test` passa.
+- `npm run build` passa.
+- A primeira tela é o produto, não uma landing page.
+- O app continua útil sem API.
+- A decisão do dia fica clara em menos de 10 segundos.
+- A geolocalização é opcional e não é armazenada fora do navegador.

docs/QA.md

@@ -0,0 +1,41 @@
+# QA
+
+## Checklist manual
+
+- [ ] Abrir a primeira tela e confirmar que já é o dashboard do produto.
+- [ ] Pesquisar uma cidade com acentos, como "São Paulo".
+- [ ] Pesquisar uma cidade internacional, como "Lisboa".
+- [ ] Selecionar cada perfil e confirmar que o semáforo pode mudar.
+- [ ] Usar o botão de geolocalização e negar permissão.
+- [ ] Usar o botão de geolocalização e aceitar permissão.
+- [ ] Simular API offline e confirmar dados de exemplo com aviso claro.
+- [ ] Rodar `npm test`.
+- [ ] Rodar `npm run build`.
+
+## Responsividade
+
+- [ ] 360px: sem scroll horizontal, busca e perfis acessíveis.
+- [ ] 390px a 430px: semáforo legível e timeline rolável.
+- [ ] 600px a 820px: métricas em grid equilibrado.
+- [ ] 1024px: dashboard com leitura confortável.
+- [ ] 1366px e 1440px: layout denso, sem vazios excessivos.
+- [ ] 1920px: conteúdo continua contido e escaneável.
+
+## Acessibilidade
+
+- [ ] Campos com labels.
+- [ ] Botões com texto ou `aria-label`.
+- [ ] Navegação por teclado na busca, botões e perfis.
+- [ ] Contraste suficiente nos estados verde, amarelo, laranja e vermelho.
+- [ ] `aria-live` para mensagens da busca.
+- [ ] `role="alert"` para erro de API.
+
+## Casos extremos
+
+- [ ] UV acima de 8.
+- [ ] PM2.5 acima de 55.
+- [ ] AQI acima de 150.
+- [ ] Chuva acima de 65% de probabilidade.
+- [ ] Sensação térmica acima de 34°C.
+- [ ] Rajadas acima de 48 km/h.
+- [ ] AQI ausente.

docs/RED_TEAM.md

@@ -0,0 +1,28 @@
+# Red Team
+
+## Riscos e mitigação
+
+| Risco | Impacto | Mitigação |
+| --- | --- | --- |
+| Interpretação como recomendação médica | Usuário pode tomar decisão de saúde inadequada | Aviso visível: "Use como orientação geral, não como recomendação médica." |
+| Falha ou lentidão da API | Tela vazia ou sensação de app quebrado | Fallback com dados de exemplo e banner claro |
+| Geolocalização sensível | Preocupação de privacidade | Permissão opcional, sem envio para servidor próprio e sem persistir coordenadas fora do navegador |
+| Dados de qualidade do ar com resolução regional | Leitura local pode não capturar microclimas | Texto explica fatores como orientação geral |
+| Score simplificado demais | Pode ocultar nuances técnicas | Bloco "Por que essa recomendação?" mostra os fatores e valores usados |
+| Uso para direção em clima severo | Decisão crítica exige fontes oficiais locais | Mensagens evitam prometer segurança absoluta |
+| Abuso por coleta futura de dados | Perda de confiança | Não há backend, login, analytics ou banco de dados no MVP |
+
+## Falhas de API esperadas
+
+- Sem resultados na busca de cidade.
+- Erro HTTP da API.
+- Campo opcional ausente, como AQI.
+- Navegador sem geolocalização.
+- Usuário nega permissão de localização.
+
+## Mitigações implementadas
+
+- Tratamento de erro em `SearchBar`.
+- Fallback em `App.tsx`.
+- Normalização defensiva em `openMeteo.ts`.
+- Testes unitários para cenários extremos do score.