Release v4928.1.4.2 stable

docs/CLIENTFLOW_V4928_1_LEGACY_COHERENCE.md

@@ -0,0 +1,33 @@
+# ClientFlow v4928.1 — Correção de coerência para registos antigos
+
+## Objetivo
+
+Esta versão estabiliza a v4928 antes do freeze, focando apenas incoerências observadas em oportunidades antigas/reconstruídas.
+
+## Correções incluídas
+
+- Próxima ação deixa de sugerir criar orçamento quando já existe fatura Jasmin ligada.
+- `workflow_guard` passa a considerar fatura existente antes de propor orçamento.
+- Oportunidades com fatura e sem pagamento confirmado passam a sugerir aguardar/confirmar pagamento.
+- Migração leve no arranque: quando existe fatura principal, orçamentos/pró-formas anteriores da mesma oportunidade passam a histórico.
+- Oportunidades com fatura e sem task pendente são marcadas em `metadata.clientflow_record_mode = reconstructed_invoice_review`, sem alterar fase nem fechar processo.
+- Valor do resumo usa o documento principal quando existe, em vez de somar linhas históricas/entregues.
+- Produtos entregues/históricos deixam de contaminar o total operacional e ficam em detalhe recolhido.
+- Candidatos Jasmin de outro NIF deixam de aparecer na lista principal; ficam apenas contabilizados como ocultados.
+- Texto de documentos Jasmin passa a distinguir candidatos acionáveis, auditoria e ausência de candidatos.
+- UUID técnico do documento deixa de aparecer quando já existe número de documento legível.
+- Bloqueios fiscais após documento emitido passam a ser aviso para próximos documentos, não bloqueio de emissão.
+
+## Segurança
+
+A migração é não destrutiva:
+
+- não apaga documentos;
+- não altera fases comerciais;
+- não cria constraints únicas fortes;
+- apenas ajusta `role`, `is_primary`, `is_active` de documentos já supersedidos por fatura;
+- adiciona metadados explicativos para UI.
+
+## Validação
+
+`207 passed`.