DataFirefly Inventory Forecasting: guia completo

Visão de conjunto

O DataFirefly Inventory Forecasting é um plugin WooCommerce de previsão de stock, geração automática de notas de encomenda a fornecedor e alertas de rutura. Transforma o back-office do WordPress num posto de pilotagem da cadeia de abastecimento, sem passar por um SaaS externo e sem custos por SKU.

O plugin assenta num algoritmo Holt-Winters multiplicativo que decompõe as suas vendas históricas em duas componentes: uma tendência estimada por regressão linear sobre uma média móvel de sete dias, e uma sazonalidade calculada como índice mensal multiplicativo. As previsões a 30, 60 e 90 dias são depois comparadas com o stock atual para produzir um ponto de reencomenda, uma quantidade de reabastecimento (tendo em conta a MOQ e o tamanho do lote) e uma estimativa da data de rutura.

Requisitos e instalação

Requisitos técnicos

• WordPress 6.4 ou superior
• WooCommerce 8.0 ou superior
• PHP 8.1 ou superior
• MySQL 5.7 ou MariaDB 10.3 no mínimo
• WP-Cron ativo (ou substituído por um cron de sistema que acione o wp-cron.php)

Instalação

1. Descarregue o arquivo ZIP a partir da sua conta de cliente em datafirefly.com.
2. No WordPress, vá a Plugins → Adicionar plugin → Carregar plugin.
3. Selecione o ZIP e clique em Instalar agora.
4. Ative a extensão. Na ativação, o plugin cria sete tabelas com prefixo wp_dfif_, declara a compatibilidade HPOS e agenda quatro tarefas cron diárias.

Primeiro arranque: reconstruir o histórico

O plugin precisa de conhecer as suas vendas passadas para calibrar a tendência e os índices sazonais. Na primeira utilização, clique em Reconstruir o histórico a partir do painel. Esta ação percorre as encomendas concluídas da janela configurada (365 dias por predefinição) e agrega as quantidades vendidas por produto e por dia na tabela wp_dfif_sales_daily.

Num catálogo de algumas centenas de produtos e 12 meses de histórico, a operação demora de um a cinco minutos. É paginada em blocos de 100 encomendas e compatível com HPOS.

Conceitos fundamentais

Tendência e sazonalidade

Em cada ciclo de previsão, o plugin constrói para cada produto uma série diária suavizada por média móvel de sete dias. Uma regressão linear sobre essa série dá a tendência (declive e ordenada na origem). Em separado, os índices sazonais mensais são calculados como a razão entre as vendas de cada mês do calendário e a média anual, com um mínimo de 0,3 e um máximo de 3,0 para absorver os valores aberrantes.

A previsão ao horizonte H dias combina depois tendência e índice do mês alvo: vendas_previstas = vendas_médias × (1 + tendência × H) × índice_sazonal.

Stock de segurança

O stock de segurança é calculado pela fórmula clássica z × σ × √lead_time, em que z é o quantil normal correspondente ao nível de serviço pretendido (1,645 para 95%, 2,326 para 99%), σ o desvio-padrão das vendas diárias e lead_time o prazo de entrega do fornecedor em dias. Esta reserva absorve as variações aleatórias da procura durante o reabastecimento.

Ponto de reencomenda e quantidade de reencomenda

O ponto de reencomenda é o limiar de stock que desencadeia uma encomenda. Vale vendas_médias × lead_time + stock_de_segurança. Na prática, assim que o stock atual desce abaixo desse limiar, deve ser feita uma encomenda para evitar a rutura.

A quantidade de reencomenda é a quantidade a encomendar. É arredondada ao múltiplo do tamanho de lote (pack size) e depois elevada à MOQ (quantidade mínima de encomenda do fornecedor), se for necessário.

Nível de confiança

Cada previsão vem acompanhada de uma pontuação de confiança de 0 a 100%, calculada heuristicamente conforme a extensão do histórico disponível, a regularidade das vendas e a presença de sazonalidade marcada. Uma confiança inferior a 40% aparece a vermelho e passa automaticamente para uma previsão simples (média móvel), mais prudente.

Gestão dos fornecedores

Criar um fornecedor

No menu Inventory Forecasting → Fornecedores, clique em Adicionar um fornecedor. Indique no mínimo o nome e o e-mail (usado para o envio das notas de encomenda). Os campos facultativos são: contacto, telefone, morada, moeda de faturação e notas internas.

Associar um fornecedor a um produto

Na página de edição de um produto WooCommerce, aparece uma metabox Fornecedores Inventory Forecasting na coluna principal. Permite acrescentar um ou vários fornecedores a esse produto, cada um com os seus próprios parâmetros:

• Preço de compra sem impostos, usado na linha da nota de encomenda
• SKU do fornecedor, muitas vezes diferente do SKU interno, impresso no PDF
• Prazo de entrega em dias, que entra no cálculo do ponto de reencomenda
• MOQ, quantidade mínima exigida pelo fornecedor
• Tamanho de lote, incremento pelo qual as quantidades são arredondadas
• Fornecedor principal, botão de opção que designa o fornecedor escolhido pela geração automática das notas de encomenda

