Release v4928.1.4.2 stable

docs/CLIENTFLOW_V45_OPERATIONAL_CORE.md

@@ -0,0 +1,110 @@
+# ClientFlow v4.5 — Operational Core
+
+Esta versão junta a proposta v4.3 + v4.4 numa atualização única e incremental para o sistema em campo.
+
+## Objetivo
+
+Transformar a UI num sistema operacional diário:
+
+```text
+Email / Chatwoot / pedido recebido
+→ Comunicação classificada
+→ Centro de trabalho
+→ Cliente / oportunidade
+→ Task humana ou Outbox automática
+→ Documento / envio
+→ Timeline
+```
+
+## O que muda
+
+### Dashboard
+
+O `/` passa a ser uma visão geral: métricas, alertas e ligação direta ao Centro de trabalho. Deixa de ser a página principal para execução item a item.
+
+### Centro de trabalho
+
+O `/operations` passa a juntar itens acionáveis:
+
+- tasks humanas pendentes;
+- comunicações por tratar;
+- outbox pending/failed/blocked;
+- clientes/produtos/documentos que bloqueiam o fluxo.
+
+### Comunicações
+
+Nova área:
+
+```text
+/communications
+/comunicacoes
+```
+
+Guarda emails/mensagens classificados com ligação opcional a cliente, oportunidade e task.
+
+Estados suportados:
+
+```text
+new
+classified
+needs_review
+linked
+task_created
+done
+ignored
+```
+
+### Oportunidade
+
+A página da oportunidade passa a incluir navegação por secções:
+
+```text
+Resumo
+Produtos
+Documentos
+Tasks
+Comunicações
+Outbox
+Timeline
+Técnico
+```
+
+### Tasks contextualizadas
+
+A tabela `tasks` recebe colunas para contexto operacional:
+
+```text
+communication_id
+document_id
+shipment_id
+outbox_id
+priority
+assigned_to
+```
+
+### Timeline unificada
+
+Nova tabela `timeline_events`, integrada na timeline da oportunidade.
+
+## Instalação
+
+1. Fazer backup da base de dados.
+2. Aplicar código v4.5.
+3. Reiniciar serviço.
+4. Confirmar que o startup executou `init_db()`.
+5. Opcional: aplicar manualmente `migrations/006_v45_operational_core.sql`.
+6. Validar no browser:
+
+```text
+/
+/operations
+/communications
+/opportunities/{id}
+```
+
+## Notas
+
+- Não muda para React/Vue.
+- Mantém FastAPI + HTML/HTMX.
+- Não remove rotas antigas.
+- A automação crítica continua por outbox e deve continuar a exigir validação humana quando aplicável.