# Research: Google News Headlines Extractor

## 1. Technical Decisions & Tradeoffs

### Decision 1: Motor de Requisição e Scraping com `foxcape` em Modo Headless
- **Decision**: Adotar o pacote `foxcape` com `FoxcapeConfig(headless=True, humanize=False)` como motor de requisição primário.
- **Rationale**: `foxcape` integra Camoufox e BeautifulSoup com evasões de fingerprinting TLS, runtime JS e headers avançados, impedindo bloqueios (429/403/Captchas) frequentes do Google News. A configuração `headless=True` garante que a execução ocorra 100% em segundo plano sem abrir janelas gráficas no sistema.
- **Alternatives Considered**:
  - `curl_cffi` + `beautifulsoup4` manual: Boa alternativa, mas exige orquestração manual de impersonação de TLS e headers.
  - `requests` padrão: Alto risco de bloqueio anti-bot pelo Google News.
  - Foxcape padrão sem configuração (`headless=False`): Abre janela visual do Firefox indesejada em execuções CLI e servidores.

---

### Decision 2: Endpoint RSS do Google News vs. Scraping de DOM
- **Decision**: Utilizar o endpoint oficial de busca RSS do Google News: `https://news.google.com/rss/search?q={query}&hl={hl}&gl={gl}&ceid={gl}:{hl}`.
- **Rationale**: Formato estruturado em XML padrão, com carregamento rápido e direto de todos os metadados necessários (`title`, `link`, `pubDate`, `description`), sem necessidade de lidar com seletores CSS voláteis da interface web renderizada.
- **Alternatives Considered**:
  - Scraping direto da interface HTML do Google News (`news.google.com/search`): Classes CSS ofuscadas e alteradas frequentemente pelo Google, quebrando facilmente a extração.

---

### Decision 3: Mapeamento de Idioma e Locale (`hl`, `gl`, `ceid`)
- **Decision**: Tabela de mapeamento determinística com fallback dinâmico.
  - `pt` → `hl=pt-BR`, `gl=BR`, `ceid=BR:pt-BR`
  - `es` → `hl=es-419`, `gl=AR`, `ceid=AR:es-419`
  - `en` → `hl=en-US`, `gl=US`, `ceid=US:en-US`
  - `de` → `hl=de`, `gl=DE`, `ceid=DE:de`
  - `fr` → `hl=fr`, `gl=FR`, `ceid=FR:fr`
  - `it` → `hl=it`, `gl=IT`, `ceid=IT:it`
  - Customizado: se fornecido `--locale MX`, sobrescreve o `gl` e ajusta `ceid={gl}:{hl}`.
- **Rationale**: Garante notícias contextualmente adequadas por país sem que o usuário precise memorizar os códigos técnicos internos do Google News.

---

### Decision 4: Resolução de URLs do Google News via `googlenewsdecoder`
- **Decision**: Resolver automaticamente as URLs intermediárias (`news.google.com/rss/articles/CBMi...`) para os links originais dos veículos de imprensa em lote com `concurrent.futures.ThreadPoolExecutor(max_workers=5)`.
- **Rationale**: Os links gerados pelo Google News contêm tokens RPC intermediários que dificultam a leitura e ingestão direta. A decodificação em lote resolve até 50 URLs em menos de 1 segundo sem sobrecarga.
- **Alternatives Considered**:
  - Resolução via Playwright headless para cada link: Muito lenta para listas de 20 a 50 notícias (demora 30 a 60 segundos).
  - Manter apenas a URL do Google News: Prejudica o usuário e sistemas downstream que precisam do domínio e link real do portal de notícias.

---

### Decision 5: Logging em Tempo Real no `stderr` e Segregação de Streams
- **Decision**: Enviar mensagens de status (`[INFO] ...`) para `sys.stderr` e reservar `sys.stdout` exclusivamente para o JSON.
- **Rationale**: Permite que o operador acompanhe o progresso em tempo real no terminal (`Consultando...`, `Decodificando URLs...`, `Arquivo salvo...`) sem quebrar a interoperabilidade com ferramentas de pipe como `jq` ou redirecionamentos de arquivo.