TextNLPClassifierApp/specs/002-google-news-extractor/research.md

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.