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

Implementation Tasks: Google News Headlines Extractor

Feature: Google News Headlines Extractor
Branch: 002-google-news-extractor | Date: 2026-08-20
Spec: spec.md | Plan: plan.md | Contracts: cli_contract.md

---

Phase 1: Setup (Shared Infrastructure)

Purpose: Instalar dependências necessárias e configurar fixtures de teste.

• T001 Adicionar foxcape, beautifulsoup4, googlenewsdecoder e selectolax ao requirements.txt e validar instalação
• T002 [P] Criar fixture XML de exemplo em tests/fixtures/google_news_sample.xml para testes offline

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Estruturas de dados base e utilitários de localização que sustentam todas as histórias de usuário.

• T003 Definir as dataclasses SearchQuery, NewsArticle e ExtractionResult em scripts/extract_google_news.py
• T004 [P] Implementar utilitário de mapeamento de idioma e país get_hl_gl_ceid em scripts/extract_google_news.py

---

Phase 3: User Story 1 - Extração Básica de Notícias por Assunto e Idioma (Priority: P1) 🌟 MVP

Goal: Permitir a extração de notícias de um termo e idioma via CLI, retornando JSON formatado com títulos, links e datas de publicação.

Independent Test: Executar python scripts/extract_google_news.py --query "tecnologia" --lang pt e verificar retorno de JSON válido no stdout contendo itens com título e URL.

Tests for User Story 1 🧪

• T005 [P] [US1] Criar testes unitários para parsing XML do RSS e limpeza de tags HTML em tests/test_extract_google_news.py

Implementation for User Story 1

• T006 [US1] Implementar função parse_google_news_rss com limpeza de tags HTML e deduplicação de subtítulos em scripts/extract_google_news.py
• T007 [US1] Implementar função extract_google_news utilizando a biblioteca foxcape em modo headless como motor primário em scripts/extract_google_news.py
• T008 [US1] Implementar interface CLI básica com argparse emitindo JSON para stdout em scripts/extract_google_news.py

Checkpoint: User Story 1 (MVP) 100% funcional e testável de forma independente.

---

Phase 4: User Story 2 - Filtragem Regional e Edição Geográfica (Priority: P2)

Goal: Permitir direcionamento de notícias por região/país com a flag --locale (ex: es com MX vs ES).

Independent Test: Executar python scripts/extract_google_news.py --query "futebol" --lang es --locale MX e verificar que a query foi montada com os parâmetros de edição regional correspondentes.

Tests for User Story 2 🧪

• T009 [P] [US2] Adicionar testes unitários para a flag --locale e resolução de ceid em tests/test_extract_google_news.py

Implementation for User Story 2

• T010 [US2] Integrar suporte à flag --locale / --country no CLI e fluxo de requisição em scripts/extract_google_news.py

Checkpoint: User Stories 1 e 2 funcionais e testáveis de forma independente.

---

Phase 5: User Story 3 - Paginação e Controle de Volume de Resultados (Priority: P3)

Goal: Permitir configuração de quantidade de páginas/itens (--max-pages de 1 a 10) e salvamento em arquivo (--output).

Independent Test: Executar com --max-pages 2 --output out/test_news.json e verificar arquivo gerado com até 20 itens divididos em páginas 1 e 2.

Tests for User Story 3 🧪

• T011 [P] [US3] Adicionar testes unitários para limite de páginas e exportação em arquivo em tests/test_extract_google_news.py

Implementation for User Story 3

• T012 [US3] Implementar fatiamento de páginas lógicas (--max-pages 1..10) e flag --output para gravação de arquivo com criação automática de diretórios pais em scripts/extract_google_news.py

Checkpoint: Todas as histórias de usuário funcionais e integradas.

---

Phase 6: URL Resolution, Headless Configuration & Real-Time Logging

Purpose: Resolver URLs reais dos veículos, suprimir janelas visuais de navegador e emitir feedback de progresso no terminal.

• T013 Implementar resolve_article_url e resolve_articles_urls com googlenewsdecoder e pool concorrente em scripts/extract_google_news.py
• T014 Configurar FoxcapeConfig(headless=True) garantindo raspagem 100% em background sem interface gráfica em scripts/extract_google_news.py
• T015 Adicionar logging em tempo real em sys.stderr e flag -s / --silent para supressão em scripts/extract_google_news.py
• T016 Adicionar flag --no-resolve-urls para permitir acesso às URLs brutas do feed quando desejado em scripts/extract_google_news.py

---

Phase 7: Verification & E2E Testing

Purpose: Testes automatizados de ponta a ponta e auditoria de tipagem e estilo.

• T017 Criar testes unitários para o resolvedor de URLs em tests/test_extract_google_news.py
• T018 Criar testes E2E ao vivo (test_e2e_resolve_real_google_news_url, test_e2e_extract_google_news_live_pipeline, test_e2e_cli_live_file_output) em tests/test_extract_google_news.py
• T019 Validar 100% de conformidade com ruff check, ruff format e mypy estrito
• T020 Executar suite completa do repositório garantindo 0 regressões