Manual de operação das fontes

Para quem opera o Clipping Jurídico e precisa responder três perguntas sem abrir o código:

1. De onde vem cada ato do acervo?
2. Como eu descubro que uma fonte parou?
3. O que eu faço quando ela para?

Este arquivo é operacional. A anatomia técnica de cada diário — como o TCE-SP delimita um ato, que armadilha custou dado perdido — está em FONTES.md, que é para quem vai mexer no código.

1. As três formas de coletar

Toda fonte do Clipping cai em uma destas três. O que muda é onde o conteúdo mora na origem, e é isso que determina como se conserta.

Na tela Administração → Fontes, a coluna api/xml/pdf de cada linha diz em qual delas ela está.

1.1 Por que a diferença importa

Numa fonte de API ou XML, a origem já separou os atos. O trabalho do Clipping é traduzir os campos dela para os campos daqui. Quando quebra, quase sempre é porque a origem renomeou um campo, mudou a URL ou passou a exigir algo novo.

Num PDF, a origem entrega um documento contínuo. O Clipping tem de descobrir onde termina um ato e começa o próximo, e ler a ficha de cada um (processo, órgão, objeto). Essa descoberta é um conjunto de expressões regulares chamado parser_config. Quando quebra, quase sempre é porque o diário mudou de diagramação — e aí é regex que precisa mudar, não código.

2. PDF: o que dá para consertar sem programar

Tela: Administração → Heurística.

Hoje aparecem ali as fontes cuja leitura é configuração:

• TCE-SP (tce:SP) — tem adaptador próprio em código, mas carrega junto a configuração equivalente, para comparar as duas antes de trocar de motor.
• DOM/SC (dom:sc-ciga) — roda 100% por configuração (clipping/configs/dom_sc.json).
• Qualquer fonte cadastrada pela tela "Cadastrar fonte" com o motor pdf_generico.

O que a oficina faz, na ordem em que se usa:

1. Analisar — baixa o diário de um dia e mostra quantos atos a configuração atual encontrou, quanto do texto ficou coberto, e uma amostra.
2. Testar regex — experimenta uma expressão contra o PDF e mostra o que ela casou, antes de salvar.
3. Comparar — roda a configuração nova ao lado da atual, lado a lado.
4. Regressão — aplica a configuração nova a vários dias passados e mostra se o número de atos por dia mudou.
5. Salvar — versiona a configuração anterior (source_config_versions), o que significa que toda mudança tem volta.
6. Reprocessar — reaplica a configuração nova aos dias já coletados.

Regra do produto: a oficina mede, não decide. Contagem diferente pode ser conserto ou estrago, e essa leitura é de quem conhece a fonte.

2.1 Os três defeitos de um PDF, e o que mexer

2.2 Quando a URL do PDF não é dedutível da data

Alguns diários nomeiam o arquivo com um número de edição ou um carimbo de tempo, que só a listagem do dia conhece:

https://edicao.dom.sc.gov.br/2026/09/1789750503_edicao_5246_assinada.pdf
                                     ^^^^^^^^^^        ^^^^

Para esses, a configuração usa descoberta: em vez de montar a URL, pede a página de listagem do dia e lê o link de lá.

"descoberta": {
  "url_template": "https://www.diariomunicipal.sc.gov.br/?r=site/edicoes&edicao={data:%d/%m/%Y}",
  "link_regex": "https://edicao\\.dom\\.sc\\.gov\\.br/[^\"'\\s]+\\.pdf",
  "limite": 4
}

Isso cobre também o caso de mais de uma edição por dia (ordinária e extra): todas são coletadas, cada uma com identificador próprio.

2.3 Cadastrar um diário PDF novo, com ajuda da IA

Tela: Fontes → Cadastrar fonte. Suba 2 ou 3 exemplares do PDF; o assistente lê o layout e devolve o parser_config pronto. O que ele propõe não é aceito às cegas: a configuração é validada, executada sobre as próprias amostras, e apresentada com números (quantos atos, quanta ficha, quanto texto coberto) antes de virar fonte.

3. API e XML: o que dá para consertar sem programar

