# PRD — Conversão de artigo JSON para Markdown

## 1. Visão geral

O `TextNLPClassifierApp` já possui scripts para extrair artigos com Trafilatura, Newspaper4k e Readability e para selecionar deterministicamente o melhor extrator de conteúdo.

Esta feature adicionará a etapa seguinte do pipeline: receber o JSON de um único artigo, já contendo `selected_extractor`, selecionar deterministicamente os metadados disponíveis e gerar um arquivo Markdown com o conteúdo do extrator escolhido.

O arquivo `river_plate_extracted_selected(2).json` foi usado como referência de estrutura. Embora esse arquivo contenha uma coleção em `articles`, a entrada operacional desta feature será somente um objeto individual dessa coleção.

## 2. Problema

Cada artigo possui três resultados de extração com campos, formatos e níveis de preenchimento diferentes. O `selected_extractor` define qual corpo tem o maior peso e deve ser utilizado, mas metadados úteis podem estar ausentes nesse extrator e disponíveis em outro.

É necessário produzir um Markdown único e previsível sem escolher novamente o melhor conteúdo, sem usar LLM e sem depender de interpretação manual.

## 3. Objetivo

Criar um CLI Python que:

1. receba um arquivo JSON contendo exatamente um artigo;
2. valide os campos obrigatórios;
3. use exclusivamente o `selected_extractor` para obter o corpo do artigo;
4. selecione título, URL original e metadados opcionais por regras determinísticas;
5. converta o corpo HTML para Markdown quando necessário;
6. grave um arquivo `.md` legível, consistente e pronto para as etapas posteriores do pipeline.

## 4. História do usuário

Como operador do pipeline de conteúdo, quero converter o JSON selecionado de um artigo em um arquivo Markdown para que o conteúdo e os melhores metadados disponíveis possam ser consumidos pelas etapas seguintes do sistema.

## 5. Escopo

### 5.1 Incluído

- CLI Python.
- Leitura de um arquivo JSON com um único artigo.
- Suporte a `trafilatura`, `newspaper4k` e `readability` como valores de `selected_extractor`.
- Seleção determinística de metadados.
- Conversão de HTML para Markdown.
- Uso direto do Markdown já gerado pela Trafilatura quando disponível.
- Geração de um único arquivo `.md` por execução.
- Validação de entrada, saída e erros.
- Gravação atômica do arquivo de saída.
- Testes unitários, testes do CLI e arquivos de resultado esperado.

### 5.2 Fora do escopo

- Receber o objeto raiz com o array `articles`.
- Processar vários artigos em uma execução.
- Executar novamente Trafilatura, Newspaper4k ou Readability.
- Calcular ou alterar `selected_extractor`.
- Comparar, combinar ou complementar o corpo com conteúdo de outro extrator.
- Usar LLM, embeddings ou qualquer seleção probabilística.
- Fazer novas requisições HTTP.
- Baixar ou armazenar imagens.
- Limpar semanticamente publicidade, recomendações, overlays ou outros blocos editoriais presentes no corpo selecionado.
- Criar API, banco de dados, fila, interface gráfica ou integração externa.
- Alterar o JSON recebido.

## 6. Contrato de entrada

### 6.1 Formato

A entrada será um arquivo JSON UTF-8 cujo objeto raiz representa um único item do array `articles` observado no arquivo de referência.

Campos esperados no objeto:

| Campo | Tipo esperado | Obrigatoriedade | Uso |
|---|---|---:|---|
| `selected_extractor` | string | Obrigatório | Define a única fonte permitida para o corpo. |
| `input_meta` | object | Opcional | Fornece principalmente URL original, título e data de fallback. |
| `crawled_url` | string | Opcional | URL de fallback. |
| `page_title` | string | Opcional | Título de fallback. |
| `trafilatura` | object | Condicional | Obrigatório quando selecionado; opcional nos demais casos. |
| `newspaper4k` | object | Condicional | Obrigatório quando selecionado; opcional nos demais casos. |
| `readability` | object | Condicional | Obrigatório quando selecionado; opcional nos demais casos. |

