Release v4928.1.4.2 stable

docs/CLIENTFLOW_V482_PRODUCTION_STABILIZATION.md

@@ -0,0 +1,76 @@
+# ClientFlow v4.8.2 — Production Stabilization & Guided Operations
+
+Esta versão fecha o ciclo de atualização com melhorias pequenas e focadas na operação diária. Não adiciona novas integrações, não muda regras LLM, não altera auto-complete e não requer migração de base de dados.
+
+## Objetivo
+
+Reduzir erros reais do operador:
+
+- cliente fiscal errado;
+- documento emitido sem dados mínimos;
+- envio preparado sem morada/telefone;
+- outbox falhada sem explicação operacional;
+- operador sem próximo passo claro.
+
+## O que muda
+
+### Cliente fiscal e contacto Chatwoot separados
+
+Operations, oportunidades e detalhe de task passam a mostrar explicitamente:
+
+- Cliente fiscal;
+- Contacto Chatwoot;
+- conversa/contacto de origem quando disponível.
+
+### Prontidão antes de documento ou envio
+
+A UI mostra uma checklist mínima:
+
+- cliente fiscal associado;
+- NIF;
+- email de faturação;
+- morada fiscal;
+- código postal;
+- localidade;
+- telefone para envio quando aplicável.
+
+Quando falta informação, a UI mostra que a ação deve aguardar correção dos dados.
+
+### Próximo passo e bloqueios atuais
+
+A ficha de oportunidade passa a destacar:
+
+- próxima ação;
+- bloqueios atuais;
+- dados fiscais/contacto;
+- prontidão para documentos;
+- prontidão para envio.
+
+### Outbox em linguagem operacional
+
+A outbox passa a mostrar uma leitura operacional do erro, por exemplo:
+
+> Motivo provável: Cliente fiscal sem NIF válido ou dados fiscais incompletos.
+
+O detalhe do item continua a incluir o payload e o erro técnico para diagnóstico.
+
+### Health para operação
+
+`/system/health` passa a mostrar estado simples:
+
+- OK;
+- Atenção;
+- Crítico.
+
+Também mostra contadores de oportunidades sem cliente fiscal, clientes fiscais incompletos em oportunidades ativas, produtos sem código externo e último webhook Chatwoot.
+
+## Validação
+
+```bash
+PYTHONPATH=. python -m compileall app scripts tests
+PYTHONPATH=. pytest -q
+```
+
+## Sem migração
+
+Esta versão é apenas UI/health/readability. Não requer alteração de schema.