Aqui a resposta honesta é: depende de como a fonte foi cadastrada.

• Fonte criada pela tela (api_generica / xml_generica) — o mapa de campos é configuração, aparece na oficina de heurística, e se conserta lá, inclusive com sugestão da IA.
• Fonte com adaptador escrito à mão (djen, doesp, stf, tcu, inlabs, queridodiario, tcesp, datajud) — o conserto é no código, porque cada uma tem regra que não cabe em configuração: o DJEN busca por termo do cliente, o INLABS faz login e baixa ZIP, o TCU divide um boletim em editais.

O que existe para as duas famílias: o diagnóstico com IA. Ele não substitui o conserto de código, mas elimina a parte cara — descobrir o que quebrou.

4. Saber que quebrou: o painel de saúde

Tela: Administração → Fontes, bloco "Saúde das fontes", no topo.

Uma linha por fonte, com veredito calculado a partir dos últimos 14 dias de coleta de verdade — não do campo "situação", que é o resultado do último teste manual e envelhece em silêncio.

Além do painel, três alarmes rodam sozinhos a cada ciclo do agendador e aparecem em Segurança:

• vpn — o túnel caiu, ou subiu num país errado (o pior: tudo parece funcionar e as origens devolvem 403);
• fonte — a coleta está dando erro;
• fonte_parada — a fonte responde, responde vazio, e parou de trazer;
• dia_encalhado — um dia ficou em aberto e o agendador não vai mais tentar. É o único estado da coleta sem conduta automática restante, e por isso o único que de fato pede uma pessoa.

5. Consertar: o diagnóstico com IA

No painel de saúde, botão "Diagnosticar com IA"; na lista de fontes, o botão IA de cada linha. Funciona para qualquer fonte, inclusive as de coletor escrito à mão.

O que ele faz:

1. Testa a origem agora (a mesma chamada que a coleta faz).
2. Junta o histórico gravado: collect_days dos últimos 10 dias, ingest_runs, o detalhe dos erros, a configuração da fonte e os atos mais recentes já coletados.
3. Manda tudo isso — só medição, nunca palpite — para a Claude.

O que ele devolve:

• Onde está o problema: origem / coletor / rede / configuração / nada;
• A causa, citando a evidência (data, status HTTP, trecho do erro);
• A conduta, em passos que uma pessoa executa;
• A confiança — e, quando não é alta, que medição resolveria a dúvida.

O laudo diz com todas as letras quando o conserto exige mexer no código; ele não finge que dá para resolver na interface.

Precisa de chave. Cadastre em Administração → IA → Fornecedores (Anthropic), ou defina ANTHROPIC_API_KEY no ambiente do servidor. Sem ela, o botão explica o que falta e o resto do sistema segue funcionando.

6. O DJEN coleta por termo do cliente — leia isto antes de abrir chamado

Esta é a característica mais mal-entendida do sistema. Vale para as 64 linhas djen:* (todos os TJs, TRFs, TRTs, STJ, TST, STM, TJMs).

O que acontece

O Clipping não baixa o DJEN inteiro. Para cada tribunal, ele consulta a API do CNJ uma vez por termo monitorado ativo de cliente que tenha aquele tribunal contratado, e guarda só o que voltar.

para cada termo ativo dos clientes com acesso a este tribunal:
    consultar a API do CNJ filtrando por esse termo
    guardar o que voltar

Por que é assim

Um tribunal grande disponibiliza mais de 10 mil comunicações por dia — TJSP, TJRJ e TRT2 bateram o teto de 10 mil da própria API em 11/09/2026. Sessenta e quatro tribunais assim dariam milhões de linhas por semana, quase nenhuma de interesse de algum cliente, e um acervo que nenhum plano de armazenamento paga.

As cinco consequências, que parecem defeito e não são