### 6.2 Valores aceitos para `selected_extractor`

- `trafilatura`
- `newspaper4k`
- `readability`

Qualquer outro valor deve invalidar a entrada.

### 6.3 Campos obrigatórios após a resolução

O processamento somente será bem-sucedido se for possível resolver:

- título não vazio;
- URL original absoluta com protocolo `http` ou `https`;
- corpo não vazio pertencente ao `selected_extractor`.

Os demais campos são opcionais e nunca devem impedir a geração do Markdown.

## 7. Contrato de saída

### 7.1 Arquivo

- Formato: Markdown UTF-8.
- Quantidade: um arquivo por execução.
- Nome padrão: mesmo nome-base do JSON de entrada, substituindo `.json` por `.md`.
- Caminho alternativo: informado por `-o` ou `--output`.
- Escrita: arquivo temporário seguido de substituição atômica do destino.

### 7.2 Estrutura do Markdown

O Markdown deve seguir esta ordem:

```markdown
# Título do artigo

Subtítulo ou descrição, quando disponível.

**Autor:** Nome do autor
**Publicado em:** 2026-08-20T00:36:33-03:00
**Site:** Nome do site
**Categoria:** Categoria 1, Categoria 2
**Tags:** Tag 1, Tag 2
**Palavras-chave:** Palavra 1, Palavra 2
**Idioma:** es
**Fonte original:** [https://exemplo.com/artigo](https://exemplo.com/artigo)

![Imagem principal](https://exemplo.com/imagem.jpg)

---

Conteúdo do artigo em Markdown.
```

Regras de apresentação:

- título, URL original e corpo sempre devem aparecer;
- cada linha opcional deve ser completamente omitida quando não houver valor válido;
- nenhum placeholder como `null`, `None`, `N/A`, `unknown` ou `[no-author]` deve aparecer;
- o subtítulo deve ser omitido quando for igual ao título após normalização;
- a imagem principal deve ser omitida quando não possuir URL absoluta `http` ou `https`;
- o nome do `selected_extractor` não deve ser exibido no documento;
- os metadados técnicos internos do JSON não devem ser exibidos.

## 8. Regras funcionais

### RF-001 — Receber um único artigo

O CLI deve aceitar somente um objeto individual de artigo. Um objeto contendo `articles` deve ser rejeitado, pois o processamento em lote não pertence a esta feature.

### RF-002 — Respeitar o extrator selecionado

O corpo deve vir exclusivamente do extrator indicado em `selected_extractor`. A ausência de corpo utilizável nesse extrator deve encerrar o processamento com erro. O sistema não pode trocar silenciosamente para outro extrator.

### RF-003 — Resolver o corpo dentro do extrator selecionado

| `selected_extractor` | Fonte principal | Fallback do mesmo extrator | Tratamento |
|---|---|---|---|
| `trafilatura` | `trafilatura.markdown` | `trafilatura.text` | Usar o Markdown diretamente; o texto puro já é Markdown válido. |
| `newspaper4k` | `newspaper4k.article_html` | `newspaper4k.text` | Converter o HTML; usar texto puro somente quando o HTML estiver vazio. |
| `readability` | `readability.cleaned_html` | `readability.cleaned_text` | Converter o HTML; usar texto puro somente quando o HTML estiver vazio. |

O fallback ocorre somente entre representações do mesmo extrator selecionado.

### RF-004 — Selecionar metadados deterministicamente

Para cada campo, o sistema deve:

1. percorrer as fontes na ordem definida neste PRD;
2. normalizar e validar cada candidato;
3. selecionar o primeiro candidato válido;
4. não consultar as fontes restantes após a seleção;
5. omitir o campo se nenhum candidato opcional for válido.

