Pendencias e Roadmap

Pendencias e Roadmap

Este backlog concentra os itens que ainda precisam virar issues no GitHub.

Resumo rapido

Pendencia	Resumo
Configurar envio diario de relatorio por email	Evitar envio repetido quando o workflow roda mais de uma vez por dia.
Criterios finais de qualidade da rodada	Transformar os sinais ja registrados pelo workflow em uma regra objetiva de aceite.
Definir resposta para fontes instaveis	Decidir quando timeouts recorrentes exigem retries, backoff ou coleta separada.
Desempenho do processamento de raws	Medir e reduzir o custo do processamento, principalmente na extracao de PDFs e nas fontes mais lentas.
Avaliar otimizacao dos PDFs brutos	Testar melhor a reducao de tamanho com qpdf antes de usar no backup oficial.
Avaliar pipeline produtor-consumidor por raw	Considerar uma fila real entre download e persistencia se o processamento virar gargalo.
Retomar Supabase no futuro	Pausar a sincronizacao enquanto o tamanho do banco excede a capacidade esperada do Supabase.
Aprimorar sincronizacao incremental com Supabase	Atualizar no Supabase registros antigos que foram corrigidos no banco local.
Duplicacao de registros e inchaco do SQLite	Resolver bug que insere cotações duplicadas e causa inchaço do banco devido a chaves dinâmicas.

Configurar envio diario de relatorio por email

O envio por e-mail ja foi parcialmente implementado no workflow por meio da action .github/actions/send-report-email, usando secrets SMTP e a variavel COTACOES_SEND_REPORT_EMAIL.

O workflow roda quatro vezes por dia (03:00, 09:00, 15:00 e 21:00 UTC). A pendencia principal e evitar um e-mail por rodada quando o objetivo for receber apenas um resumo diario.

Decisao atual:

• manter o envio opcional e desativavel por configuracao;
• nao bloquear a coleta por falta de provedor SMTP;
• escolher se o envio diario sera controlado por uma janela fixa ou por um marcador salvo na release;
• retomar a pesquisa de servidor SMTP gratuito/confiavel somente depois de definir essa regra diaria.

Criterios finais de qualidade da rodada

Foram implementadas melhorias importantes: o workflow registra download concluido, parcial ou falho por fonte, separa o status da persistencia, contabiliza falhas parciais e tenta salvar os artefatos antes da validacao final. Ainda falta transformar esses sinais em uma regra objetiva de aceite do pacote publicado.

Comportamento esperado:

1. definir limites minimos por fonte, volume ou perda aceitavel;
2. classificar a rodada como valida, parcial aproveitavel ou invalida no relatorio final;
3. deixar claro quando o pacote publicado nao deve substituir uma rodada boa;
4. manter os artefatos salvos para depuracao mesmo quando a rodada for invalida.

Definir resposta para fontes instaveis

A analise dos relatorios recentes nao indicou bloqueio explicito por 403, 429, HttpSourceBlocked, Forbidden ou Too Many Requests. Os problemas observados ficaram mais associados a timeout, fonte instavel, limite de busca historica e PDFs ausentes/malformados.

Pontos a investigar com mais cuidado:

1. A persistencia da CEASA-PR por Cotacao sem data foi tratada nos ajustes pos-analise locais da entrega final; agora o ponto restante e acompanhar se novas rodadas confirmam a estabilidade da correcao.
2. CEASA-PR ainda pode ter PDFs ausentes em algumas datas. PDFs malformados passaram a ter fallback com pdftotext, mas vale acompanhar se novas rodadas ainda registram falhas reais de extracao.
3. CEASA-Campinas e CEASA-RJ aparecem com timeouts frequentes e, quando o download falha, a persistencia fica como persistencia ignorada porque o download falhou.
4. CEASA-GO e CEASA-CE tambem apresentam timeouts, mas com frequencia menor que Campinas e RJ nas coletas recentes.
5. CEASA-BA e CEAGESP-SP foram tratadas como fontes de historico limitado; agora a pendencia e acompanhar se os limites reduzem avisos sem perder dado relevante.
6. A publicacao do pacote deve considerar essas falhas parciais para evitar substituir um pacote bom por uma rodada com perda relevante de fontes.

