Release v4928.1.4.2 stable

docs/CLIENTFLOW_V483_OPERATIONS_GUARDRAILS.md

@@ -0,0 +1,85 @@
+# 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:
+
+```bash
+python scripts/cleanup_non_commercial_opportunities.py --limit 100
+```
+
+Por defeito é dry-run. Para aplicar:
+
+```bash
+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.