V.1.0
This commit is contained in:
kolmeasi
169
softwares/test/meteorologia_aeroportos/docs/about.md
Normal file
169
softwares/test/meteorologia_aeroportos/docs/about.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Documentação Técnica — Meteorologia de Superfície
|
||||
|
||||
## O que é
|
||||
|
||||
Sistema de coleta, processamento e visualização de dados meteorológicos horários de aeródromos brasileiros. Os dados são extraídos do portal de dados de superfície do ICEA/DECEA, armazenados em um banco SQLite local e disponibilizados em um dashboard interativo para análise de séries temporais, climatologia e condições operacionais de voo.
|
||||
|
||||
O sistema foi desenvolvido como parte de projeto de pesquisa no IED/ITA.
|
||||
|
||||
---
|
||||
|
||||
## Fonte dos dados
|
||||
|
||||
**Portal:** https://pesquisa.icea.decea.mil.br/superficie_list/
|
||||
**Órgão:** ICEA — Instituto de Controle do Espaço Aéreo / DECEA — Departamento de Controle do Espaço Aéreo
|
||||
**Tipo:** Observações meteorológicas de superfície de aeródromos brasileiros
|
||||
|
||||
Os dados são organizados no portal em **9 abas temáticas** por período trimestral:
|
||||
|
||||
| Aba | Conteúdo |
|
||||
|-----|----------|
|
||||
| CGT | Dados corrigidos de superfície (conjunto) |
|
||||
| Nuvem | Cobertura e tipo de nuvem |
|
||||
| Precipitação | Intensidade e duração da chuva |
|
||||
| Pressão | QNH e pressão de superfície |
|
||||
| RVR | Alcance visual de pista por cabeceira |
|
||||
| Temperatura | Bulbo seco, orvalho, umidade por pista |
|
||||
| Teto | Teto de nuvens por pista |
|
||||
| Vento | Velocidade, rajada e direção por cabeceira |
|
||||
| Visibilidade | Visibilidade predominante |
|
||||
|
||||
A cobertura histórica varia por aeródromo. Os três aeródromos com dados carregados
|
||||
no banco na versão inicial são:
|
||||
|
||||
| ICAO | Aeródromo | Início do histórico |
|
||||
|------|-----------|---------------------|
|
||||
| SBGR | Guarulhos / Cumbica (SP) | 1951 |
|
||||
| SBAN | Santos (SP) | 1973 |
|
||||
| SBCC | Campinas / Viracopos (SP) | 1992 |
|
||||
|
||||
---
|
||||
|
||||
## Como funciona
|
||||
|
||||
O fluxo completo é orquestrado pelo módulo `pipeline.py`:
|
||||
|
||||
```
|
||||
1. Verifica cobertura existente no banco (db.get_coverage)
|
||||
2. Passe forward — baixa dados novos após a data máxima existente
|
||||
3. Passe backward — baixa histórico anterior à data mínima existente
|
||||
4. Concatena os CSVs trimestrais por aba (concat_meteorologia)
|
||||
5. Deriva as 10 variáveis analíticas (build_analytics)
|
||||
6. Persiste no SQLite com validação de limites físicos (db.upsert_analytics)
|
||||
7. Salva CSV de backup em tabelas/preproc/meteorologia_aeroportos/<ICAO>/
|
||||
8. Valida por amostragem contra os arquivos fonte
|
||||
9. Remove os CSVs temporários (se validação aprovada e --cleanup ativo)
|
||||
```
|
||||
|
||||
### Derivação das variáveis analíticas
|
||||
|
||||
As 84+ colunas brutas (uma por medição específica, por pista ou cabeceira) são reduzidas
|
||||
a 10 variáveis float por timestamp:
|
||||
|
||||
| Variável | Derivação |
|
||||
|----------|-----------|
|
||||
| `T` | Média das colunas de temperatura de bulbo seco |
|
||||
| `Td` | Média das colunas de ponto de orvalho |
|
||||
| `UR` | Média das colunas de umidade relativa |
|
||||
| `QNH` | Coluna genérica de QNH ou agregação das específicas |
|
||||
| `WS` | Média das velocidades de vento por cabeceira |
|
||||
| `WG` | Máximo das rajadas por cabeceira |
|
||||
| `WD` | Média da direção do vento |
|
||||
| `VIS` | Mínimo da visibilidade predominante |
|
||||
| `TETO` | Mínimo do teto por pista (conservador) |
|
||||
| `PREC` | Soma da precipitação acumulada |
|
||||
|
||||
### Limites físicos aplicados
|
||||
|
||||
Valores fora dos intervalos abaixo são substituídos por `NULL` e registrados em `outlier_log`:
|
||||
|
||||
| Variável | Mínimo | Máximo |
|
||||
|----------|--------|--------|
|
||||
| T | −25 °C | 55 °C |
|
||||
| Td | −30 °C | 40 °C |
|
||||
| UR | 0 % | 100 % |
|
||||
| QNH | 940 hPa | 1060 hPa |
|
||||
| WS | 0 kt | 200 kt |
|
||||
| WG | 0 kt | 250 kt |
|
||||
| WD | 0° | 360° |
|
||||
| VIS | 0 dam | 9999 dam |
|
||||
| TETO | 0 dam | 9999 dam |
|
||||
| PREC | 0 mm | 500 mm |
|
||||
|
||||
---
|
||||
|
||||
## Limitações conhecidas
|
||||
|
||||
1. **Extração via web scraping, não via API oficial.**
|
||||
O sistema automatiza interações de navegador (Selenium + Chrome). Qualquer alteração
|
||||
no layout, estrutura HTML ou comportamento JavaScript do portal ICEA pode interromper
|
||||
a coleta sem aviso prévio.
|
||||
|
||||
2. **Fonte única e exclusiva.**
|
||||
Os dados provêm exclusivamente da tabela de dados de superfície do portal
|
||||
https://pesquisa.icea.decea.mil.br/superficie_list/. Não há integração com METAR,
|
||||
SYNOP, REDEMET, SPECI, SIGMET, ou qualquer outra fonte meteorológica ou aeronáutica.
|
||||
|
||||
3. **Sem tratamento de erros de lançamento.**
|
||||
Os dados são replicados como estão no portal. Erros de digitação, transcrição incorreta
|
||||
ou valores biologicamente implausíveis mas dentro dos limites físicos definidos não são
|
||||
detectados nem corrigidos. A qualidade dos dados depende integralmente da fonte.
|
||||
|
||||
4. **Limites físicos são condição necessária, não suficiente.**
|
||||
Os filtros removem valores meteorologicamente impossíveis (ex: temperatura de 500 °C),
|
||||
mas não detectam erros plausíveis dentro dos limites (ex: QNH de 1010 hPa registrado
|
||||
incorretamente como 1001 hPa).
|
||||
|
||||
5. **Dependência de hardware e software local.**
|
||||
A coleta requer Google Chrome instalado. A performance e o sucesso da coleta dependem
|
||||
de conexão com a internet, versão do Chrome, e disponibilidade do portal.
|
||||
|
||||
6. **Cobertura histórica variável.**
|
||||
Nem todos os aeródromos possuem histórico completo. A disponibilidade de dados depende
|
||||
do que foi inserido no portal — aeródromos mais antigos ou de menor porte podem ter
|
||||
lacunas significativas.
|
||||
|
||||
7. **Processamento sequencial.**
|
||||
A coleta é executada para um aeródromo por vez. Não há paralelização da coleta
|
||||
de múltiplos aeródromos.
|
||||
|
||||
8. **Sem atualização automática.**
|
||||
A coleta de dados novos deve ser iniciada manualmente pelo usuário, seja via dashboard
|
||||
ou via linha de comando.
|
||||
|
||||
---
|
||||
|
||||
## Oportunidades de melhoria
|
||||
|
||||
| Prioridade | Melhoria |
|
||||
|------------|----------|
|
||||
| Alta | Agendamento automático da coleta (cron / Task Scheduler) |
|
||||
| Alta | Notificação de falha na coleta (e-mail, webhook) |
|
||||
| Alta | Coleta paralela de múltiplos aeródromos |
|
||||
| Média | Integração com REDEMET / METAR para validação cruzada |
|
||||
| Média | Detecção de anomalias por métodos estatísticos (z-score, IQR) |
|
||||
| Média | API REST sobre o banco SQLite para consumo programático |
|
||||
| Média | Suporte a dados SYNOP e SPECI do portal |
|
||||
| Baixa | Exportação em formatos científicos (NetCDF, HDF5, Parquet) |
|
||||
| Baixa | Interface de configuração de alertas por variável e limiar |
|
||||
| Baixa | Mapa de cobertura dos aeródromos disponíveis |
|
||||
|
||||
---
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
**Chrome não encontrado / erro de WebDriver:**
|
||||
Verifique se o Google Chrome está instalado. O `webdriver-manager` baixa o ChromeDriver
|
||||
compatível automaticamente — é necessária conexão com a internet.
|
||||
|
||||
**Portal ICEA indisponível ou com layout alterado:**
|
||||
A coleta depende da estrutura HTML do portal. Se o portal alterar sua interface, o scraper
|
||||
pode parar de funcionar. Verifique o portal manualmente e abra uma issue no repositório.
|
||||
|
||||
**Dashboard não abre / porta ocupada:**
|
||||
```bash
|
||||
streamlit run _apps/dashboard.py --server.port 8502
|
||||
```
|
||||
|
||||
**Banco de dados não encontrado:**
|
||||
Execute o pipeline ao menos uma vez para criar e popular `db/met.db`.
|
||||
51
softwares/test/meteorologia_aeroportos/docs/authors.md
Normal file
51
softwares/test/meteorologia_aeroportos/docs/authors.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Autoria e Contribuições
|
||||
|
||||
## Autor original
|
||||
|
||||
| Campo | Informação |
|
||||
|-------|------------|
|
||||
| **Nome** | Sérgio Rebouças |
|
||||
| **Instituição** | IED — Instituto de Estudos para o Desenvolvimento / ITA — Instituto Tecnológico de Aeronáutica |
|
||||
| **Contato** | sreboucas1979@gmail.com |
|
||||
| **Versão inicial** | 2026 |
|
||||
|
||||
---
|
||||
|
||||
## Licença
|
||||
|
||||
Este software é distribuído sob a **MIT License** — veja o arquivo [`../LICENSE`](../LICENSE).
|
||||
|
||||
Em síntese: você pode usar, modificar e redistribuir livremente, inclusive para fins
|
||||
comerciais, desde que o aviso de copyright original seja mantido em todas as cópias
|
||||
e derivações.
|
||||
|
||||
---
|
||||
|
||||
## Como contribuir
|
||||
|
||||
Contribuições são bem-vindas. Ao modificar ou estender este software:
|
||||
|
||||
1. **Mantenha o aviso de copyright original** no topo de cada arquivo modificado.
|
||||
2. **Documente suas mudanças** em [`changelog.md`](changelog.md) com o seguinte formato:
|
||||
```
|
||||
## v<versão> — <Seu Nome> — <YYYY-MM>
|
||||
- Descrição objetiva da melhoria ou correção
|
||||
- Outra mudança relevante
|
||||
```
|
||||
3. **Siga o padrão de código** do projeto: Google Python Style Guide, type hints (PEP 484),
|
||||
docstrings Google-style (Args / Returns / Raises).
|
||||
4. **Não altere a autoria original** nos cabeçalhos existentes — apenas adicione a sua
|
||||
entrada no changelog.
|
||||
5. **Identifique claramente o escopo** da contribuição: use o campo de descrição do commit
|
||||
e o changelog para delimitar o que foi criado ou modificado por você.
|
||||
|
||||
---
|
||||
|
||||
## Histórico de contribuições
|
||||
|
||||
| Versão | Autor | Data | Descrição resumida |
|
||||
|--------|-------|------|--------------------|
|
||||
| v1.0 | Sérgio Rebouças | 2026-06 | Versão inicial — coleta, processamento, dashboard e documentação |
|
||||
|
||||
> Contribuidores futuros: adicione uma linha nesta tabela e crie a entrada correspondente
|
||||
> em `changelog.md`.
|
||||
39
softwares/test/meteorologia_aeroportos/docs/changelog.md
Normal file
39
softwares/test/meteorologia_aeroportos/docs/changelog.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Changelog
|
||||
|
||||
Todas as versões significativas estão registradas aqui.
|
||||
Cada entrada identifica o autor responsável pelas mudanças daquela versão.
|
||||
|
||||
Formato:
|
||||
```
|
||||
## v<versão> — <Autor> — <YYYY-MM>
|
||||
### Adicionado / Corrigido / Alterado / Removido
|
||||
- Descrição objetiva
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## v1.0 — Sérgio Rebouças — 2026-06
|
||||
|
||||
### Adicionado
|
||||
- Coleta automatizada de dados de superfície do portal ICEA/DECEA via Selenium
|
||||
- Pipeline completo: scraping → concatenação → analytics → SQLite → validação amostral
|
||||
- Dashboard interativo Streamlit com 8 abas (coleta, visão geral, temperatura, vento,
|
||||
pressão/precipitação, visibilidade/teto, climatologia, dados)
|
||||
- Classificação automática de condições de voo por categorias ICAO (LIFR/IFR/MVFR/VMC)
|
||||
- Banco SQLite com tabelas `observations`, `outlier_log` e `aerodromes`
|
||||
- Filtros de limites físicos com auditoria completa em `outlier_log`
|
||||
- Seletor de aeródromo no dashboard: sidebar mostra apenas aeródromos com dados;
|
||||
formulário de coleta mostra catálogo completo
|
||||
- Scripts de inicialização one-command (`run/run.bat`, `run/run.sh`)
|
||||
- Estrutura de diretórios organizada: `_apps/`, `run/`, `env/`, `db/`, `docs/`
|
||||
- Migração automática de layouts anteriores na inicialização do dashboard
|
||||
- Documentação técnica com limitações e oportunidades de melhoria (`docs/about.md`)
|
||||
|
||||
### Aeródromos com dados na versão inicial
|
||||
- SBGR — Guarulhos / Cumbica (SP) — histórico desde 1951
|
||||
- SBAN — Santos (SP) — histórico desde 1973
|
||||
- SBCC — Campinas / Viracopos (SP) — histórico desde 1992
|
||||
|
||||
---
|
||||
|
||||
<!-- Próximas versões: adicione acima desta linha -->
|
||||
Reference in New Issue
Block a user