Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_v4928_1_5_132_OPERATIONAL_COHERENCE.md

@@ -0,0 +1,94 @@
+# ClientFlow v4928.1.5.132 — Coerência operacional e precedência do Centro de Trabalho
+
+## Objetivo
+
+Corrigir as incoerências identificadas pela auditoria forense entre:
+
+- estado físico Odoo;
+- fase persistida da oportunidade;
+- revisão de processos reconstruídos;
+- task pendente;
+- ação apresentada no Centro de Trabalho;
+- candidatos de reconciliação já ligados.
+
+A atualização não altera valores comerciais, documentos, pagamentos nem associações de clientes fiscais.
+
+## Correções de código
+
+### Odoo `assigned`
+
+- `assigned` passa a significar apenas stock/picking reservado.
+- A fase segura é `ORDER_PREPARATION` enquanto não existir validação física.
+- Só uma validação física explícita permite `READY_TO_SHIP`.
+- Só um envio/tracking real permite `SHIPMENT_CREATED`.
+- O sincronizador pode corrigir de forma controlada uma fase demasiado avançada quando não existe validação, tracking nem envio.
+- Evidência `physical_validation` deixa de ser criada a partir de `assigned`.
+
+### Revisão de processos reconstruídos
+
+- Novo estado persistido: `required`, `validated` ou `waived`.
+- O título ou `clientflow_record_mode` deixam de ser suficientes para inventar um bloqueio.
+- `VALIDATE_PHYSICAL_ORDER` passa a ser tratada como ação sensível.
+- Uma revisão concluída não volta a abrir apenas porque o título continua histórico.
+- Tasks ignoradas ou saltadas não contam como revisão concluída.
+
+### Precedência das ações
+
+A primeira ação apresentada passa a respeitar:
+
+1. associação explicitamente bloqueante;
+2. revisão reconstruída explicitamente obrigatória;
+3. task pendente executável;
+4. decisão central seguinte.
+
+A lista e o detalhe das Oportunidades usam a mesma política.
+
+### Reconciliação
+
+- candidatos já ligados podem ser resolvidos por script com guards;
+- exige exatamente uma ligação externa;
+- exige NIF ou nome coerente por defeito;
+- identidade desconhecida fica para revisão;
+- `S00323` não é resolvido automaticamente sem confirmação explícita.
+
+## Script de migração
+
+`scripts/apply_v132_operational_coherence.py`
+
+Características:
+
+- dry-run por defeito;
+- filtros independentes para oportunidades e candidatos;
+- transação protegida;
+- idempotente;
+- relatório JSON e Markdown;
+- não modifica valores, documentos, pagamentos ou clientes.
+
+Opções principais:
+
+```text
+--focus <nome/UUID>
+--candidate-ref <S00...>
+--skip-opportunities
+--skip-candidates
+--allow-unknown-identity
+--apply
+```
+
+## Casos atuais esperados
+
+- NOLTIA: `SHIPMENT_CREATED` → `ORDER_PREPARATION`; revisão reconstruída antes da validação física.
+- MAFIROL: `SHIPMENT_CREATED` → `ORDER_PREPARATION`; revisão reconstruída antes da validação física.
+- DUNAS: `READY_TO_SHIP` → `ORDER_PREPARATION`; resolver S00318; revisão antes da validação física.
+- RICARDO: persistir revisão como validada e manter `SEND_INVOICE`.
+- ENVIENERGY: remover o falso override visual de associação e mostrar a task real.
+- S00323: permanece para revisão até confirmação da oportunidade BBKW.
+
+## Validação
+
+- `py_compile`: OK
+- self-test do corretor: OK
+- self-test do auditor forense: OK
+- suite completa: **522 testes aprovados**
+
+A atualização não foi executada contra a base de dados de produção durante a preparação do pacote. Deve ser aplicada primeiro em dry-run no servidor.