Previsões e horizontes

A página Inventory Forecasting → Previsões lista todos os produtos com, para cada um, a previsão ao horizonte selecionado, o ponto de reencomenda, a quantidade a encomendar, a data estimada de rutura e o nível de confiança.

Filtros

• Horizonte: 30, 60 ou 90 dias (os três são calculados em paralelo pelo cron)
• Gravidade: crítica (rutura em menos de 7 dias), aviso (rutura em menos de 14 dias), normal
• Pesquisa: por título de produto ou SKU

Recálculo manual

O botão Recalcular as previsões do painel força um ciclo imediato sem esperar pelo cron das 2h30. Útil depois de mudar um parâmetro (nível de serviço, tamanho da janela de histórico) ou depois de uma importação massiva de encomendas.

Notas de encomenda a fornecedor

Ciclo de vida de uma nota de encomenda

1. Rascunho: criada mas não enviada, editável
2. Enviada: PDF gerado e expedido ao fornecedor por e-mail
3. Parcialmente recebida: pelo menos uma linha, mas não todas as quantidades, recebida
4. Recebida: todas as quantidades registadas
5. Cancelada: encomenda abandonada antes da receção

Geração manual

A partir de Inventory Forecasting → Notas de encomenda, o botão Gerar a partir das previsões percorre os produtos abaixo do ponto de reencomenda, agrupa-os por fornecedor principal e cria uma nota de encomenda em rascunho por fornecedor. Pode depois editar as quantidades, acrescentar ou retirar linhas, e enviar.

Geração automática

O cron das 4h pode gerar automaticamente as notas de encomenda, com ou sem envio imediato. Esta opção está desativada por predefinição. Depois de ativada nas definições, há dois modos possíveis: criação em rascunho (envio manual após validação) ou envio imediato.

PDF nativo

O PDF é gerado por um motor em PHP puro integrado (tipo de letra Helvetica, formato A4, cerca de 250 linhas de código). Inclui o cabeçalho da sua empresa, os dados do fornecedor, a tabela de linhas com SKU do fornecedor e preço de compra, o total sem IVA, e um rodapé personalizável. Não é exigida qualquer dependência do Dompdf, do TCPDF ou do mPDF.

Receção da mercadoria

Na vista de detalhe de uma nota de encomenda, cada linha tem um campo Quantidade recebida. Introduzir o valor recebido atualiza o stock WooCommerce do produto pelo delta face ao valor anterior. Esta lógica evita as contagens duplicadas se corrigir uma receção à posteriori.

Alertas de rutura

O plugin deteta diariamente quatro tipos de situação e atribui a cada uma um nível de gravidade.

Tipos de alertas

• IMMINENT: rutura prevista em menos de 7 dias (parametrizável), gravidade crítica
• WARNING: rutura prevista em menos de 14 dias (parametrizável), gravidade de aviso
• OVERSTOCK: cobertura de stock superior a 180 dias, gravidade informativa
• REORDER: stock abaixo do ponto de reencomenda, gravidade de aviso

Ciclo de vida

Uma alerta é criada com o estado active. No ciclo seguinte, se a situação persistir, é marcada como pending_recheck; se tiver desaparecido, passa a resolved com data e hora. Este mecanismo evita o spam de alertas repetitivas.

Notificações por e-mail

É enviado um resumo diário para o endereço configurado nas definições, com a lista das novas alertas críticas e de aviso. O conteúdo do e-mail é uma tabela HTML sóbria, filtrável por gravidade.

Definições

A página Inventory Forecasting → Definições reúne quatro secções.

Previsões

• Janela de histórico: 365 dias por predefinição. Quanto mais longa for a janela, mais robusta é a sazonalidade, mas maior fica a tabela sales_daily.
• Horizontes de previsão: lista separada por vírgulas, 30, 60 e 90 por predefinição. Pode acrescentar, por exemplo, 14 ou 180.
• Nível de serviço: 95% por predefinição. Traduzido em z = 1,645 pela inversa normal. Passe a 99% (z = 2,326) para stock crítico, e a 90% (z = 1,282) para o não estratégico.

Alertas

• Dias de antecipação de aviso: 14 por predefinição
• Dias de antecipação crítica: 7 por predefinição
• E-mail destinatário do resumo diário

Notas de encomenda

• Geração automática ativada: desassinalada por predefinição
• Prefixo de numeração: PO- por predefinição, produz identificadores como PO-2026-00042
• Moeda: herdada do WooCommerce, substituível por fornecedor

Empresa

Dados da sua empresa impressos no cabeçalho dos PDF das notas de encomenda: designação social, morada, número de identificação da empresa ou número de IVA, e-mail, telefone e logótipo.

Tarefas cron

São agendadas automaticamente quatro tarefas na ativação do plugin, no fuso horário do site.

