Regras de Atualização e Sincronização¶

Sistema: Drexies Agro | Responsável: Equipe de Dados Sonar

Esta página descreve como os dados da Drexies Agro são consultados, atualizados, sincronizados, invalidados e armazenados, conforme o comportamento identificado no código.

Visão geral¶

flowchart LR
    O[Origem] --> Q[Consulta ou sincronização]
    Q --> P[Supabase persistido]
    Q --> M[Dados em memória]
    P --> R[Hooks e React Query]
    R --> C[Cache do frontend]
    C --> T[Telas]
    M --> T
    T --> A[Criação, edição ou exclusão]
    A --> P
    A --> I[Invalidação ou atualização do cache]
    I --> T

Não foi identificado um único processo global de atualização. Cada domínio usa o mecanismo adequado: leitura PostgREST, RPC, Edge Function, cache do React Query, cálculo no frontend ou armazenamento local.

Tipos de dado e comportamento de atualização¶

PostgREST e RPCs¶

Os services usam o cliente Supabase para executar consultas e mutações nas tabelas PostgreSQL por PostgREST. Foram identificadas operações select, insert, update, upsert e delete.

Tela → hook/service → PostgREST → PostgreSQL → resposta → cache ou estado da tela

A visão regional também utiliza a RPC get_macro_aggregates. Os filtros selecionados são enviados ao banco, que devolve agregações por município, cultura e vendedor.

Filtros → RPC get_macro_aggregates → agregação no PostgreSQL → indicadores regionais

Não foi identificado no repositório um agendamento periódico para executar essa RPC. A consulta ocorre quando o fluxo da aplicação a solicita.

React Query, cache e invalidação¶

O frontend usa React Query para identificar consultas por chaves, reutilizar respostas em memória e controlar quando um dado passa a ser considerado desatualizado.

Tempos técnicos identificados¶

staleTime define quando o React Query passa a considerar a resposta desatualizada; ele não comprova que a fonte externa tenha sido modificada nesse intervalo. gcTime controla por quanto tempo uma consulta sem uso pode permanecer no cache do cliente.

Alguns hooks de dados macro e potenciais personalizados desabilitam a atualização automática ao voltar o foco para a janela. Portanto, recuperar o foco do navegador não garante nova consulta nesses casos.

Invalidação e atualização direta¶

Após determinadas mutações, a aplicação invalida as chaves relacionadas para permitir uma nova leitura. Em outros fluxos, usa setQueryData para substituir imediatamente o conteúdo em cache pela resposta recebida.

Exemplos comprovados:

• a alteração dos parâmetros de mercado invalida drexies-market-params;
• sincronizações e consultas AgRisk invalidam os conjuntos afetados, como produtos, clientes, consultas, protestos, processos, conformidade, imóveis e grupo familiar;
• o enriquecimento de contatos atualiza diretamente o cache producer-contacts com a resposta da operação.

Google Sheets¶

O hook de planilha chama a Edge Function google-sheets-proxy. A função consulta a API do Google Sheets e devolve as linhas ao service dataSource, que normaliza e calcula os dados em memória.

Tela → React Query → google-sheets-proxy → Google Sheets
→ normalização no frontend → cache de 5 minutos → indicadores

No frontend, a consulta fica atual por 5 minutos e pode permanecer no cache por 10 minutos após ficar sem uso. Esses valores não definem quando a planilha de origem é editada.

Não foi identificada persistência das linhas da planilha em tabela Supabase nesse fluxo, nem uma rotina agendada de importação no repositório.

Planos de vendas¶

Planos, metas e itens são persistidos em drexies_sales_plans, drexies_sales_plan_targets e drexies_sales_plan_items.

Os hooks de planos usam staleTime de 1 minuto. Itens e manejos vinculados ao plano usam 30 segundos. Projeções, totais e classificações derivados são recalculados no frontend quando os dados usados pelos componentes mudam.

Simulações¶

As simulações e seus itens são persistidos em drexies_simulation_orders e drexies_simulation_order_items. O código implementa criação, alteração de estado, arquivamento, restauração, exclusão e conversão dos itens em itens do plano de vendas.

Ação do usuário → simulationOrderService → PostgREST
→ pedido/itens persistidos → atualização da consulta → tela

Os hooks de simulações usam staleTime de 30 segundos. O arquivamento grava archived_at; portanto, não equivale necessariamente à exclusão física. A exclusão definitiva usa uma operação delete explícita.

Potenciais, manejo, preços e parâmetros¶

Potenciais personalizados são persistidos por usuário em drexies_custom_potentials e drexies_custom_potential_items. O salvamento atualiza ou cria o cabeçalho, substitui os itens associados e o reset remove cabeçalho e itens do escopo.

Manejos e preços usam as tabelas de produtos, tabelas de preço, itens de preço e itens de manejo. Foram identificadas operações de atualização, inclusão e exclusão. Os parâmetros de mercado usam upsert e, após sucesso, invalidam sua consulta no React Query.

Dados persistidos + áreas e filtros → services de potencial
→ cálculo no frontend → indicadores e telas

O potencial padrão, o valor capturável e outras totalizações derivadas não possuem uma rotina de atualização independente: são recalculados pela aplicação conforme os dados carregados e as seleções atuais.

Comissões, aprovações e DRE¶