A mesma entrada deve sempre gerar a mesma seleção e o mesmo arquivo.

### RF-005 — Priorizar metadados por campo

`SELECIONADO` representa o campo equivalente dentro do objeto indicado por `selected_extractor`. Quando o extrator não possuir o campo, essa posição é ignorada.

| Campo de saída | Ordem de prioridade |
|---|---|
| Título | `SELECIONADO.title` → `input_meta.titulo` → `page_title` → `newspaper4k.title` → `trafilatura.title` → `readability.title` |
| URL original | `input_meta.url` → `crawled_url` → URL canônica do selecionado → `trafilatura.canonical_url` → `newspaper4k.canonical_link` |
| Subtítulo/descrição | descrição do selecionado → `trafilatura.description` → `newspaper4k.meta_description` → `input_meta.subtitulo` |
| Autores | autor(es) do selecionado → `newspaper4k.authors` → `trafilatura.author` → `readability.author` |
| Data de publicação | data do selecionado → `newspaper4k.publish_date` → `trafilatura.date` → `input_meta.quando_publicado` |
| Site | site do selecionado → `trafilatura.sitename` → `newspaper4k.meta_site_name` → `trafilatura.hostname` → hostname da URL original |
| Categorias | categorias do selecionado → `trafilatura.categories` |
| Tags | tags do selecionado → `trafilatura.tags` → `newspaper4k.tags` → `newspaper4k.meta_keywords` |
| Palavras-chave | `newspaper4k.keywords` → `newspaper4k.meta_keywords` |
| Idioma | idioma do selecionado → `trafilatura.language` → `newspaper4k.meta_lang` |
| Imagem principal | imagem do selecionado → `newspaper4k.top_image` → `trafilatura.image` |

Mapeamento dos campos equivalentes do extrator selecionado:

| Informação | Trafilatura | Newspaper4k | Readability |
|---|---|---|---|
| Título | `title` | `title` | `title` |
| Descrição | `description` | `meta_description` | Não disponível |
| Autores | `author` | `authors` | `author` |
| Data | `date` | `publish_date` | Não disponível |
| Site | `sitename` | `meta_site_name` | Não disponível |
| Categorias | `categories` | Não disponível | Não disponível |
| Tags | `tags` | `tags` | Não disponível |
| Idioma | `language` | `meta_lang` | Não disponível |
| Imagem principal | `image` | `top_image` | Não disponível |
| URL canônica | `canonical_url` | `canonical_link` | Não disponível |

### RF-006 — Normalizar valores escalares

Antes da validação, toda string candidata deve:

- ter entidades HTML decodificadas;
- remover espaços no início e no fim;
- colapsar sequências internas de espaços em um único espaço;
- ser considerada ausente quando vazia ou quando corresponder, sem diferença entre maiúsculas e minúsculas, a um placeholder conhecido: `null`, `none`, `n/a`, `unknown`, `[no-author]` ou `no-author`.

### RF-007 — Normalizar listas

Autores, categorias, tags e palavras-chave podem chegar como lista ou string. O sistema deve:

- aceitar lista de strings;
- aceitar string única;
- separar strings com múltiplos valores apenas por ponto e vírgula;
- normalizar cada item conforme RF-006;
- descartar autor iniciado por `http://`, `https://` ou `www.`;
- eliminar duplicatas sem diferenciar maiúsculas de minúsculas, preservando a primeira grafia e a ordem original;
- considerar a fonte inválida quando nenhum item válido restar;
- usar somente a primeira fonte da tabela de prioridade que resultar em lista válida, sem unir listas de fontes diferentes.

### RF-008 — Normalizar datas

- Aceitar datas ISO 8601 e RFC 2822 observadas na entrada de referência.
- Emitir ISO 8601.
- Preservar o fuso horário informado.
- Emitir somente `YYYY-MM-DD` quando a fonte fornecer apenas a data.
- Considerar inválida uma data que não possa ser interpretada e continuar para a próxima fonte de prioridade.

