Release v4928.1.4.2 stable

docs/CLIENTFLOW_V45_UPDATE_GUIDE.md

@@ -0,0 +1,83 @@
+# Guia de atualização — ClientFlow v4.5 Operational Core
+
+## Antes de atualizar
+
+1. Fazer backup da base de dados PostgreSQL.
+2. Guardar o `.env` atual.
+3. Confirmar que os timers/serviços atuais estão estáveis:
+
+```bash
+systemctl status clientflow-api.service
+systemctl list-timers | grep clientflow
+```
+
+## Instalação recomendada
+
+```bash
+# exemplo; ajustar diretórios ao servidor real
+cd /opt/clientflow
+systemctl stop clientflow-api.service
+cp -a clientflow_backend clientflow_backend_backup_$(date +%Y%m%d_%H%M)
+unzip clientflow_backend_v45_operational_core.zip -d /opt/clientflow/clientflow_backend_v45
+cp /opt/clientflow/clientflow_backend/.env /opt/clientflow/clientflow_backend_v45/.env
+cd /opt/clientflow/clientflow_backend_v45
+python -m compileall app scripts tests
+pytest -q
+systemctl start clientflow-api.service
+```
+
+Se o serviço usa um caminho fixo, trocar o symlink/current release conforme o teu deploy atual.
+
+## Migração de base de dados
+
+A v4.5 é aditiva. O `init_db()` cria/atualiza:
+
+```text
+communications
+timeline_events
+tasks.communication_id
+tasks.document_id
+tasks.shipment_id
+tasks.outbox_id
+tasks.priority
+tasks.assigned_to
+```
+
+Também existe migração SQL explícita:
+
+```bash
+psql "$DATABASE_URL" -f migrations/006_v45_operational_core.sql
+```
+
+## Validação pós-instalação
+
+Abrir:
+
+```text
+/
+/operations
+/communications
+/opportunities
+/outbox
+/integrations
+```
+
+Verificar:
+
+```text
+Dashboard mostra apenas visão geral.
+Centro de trabalho mostra fila operacional.
+Comunicações abre sem erro.
+Oportunidade mostra tabs: Resumo, Produtos, Documentos, Tasks, Comunicações, Outbox, Timeline, Técnico.
+Outbox continua a processar sem marcar dry_run como sent.
+```
+
+## Rollback
+
+Como a migração é aditiva, o rollback de código pode ser feito voltando para a pasta/ZIP anterior. As tabelas e colunas novas podem ficar na BD sem afetar a versão anterior.
+
+## Limitações conhecidas
+
+- A v4.5 cria a estrutura de Comunicações, mas o conector real de email/classificação deve inserir dados nessa tabela.
+- A confirmação de pagamentos e ações críticas continuam humanas.
+- Permissões e CSRF completos continuam recomendados para uma ronda posterior se o sistema estiver exposto fora da rede controlada.