# Implementation Tasks: Google News Headlines Extractor

**Feature**: Google News Headlines Extractor  
**Branch**: `002-google-news-extractor` | **Date**: 2026-08-20  
**Spec**: [spec.md](./spec.md) | **Plan**: [plan.md](./plan.md) | **Contracts**: [cli_contract.md](./contracts/cli_contract.md)

---

## Phase 1: Setup (Shared Infrastructure)

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

- [X] T001 Adicionar `foxcape`, `beautifulsoup4`, `googlenewsdecoder` e `selectolax` ao requirements.txt e validar instalação
- [X] 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.

- [X] T003 Definir as dataclasses `SearchQuery`, `NewsArticle` e `ExtractionResult` em scripts/extract_google_news.py
- [X] 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 🧪
- [X] 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
- [X] 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
- [X] 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
- [X] 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 🧪
- [X] 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
- [X] 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 🧪
- [X] 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
- [X] 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.

- [X] T013 Implementar `resolve_article_url` e `resolve_articles_urls` com `googlenewsdecoder` e pool concorrente em scripts/extract_google_news.py
- [X] T014 Configurar `FoxcapeConfig(headless=True)` garantindo raspagem 100% em background sem interface gráfica em scripts/extract_google_news.py
- [X] T015 Adicionar logging em tempo real em `sys.stderr` e flag `-s / --silent` para supressão em scripts/extract_google_news.py
- [X] 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.

- [X] T017 Criar testes unitários para o resolvedor de URLs em tests/test_extract_google_news.py
- [X] 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
- [X] T019 Validar 100% de conformidade com `ruff check`, `ruff format` e `mypy` estrito
- [X] T020 Executar suite completa do repositório garantindo 0 regressões