Acoes futuras:

• acompanhar as proximas rodadas para confirmar que a CEASA-PR nao volta a falhar por Cotacao sem data;
• separar falha de download, falha de parser e falha de persistencia no resumo para deixar o impacto por fonte mais claro;
• manter CEASA-Campinas e CEASA-RJ sob observacao; retries/backoff ou coleta separada ficam como alternativa futura se os timeouts continuarem relevantes;
• acompanhar fontes com historico limitado, como BA e CEAGESP-SP, para ajustar os limites se necessario;
• acompanhar nos proximos relatorios se surgem sinais reais de bloqueio HTTP (403, 429 ou Retry-After).

Desempenho do processamento de raws

Melhorar o desempenho do processamento de raws, principalmente nas fontes com grande volume de arquivos e nos parsers de PDF.

O relatorio data/relatorios/persistencia_20260610_204715_856649.md mostrou:

• duracao total de 1h53min54s;
• processamento dos raws: 1h30min34s, aproximadamente 79,5% do total;
• persistencia no SQLite: 19min07s, aproximadamente 16,8% do total;
• complemento PROHORT: 3min35s, aproximadamente 3,1% do total;
• CEASA-PR, CEASA-PE e CEASA-ES concentraram aproximadamente 85% da execucao;
• a CEASA-PR consumiu aproximadamente 50min12s, principalmente durante o processamento de 618 PDFs.

Medicoes necessarias:

• comparar por rodada COTACOES_WORKERS, tempo total do pipeline, janela de downloads, tempo acumulado de persistencia, espera na fila e backlog maximo;
• medir listagem e leitura dos arquivos;
• medir extracao de texto dos PDFs;
• medir parser especifico de cada fonte;
• medir normalizacao e criacao das cotacoes;
• medir persistencia no SQLite.

Melhorias a avaliar:

• acompanhar as metricas de tempo por etapa nos relatorios;
• comparar duracao, volume baixado e COTACOES_WORKERS para confirmar o ganho real do paralelismo entre fontes;
• acompanhar o ganho do salto de raws ja processados sem alteracao;
• acompanhar o ganho do cache de texto extraido de PDFs;
• processar raws independentes em paralelo com limite configuravel;
• reduzir trabalho repetido dentro dos parsers;
• priorizar a investigacao dos PDFs da CEASA-PR.

Qualquer otimizacao deve preservar os resultados atuais dos parsers, a proveniencia dos registros e a capacidade de reconstruir o banco a partir dos raws.

Avaliar otimizacao dos PDFs brutos

Foram feitos testes locais usando qpdf para reduzir o tamanho dos PDFs brutos sem alterar o conteudo aparente dos arquivos. A ideia pode ajudar a diminuir o tamanho do backup completo, principalmente no OneDrive, mas ainda nao deve entrar no fluxo oficial.

Motivo da cautela:

1. alguns PDFs das fontes ja chegam danificados ou fora do padrao esperado;
2. o qpdf consegue emitir avisos e reconstruir parcialmente alguns arquivos, mas isso precisa ser avaliado com cuidado;
3. ainda falta confirmar que o PDF otimizado nao interfere na extracao de texto, na interpretacao dos parsers e na persistencia correta no SQLite;
4. qualquer ganho de espaco nao pode comprometer a capacidade de reconstruir o banco a partir dos raws.

Decisao atual:

• manter o otimizador de PDF apenas como experimento local;
• nao incluir a otimizacao de PDFs no workflow oficial por enquanto;
• continuar preservando os raws originais no backup completo;
• usar xz no empacotamento oficial, porque ja reduz o tamanho do backup sem mexer no conteudo interno dos PDFs.