### RF-009 — Validar URLs

- Aceitar somente URLs absolutas com protocolo `http` ou `https`.
- Não fazer requisições para validar existência ou disponibilidade.
- Não aceitar `data:`, `javascript:`, caminhos relativos ou strings sem hostname.

### RF-010 — Converter HTML para Markdown

A conversão deve usar a biblioteca Python `markdownify`, configurada para produzir títulos no padrão ATX (`#`, `##`, `###`).

Devem ser preservados, quando presentes no HTML selecionado:

- parágrafos;
- títulos e subtítulos estruturais;
- listas ordenadas e não ordenadas;
- negrito e itálico;
- links;
- citações;
- blocos de código;
- tabelas suportadas pela biblioteca;
- imagens válidas do próprio corpo.

A escolha de `markdownify` é intencional: a necessidade é exclusivamente converter HTML para Markdown. O Microsoft MarkItDown suporta HTML, mas atende vários outros formatos e acrescentaria uma abstração mais ampla do que a requerida por esta feature.

### RF-011 — Tratar imagens do corpo

- Preservar imagens convertidas do corpo somente quando o destino for uma URL absoluta `http` ou `https`.
- Remover imagens com URL vazia, relativa ou `data:`.
- Eliminar repetições exatas da mesma URL de imagem, preservando a primeira ocorrência.
- Não adicionar ao corpo a coleção `newspaper4k.images`.
- Não baixar, redimensionar ou validar remotamente imagens.

### RF-012 — Evitar título duplicado

Após a conversão do corpo, o sistema deve remover o primeiro título H1 do corpo somente quando ele for igual ao título resolvido após decodificação de HTML, normalização de espaços e comparação sem diferença entre maiúsculas e minúsculas.

Outros títulos do conteúdo devem ser preservados.

### RF-013 — Normalizar o Markdown final

O arquivo final deve:

- usar quebra de linha `LF`;
- terminar com exatamente uma quebra de linha;
- eliminar espaços no final das linhas;
- limitar sequências de linhas vazias a no máximo duas;
- não conter tags HTML remanescentes geradas apenas pela estrutura do documento;
- preservar o texto, a pontuação e os caracteres Unicode do conteúdo selecionado.

### RF-014 — Não gerar saída parcial

Se ocorrer qualquer erro antes da conclusão, o arquivo de destino existente deve permanecer intacto e nenhum arquivo temporário deve permanecer no diretório de saída.

## 9. Interface CLI

### 9.1 Script

`scripts/convert_article_to_markdown.py`

### 9.2 Argumentos

| Parâmetro | Tipo | Obrigatoriedade | Padrão | Descrição |
|---|---|---:|---|---|
| `-i`, `--input` | caminho | Obrigatório | — | JSON contendo um único artigo. |
| `-o`, `--output` | caminho | Opcional | `<input_stem>.md` | Arquivo Markdown de destino. |

Não devem ser adicionadas flags sem requisito funcional neste PRD.

### 9.3 Exemplos

```bash
python scripts/convert_article_to_markdown.py -i out/article_001.json
```

Resultado: `out/article_001.md`.

```bash
python scripts/convert_article_to_markdown.py \
  -i out/article_001.json \
  -o out/markdown/article_001.md
```

### 9.4 Saída do processo

- Código `0`: arquivo gerado com sucesso.
- Código `2`: argumentos inválidos, conforme comportamento do `argparse`.
- Código `1`: erro de leitura, validação, conversão ou gravação.
- Mensagens de erro e confirmação devem ir para `stderr`.
- O conteúdo Markdown não deve ser impresso no terminal quando houver arquivo de saída.

## 10. Tratamento de erros

O processamento deve falhar de forma clara nos seguintes casos:

