clientflow_backend/docs/CLIENTFLOW_V483_OPERATIONS_GUARDRAILS.md

ClientFlow v4.8.3 — Operations Card Simplification & Opportunity Guardrails

Esta versão fecha o ciclo de estabilização operacional após a v4.8.2. O foco é reduzir ruído em /operations e impedir que mensagens sem intenção comercial criem oportunidades falsas.

Objetivos

• Tornar os cards de Operations mais leves para o operador.
• Nunca mostrar contact_id do Chatwoot como se fosse cliente fiscal.
• Mostrar bloqueios apenas quando bloqueiam a próxima ação da jornada.
• Criar oportunidades apenas quando existe intenção comercial real.
• Evitar oportunidades para bounces, spam, Mail Delivery Subsystem, unsubscribe e revisão falhada.

Regras de criação de oportunidade

Criar oportunidade automaticamente apenas para ações comerciais claras, como:

• SEND_QUOTE
• SEND_PROFORMA
• SEND_INVOICE
• CONFIRM_PAYMENT
• PREPARE_ORDER
• CREATE_SHIPMENT

SEND_INFO só cria oportunidade se houver intenção comercial explícita no assunto/corpo/nota, como orçamento, cotação, preço, comprar, encomendar, pró-forma, fatura ou pagamento.

Nunca cria oportunidade para:

• REVIEW_MANUALLY
• REMOVE_FROM_LIST
• IGNORE_SPAM
• NO_ACTION
• SUPPORT
• MARK_NO_INTEREST sem oportunidade existente
• Mail Delivery Subsystem / mailer-daemon / postmaster
• returned mail / undelivered mail / delivery status notification

Bloqueios por fase da jornada

Cliente fiscal por associar só aparece como bloqueio quando a próxima ação exige dados fiscais, documento, pagamento ou envio.

Não aparece como bloqueio em fases iniciais como:

• rever mensagem
• responder informação simples
• suporte simples
• marketing/remover da lista
• mensagem automática/bounce

Cards de Operations

O card principal passa a mostrar apenas:

• título simples
• contexto curto
• próxima ação
• bloqueio atual, se existir
• botões principais

Campos técnicos foram movidos para Ver detalhes:

• fila
• estado
• origem
• contacto Chatwoot
• cliente fiscal quando existir ou for necessário

Limpeza de oportunidades antigas

Foi adicionado script conservador:

python scripts/cleanup_non_commercial_opportunities.py --limit 100

Por defeito é dry-run. Para aplicar:

python scripts/cleanup_non_commercial_opportunities.py --apply

Só fecha oportunidades abertas com valor 0, sem documentos comerciais e sem envios, que parecem ter sido criadas por mensagens automáticas/bounce.

Sem migração

Esta versão não cria tabelas nem exige migração de base de dados.