• 02:00 — Reconstrução do histórico: agrega as encomendas da véspera na tabela sales_daily. Leve, alguns segundos.
• 02:30 — Cálculo das previsões: recalcula tendência, sazonalidade e pontos de reencomenda. Mais pesado, de um a cinco minutos consoante o catálogo.
• 03:00 — Deteção das alertas: cria e resolve as alertas conforme os limiares. Rápido.
• 04:00 — Geração automática das notas de encomenda: só é executada se a opção estiver ativa nas definições.

API REST

O plugin expõe várias rotas REST no namespace dfif/v1. Todas exigem a permissão manage_woocommerce e o nonce do WordPress wp_rest.

POST /wp-json/dfif/v1/run-forecast
POST /wp-json/dfif/v1/rebuild-history
POST /wp-json/dfif/v1/detect-alerts
POST /wp-json/dfif/v1/generate-pos
POST /wp-json/dfif/v1/send-po/{id}
POST /wp-json/dfif/v1/po/{id}/items/{item_id}/receive
GET  /wp-json/dfif/v1/stats

Estas rotas são usadas internamente pelos botões do painel (através do wp.apiFetch com o cabeçalho X-WP-Nonce) e podem também ser chamadas a partir de qualquer cliente autenticado por cookies do WordPress ou por application passwords.

Hooks do WordPress

As principais etapas do plugin emitem ações e filtros que pode intercetar:

do_action('dfif_forecast_calculated', $product_id, $forecast_data);
do_action('dfif_purchase_order_created', $po_id, $supplier_id);
do_action('dfif_purchase_order_sent', $po_id);
do_action('dfif_alert_triggered', $alert_id, $alert_type);
apply_filters('dfif_reorder_qty', $qty, $product_id, $supplier_id);
apply_filters('dfif_pdf_company_info', $info);

Resolução de problemas

As previsões continuam a zero

Verifique que a reconstrução do histórico foi mesmo executada e que a tabela sales_daily contém linhas. Se não tiver encomendas concluídas ou em processamento na janela configurada, o plugin não consegue prever nada. Verifique também que o WooCommerce está ativo.

As previsões parecem incoerentes

Duas causas frequentes: um histórico demasiado curto (menos de 30 dias, o plugin passa a uma previsão simples) ou uma sazonalidade extrema não representativa (uma Black Friday isolada). Olhe para o nível de confiança apresentado: abaixo de 40%, a previsão deve ser tomada com cautela.

O PDF não é gerado

Verifique que o diretório wp-content/uploads/dfif-po/ tem permissões de escrita. É aí que o plugin coloca os PDF antes do envio. É criado automaticamente um ficheiro .htaccess para impedir o acesso público direto.

O e-mail não é enviado

O plugin usa o wp_mail, que por vezes falha em alguns alojamentos. Instale um plugin de SMTP (WP Mail SMTP, FluentSMTP) e configure um serviço de entregabilidade (Postmark, SendGrid, Mailjet, Brevo). Verifique também que o e-mail do fornecedor está bem introduzido e é válido.

O cron não corre

Use o plugin WP Crontrol para listar os hooks agendados e ver a próxima execução. Os quatro hooks têm o prefixo dfif_. Se não os vir, desative e volte a ativar o Inventory Forecasting.

Desinstalação

Na desativação, os crons são desagendados mas as tabelas e os dados são conservados. Na desinstalação completa através de Plugins → Eliminar, há dois comportamentos possíveis consoante a opção dfif_delete_data_on_uninstall nas definições:

• Desassinalada por predefinição: as tabelas são conservadas e pode reinstalar sem perder o histórico.
• Assinalada: as sete tabelas e o diretório wp-content/uploads/dfif-po/ são eliminados.

FAQ

Posso usar o plugin num catálogo variável (variações de produto)?

Sim. As previsões e as notas de encomenda funcionam ao nível da variação individual. Cada variação pode ter os seus próprios fornecedores e os seus próprios parâmetros.

O plugin é compatível com multisite?

Sim, mas cada site da rede gere o seu próprio catálogo, os seus fornecedores e as suas previsões. Não há partilha entre sites.

Posso exportar os dados?

Todas as tabelas são acessíveis por SQL padrão. Está prevista uma exportação CSV nativa numa versão posterior. Até lá, basta um simples SELECT INTO OUTFILE ou um plugin como o WP All Export.

O plugin bloqueia a administração se o cron não tiver corrido?

Não. O plugin continua a funcionar, apenas as previsões apresentadas podem ter vários dias. Um distintivo Último cron no painel indica a frescura dos dados.

Como se comporta o plugin num catálogo de vários milhares de SKU?

A reconstrução do histórico e o cálculo das previsões mantêm-se lineares no número de produtos ativos. Com 5000 SKU e 12 meses de histórico, conte com 10 a 30 minutos de processamento noturno, consoante a potência do servidor. Sem qualquer impacto no desempenho do front-office: todos os cálculos são assíncronos.