Release v4928.1.4.2 stable

docs/CLIENTFLOW_V484_FISCAL_LINK_CONSISTENCY.md

@@ -0,0 +1,30 @@
+# ClientFlow v4.8.4 — Fiscal Link Consistency Hotfix
+
+## Objetivo
+
+Corrigir inconsistências entre a ficha da task, a fila Operations e os cards de oportunidade quando a oportunidade já tem cliente fiscal associado.
+
+## Problema corrigido
+
+Em alguns casos a task mostrava corretamente o cliente fiscal ligado pela oportunidade, por exemplo `Elegantlegacy Lda`, mas o card em Operations continuava a mostrar `Cliente fiscal por associar`. Isto acontecia porque a fila operacional lia o cliente fiscal a partir de `tasks.customer_id`, enquanto o detalhe da task usava `opportunities.local_customer_id`.
+
+## Alterações
+
+- Operations passa a procurar primeiro o cliente fiscal da oportunidade (`opportunities.local_customer_id`).
+- `tasks.customer_id` fica apenas como fallback quando for um UUID local válido/resolvido.
+- O contact_id do Chatwoot nunca é usado como cliente fiscal.
+- Operations passa a receber também NIF, email, morada, código postal e localidade do cliente fiscal.
+- Bloqueios de Operations passam a mostrar dados fiscais em falta quando há cliente fiscal associado, em vez de dizer apenas “cliente fiscal por associar”.
+- O detalhe da task passa a carregar morada/código postal/localidade do cliente fiscal.
+- A secção “Dados em falta” da task passa a incluir falhas fiscais críticas, para não contradizer a “Prontidão fiscal da tarefa”.
+
+## Sem migração
+
+Esta versão não altera schema de base de dados.
+
+## Validação
+
+```bash
+PYTHONPATH=. python -m compileall app scripts tests
+PYTHONPATH=. pytest -q
+```