| Situação | Comportamento esperado |
|---|---|
| Arquivo não encontrado ou ilegível | Encerrar com código `1` e informar o caminho. |
| JSON inválido | Encerrar com código `1` e informar que a entrada não é JSON válido. |
| Raiz diferente de objeto | Encerrar com código `1`. |
| Entrada contém `articles` | Encerrar com código `1` e informar que o CLI aceita um único artigo. |
| `selected_extractor` ausente ou desconhecido | Encerrar com código `1`. |
| Objeto do extrator selecionado ausente | Encerrar com código `1`. |
| Corpo do extrator selecionado vazio | Encerrar com código `1`; não usar outro extrator. |
| Título não resolvido | Encerrar com código `1`. |
| URL original não resolvida ou inválida | Encerrar com código `1`. |
| Metadado opcional inválido | Ignorar o candidato e tentar o próximo; omitir se todos falharem. |
| Falha na conversão | Encerrar com código `1`. |
| Falha na gravação | Encerrar com código `1` sem alterar o destino anterior. |

As mensagens não devem imprimir o conteúdo integral do artigo.

## 11. Requisitos não funcionais

### RNF-001 — Determinismo

A mesma entrada e a mesma versão das dependências devem produzir exatamente o mesmo arquivo Markdown.

### RNF-002 — Compatibilidade

A feature deve manter as versões de Python declaradas como suportadas pelo projeto e funcionar nos sistemas operacionais já suportados pelo repositório.

### RNF-003 — Execução local

O processamento deve ocorrer inteiramente em memória local, sem rede, browser, LLM ou serviço externo.

### RNF-004 — Integridade

A entrada não deve ser modificada. A gravação de saída deve ser atômica.

### RNF-005 — Manutenibilidade

As regras de resolução de campos e as regras de conversão devem ser isoladas em funções testáveis, sem duplicação entre o CLI e o uso interno.

### RNF-006 — Qualidade

O código deve atender aos gates já adotados pelo projeto: Ruff, Mypy, Pytest e SonarQube.

## 12. Critérios de aceite

### CA-001 — Trafilatura selecionada

**Dado** um artigo com `selected_extractor` igual a `trafilatura` e `trafilatura.markdown` preenchido  
**Quando** o CLI for executado  
**Então** o corpo do arquivo deve vir de `trafilatura.markdown` e nenhum corpo dos demais extratores deve ser incorporado.

### CA-002 — Newspaper4k selecionado

**Dado** um artigo com `selected_extractor` igual a `newspaper4k` e `newspaper4k.article_html` preenchido  
**Quando** o CLI for executado  
**Então** esse HTML deve ser convertido para Markdown preservando sua estrutura editorial.

### CA-003 — Readability selecionado

**Dado** um artigo com `selected_extractor` igual a `readability` e `readability.cleaned_html` preenchido  
**Quando** o CLI for executado  
**Então** esse HTML deve ser convertido para Markdown preservando sua estrutura editorial.

### CA-004 — Fallback dentro do extrator

**Dado** um extrator selecionado cujo campo estruturado esteja vazio, mas cujo campo de texto puro esteja preenchido  
**Quando** o CLI for executado  
**Então** o texto puro do mesmo extrator deve ser usado.

### CA-005 — Proibição de fallback de corpo entre extratores

**Dado** um extrator selecionado sem HTML, Markdown ou texto utilizável e outro extrator com conteúdo  
**Quando** o CLI for executado  
**Então** o processamento deve falhar sem utilizar o outro extrator.

### CA-006 — Metadado vindo de outro extrator

**Dado** um artigo cujo extrator selecionado não possua autor e outro extrator possua autor válido  
**Quando** o CLI for executado  
**Então** o primeiro autor válido conforme a prioridade deve aparecer no Markdown.

### CA-007 — Obrigatórios presentes

**Dado** um artigo válido  
**Quando** o Markdown for gerado  
**Então** ele deve conter título, URL original e corpo não vazio.

### CA-008 — Opcionais ausentes

