feat(extractor): implement multi-engine article content extractor

- Added scripts/extract_article_contents.py for batch scraping with stealth Foxcape and triple extraction (Trafilatura, Newspaper4k, Readability) - Created unit, integration, and E2E test suite in tests/test_extract_article_contents.py (90/90 passing) - Updated specs/003-article-content-extractor and README.md with usage documentation and CLI contracts - Passed ruff linting/formatting and mypy type checking cleanly
2026-08-20 19:22:20 -03:00
parent 6e3d57619b
commit 6a45368cb0
85 changed files with 18345 additions and 3897 deletions
@@ -0,0 +1,85 @@
+# 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.