1. Tribunal sem nenhum termo apontado nunca traz nada. Zero publicações não é pane; é a ausência de pergunta. Se nenhum cliente monitora nada no TJAC, o TJAC não coleta nada — e está certo.
2. Termo novo não traz o passado. A busca roda para a frente. Cadastrou um termo hoje? Ele passa a ser procurado a partir de hoje. Para trazer o histórico é preciso repescar os dias à mão.
3. Testar sem termo não prova nada. O botão "testar" numa linha djen:* prova que a API responde; não prova o que um cliente veria. Use o campo "testar com este termo" ao lado, que faz exatamente a chamada da coleta.
4. A chave guarda-chuva djen não aceita teste sem termo. A API do CNJ recusa consulta sem tribunal nem texto (HTTP 422) — seria o país inteiro. Isso já fez o painel marcar como "falhou" a fonte que traz a maior parte do acervo judicial.
5. Silêncio de um tribunal não gera alerta. Por isso as linhas djen:* ficam fora do alarme "fonte parada": ele daria falso positivo todo dia. Quem revela uma queda real do DJEN é a chave guarda-chuva djen, que continua vigiada, e o alarme de erro, que vale para todas.

O que não funciona assim

Todas as outras fontes trazem o dia inteiro, independentemente de termo: DOU, DOE-SP, TCE-SP, TCU, STF (~900 publicações/dia, cabe inteiro), Querido Diário e DOM/SC. O casamento com os termos do cliente acontece depois, já dentro do Clipping, sobre o acervo completo.

Acesso é hierárquico

A chave djen libera djen:TJSP e os outros 63. A chave djen:TJSP libera só o TJSP. Mesma regra em qd:SP → qd:SP:3550308.

7. As fontes catalogadas que não coletam, e por quê

Medido de dentro do container (pela VPN brasileira) em 19/09/2026. A lista viva está em catalog.BLOQUEIOS e aparece na própria tela.

Quatro linhas foram removidas do catálogo em 19/09/2026 por serem duplicatas de cobertura que já funciona: fed:stf e djen:STF (o STF tem coletor próprio, stf), fed:stj (coberto por djen:STJ) e fed:tcu (o TCU tem coletor próprio, tcu). Elas apareciam como "sem coletor" e faziam a operação procurar defeito onde não havia.

O caminho para destravar uma dessas

Se a origem publica em PDF e tem uma página de listagem por data, a fonte pode ser cadastrada pela oficina com descoberta, sem código — foi assim que o DOM/SC entrou (2.577 atos de 143 municípios num dia). O que resta bloqueado exige navegador com execução de JavaScript, que este servidor não roda hoje.

8. Roteiro: "uma fonte parou, e agora?"

1. Administração → Fontes, topo da tela. Se o painel diz "Nenhuma fonte pedindo atenção", o problema não está na coleta.
2. Veja Segurança. Se há alerta de VPN, comece por ele: com o túnel fora do ar, ou no país errado, tudo falha junto e as origens devolvem 403 como se o coletor estivesse quebrado.
3. Clique em "Diagnosticar com IA" na fonte. O laudo já testou a origem.
4. Siga a conduta do laudo. Se ele diz "configuração", vá para a oficina de heurística. Se diz "origem", abra a URL no navegador e confirme. Se diz "coletor", é mudança de código.
5. Depois do conserto, repesque os dias perdidos. O agendador repesca sozinho até coleta_repescagem_dias (padrão: 7). Mais antigo que isso vira alerta dia_encalhado e precisa de repescagem manual — suba coleta_repescagem_dias temporariamente em Coletas → Regras da coleta, deixe o ciclo rodar, e restaure o valor.

9. Vocabulário

• collect_days — uma linha por (fonte, dia), com o estado da coleta daquele dia. ok e sem_edicao encerram; vazio, parcial e erro são retentados.
• sem_edicao — afirmação da origem de que não publicou. É terminal e nunca mais é tentado, então só é escrito quando alguém de fato perguntou depois da hora em que a fonte costuma publicar.
• vazio — nada veio, e ninguém afirmou nada. Continua tentando.
• Hora de corte — a hora a partir da qual "não publicou ainda" vira "não publicou". Por fonte, em Fontes → calendário.
• Repescagem — dias que saíram da janela normal e voltam à fila.
• Dia encalhado — dia em aberto que o agendador não vai mais tentar.