**Dado** um artigo sem metadados opcionais válidos  
**Quando** o Markdown for gerado  
**Então** nenhuma linha vazia de metadado ou placeholder deve ser exibida.

### CA-009 — Imagens inválidas

**Dado** um corpo com imagens `data:`, vazias ou relativas  
**Quando** o conteúdo for convertido  
**Então** essas imagens devem ser removidas do Markdown.

### CA-010 — Título repetido no corpo

**Dado** um corpo que começa com H1 igual ao título resolvido  
**Quando** o Markdown for montado  
**Então** deve existir somente um H1 com esse título no arquivo final.

### CA-011 — Entrada em lote rejeitada

**Dado** o arquivo completo de referência contendo `articles`  
**Quando** ele for passado diretamente ao CLI  
**Então** o processamento deve falhar informando que a entrada esperada é um único artigo.

### CA-012 — Determinismo

**Dado** o mesmo JSON processado duas vezes com as mesmas dependências  
**Quando** os arquivos forem comparados byte a byte  
**Então** eles devem ser idênticos.

### CA-013 — Gravação segura

**Dado** um arquivo de destino preexistente e uma falha durante o processamento  
**Quando** o CLI encerrar  
**Então** o arquivo preexistente deve continuar inalterado.

## 13. Estratégia de testes

### 13.1 Testes unitários

- resolução de cada campo conforme a ordem de prioridade;
- normalização de strings e placeholders;
- normalização, deduplicação e seleção de listas;
- parsing e padronização de datas ISO 8601 e RFC 2822;
- validação de URLs;
- seleção do corpo para cada extrator;
- fallback de representação dentro do mesmo extrator;
- bloqueio do fallback de corpo para outro extrator;
- conversão dos principais elementos HTML;
- remoção de imagens inválidas e duplicadas;
- remoção somente do H1 inicial duplicado;
- normalização final de espaços e quebras de linha.

### 13.2 Testes de integração do CLI

- geração com caminho padrão;
- geração com `--output`;
- códigos de saída `0`, `1` e `2`;
- mensagens em `stderr`;
- rejeição do JSON com coleção `articles`;
- preservação do destino em caso de falha;
- codificação UTF-8 com caracteres acentuados.

### 13.3 Casos de resultado esperado

Devem existir pelo menos três fixtures válidas, uma para cada valor de `selected_extractor`, acompanhadas dos respectivos arquivos Markdown esperados. A comparação deve ser exata.

Também devem existir fixtures inválidas cobrindo:

- JSON corrompido;
- `selected_extractor` ausente;
- extrator desconhecido;
- corpo selecionado vazio;
- título ausente em todas as fontes;
- URL ausente ou inválida em todas as fontes;
- objeto raiz contendo `articles`.

## 14. Definition of Done

A feature será considerada concluída quando:

- o script `scripts/convert_article_to_markdown.py` estiver implementado;
- `markdownify` estiver declarada nas dependências do projeto;
- todos os requisitos funcionais e critérios de aceite estiverem cobertos;
- os testes unitários e de integração estiverem passando;
- as três fixtures de extratores produzirem exatamente os Markdown esperados;
- Ruff não apontar erros;
- Mypy não apontar erros;
- o conjunto completo de testes do projeto permanecer aprovado;
- o Quality Gate do SonarQube estiver aprovado;
- o README documentar a nova etapa, os argumentos e exemplos do CLI;
- nenhuma funcionalidade fora do escopo tiver sido adicionada.

## 15. Dependência técnica escolhida

- Biblioteca: [`markdownify`](https://github.com/matthewwithanm/python-markdownify)
- Finalidade: conversão direta de HTML para Markdown em Python.
- Alternativa avaliada: [`Microsoft MarkItDown`](https://github.com/microsoft/markitdown).
- Decisão: não usar MarkItDown nesta feature porque seu escopo de conversão multiformato excede a necessidade de HTML para Markdown.