Antes de considerar essa otimizacao como parte do produto, validar pelo menos:

• tamanho antes/depois por fonte;
• quantidade de PDFs com aviso ou erro do qpdf;
• comparacao da extracao de texto antes/depois;
• comparacao das cotacoes persistidas antes/depois;
• impacto no tempo total do workflow.

Avaliar pipeline produtor-consumidor por raw

O fluxo atual ja sobrepoe download e persistencia entre fontes quando COTACOES_WORKERS e maior que 1: os downloads rodam em paralelo e a persistencia sequencial consome os resultados conforme cada fonte termina. Ainda assim, o processamento so comeca depois que a fonte conclui o download completo ou parcial.

A melhoria futura seria trocar esse modelo por uma fila produtor-consumidor por raw: cada arquivo baixado entraria em uma fila, enquanto um consumidor de persistencia processaria os raws continuamente sem interromper a raspagem.

No estado atual, os relatorios recentes indicam que o gargalo principal ainda e o download. A persistencia acumulada ficou baixa em comparacao com a janela de downloads, entao a mudanca nao parece prioritaria para ganho de tempo agora.

Avaliar essa implementacao somente se os relatorios mostrarem:

• aumento relevante do tempo acumulado de persistencia;
• crescimento do backlog ou da espera na fila;
• processamento de raws virando gargalo em relacao aos downloads;
• necessidade operacional de isolar melhor download e persistencia.

Cuidados antes de implementar:

• garantir que arquivos ainda em escrita nao sejam processados;
• preservar o tratamento de downloads parciais por fonte;
• manter a persistencia SQLite sem escrita concorrente perigosa;
• registrar metricas separadas de fila, processamento e salvamento;
• manter a capacidade de reconstruir o banco a partir dos raws.

Retomar Supabase no futuro

A integracao com Supabase existe, mas fica fora do escopo operacional por enquanto. O banco SQLite ficou grande demais para a capacidade esperada do plano avaliado, entao manter a sincronizacao remota ativa agora tende a trazer mais custo e instabilidade do que beneficio.

Decisao atual:

• manter o SQLite publicado como artefato principal;
• nao investir agora em correcoes incrementais do Supabase;
• retomar essa frente somente se houver plano/infra compatível com o tamanho da base ou necessidade real de API remota;
• se a frente voltar, reavaliar tambem atualizacao de registros antigos ja enviados, nao apenas insercao de novos registros.

Aprimorar sincronizacao incremental com Supabase

Atualmente, a sincronizacao incremental envia registros novos e atualiza as tabelas pequenas de referencia. Porem, ela nao detecta correcoes feitas em coletas ou cotacoes que ja haviam sido enviadas ao Supabase.

Exemplo: se o preco de uma cotacao antiga for corrigido no SQLite local, a sincronizacao incremental nao atualiza essa cotacao no Supabase. Atualmente, e necessario executar a substituicao completa para enviar a correcao.

A sincronizacao incremental deve identificar e atualizar esses registros antigos sem precisar substituir todo o banco remoto.

Duplicacao de registros e inchaco do SQLite

O banco de dados SQLite cresce indevidamente (~1.03 GB) devido a falhas na constraint de unicidade (ON CONFLICT (chave_unica) DO NOTHING).

Detalhes tecnicos:

1. A chave_unica de cotacoes baseia-se na coleta_key.
2. A coleta_key usa a coluna arquivo_raw (que inclui a data/hora do download no nome do arquivo físico).
3. Downloads repetidos do mesmo arquivo histórico criam novas chaves únicas, inserindo cópias idênticas.

Acoes futuras:

• Desvincular a chave_unica de dados físicos/timestamps de download (usar dados lógicos da cotação: data_cotacao, produto, categoria, preços, etc.).
• Limpar os registros duplicados existentes no banco SQLite.