# Implementation Plan: Article Content Multi-Engine Extractor

**Branch**: `003-article-content-extractor` | **Date**: 2026-08-20 | **Spec**: [spec.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/spec.md)

**Input**: Feature specification from `specs/003-article-content-extractor/spec.md`

---

## Summary

Construção do extrator de conteúdo de artigos em lote (`scripts/extract_article_contents.py`), que consome listagens de notícias em JSON, acessa e renderiza as páginas de forma stealth via `foxcape` em modo headless reutilizando sessão de navegador, e executa uma tríplice extração de conteúdo com **Trafilatura**, **Newspaper4k** e **Readability**, salvando o resultado consolidado e higienizado em JSON na pasta `out/`.

---

## Technical Context

**Language/Version**: Python 3.10+  
**Primary Dependencies**: `foxcape` (Camoufox / stealth scraping), `trafilatura` (artigo e metadados), `newspaper4k` (artigo e NLP), `readability-lxml` (miolo e legibilidade), `beautifulsoup4`, `lxml`  
**Storage**: Arquivos JSON locais no diretório `out/`  
**Testing**: `pytest` com testes unitários e de integração mockando/testando o pipeline  
**Target Platform**: Windows / Linux / macOS (Terminal CLI)  
**Project Type**: CLI tool & modular extraction engine  
**Performance Goals**: Processamento em lote mantendo sessão de navegador ativa (estimativa de 1 a 2 segundos por notícia com DOMContentLoaded)  
**Constraints**: Operação 100% headless, descarte de HTML bruto da memória após extração para conter volume, logs em `stderr`  
**Scale/Scope**: Lotes de 1 a 100+ notícias por execução  

---

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Princípio | Avaliação | Status |
|---|---|---|
| **I. Library / Modular Design** | Classes de extração desacopladas por motor (`TrafilaturaExtractor`, `NewspaperExtractor`, `ReadabilityExtractor`). | ✅ Aprovado |
| **II. CLI Interface** | CLI via `scripts/extract_article_contents.py` com flags descritivas, `stderr` para status e `stdout` para JSON. | ✅ Aprovado |
| **III. Test-First / Automated Tests** | Testes automatizados cobrindo parsing de JSON, orquestração dos 3 motores e resiliência a falhas de rede. | ✅ Aprovado |
| **IV. Simplicity & YAGNI** | Uso direto dos módulos especializados existentes sem sobre-engenharia desnecessária. | ✅ Aprovado |

---

## Project Structure

### Documentation (this feature)

```text
specs/003-article-content-extractor/
├── plan.md              # Este plano de implementação
├── research.md          # Decisões técnicas e tradeoffs
├── data-model.md        # Entidades e modelos de dados
├── quickstart.md        # Guia de validação e execução
├── contracts/
│   ├── cli-contract.md  # Contrato de linha de comando
│   └── json-schema.md   # Esquemas JSON de entrada e saída
└── checklists/
    └── requirements.md  # Checklist de validação da especificação
```

### Source Code Layout

```text
scripts/
├── extract_google_news.py          # Extrator RSS do Google News existente
└── extract_article_contents.py     # [NEW] Extrator e Parser Multimotor de Artigos

tests/
├── test_extract_google_news.py     # Testes do extrator Google News existente
└── test_extract_article_contents.py # [NEW] Testes unitários e de integração do novo extrator
```

---

## Implementation Phases

### Phase 0: Outline & Research *(Completed)*
- Decisões de arquitetura consolidadas em [research.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/research.md).
- Definição do uso de sessão única de navegador `Foxcape(config=FoxcapeConfig(headless=True))` para aceleração em lote.
- Definição da estratégia de try/catch em 2 níveis para resiliência máxima.

### Phase 1: Design & Contracts *(Completed)*
- Entidades e contratos definidos em [data-model.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/data-model.md) e [contracts/](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/contracts/).
- Guia de execução rápida e validação em [quickstart.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/quickstart.md).

### Phase 2: Tasks & Execution *(Completed)*
- Decomposição das tarefas de implementação em `tasks.md` e execução 100% concluída.