As configurações de comissão são persistidas em drexies_producer_commissions por operações de leitura, upsert e exclusão. O hook de consulta considera esses dados atuais por 5 minutos.

O fluxo de aprovação da DRE usa drexies_dre_plan_approvals e permite inserir, atualizar, arquivar e restaurar registros. O hook correspondente utiliza staleTime de 30 segundos.

A DRE é calculada no frontend a partir de planos, metas, realizados, comissões, Over Price, ajustes e despesas. Não foi identificado um processo periódico de materialização do resultado completo.

Dados locais da DRE e RDV¶

Os lançamentos de RDV ficam no localStorage, usando chave por vendedor e ano. Inclusões, alterações e exclusões atualizam o estado React e, em seguida, o conteúdo local do navegador. As agregações mensais são recalculadas em memória.

Também foram identificados ajustes manuais da DRE no localStorage. O serviço de limpeza altera esses valores locais e registra a operação em drexies_dre_clear_log quando o fluxo de auditoria é executado.

Dados climáticos¶

A Edge Function weather-summary recebe coordenadas arredondadas para duas casas decimais e procura primeiro em drexies_weather_cache.

• Se o registro tiver menos de 24 horas, o payload persistido é devolvido com indicação de cache.
• Se não houver cache válido, a função consulta condições atuais e histórico horário no serviço Google Weather.
• A função calcula temperatura média e precipitação acumulada do período consultado e grava o novo payload por upsert.

Coordenadas → drexies_weather_cache
→ cache válido: resposta persistida
→ cache ausente/expirado: Google Weather → cálculo → upsert → resposta

O prazo de 24 horas é a política técnica explicitamente implementada para esse cache.

AgRisk sob demanda¶

As operações AgRisk são disparadas pela interface por meio da Edge Function agrisk. Foram identificadas ações para sincronizar produtos e clientes, criar consultas, buscar resultados, executar análise completa e atualizar grupos específicos de risco e patrimônio.

Ação do usuário → useAgrisk → Edge Function agrisk → API AgRisk
→ normalização e persistência → invalidação das consultas afetadas → tela

Após as operações, o frontend invalida somente os grupos relacionados. Por exemplo:

• sincronização de produtos invalida produtos;
• sincronização ou vinculação de clientes invalida clientes;
• análise completa invalida consultas, clientes e informações de contato;
• atualização de risco invalida protestos, situação dos protestos, processos e clientes;
• atualização de ativos invalida conformidade, imóveis rurais, grupo familiar e consultas.

O código persiste consultas, resultados consolidados, vínculos e erros em tabelas AgRisk do Supabase. Não foi identificado agendamento automático dessas consultas no repositório.

eEmóvel sob demanda¶

A Edge Function eemovel-enrich consulta a eEmóvel por documento, normaliza a resposta e persiste contatos em drexies_producer_contacts.

Antes de consultar a API, a função pode reutilizar um contato já persistido. O parâmetro force=true ignora essa reutilização e força nova consulta externa. O código não define uma expiração temporal para o registro persistido.

Documento → contato persistido disponível: reutilização
Documento → force ou ausência: API eEmóvel → upsert → cache React Query → tela

No frontend, a consulta de contatos possui staleTime: Infinity; após o enriquecimento ou atualização, o cache é substituído diretamente com setQueryData.

IBGE e Google Maps¶

IBGE¶

A lista de municípios é consultada sob demanda pela Edge Function ibge-municipios. Os nomes de municípios mantidos pelo hook possuem cache sem expiração. As malhas municipais GeoJSON são consultadas diretamente pela interface e mantidas em um cache global em memória para evitar novas requisições durante a mesma execução da aplicação.

Google Maps¶

A Edge Function nearby-competitors consulta estabelecimentos próximos quando recebe coordenadas e raio. Os resultados são deduplicados, filtrados pela distância e devolvidos à tela. Não foi identificada persistência desses resultados nem periodicidade automática.

Os dados persistidos de drexies_silos e drexies_revendas são carregados separadamente por PostgREST e considerados atuais pelo React Query por 5 minutos.

Resumo dos mecanismos¶

Pontos a validar¶

1. Confirmar a frequência real de atualização da planilha Google Sheets e seus responsáveis operacionais.
2. Confirmar se os tempos de cache do frontend e o cache climático de 24 horas atendem às políticas operacionais esperadas.
3. Verificar se existem rotinas agendadas, cron jobs, webhooks ou automações configuradas diretamente no Supabase remoto e ausentes do repositório.
4. Definir os responsáveis pela atualização de produtores, propriedades, produtos, preços, manejos, silos, revendas e parâmetros de mercado.
5. Confirmar o processo real de sincronização, promoção e consistência de dados entre ambientes.
6. Confirmar o comportamento efetivo no ambiente publicado para invalidação, recarga e permissões após mutações.
7. Definir expiração e reconsulta para contatos da eEmóvel e resultados persistidos da AgRisk.
8. Confirmar a estratégia definitiva de persistência e compartilhamento dos dados locais de RDV e dos ajustes da DRE.

Referências¶

• Fontes de Dados e Linhagem — origens, integrações e estruturas persistidas
• Dicionário de Indicadores e Regras de Negócio — cálculos derivados dos dados
• Telas e Funcionalidades — utilização dos dados nas telas