TextNLPClassifierApp/specs/003-article-content-extractor/plan.md

Implementation Plan: Article Content Multi-Engine Extractor

Branch: 003-article-content-extractor | Date: 2026-08-20 | Spec: 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)

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

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.
• 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 e contracts/.
• Guia de execução rápida e validação em quickstart.md.

Phase 2: Tasks & Execution (Completed)

• Decomposição das tarefas de implementação em tasks.md e execução 100% concluída.